### Convex CLI Commands

Source: https://github.com/darialyphia/convex-vue/blob/master/packages/convex-vue/convex/README.md

Provides essential Convex Command Line Interface (CLI) commands for managing deployments and accessing project documentation. These commands are executed from the project's root directory.

```APIDOC
npx convex -h
  - Displays help information for the Convex CLI, listing all available commands and options.

npx convex docs
  - Launches the official Convex documentation in your web browser, providing comprehensive guides and API references.
```

--------------------------------

### Define a Convex Query Function

Source: https://github.com/darialyphia/convex-vue/blob/master/packages/convex-vue/convex/README.md

Demonstrates how to define a Convex query function using TypeScript. It includes argument validation with `convex/values` and an asynchronous handler that can read from the database.

```ts
import { query } from "./_generated/server";
import { v } from "convex/values";

export const myQueryFunction = query({
  // Validators for arguments.
  args: {
    first: v.number(),
    second: v.string(),
  },

  // Function implementation.
  hander: async (ctx, args) => {
    // Read the database as many times as you need here.
    // See https://docs.convex.dev/database/reading-data.
    const documents = await ctx.db.query("tablename").collect();

    // Arguments passed from the client are properties of the args object.
    console.log(args.first, args.second);

    // Write arbitrary JavaScript here: filter, aggregate, build derived data,
    // remove non-public properties, or create new objects.
    return documents;
  },
});
```

--------------------------------

### Use Convex Query in React Component

Source: https://github.com/darialyphia/convex-vue/blob/master/packages/convex-vue/convex/README.md

Illustrates how to consume a Convex query function from a React component using the `useQuery` hook. This allows fetching data from Convex in a declarative way.

```ts
const data = useQuery(api.functions.myQueryFunction, {
  first: 10,
  second: "hello",
});
```

--------------------------------

### Install @convex-vue/core

Source: https://github.com/darialyphia/convex-vue/blob/master/packages/convex-vue/README.md

Installs the @convex-vue/core package along with its peer dependencies, @vueuse/core and convex.

```bash
npm install @convex-vue/core @vueuse/core convex
```

--------------------------------

### Development Commands

Source: https://github.com/darialyphia/convex-vue/blob/master/packages/nuxt/README.md

Common commands for developing the Nuxt module, including installing dependencies, running the development server, building, linting, testing, and releasing.

```bash
# Install dependencies
npm install

# Generate type stubs
npm run dev:prepare

# Develop with the playground
npm run dev

# Build the playground
npm run dev:build

# Run ESLint
npm run lint

# Run Vitest
npm run test
npm run test:watch

# Release new version
npm run release
```

--------------------------------

### Install My Module

Source: https://github.com/darialyphia/convex-vue/blob/master/packages/nuxt/README.md

Instructions for adding the 'my-module' dependency to your project using different package managers like pnpm, yarn, and npm.

```bash
# Using pnpm
pnpm add -D my-module

# Using yarn
yarn add --dev my-module

# Using npm
npm install --save-dev my-module
```

--------------------------------

### Configure Nuxt with My Module

Source: https://github.com/darialyphia/convex-vue/blob/master/packages/nuxt/README.md

Example of how to integrate 'my-module' into your Nuxt application by adding it to the 'modules' section in your nuxt.config.ts file.

```javascript
export default defineNuxtConfig({
  modules: [
    'my-module'
  ]
})
```

--------------------------------

### Define a Convex Mutation Function

Source: https://github.com/darialyphia/convex-vue/blob/master/packages/convex-vue/convex/README.md

Shows how to define a Convex mutation function in TypeScript. It covers argument validation and an asynchronous handler for database writes, such as inserting new documents.

```ts
import { mutation } from "./_generated/server";
import { v } from "convex/values";

export const myMutationFunction = mutation({
  // Validators for arguments.
  args: {
    first: v.string(),
    second: v.string(),
  },

  // Function implementation.
  hander: async (ctx, args) => {
    // Insert or modify documents in the database here.
    // Mutations can also read from the database like queries.
    // See https://docs.convex.dev/database/writing-data.
    const message = { body: args.first, author: args.second };
    const id = await ctx.db.insert("messages", message);

    // Optionally, return a value from your mutation.
    return await ctx.db.get(id);
  },
});
```

--------------------------------

### Use Convex Mutation in React Component

Source: https://github.com/darialyphia/convex-vue/blob/master/packages/convex-vue/convex/README.md

Demonstrates how to call a Convex mutation function from a React component using the `useMutation` hook. It shows both fire-and-forget usage and handling the mutation's return value.

```ts
const mutation = useMutation(api.functions.myMutationFunction);
function handleButtonPress() {
  // fire and forget, the most common way to use mutations
  mutation({ first: "Hello!", second: "me" });
  // OR
  // use the result once the mutation has completed
  mutation({ first: "Hello!", second: "me" }).then((result) =>
    console.log(result)
  );
}
```

--------------------------------

### Convex-Vue Authentication with Auth0 (JavaScript)

Source: https://github.com/darialyphia/convex-vue/blob/master/packages/convex-vue/README.md

Demonstrates how to configure Convex-Vue to use Auth0 for authentication. It shows the setup of the Auth0 client and how to integrate its authentication state and token retrieval with Convex-Vue's auth configuration.

```js
import { createConvexVue } from "@convex-vue/core";

// Example with auth using auth0
const auth = createAuth0({
  domain: import.meta.env.VITE_AUTH0_DOMAIN,
  clientId: import.meta.env.VITE_AUTH0_CLIENTID,
  authorizationParams: {
    redirect_uri: window.location.origin
  }
});

const convexVue = createConvexVue({
  convexUrl: import.meta.env.VITE_CONVEX_URL,
  auth: {
    isAuthenticated: auth.isAuthenticated,
    isLoading: auth.isLoading,
    getToken: async ({ forceRefreshToken }) => {
      try {
        const response = await auth.getAccessTokenSilently({
          detailedResponse: true,
          cacheMode: forceRefreshToken ? 'off' : 'on'
        });
        return response.id_token;
      } catch (error) {
        return null;
      }
    },
    installNavigationGuard: true,
    needsAuth: to => to.meta.needsAuth,
    redirectTo: () => ({
      name: 'Login'
    })
  }
});

app.use(convexVue);
```

--------------------------------

### Convex-Vue Authentication with Clerk (TypeScript)

Source: https://github.com/darialyphia/convex-vue/blob/master/packages/convex-vue/README.md

Illustrates setting up Convex-Vue with Clerk for authentication. This example shows how to use the vue-clerk plugin, manage authentication state, and provide the necessary token to Convex-Vue.

```ts
import { Ref, computed, createApp, ref } from 'vue';
import { Resources } from '@clerk/types';
import { clerkPlugin } from 'vue-clerk/plugin';

const app = createApp(App).use(clerkPlugin, {
  publishableKey: import.meta.env.VITE_CLERK_PUBLISHABLE_KEY
});

const authState: { isLoading: Ref<boolean>; session: Ref<Resources['session']> } = {
  isLoading: ref(true),
  session: ref(undefined)
};
app.config.globalProperties.$clerk.addListener(arg => {
  authState.isLoading.value = false;
  authState.session.value = arg.session;
});

const convexVue = createConvexVue({
  convexUrl: import.meta.env.VITE_CONVEX_URL,
  auth: {
    isAuthenticated: computed(() => !!authState.session.value),
    isLoading: authState.isLoading,
    getToken: async ({ forceRefreshToken }) => {
      try {
        return await authState.session.value?.getToken({
          template: 'convex',
          skipCache: forceRefreshToken
        });
      } catch (error) {
        return null;
      }
    },
  }
});

app.use(convexVue).mount('#app');
```

--------------------------------

### Convex-Vue Route Loaders Setup (TypeScript)

Source: https://github.com/darialyphia/convex-vue/blob/master/packages/convex-vue/README.md

Details the experimental Route Loaders feature in Convex-Vue, inspired by Remix. It covers defining route loader maps with Convex queries, passing the map to the Convex-Vue plugin, and using the `useRouteLoader` hook to access prefetched data.

```ts
import { api } from '@api';
import { defineRouteLoader } from '@convex-vue/core';

// defineRouteLoader will provide you with type safety
export const loaders = {
  Home: defineRouteLoader({
    todos: {
     query: api.todos.list,
      args() {
        return {};
      }
    }
  }),

 TodoDetails: defineRouteLoader({
    todo: {
      query: api.todos.byId,
      args(route) {
        return {
          id: route.params.id as Id<'Todos'>
        };
      }
    }
  })
};

export type Loaders = typeof loaders;
```

```ts
import { loaders } from './loaders';

const convexVue = createConvexVue({
  convexUrl: import.meta.env.VITE_CONVEX_URL,
  routeLoaderMap: loaders
});

app.use(convexVue);
```

```ts
const { todos } = useRouteLoader<Loaders['Home']>();
```

--------------------------------

### useConvexQuery Composable

Source: https://github.com/darialyphia/convex-vue/blob/master/packages/convex-vue/README.md

Subscribes to a Convex Query and exposes data, loading states, and error handling. Supports suspense for use within <Suspense /> boundaries.

```html
<script setup lang="ts">
  import { api } from '../convex/_generated/api';
  import { useConvexQuery } from "@convex-vue/core";

  const { data, isLoading, error, suspense } = useConvexQuery(
    api.todos.list, // the query name
    { completed: true } // query arguments, if no arguments you need to pass an empty object. It can be ref
  );

  await suspense(); // if used, must be called as a child of <Suspense/> component
</script>
```

--------------------------------

### useConvex Composable

Source: https://github.com/darialyphia/convex-vue/blob/master/packages/convex-vue/README.md

Provides direct access to the ConvexClient instance for one-off queries or custom functionality within your Vue components.

```html
<script setup lang="ts">
  import { api } from '../convex/_generated/api';
  import { useConvex } from "@convex-vue/core";

  const convex = useConvex(); // instance of `ConvexClient`
  const data = convex.query(api.todos.list, {}); // query once, no subscription
</script>
```

--------------------------------

### useConvexMutation Composable

Source: https://github.com/darialyphia/convex-vue/blob/master/packages/convex-vue/README.md

Handles Convex Mutations, supporting optimistic updates and providing callbacks for success and error scenarios. It returns loading and error states.

```javascript
import { useConvexMutation } from "@convex-vue/core";

const { isLoading, error, mutate: addTodo } = useConvexMutation(api.todos.add, {
  onSuccess() {
    todo.value = '';
  },
  onError(err) {
   console.error(err)
  },
  optimisticUpdate(ctx) {
    const current = ctx.getQuery(api.todos.list, {});
    if (!current) return;

    ctx.setQuery(api.todos.list, {}, [
      {
        _creationTime: Date.now(),
        _id: 'optimistic_id' as Id<'todos'>,
        completed: false,
        text: todo.text
      },
      ...current
    ]);
  }
});
```

--------------------------------

### useConvexPaginatedQuery Composable

Source: https://github.com/darialyphia/convex-vue/blob/master/packages/convex-vue/README.md

Subscribes to a Convex Paginated Query, managing data loading, pagination states (isDone, isLoadingMore), and providing functions to load more data or reset the query.

```html
<script setup lang="ts">
  import { api } from '../convex/_generated/api';
  import { useConvexPaginatedQuery } from "@convex-vue/core";

  const { 
    data,
    lastPage,
    isLoading,
    isLoadingMore,
    isDone,
    loadMore,
    reset,
    pages,
    error,
    suspense,
  } = useConvexPaginatedQuery(
    api.todos.list, // the query name
    { completed: true } // query arguments, if no arguments you need to pass an empty object. It can be ref,
    { numItems: 50 } // the number of items per page
  );

  await suspense(); // if used, must be called as a child of <Suspense/> component
</script>
```

--------------------------------

### useConvexAction Composable

Source: https://github.com/darialyphia/convex-vue/blob/master/packages/convex-vue/README.md

Handles Convex Actions, providing loading and error states, and callbacks for success and error handling. It allows executing server-side actions.

```javascript
import { useConvexAction } from "@convex-vue/core";

const { isLoading, error, mutate } = useConvexAction(api.some.action, {
  onSuccess(result) {
    console.log(result);
  },
  onError(err) {
    console.error(err);
  }
});
```

--------------------------------

### Add ConvexVue Plugin to Vue App

Source: https://github.com/darialyphia/convex-vue/blob/master/packages/convex-vue/README.md

Configures and adds the ConvexVue plugin to your Vue application, setting up the Convex client with your Convex URL.

```javascript
import { createConvexVue } from "@convex-vue/core";

const convexVue = createConvexVue({
  convexUrl: import.meta.env.VITE_CONVEX_URL
});

app.use(convexVue);
```

--------------------------------

### ConvexQuery Component

Source: https://github.com/darialyphia/convex-vue/blob/master/packages/convex-vue/README.md

A Vue component that simplifies using Convex queries directly in templates. It provides slots for loading, error, empty states, and the data itself.

```jsx
<ConvexQuery :query="api.todos.list" :args="{}">
  <template #loading>Loading todos...</template>

  <template #error="{ error }">{{ error }}</template>

  <template #empty>No todos yet.</template>

  <template #default="{ data: todos }">
    <ul>
      <li v-for="todo in todos" :key="todo._id">
        <Todo :todo="todo" />
      </li>
    </ul>
  </template>
</ConvexQuery>
```

--------------------------------

### Convex-Vue ConvexLink Component (JavaScript)

Source: https://github.com/darialyphia/convex-vue/blob/master/packages/convex-vue/README.md

Introduces the ConvexLink component, a wrapper around Vue Router's RouterLink. It enhances navigation by prefetching route loader data on hover, improving perceived performance for users navigating between routes.

```js
<ConvexLink :to="{ name: 'Home' }">Todos</ConvexLink>
```

--------------------------------

### ConvexPaginatedQuery Component

Source: https://github.com/darialyphia/convex-vue/blob/master/packages/convex-vue/README.md

A Vue component for displaying paginated Convex query results. It manages loading states, provides buttons to load more, and allows resetting the query.

```jsx
<ConvexPaginatedQuery
  :query="api.todos.paginatedList"
  :args="{}"
  :options="{ numItems: 5 }"
>
  <template #loading>Loading todos...</template>

  <template #error="{ error, reset }">
    <p>{{ error }}</p>
   <button @click="reset">Retry</button>
  </template>

  <template #default="{ data: todos, isDone, loadMore, isLoadingMore, reset }">
    <ul>
      <li v-for="todo in todos" :key="todo._id">
        <Todo :todo="todo" />
      </li>
    </ul>
    <Spinner v-if="isLoadingMore" />
    <footer>
      <button :disabled="isDone" @click="loadMore">Load more</button>
      <button @click="reset">Reset</button>
    </footer>
  </template>
</ConvexPaginatedQuery>
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.