Nuxt Convex

https://nuxt-convex.onmax.me
Admin
Nuxt Convex is a complete integration that brings Convex's reactive backend with real-time sync,...
Tokens:16,295
Snippets:140
Trust Score:2.1
Update:9 months ago
Show doc for...
Tokens:
Raw
### Import Nuxt Convex Composables and API

Source: https://nuxt-convex.onmax.me/getting-started/installation

Demonstrates how to import core Convex composables and the generated API types using Nuxt's virtual modules. This is essential for interacting with your Convex backend from Vue components.

```typescript
import { useConvexQuery } from '#convex'
import { api } from '#convex/api'

```

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

### Install Nuxt Convex with Yarn

Source: https://nuxt-convex.onmax.me/getting-started/installation

Installs the nuxt-convex, convex, and @convex-vue/core packages using Yarn. This is an alternative package manager command for setting up Nuxt Convex.

```bash
yarn add nuxt-convex convex @convex-vue/core
```

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

### Install Nuxt Convex with NPM

Source: https://nuxt-convex.onmax.me/getting-started/installation

Installs the nuxt-convex, convex, and @convex-vue/core packages using NPM. This command ensures all necessary packages are added to your project's dependencies.

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

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

### Install Nuxt Convex with PNPM

Source: https://nuxt-convex.onmax.me/getting-started/installation

Installs the nuxt-convex, convex, and @convex-vue/core packages using PNPM. These are the core dependencies for integrating Convex with a Nuxt.js project.

```bash
pnpm add nuxt-convex convex @convex-vue/core
```

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

### Install Better Auth Module

Source: https://nuxt-convex.onmax.me/integrations/better-auth

Installs the nuxt-better-auth module using pnpm. This is the first step to integrating Better Auth with your Nuxt Convex project.

```bash
pnpm add @onmax/nuxt-better-auth
```

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

### File Upload Progress Bar Example (Nuxt Convex)

Source: https://nuxt-convex.onmax.me/file-storage/use-convex-upload

An example showcasing how to integrate `useConvexUpload` with a visual progress bar. It utilizes the `progress` ref returned by the composable to dynamically update the width of a styled div, providing visual feedback during the upload process.

```vue
<script setup lang="ts">
import { api } from '#convex/api'

const { generateUploadUrl } = useConvexStorage(api)

const { upload, isUploading, progress } = useConvexUpload({
  generateUploadUrl,
  onSuccess: (storageId) => {
    console.log('File uploaded:', storageId)
  },
})
</script>

<template>
  <div>
    <input type="file" :disabled="isUploading" @change="e => upload(e.target.files[0])">

    <div v-if="isUploading" class="w-full bg-gray-200 rounded">
      <div
        class="bg-blue-500 h-2 rounded transition-all"
        :style="{ width: `${progress}%` }"
      />
    </div>
  </div>
</template>

```

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

### Install Dependencies for Convex Auth Database

Source: https://nuxt-convex.onmax.me/integrations/better-auth

Installs additional dependencies required to use Convex as the backend database for Better Auth. This enables storing authentication data directly within Convex.

```bash
pnpm add @convex-dev/better-auth better-auth --save-exact
```

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

### Configure Nuxt Convex Module

Source: https://nuxt-convex.onmax.me/getting-started/installation

Adds the 'nuxt-convex' module to the Nuxt configuration file (nuxt.config.ts). It also shows how to optionally enable Convex file storage by setting `storage: true` within the `convex` configuration object.

```typescript
export default defineNuxtConfig({
  modules: ['nuxt-convex'],
  convex: {
    storage: true, // Enable file storage (optional)
  },
})
```

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

### Getting File URLs

Source: https://nuxt-convex.onmax.me/file-storage/use-convex-storage

Demonstrates how to use the `getUrl` function from `useConvexStorage` to obtain a reactive URL for a stored file. This is useful for displaying images or other file types in your application.

```APIDOC
## Getting File URLs

### Description
Use the `getUrl` function to get a reactive URL for a stored file. The returned ref updates automatically.

### Usage Example
```vue
<script setup lang="ts">
import { api } from '#convex/api'

const props = defineProps({
  storageId: String
})

const { getUrl } = useConvexStorage(api)
const url = getUrl(props.storageId)
</script>

<template>
  <img v-if="url" :src="url" alt="Uploaded file">
  <p v-else>
    Loading...
  </p>
</template>
```

### Parameters
#### Path Parameters
- **storageId** (string) - Required - The unique identifier for the file stored in Convex.

### Return Values
#### Success Response (200)
- **url** (Ref<string | null>) - A reactive reference to the file's URL. It will be `null` initially or if the file is not found, and will update when the URL is available.
```

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

### Sequential Multiple File Upload (Nuxt Convex)

Source: https://nuxt-convex.onmax.me/file-storage/use-convex-upload

Demonstrates how to upload multiple files sequentially using `useConvexUpload`. The example iterates through a list of files selected by the user, uploading each one and storing its `storageId` in a reactive array.

```vue
<script setup lang="ts">
import { api } from '#convex/api'

const { generateUploadUrl } = useConvexStorage(api)
const { upload, isUploading, progress } = useConvexUpload({ generateUploadUrl })

const uploadedFiles = ref<string[]>([])

async function handleFiles(event: Event) {
  const files = (event.target as HTMLInputElement).files
  if (!files)
    return

  for (const file of files) {
    const storageId = await upload(file)
    if (storageId)
      uploadedFiles.value.push(storageId)
  }
}
</script>

```

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

### Image Preview Before Upload (Nuxt Convex)

Source: https://nuxt-convex.onmax.me/file-storage/use-convex-upload

An example for implementing image previews before uploading using `useConvexUpload`. It utilizes `URL.createObjectURL` to generate a temporary URL for the selected image, displaying it in an `<img>` tag before the user confirms the upload.

```vue
<script setup lang="ts">
import { api } from '#convex/api'

const { generateUploadUrl } = useConvexStorage(api)
const { upload, isUploading } = useConvexUpload({ generateUploadUrl })

const preview = ref<string | null>(null)

function handleFileSelect(event: Event) {
  const file = (event.target as HTMLInputElement).files?.[0]
  if (file && file.type.startsWith('image/')) {
    preview.value = URL.createObjectURL(file)
  }
}

async function handleUpload(event: Event) {
  const file = (event.target as HTMLInputElement).files?.[0]
  if (file) {
    await upload(file)
  }
}
</script>

<template>
  <div>
    <img v-if="preview" :src="preview" class="max-w-xs">
    <input type="file" accept="image/*" @change="handleFileSelect">
    <button :disabled="isUploading" @click="handleUpload">
      Upload
    </button>
  </div>
</template>

```

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

### Use Convex Storage Operations (Vue)

Source: https://nuxt-convex.onmax.me/file-storage/use-convex-storage

Demonstrates the basic usage of `useConvexStorage` to get a reactive file URL, generate an upload URL, and delete a file. Requires the Convex API object.

```vue
<script setup lang="ts">
import { api } from '#convex/api'

const { generateUploadUrl, getUrl, remove } = useConvexStorage(api)

// Get a reactive URL for a stored file
const fileUrl = getUrl('storage_id_here')

// Generate upload URL for direct upload
const uploadUrl = await generateUploadUrl.mutate()

// Delete a file
await remove.mutate({ storageId: 'storage_id_here' })
</script>
```

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

### Execute Convex Mutation to Create Document (Vue.js)

Source: https://nuxt-convex.onmax.me/composables/use-convex-mutation

Shows how to use useConvexMutation to create a new document and then navigate to its page. This example highlights the return value of the mutation, which is the ID of the newly created document. It depends on the Convex API and Vue.js routing.

```vue
<script setup lang="ts">
import { api } from '#convex/api'

const { mutate: createDoc } = useConvexMutation(api.documents.create)

async function handleCreate() {
  const docId = await createDoc({ title: 'New Document' })
  navigateTo(`/docs/${docId}`)
}
</script>

```

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

### Handle Errors with useConvexMutation (Vue.js)

Source: https://nuxt-convex.onmax.me/composables/use-convex-mutation

Illustrates error handling when using useConvexMutation, showing both try/catch blocks and direct error ref usage. This example demonstrates how to catch and log errors during mutation execution, and display them to the user. It requires the Convex API and Vue.js.

```vue
<script setup lang="ts">
import { api } from '#convex/api'

const { mutate: deleteTask, error } = useConvexMutation(api.tasks.remove)

async function handleDelete(id: string) {
  try {
    await deleteTask({ id })
  }
  catch (e) {
    console.error('Delete failed:', e)
  }
}
</script>

<template>
  <div>
    <button @click="handleDelete(taskId)">
      Delete
    </button>
    <p v-if="error" class="text-red-500">
      {{ error.message }}
    </p>
  </div>
</template>

```

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

### Server Auth Configuration with Better Auth

Source: https://nuxt-convex.onmax.me/integrations/better-auth

Defines a server authentication configuration for Better Auth, enabling email and password authentication. This is a basic setup for handling user credentials.

```typescript
import { defineServerAuth } from '@onmax/nuxt-better-auth/config'

export default defineServerAuth(() => ({
  emailAndPassword: { enabled: true },
}))
```

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

### Direct Upload with useConvexStorage (Vue)

Source: https://nuxt-convex.onmax.me/file-storage/use-convex-storage

Illustrates how to use `generateUploadUrl` from `useConvexStorage` to get a URL for direct browser uploads to Convex storage. It then performs a POST request to upload the file.

```vue
<script setup lang="ts">
import { api } from '#convex/api'

const { generateUploadUrl } = useConvexStorage(api)

async function uploadFile(file: File) {
  // Get upload URL
  const uploadUrl = await generateUploadUrl.mutate()

  // Upload directly to Convex
  const response = await fetch(uploadUrl, {
    method: 'POST',
    headers: { 'Content-Type': file.type },
    body: file,
  })

  const { storageId } = await response.json()
  return storageId
}
</script>
```

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

### Action Calling External API and Convex Mutation (TypeScript)

Source: https://nuxt-convex.onmax.me/backend/actions

This example shows a Convex action written in TypeScript that first processes text using an external API and then saves the result to the database by calling a Convex mutation. It uses `ctx.runMutation` to interact with the database indirectly. Actions are suitable for long-running operations and side effects.

```typescript
import { v } from 'convex/values'
import { api } from './_generated/api'
import { action } from './_generated/server'

export const processAndSave = action({
  args: { text: v.string(), userId: v.string() },
  handler: async (ctx, { text, userId }) => {
    // Call external API
    const processed = await processText(text)

    // Save result using a mutation
    await ctx.runMutation(api.tasks.add, {
      title: processed,
      userId,
    })

    return processed
  },
})

```

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

### useConvexStorage Composable

Source: https://nuxt-convex.onmax.me/file-storage/use-convex-storage

The `useConvexStorage` composable provides functions for managing files in Convex storage. It requires the Convex API object as an argument and returns functions for generating upload URLs, getting file URLs, and removing files.

```APIDOC
## useConvexStorage Composable

### Description
Provides low-level access to Convex storage operations. It is auto-imported when storage is enabled in your Nuxt Convex project.

### Parameters
#### Path Parameters
- **api** (API) - Required - The Convex API object from `#convex/api`.

### Return Values
#### Success Response (200)
- **generateUploadUrl** ({ mutate: () => Promise<string> }) - Returns an object with a `mutate` function to generate a pre-signed URL for uploading files directly to Convex storage.
- **getUrl** ((storageId: string) => Ref<string | null>) - Returns a reactive ref containing the URL of the file associated with the given `storageId`. The ref updates automatically if the file URL changes.
- **remove** ({ mutate: (args) => Promise<void> }) - Returns an object with a `mutate` function that accepts a `storageId` argument to delete a file from Convex storage.
```

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

### Execute Convex Mutation to Add Task (Vue.js)

Source: https://nuxt-convex.onmax.me/composables/use-convex-mutation

Demonstrates how to use useConvexMutation to add a new task. It includes input binding, submission handling, and displaying loading and error states. This composable requires the Convex API and a Vue.js setup.

```vue
<script setup lang="ts">
import { api } from '#convex/api'

const { mutate: addTask, isLoading, error } = useConvexMutation(api.tasks.add)

const title = ref('')

async function handleSubmit() {
  await addTask({ title: title.value, userId: 'user_123' })
  title.value = ''
}
</script>

<template>
  <form @submit.prevent="handleSubmit">
    <input v-model="title" :disabled="isLoading" placeholder="New task...">
    <button :disabled="isLoading">
      Add
    </button>
    <p v-if="error">
      {{ error.message }}
    </p>
  </form>
</template>

```

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

### Get File URL with useConvexStorage (Vue)

Source: https://nuxt-convex.onmax.me/file-storage/use-convex-storage

Shows how to use the `getUrl` function from `useConvexStorage` to obtain a reactive URL for a stored file, suitable for displaying images. It updates automatically when the file URL changes.

```vue
<script setup lang="ts">
import { api } from '#convex/api'

const props = defineProps({
  storageId: String
})

const { getUrl } = useConvexStorage(api)
const url = getUrl(props.storageId)
</script>

<template>
  <img v-if="url" :src="url" alt="Uploaded file">
  <p v-else>
    Loading...
  </p>
</template>
```

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

### Access Raw Convex Client with useConvex (Vue/Nuxt)

Source: https://nuxt-convex.onmax.me/composables/use-convex

Demonstrates how to use the useConvex composable to get the raw Convex client instance within a Vue/Nuxt component. This allows for direct execution of queries, mutations, and actions, suitable for advanced patterns or one-off data fetching without reactive subscriptions. It requires importing the Convex API.

```typescript
<script setup lang="ts">
import { api } from '#convex/api'

const client = useConvex()

// Direct client access for advanced patterns
const result = await client.query(api.tasks.get, { id: 'abc123' })
</script>

```

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

### Enable Convex Storage in Nuxt Config

Source: https://nuxt-convex.onmax.me/file-storage/setup

Configure Nuxt Convex to enable built-in file storage by adding the `storage: true` option to the `convex` property in `nuxt.config.ts`. This action auto-scaffolds essential storage functions.

```typescript
export default defineNuxtConfig({
  modules: ['nuxt-convex'],
  convex: {
    storage: true,
  },
})
```

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

### Define Uploads Table Schema for Convex

Source: https://nuxt-convex.onmax.me/file-storage/setup

Define the `uploads` table in `convex/schema.ts` to store file metadata, including `storageId`, `name`, `type`, `url`, `userId`, and `createdAt`. It also sets up an index for efficient querying by `userId`.

```typescript
import { defineSchema, defineTable } from 'convex/server'
import { v } from 'convex/values'

export default defineSchema({
  uploads: defineTable({
    storageId: v.id('_storage'),
    name: v.string(),
    type: v.string(),
    url: v.optional(v.string()),
    userId: v.string(),
    createdAt: v.number(),
  }).index('by_user', ['userId'])
})
```

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

### Use Convex Query in Nuxt Vue Component

Source: https://nuxt-convex.onmax.me/backend/queries

This Vue.js script setup uses the `useConvexQuery` composable to fetch tasks from the Convex backend. It calls the `api.tasks.list` query with a `userId` and receives the data reactively. The template displays the task titles if the data is not currently loading.

```vue
<script setup lang="ts">
import { api } from '#convex/api'

const { data: tasks, isLoading } = useConvexQuery(api.tasks.list, { userId: 'user_123' })
</script>

<template>
  <ul v-if="!isLoading">
    <li v-for="task in tasks" :key="task._id">
      {{ task.title }}
    </li>
  </ul>
</template>
```

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

### Static Site Generation with Nuxt Convex

Source: https://nuxt-convex.onmax.me/composables/use-convex-query

This command demonstrates how to perform static site generation (SSG) with Nuxt Convex. When using `nuxi generate`, Convex data is fetched at build time and embedded into the static HTML, ensuring fast load times for statically generated pages.

```bash
nuxi generate

```

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

### Custom Subscription with useConvex (TypeScript)

Source: https://nuxt-convex.onmax.me/composables/use-convex

Shows how to create a custom composable, `useCustomSubscription`, using the raw Convex client obtained from `useConvex`. This pattern manually handles subscriptions to query updates and manages the unsubscribe logic on component unmount. It's an alternative for complex subscription needs.

```typescript
export function useCustomSubscription() {
  const client = useConvex()
  const data = ref(null)

  let unsubscribe: (() => void) | null = null

  function subscribe(query: any, args: any) {
    unsubscribe = client.onUpdate(query, args, (result) => {
      data.value = result
    })
  }

  onUnmounted(() => {
    unsubscribe?.()
  })

  return { data, subscribe }
}

```

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

### Basic File Upload with Progress Tracking (Nuxt Convex)

Source: https://nuxt-convex.onmax.me/file-storage/use-convex-upload

Demonstrates the high-level `useConvexUpload` composable for handling file uploads in Nuxt Convex. It includes progress tracking and success/error callbacks. This composable requires `generateUploadUrl` from `useConvexStorage` and can optionally trigger a mutation on success.

```vue
<script setup lang="ts">
import { api } from '#convex/api'

const { generateUploadUrl } = useConvexStorage(api)
const saveFile = useConvexMutation(api._hub.storage.saveFile)

const { upload, isUploading, progress, error } = useConvexUpload({
  generateUploadUrl,
  onSuccess: async (storageId, file) => {
    await saveFile.mutate({
      storageId,
      name: file.name,
      type: file.type,
      userId: 'user_123',
    })
  },
  onError: err => console.error('Upload failed:', err),
})

async function handleFileChange(event: Event) {
  const file = (event.target as HTMLInputElement).files?.[0]
  if (file) {
    const storageId = await upload(file)
    console.log('Uploaded:', storageId)
  }
}
</script>

<template>
  <div>
    <input type="file" :disabled="isUploading" @change="handleFileChange">
    <p v-if="isUploading">
      Uploading... {{ progress }}%
    </p>
    <p v-if="error">
      {{ error.message }}
    </p>
  </div>
</template>

```

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

### Import Core Composables and API

Source: https://nuxt-convex.onmax.me/api/configuration

Import core Convex composables and the generated API types from virtual modules provided by the Nuxt Convex module. These imports allow you to interact with your Convex backend.

```typescript
import { useConvexMutation, useConvexQuery } from '#convex'
import { api } from '#convex/api'
```

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

### Using Better Auth User ID with Convex Queries

Source: https://nuxt-convex.onmax.me/integrations/better-auth

Demonstrates how to pass the user ID obtained from Better Auth to Convex queries. This ensures that Convex queries are executed in the context of the currently logged-in user.

```vue
<script setup lang="ts">
import { api } from '#convex/api'

const { user } = useAuth()
const { data: tasks } = useConvexQuery(
  api.tasks.list,
  computed(() => user.value ? { userId: user.value.id } : undefined)
)
</script>
```

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

### Query Builder Methods

Source: https://nuxt-convex.onmax.me/backend/queries

Overview of the methods available on the Convex database query builder for filtering, sorting, and collecting results.

```APIDOC
## Database Query Builder Methods

### Description
The Convex database query builder provides a fluent API for constructing read-only queries against your database tables.

### Methods

- **`.query('table_name')`**
  - Description: Starts a new query targeting the specified table.
  - Example: `ctx.db.query('tasks')`

- **`.withIndex('index_name', (q) => ...)`**
  - Description: Filters the query results using a pre-defined database index. The second argument is a function that receives the index query builder and should return the conditions for the index.
  - Example: `.withIndex('by_user', q => q.eq('userId', userId))`

- **`.filter((q) => ...)`**
  - Description: Filters the query results using a JavaScript predicate function that is applied to each document.
  - Example: `.filter(q => q.field('status') === 'completed')`

- **`.order('asc' | 'desc')`**
  - Description: Sorts the query results in ascending or descending order. Requires an index to be specified first.
  - Example: `.order('desc')`

- **`.collect()`**
  - Description: Executes the query and returns all matching documents as an array.
  - Example: `.collect()`

- **`.first()`**
  - Description: Executes the query and returns the first matching document, or null if no documents match.
  - Example: `.first()`

- **`.take(n)`**
  - Description: Executes the query and returns the first `n` matching documents as an array.
  - Example: `.take(10)`
```

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

### Direct Upload

Source: https://nuxt-convex.onmax.me/file-storage/use-convex-storage

Shows how to use the `generateUploadUrl` function for direct browser uploads to Convex storage. This method involves first obtaining an upload URL and then performing a POST request to that URL with the file content.

```APIDOC
## Direct Upload

### Description
Use `generateUploadUrl` to get a pre-signed URL for uploading files directly from the browser to Convex storage.

### Usage Example
```vue
<script setup lang="ts">
import { api } from '#convex/api'

const { generateUploadUrl } = useConvexStorage(api)

async function uploadFile(file: File) {
  // Get upload URL
  const uploadUrl = await generateUploadUrl.mutate()

  // Upload directly to Convex
  const response = await fetch(uploadUrl, {
    method: 'POST',
    headers: { 'Content-Type': file.type },
    body: file,
  })

  const { storageId } = await response.json()
  return storageId
}
</script>
```

### Return Values
#### Success Response (200)
- **uploadUrl** (string) - A pre-signed URL for uploading the file.

### Request Body Example
- **file** (File) - The file object to be uploaded.

### Response Example
```json
{
  "storageId": "your_generated_storage_id"
}
```
```

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

### Configure Convex App with Better Auth

Source: https://nuxt-convex.onmax.me/integrations/better-auth

Configures the Convex application to use the Better Auth plugin. This integrates Better Auth's functionality directly into your Convex backend.

```typescript
import betterAuth from '@convex-dev/better-auth/convex.config'
import { defineApp } from 'convex/server'

const app = defineApp()
app.use(betterAuth)
export default app
```

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

### Execute Convex Actions with useConvexAction in Nuxt.js

Source: https://nuxt-convex.onmax.me/composables/use-convex-action

Demonstrates how to use the useConvexAction composable to call a Convex AI summarize action from a Nuxt.js component. It handles loading states and errors, and displays the summarized result. Dependencies: Nuxt.js, Convex.js.

```vue
<script setup lang="ts">
import { api } from '#convex/api'

const { execute: summarize, isLoading, error } = useConvexAction(api.ai.summarize)

const result = ref('')

async function handleSummarize(text: string) {
  result.value = await summarize({ text })
}
</script>

<template>
  <div>
    <button :disabled="isLoading" @click="handleSummarize('Some text to summarize')">
      {{ isLoading ? 'Processing...' : 'Summarize' }}
    </button>
    <p v-if="result">
      {{ result }}
    </p>
    <p v-if="error">
      {{ error.message }}
    </p>
  </div>
</template>

```

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

### Process Payments using useConvexAction in Nuxt.js

Source: https://nuxt-convex.onmax.me/composables/use-convex-action

Illustrates using the useConvexAction composable to initiate a payment process via a Convex action. It navigates to a confirmation page upon successful payment. Dependencies: Nuxt.js, Convex.js.

```vue
<script setup lang="ts">
import { api } from '#convex/api'

const { execute: processPayment, isLoading } = useConvexAction(api.payments.process)

async function handleCheckout(amount: number) {
  const result = await processPayment({ amount, currency: 'usd' })
  if (result.success) {
    navigateTo('/order-confirmation')
  }
}
</script>

```

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

### Configure Nuxt Modules for Better Auth

Source: https://nuxt-convex.onmax.me/integrations/better-auth

Adds both the 'nuxt-convex' and '@onmax/nuxt-better-auth' modules to your Nuxt configuration. This enables both Convex for data and Better Auth for authentication.

```typescript
export default defineNuxtConfig({
  modules: ['nuxt-convex', '@onmax/nuxt-better-auth'],
  convex: { storage: true },
})
```

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

### Basic Query: List Tasks

Source: https://nuxt-convex.onmax.me/backend/queries

Defines a server-side query function to retrieve a list of tasks for a given user, sorted in descending order.

```APIDOC
## POST /convex/tasks.ts (list query)

### Description
This endpoint defines a reactive query to fetch a list of tasks from the 'tasks' table, filtered by a userId and ordered by creation time.

### Method
GET (implicitly via query definition)

### Endpoint
`api.tasks.list` (Client-side invocation)

### Parameters
#### Query Parameters
- **userId** (string) - Required - The ID of the user whose tasks are to be fetched.

### Request Example
```typescript
// In a Nuxt component:
import { api } from '#convex/api'
const { data: tasks, isLoading } = useConvexQuery(api.tasks.list, { userId: 'user_123' })
```

### Response
#### Success Response (200)
- **tasks** (Array<Object>) - A list of task objects. Each task object contains at least `_id` and `title`.

#### Response Example
```json
{
  "_id": "task_abc123",
  "title": "Buy groceries",
  "userId": "user_123",
  "status": "pending"
}
```
```

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

### Create Basic Action to Call External API (TypeScript)

Source: https://nuxt-convex.onmax.me/backend/actions

This code snippet demonstrates how to create a basic Convex action in TypeScript that calls an external API. It takes a text input and sends it to an OpenAI API endpoint, returning the JSON response. This action cannot directly access the database.

```typescript
import { v } from 'convex/values'
import { action } from './_generated/server'

export const summarize = action({
  args: { text: v.string() },
  handler: async (ctx, { text }) => {
    const response = await fetch('https://api.openai.com/v1/...', {
      method: 'POST',
      headers: { Authorization: `Bearer ${process.env.OPENAI_API_KEY}` },
      body: JSON.stringify({ prompt: text }),
    })
    return await response.json()
  },
})

```

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

### Subscribe to Convex Query with SSR (Default) - Nuxt Vue

Source: https://nuxt-convex.onmax.me/composables/use-convex-query

This snippet demonstrates how to subscribe to a Convex query with Server-Side Rendering (SSR) enabled by default. Data is fetched on the server for SEO and then subscribes for real-time updates on the client. It handles loading and error states.

```vue
<script setup lang="ts">
import { api } from '#convex/api'

// SSR + real-time (default)
const { data: tasks, pending, error } = await useConvexQuery(api.tasks.list, { userId: 'user_123' })
</script>

<template>
  <div v-if="pending">
    Loading...
  </div>
  <div v-else-if="error">
    Error: {{ error.message }}
  </div>
  <ul v-else>
    <li v-for="task in tasks" :key="task._id">
      {{ task.title }}
    </li>
  </ul>
</template>

```

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

### Server Auth Config Using Convex as Database

Source: https://nuxt-convex.onmax.me/integrations/better-auth

Updates the server authentication configuration to use Convex as the database adapter for Better Auth. This stores users, sessions, and accounts in Convex, with email and password authentication enabled.

```typescript
import { components } from '#convex/api'
import { createClient } from '@convex-dev/better-auth'
import { convex } from '@convex-dev/better-auth/server/plugins'
import { defineServerAuth } from '@onmax/nuxt-better-auth/config'

const authComponent = createClient(components.betterAuth)

export default defineServerAuth(() => ({
  database: authComponent.adapter(),
  plugins: [convex()],
  emailAndPassword: { enabled: true },
}))
```

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

### Reactive Arguments for Convex Query - Nuxt Vue

Source: https://nuxt-convex.onmax.me/composables/use-convex-query

This snippet illustrates how to use reactive arguments with useConvexQuery. When the reactive argument (e.g., a ref or computed property) changes, the Convex query automatically re-subscribes with the new arguments. This is useful for dynamic filtering or user-specific data.

```vue
<script setup lang="ts">
import { api } from '#convex/api'

const userId = ref('user_123') // auto-imported
const { data: tasks } = await useConvexQuery(
  api.tasks.list,
  computed(() => ({ userId: userId.value }))
)

function switchUser(newUserId: string) {
  userId.value = newUserId // Query re-subscribes automatically
}
</script>

```

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

### One-off Query with useConvex (Vue/Nuxt)

Source: https://nuxt-convex.onmax.me/composables/use-convex

Illustrates performing a single query using the useConvex composable without setting up a reactive subscription. This is useful for fetching data that doesn't need to update in real-time, such as generating a report. The result is stored in a ref.

```typescript
<script setup lang="ts">
import { api } from '#convex/api'

const client = useConvex()
const report = ref(null)

async function generateReport() {
  // Single fetch, no subscription
  report.value = await client.query(api.reports.generate, { month: 'december' })
}
</script>

```

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

### Delete File with useConvexStorage (Vue)

Source: https://nuxt-convex.onmax.me/file-storage/use-convex-storage

Demonstrates how to use the `remove` function from `useConvexStorage` to delete a file from Convex storage by providing its `storageId`.

```vue
<script setup lang="ts">
import { api } from '#convex/api'

const { remove } = useConvexStorage(api)

async function deleteFile(storageId: string) {
  await remove.mutate({ storageId })
}
</script>
```

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

### useConvexAction - Execute Convex Actions

Source: https://nuxt-convex.onmax.me/composables/use-convex-action

The `useConvexAction` composable allows you to execute Convex actions from your Nuxt application. This is useful for making external API calls, performing long-running tasks, or any server-side logic that doesn't involve direct database mutations.

```APIDOC
## POST /convex/action

### Description
Executes a specified Convex action on the server.

### Method
POST

### Endpoint
`/convex/action` (This is a conceptual endpoint. The actual execution is handled by the Nuxt Convex integration.)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **action** (`FunctionReference`) - Required - A reference to the Convex action function to be executed.
- **args** (`object`) - Optional - The arguments to be passed to the Convex action.

### Request Example
```json
{
  "action": "api.ai.summarize",
  "args": {"text": "Some text to summarize"}
}
```

### Response
#### Success Response (200)
- **result** (`any`) - The result returned by the Convex action.

#### Response Example
```json
{
  "result": "Summarized text output"
}
```

#### Error Response (400 or 500)
- **error** (`Error`) - An error object if the action execution fails.

#### Error Response Example
```json
{
  "error": {"message": "Action failed: ..."}
}
```
```

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

### Configure Nuxt Convex Module

Source: https://nuxt-convex.onmax.me/api/configuration

Configure the Nuxt Convex module in your `nuxt.config.ts` file. This includes setting the Convex deployment URL and optionally enabling file storage integration.

```typescript
export default defineNuxtConfig({
  modules: ['nuxt-convex'],
  convex: {
    url: 'https://your-deployment.convex.cloud',
    storage: true,
  },
})
```

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

### Action Sending Email via External API (TypeScript)

Source: https://nuxt-convex.onmax.me/backend/actions

This Convex action in TypeScript is configured to send emails using an external service like SendGrid. It accesses environment variables like `SENDGRID_API_KEY` via `process.env` to authenticate with the API. Environment variables should be configured in the Convex dashboard.

```typescript
export const sendEmail = action({
  args: { to: v.string(), subject: v.string(), body: v.string() },
  handler: async (ctx, { to, subject, body }) => {
    await fetch('https://api.sendgrid.com/v3/mail/send', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.SENDGRID_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ to, subject, body }),
    })
  },
})

```

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

### Deleting Files

Source: https://nuxt-convex.onmax.me/file-storage/use-convex-storage

Illustrates how to remove files from Convex storage using the `remove` function provided by `useConvexStorage`. This function requires the `storageId` of the file to be deleted.

```APIDOC
## Deleting Files

### Description
Use the `remove` function to delete a file from Convex storage.

### Usage Example
```vue
<script setup lang="ts">
import { api } from '#convex/api'

const { remove } = useConvexStorage(api)

async function deleteFile(storageId: string) {
  await remove.mutate({ storageId })
}
</script>
```

### Parameters
#### Path Parameters
- **storageId** (string) - Required - The unique identifier of the file to be deleted.

### Method
`POST` (for the underlying `mutate` operation)

### Return Values
#### Success Response (200)
- **(void)** - Indicates successful deletion.
```

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

### Define Basic Convex Query in TypeScript

Source: https://nuxt-convex.onmax.me/backend/queries

This TypeScript code defines a basic reactive query in Convex. It accepts a `userId` argument and fetches tasks associated with that user from the 'tasks' table using the 'by_user' index, ordered in descending order. It returns all matching documents.

```typescript
import { v } from 'convex/values'
import { query } from './_generated/server'

export const list = query({
  args: { userId: v.string() },
  handler: async (ctx, { userId }) => {
    return await ctx.db
      .query('tasks')
      .withIndex('by_user', q => q.eq('userId', userId))
      .order('desc')
      .collect()
  },
})
```

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

### Define Convex Payment Processing Action (Server-side)

Source: https://nuxt-convex.onmax.me/composables/use-convex-action

Backend definition of a Convex action named 'process' that handles payment processing. It integrates with an external Stripe API and then records the transaction details in the database using a mutation. Dependencies: Convex.js, Stripe API.

```typescript
import { v } from 'convex/values'
import { api } from './_generated/api'
import { action } from './_generated/server'

export const process = action({
  args: { amount: v.number(), currency: v.string() },
  handler: async (ctx, { amount, currency }) => {
    // Call external payment API
    const result = await stripe.charges.create({ amount, currency })

    // Save result to database
    await ctx.runMutation(api.orders.create, {
      chargeId: result.id,
      amount,
      status: result.status,
    })

    return { success: result.status === 'succeeded' }
  },
})

```

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

### Calling Convex Action from Vue Component (Vue/TypeScript)

Source: https://nuxt-convex.onmax.me/backend/actions

This Vue.js component snippet demonstrates how to call a Convex action using the `useConvexAction` composable. It defines a button that triggers the `summarize` action and displays the result or any errors. This is how client-side applications interact with backend logic.

```vue
<script setup lang="ts">
import { api } from '#convex/api'

const { execute: summarize, isLoading, error } = useConvexAction(api.ai.summarize)
const result = ref('')

async function handleSummarize(text: string) {
  result.value = await summarize({ text })
}
</script>

<template>
  <div>
    <button :disabled="isLoading" @click="handleSummarize('Some text')">
      Summarize
    </button>
    <p v-if="result">
      {{ result }}
    </p>
    <p v-if="error">
      {{ error.message }}
    </p>
  </div>
</template>

```

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

### Mutations API

Source: https://nuxt-convex.onmax.me/backend/mutations

This section details the various mutations available in Convex for interacting with your database. These mutations are transactional and run on the server.

```APIDOC
## Mutations API

Mutations are used to write data to your Convex database. They are transactional and run on the server.

### Creating Documents

Use `ctx.db.insert()` to create new documents.

#### Endpoint

`POST /mutations/tasks/add` (example endpoint, actual endpoint determined by Convex configuration)

#### Method

`POST`

#### Parameters

##### Request Body
- **title** (string) - Required - The title of the task.
- **userId** (string) - Required - The ID of the user associated with the task.

##### Response

- **_id** (ID) - The unique identifier of the newly created document.

#### Request Example

```json
{
  "title": "Buy groceries",
  "userId": "user_123"
}
```

#### Success Response (200)

- **_id** (ID) - The ID of the created task.

#### Response Example

```json
{
  "_id": "task_abc123"
}
```

### Updating Documents

#### Using `ctx.db.patch()`

Use `ctx.db.patch()` to update specific fields of a document.

##### Endpoint

`POST /mutations/tasks/toggle` (example endpoint)

##### Method

`POST`

##### Parameters

*   **Path Parameters**
    *   None

*   **Query Parameters**
    *   None

*   **Request Body**
    *   **id** (ID) - Required - The ID of the task to toggle completion status.

##### Request Example

```json
{
  "id": "task_abc123"
}
```

##### Success Response (200)

*   No explicit response body is defined for this operation, success is indicated by the absence of errors.

#### Using `ctx.db.replace()`

Use `ctx.db.replace()` to replace the entire document.

##### Endpoint

`POST /mutations/tasks/update` (example endpoint)

##### Method

`POST`

##### Parameters

*   **Path Parameters**
    *   None

*   **Query Parameters**
    *   None

*   **Request Body**
    *   **id** (ID) - Required - The ID of the task to update.
    *   **title** (string) - Required - The new title of the task.
    *   **isCompleted** (boolean) - Required - The new completion status of the task.

##### Request Example

```json
{
  "id": "task_abc123",
  "title": "Buy organic groceries",
  "isCompleted": false
}
```

##### Success Response (200)

*   No explicit response body is defined for this operation, success is indicated by the absence of errors.

### Deleting Documents

Use `ctx.db.delete()` to remove documents.

#### Endpoint

`POST /mutations/tasks/remove` (example endpoint)

#### Method

`POST`

#### Parameters

##### Request Body
- **id** (ID) - Required - The ID of the task to delete.

#### Request Example

```json
{
  "id": "task_abc123"
}
```

#### Success Response (200)

*   No explicit response body is defined for this operation, success is indicated by the absence of errors.

### Transactions

Mutations are transactional. All database operations within a mutation either succeed together or fail together. All operations in a mutation are atomic. If any operation fails, all changes roll back automatically.

#### Example: `completeAll` Mutation

This mutation completes all tasks for a given user.

##### Endpoint

`POST /mutations/tasks/completeAll` (example endpoint)

##### Method

`POST`

##### Parameters

*   **Path Parameters**
    *   None

*   **Query Parameters**
    *   None

*   **Request Body**
    *   **userId** (string) - Required - The ID of the user whose tasks should be completed.

##### Request Example

```json
{
  "userId": "user_123"
}
```

##### Success Response (200)

*   No explicit response body is defined for this operation, success is indicated by the absence of errors.

### Using Mutations in Components

Mutations can be called from Vue components using the `useConvexMutation` hook.

#### Example: `AddTask.vue` Component

This component demonstrates how to use the `addTask` mutation.

```vue
<script setup lang="ts">
import { api } from '#convex/api'

const { mutate: addTask, isLoading } = useConvexMutation(api.tasks.add)
const title = ref('')

async function handleSubmit() {
  await addTask({ title: title.value, userId: 'user_123' })
  title.value = ''
}
</script>

<template>
  <form @submit.prevent="handleSubmit">
    <input v-model="title" :disabled="isLoading" placeholder="New task...">
    <button :disabled="isLoading">
      Add
    </button>
  </form>
</template>
```

See `useConvexMutation` for full documentation.
```

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

### TypeScript Document and ID Types

Source: https://nuxt-convex.onmax.me/api/configuration

Reference generated TypeScript types for your Convex documents and IDs. This ensures type safety when working with data from your Convex backend, such as task documents and their corresponding IDs.

```typescript
import type { Doc, Id } from '#convex/api'

// Document type
type Task = Doc<'tasks'>

// ID type
type TaskId = Id<'tasks'>
```

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

### Create Document with Convex Mutation

Source: https://nuxt-convex.onmax.me/backend/mutations

This TypeScript mutation adds a new task document to the 'tasks' table in the Convex database. It takes a title and userId as arguments and returns the ID of the newly created document. It ensures tasks have a title, userId, completion status, and creation timestamp.

```typescript
import { v } from 'convex/values'
import { mutation } from './_generated/server'

export const add = mutation({
  args: { title: v.string(), userId: v.string() },
  handler: async (ctx, { title, userId }) => {
    return await ctx.db.insert('tasks', {
      title,
      userId,
      isCompleted: false,
      createdAt: Date.now(),
    })
  },
})

```

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

### Define Messages Table Schema with Multiple Indexes in Convex

Source: https://nuxt-convex.onmax.me/backend/schema

Defines the 'messages' table schema in Convex, including fields for channelId, authorId, content, and createdAt. It features two indexes: 'by_channel' on 'channelId' and 'by_author' on 'authorId' to optimize queries by channel and author respectively.

```typescript
export default defineSchema({
  messages: defineTable({
    channelId: v.id('channels'),
    authorId: v.id('users'),
    content: v.string(),
    createdAt: v.number(),
  })
    .index('by_channel', ['channelId'])
    .index('by_author', ['authorId'])
})
```

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

### Define Tasks Table Schema in Convex

Source: https://nuxt-convex.onmax.me/backend/schema

Defines the 'tasks' table schema in Convex with fields for title, userId, isCompleted, and createdAt. It also includes an index 'by_user' on the 'userId' field for efficient querying by user.

```typescript
import { defineSchema, defineTable } from 'convex/server'
import { v } from 'convex/values'

export default defineSchema({
  tasks: defineTable({
    title: v.string(),
    userId: v.optional(v.string()),
    isCompleted: v.boolean(),
    createdAt: v.number(),
  }).index('by_user', ['userId'])
})
```

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

### Convex Mutation for Transactional Updates

Source: https://nuxt-convex.onmax.me/backend/mutations

This TypeScript mutation demonstrates transactional database operations in Convex by completing all tasks for a given user. It first queries all tasks for the specified `userId` using an index and then iterates through them, updating each task's `isCompleted` status to true using `ctx.db.patch`. All operations within this mutation are atomic and will succeed or fail together.

```typescript
export const completeAll = mutation({
  args: { userId: v.string() },
  handler: async (ctx, { userId }) => {
    const tasks = await ctx.db
      .query('tasks')
      .withIndex('by_user', q => q.eq('userId', userId))
      .collect()

    for (const task of tasks) {
      await ctx.db.patch(task._id, { isCompleted: true })
    }
  },
})

```
Tokens:
Raw