Convex

https://docs.convex.dev/
Admin
Convex is a full-stack backend as a service (BaaS) that provides a real-time database, serverless...
Tokens:197,090
Snippets:1,594
Trust Score:9.9
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Create a Nuxt application

Source: https://docs.convex.dev/quickstart/nuxt

Initialize a new Nuxt project using create-nuxt. Skip installing official modules for the initial quickstart setup.

```bash
npm create nuxt@latest my-nuxt-app
```

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

### Install AuthKit TanStack Start SDK

Source: https://docs.convex.dev/auth/authkit/add-to-app

Install the @workos/authkit-tanstack-react-start package using npm.

```bash

npm install @workos/authkit-tanstack-react-start  


```

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

### Clone and run the agent example

Source: https://docs.convex.dev/agents/files

Clone the agent repository and run the development setup commands.

```bash
git clone https://github.com/get-convex/agent.git

cd agent

npm run setup

npm run dev
```

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

### Setup Script for ChatGPT Codex

Source: https://docs.convex.dev/ai/using-codex

Installs dependencies and provisions a local Convex deployment non-interactively. Requires full internet access during setup to download the Convex binary.

```bash
npm i

npx convex dev --once
```

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

### Clone and run the RAG example repository

Source: https://docs.convex.dev/agents/rag

Clone the get-convex/rag repository, change directory into it, and execute setup and example scripts.

```bash
git clone https://github.com/get-convex/rag.git

cd rag

npm run setup

npm run example
```

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

### Set up Convex for background agents using Bun

Source: https://docs.convex.dev/ai/overview

Alternative setup script to install dependencies and execute Convex in Agent Mode using Bun. Requires full internet access to download the binary.

```bash
bun i

bun x convex dev --once
```

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

### Install the Convex client library

Source: https://docs.convex.dev/quickstart/react-native

Navigates into the project directory and installs the convex package.

```shell
cd my-app && npm install convex
```

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

### Install Convex backend npm packages

Source: https://docs.convex.dev/quickstart/android

Initialize a Node.js project and install the Convex client and server library.

```shell
npm init -y

npm install convex
```

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

### Create a TanStack Start site

Source: https://docs.convex.dev/quickstart/tanstack-start

Creates a new TanStack Start project using the create-start-app command.

```bash
npx create-start-app@latest
```

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

### Start development server to trigger WorkOS onboarding

Source: https://docs.convex.dev/auth/authkit

Navigates into the newly created project directory and starts the dev server. This triggers the interactive Convex and WorkOS onboarding flow.

```bash
cd my-app  # or whatever you name the directory  

npm run dev  
```

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

### Install Convex and convex-vue

Source: https://docs.convex.dev/quickstart/vue

Navigate to the project root and install the convex backend and convex-vue client packages.

```bash
cd my-vue-app && npm install convex convex-vue
```

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

### Clone the tutorial repository and install dependencies

Source: https://docs.convex.dev/tutorial/overview

Clones the Convex tutorial project repository from GitHub, changes directory into the project folder, and installs all necessary npm packages.

```bash
git clone https://github.com/get-convex/convex-tutorial.git

cd convex-tutorial

npm install
```

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

### Start development server

Source: https://docs.convex.dev/quickstart/nuxt

Run the Nuxt application development server locally.

```bash
npm run dev
```

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

### Start New Project with Claude Code CLI

Source: https://docs.convex.dev/ai/using-claude-code

Launches Claude Code from an empty directory to scaffold a new application. Automatically runs project setup and local backend provisioning without prompting for login.

```shell
claude "build me a todo app with Convex" --permission-mode auto
```

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

### Install Convex package with Bun

Source: https://docs.convex.dev/quickstart/bun

Install the Convex client and server library in your Bun project.

```shell
bun add convex
```

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

### Install Convex and convex-svelte with bun

Source: https://docs.convex.dev/client/svelte/overview

Installs the required Convex client and Svelte integration package using bun.

```bash
bun add convex convex-svelte
```

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

### Install latest Convex plugin from Convex marketplace

Source: https://docs.convex.dev/ai/using-codex

Adds the Convex marketplace and installs the full plugin build with subagents, skills, and runtime error watching directly from Convex.

```shell
codex plugin marketplace add get-convex/convex-codex-plugin

codex plugin add convex@convex-codex-plugin
```

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

### Install Convex client and server dependencies

Source: https://docs.convex.dev/quickstart/rust

Initialize npm, install the Convex server package, and add the Convex Rust client, Tokio runtime, and dotenvy to Cargo dependencies.

```bash
npm init -y && npm install convex && cargo add convex tokio dotenvy
```

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

### Install Clerk Next.js SDK with npm

Source: https://docs.convex.dev/auth/clerk

Installs the `@clerk/nextjs` package into your Next.js application.

```shell

npm install @clerk/nextjs  

```

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

### Install Convex and convex-nuxt module

Source: https://docs.convex.dev/quickstart/nuxt

Install the convex library and add the community-maintained convex-nuxt module to the Nuxt application.

```bash
cd my-nuxt-app && npm install convex && npx nuxi module add convex-nuxt
```

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

### Install @convex-dev/eslint-plugin

Source: https://docs.convex.dev/eslint

Install the Convex ESLint plugin as a development dependency.

```bash
npm i @convex-dev/eslint-plugin --save-dev
```

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

### Install Convex and convex-svelte with npm

Source: https://docs.convex.dev/client/svelte/overview

Installs the required Convex client and Svelte integration package using npm.

```bash
npm install convex convex-svelte
```

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

### Install @convex-dev/ai-sdk-provider and ai packages

Source: https://docs.convex.dev/ai-gateway/setup

Installs the Convex AI SDK provider and the Vercel AI SDK. Requires @convex-dev/ai-sdk-provider 0.2.1 or later, convex 1.45 or later, and AI SDK 7.0.105 or later.

```bash
npm install @convex-dev/ai-sdk-provider@^0.2.1 ai
```

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

### Install AuthKit Next.js and Convex WorkOS packages

Source: https://docs.convex.dev/auth/authkit/add-to-app

Install the required WorkOS AuthKit SDK and Convex WorkOS integration packages via npm.

```bash
npm install @workos-inc/authkit-nextjs @convex-dev/workos
```

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

### Install Convex Agent Skills with npx skills

Source: https://docs.convex.dev/ai/agent-skills

Installs Convex skills into .agents/skills/ interactively or all at once using the --all flag. Installed skills are automatically detected by compatible agents such as Cursor, Claude Code, and GitHub Copilot.

```bash
# Choose which skills to install

npx skills add get-convex/agent-skills



# Or install all of them at once

npx skills add get-convex/agent-skills --all
```

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

### Install Convex client and server libraries

Source: https://docs.convex.dev/quickstart/python

Installs the Convex npm backend package along with the Convex Python client library and python-dotenv in the virtual environment.

```bash
cd my-app && npm init -y && npm install convex && venv/bin/pip install convex python-dotenv
```

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

### Initialize Convex dev deployment with npx convex dev

Source: https://docs.convex.dev/client/svelte/overview

Starts the Convex dev deployment, creates project configuration, and sets up the `src/convex/` directory.

```bash
npx convex dev
```

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

### Install Convex and convex-svelte with pnpm

Source: https://docs.convex.dev/client/svelte/overview

Installs the required Convex client and Svelte integration package using pnpm.

```bash
pnpm add convex convex-svelte
```

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

### Install Convex and dotenv packages

Source: https://docs.convex.dev/quickstart/nodejs

Installs the Convex client and server library along with dotenv for environment variable loading.

```shell
npm install convex dotenv
```

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

### Install Clerk React SDK via npm

Source: https://docs.convex.dev/auth/clerk

Installs the Clerk React package required for client-side authentication.

```bash
npm install @clerk/react  
```

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

### Start Convex dev deployment

Source: https://docs.convex.dev/quickstart/bun

Log in, create a project, save deployment URLs, and sync functions in the convex/ folder with the cloud development deployment.

```shell
bunx convex dev
```

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

### Install Convex and convex-svelte with yarn

Source: https://docs.convex.dev/client/svelte/overview

Installs the required Convex client and Svelte integration package using yarn.

```bash
yarn add convex convex-svelte
```

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

### Install Agent packages and configure Agent with convexGateway

Source: https://docs.convex.dev/ai-gateway/setup

Install the agent packages and initialize an Agent using convexGateway as its languageModel provider.

```bash
npm install @convex-dev/agent @convex-dev/ai-sdk-provider
```

```typescript
import { Agent } from "@convex-dev/agent";

import { convexGateway } from "@convex-dev/ai-sdk-provider";

import { components } from "./_generated/api";



const agent = new Agent(components.agent, {

  name: "Support agent",

  languageModel: convexGateway("openai/gpt-4o-mini"),

  instructions: "You answer questions about our product.",

});
```

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

### Install AuthKit React SDK and Convex WorkOS integration

Source: https://docs.convex.dev/auth/authkit/add-to-app

Installs the required packages @workos-inc/authkit-react and @convex-dev/workos via npm.

```bash

npm install @workos-inc/authkit-react @convex-dev/workos  


```

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

### Install the Convex CLI via npm

Source: https://docs.convex.dev/cli/overview

Install the `convex` package to use the Convex command-line interface for managing projects and functions.

```bash
npm install convex
```

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

### Install Convex AI rules and skills via CLI

Source: https://docs.convex.dev/ai/using-codex

Run this command from the root of an existing project to update AGENTS.md and install Convex Agent Skills into .agents/skills/.

```shell
npx convex ai-files install
```

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

### Install OpenAI SDK and call models via AI Gateway action

Source: https://docs.convex.dev/ai-gateway/setup

Install the openai package and configure the OpenAI client with the AI Gateway base URL and dynamic service token in a Convex action.

```bash
npm install openai
```

```typescript
import { action } from "./_generated/server";

import { v } from "convex/values";

import OpenAI from "openai";

import { getServiceToken } from "convex/server";



export const chat = action({

  args: { prompt: v.string() },

  handler: async (ctx, { prompt }) => {

    const openai = new OpenAI({

      baseURL: "https://ai-gateway.convex.dev/v1",

      apiKey: () => getServiceToken("ai-gateway"),

    });

    const completion = await openai.chat.completions.create({

      model: "openai/gpt-4o-mini",

      messages: [{ role: "user", content: prompt }],

    });

    return completion.choices[0].message.content;

  },

});
```

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

### Start asynchronous video generation with experimental_startVideo

Source: https://docs.convex.dev/ai-gateway/images-and-videos

Starts an asynchronous video generation job with Convex AI Gateway. Requires creating a job record beforehand to pass its requestId and saving the returned operation handle, inferenceId, and webhookSecret.

```typescript
import { experimental_startVideo as startVideo } from "ai";

import { convexGateway } from "@convex-dev/ai-sdk-provider";



async function startJob(requestId: string) {

  const modelId = "google/veo-3.1";

  const started = await startVideo({

    model: convexGateway.videoModel(modelId),

    prompt: "A camera pan across a mountain lake",

    duration: 8,

    webhookUrl: `${process.env.CONVEX_SITE_URL}/video-complete?requestId=${requestId}`,

    maxRetries: 0,

  });



  return {

    modelId,

    operation: started.operation,

    inferenceId: started.providerMetadata?.convexGateway?.inferenceId,

    webhookSecret: started.providerMetadata?.convexGateway?.webhookSecret,

  };

}
```

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

### Start MCP Server with Custom Project Directory

Source: https://docs.convex.dev/ai/convex-mcp-server

Use the `--project-dir` flag to specify a default project directory when launching the MCP server from outside a Convex project folder.

```bash

npx -y convex@latest mcp start --project-dir /path/to/project  

```

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

### Install Convex and React Query dependencies

Source: https://docs.convex.dev/quickstart/tanstack-start

Installs the Convex client, Convex React Query integration, TanStack React Query, and SSR router query integration packages.

```bash
npm install convex @convex-dev/react-query @tanstack/react-router-ssr-query @tanstack/react-query
```

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

### Install convex-helpers npm package

Source: https://docs.convex.dev/client/open-api

Installs the convex-helpers package which provides the CLI command to generate OpenAPI specifications.

```shell
npm install convex-helpers
```

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

### Scaffold a new Convex project manually for Conductor

Source: https://docs.convex.dev/ai/using-conductor

Initializes a new Convex project and installs the required AI files before pointing Conductor at the project directory.

```bash
npm create convex@latest my-app

cd my-app

npx convex ai-files install
```

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

### Install dependencies for legacy .eslintrc.js

Source: https://docs.convex.dev/eslint

Install both typescript-eslint and the Convex ESLint plugin when using the legacy .eslintrc.js configuration format.

```bash
npm i @typescript-eslint/eslint-plugin @convex-dev/eslint-plugin --save-dev
```

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

### Configure Start middleware in src/start.ts

Source: https://docs.convex.dev/auth/authkit/add-to-app

Add authkitMiddleware to TanStack Start request middleware to handle server-side authentication sessions.

```typescript

import { createStart } from '@tanstack/react-start';  

import { authkitMiddleware } from '@workos/authkit-tanstack-react-start';  

  

export const startInstance = createStart(() => {  

  return {  

    requestMiddleware: [authkitMiddleware()],  

  };  

});  


```

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

### Install Agent component and dependencies

Source: https://docs.convex.dev/agents/getting-started

Install the required npm packages for the Convex Agent component and Convex AI Gateway provider.

```bash
npm install @convex-dev/agent @convex-dev/ai-sdk-provider ai convex
```

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

### Start Convex MCP Server

Source: https://docs.convex.dev/ai/convex-mcp-server

Add this command to your MCP servers configuration to run the Convex MCP server with default settings.

```bash

npx -y convex@latest mcp start  

```

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

### Set up Convex for background agents using npm

Source: https://docs.convex.dev/ai/overview

Installs dependencies and runs Convex codegen and deployment in Agent Mode using npm. Requires internet access to download the binary.

```bash
npm i

# npx convex init # allows setting environment variables before pushing

# npx convex env set --from-file ./path/to/.env.agent (optional)

npx convex dev --once
```

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

### Scaffold a Convex project and launch Codex manually

Source: https://docs.convex.dev/ai/using-codex

Manually create a new Convex project, install AI rules and agent skills, and launch Codex.

```shell
npm create convex@latest my-app

cd my-app

npx convex ai-files install

codex
```

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

### Start the Expo development server

Source: https://docs.convex.dev/quickstart/react-native

Runs the local Expo development server to test the app on a mobile device.

```shell
npm start
```

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

### Query and subscribe to Convex data in main.py

Source: https://docs.convex.dev/quickstart/python

Initializes a ConvexClient using the deployment URL and queries/subscribes to the "tasks:get" API function.

```python
import os



from convex import ConvexClient

from dotenv import load_dotenv



load_dotenv(".env.local")

CONVEX_URL = os.getenv("CONVEX_URL")

# or you can hardcode your deployment URL instead

# CONVEX_URL = "https://happy-otter-123.convex.cloud"



client = ConvexClient(CONVEX_URL)



print(client.query("tasks:get"))



for tasks in client.subscribe("tasks:get"):

    print(tasks)

    # this loop lasts forever, ctrl-c to exit it
```

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

### Connect to Convex via script tag in index.html

Source: https://docs.convex.dev/quickstart/script-tag

Loads the Convex browser bundle via unpkg script tag, initializes ConvexClient with CONVEX_URL, and subscribes to real-time updates from tasks:get.

```html
<!doctype html>

<script src="https://unpkg.com/convex@1.3.1/dist/browser.bundle.js"></script>

<script>

  const CONVEX_URL = "CONVEX_URL_GOES_HERE";

  const client = new convex.ConvexClient(CONVEX_URL);

  client.onUpdate("tasks:get", {}, (tasks) =>

    console.log(tasks.map((task) => task.text)),

  );

</script>
```

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

### Launch Codex to create a new Convex project

Source: https://docs.convex.dev/ai/using-codex

Run this command from an empty directory to let Codex scaffold a Convex project, install AI files and skills, and auto-provision a local backend.

```shell
codex "build me a todo app with Convex"
```

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

### Install Convex plugin for Claude Code

Source: https://docs.convex.dev/ai/convex-plugins

Installs the official Convex plugin in Claude Code via the built-in plugin manager command.

```bash
/plugin install convex@claude-plugins-official
```

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

### Generate Go client with openapi-generator-cli

Source: https://docs.convex.dev/client/open-api

Installs openapi-generator-cli and creates a type-safe Go client package inside the convex_client directory using convex-spec.yaml.

```shell
npm i openapi-generator-cli

npx openapi-generator-cli generate -i convex-spec.yaml -g go -o convex_client
```

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

### Create a new Bun project

Source: https://docs.convex.dev/quickstart/bun

Create a new directory and initialize a Bun project.

```shell
mkdir my-project && cd my-project && bun init -y
```

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

### Query Convex backend from src/main.rs

Source: https://docs.convex.dev/quickstart/rust

Connect to Convex using `ConvexClient` with the deployment URL from the environment and query the `tasks:get` API.

```rust
use std::{

    collections::BTreeMap,

    env,

};



use convex::ConvexClient;



#[tokio::main]

async fn main() {

    dotenvy::from_filename(".env.local").ok();

    dotenvy::dotenv().ok();



    let deployment_url = env::var("CONVEX_URL").unwrap();



    let mut client = ConvexClient::new(&deployment_url).await.unwrap();

    let result = client.query("tasks:get", BTreeMap::new()).await.unwrap();

    println!("{result:#?}");

}
```

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

### Example generated convex-spec.yaml structure

Source: https://docs.convex.dev/client/open-api

Illustrates the structure of the OpenAPI 3.0.3 specification file generated by convex-helpers.

```yaml
# convex-spec.yaml

openapi: 3.0.3

info:

  title: Convex App - OpenAPI 3.0

  version: 0.0.0

  servers:

    - url: "{hostUrl}"

  description: Convex App API

  ...
```

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

### Add AuthKit OAuth callback route in src/routes/callback.tsx

Source: https://docs.convex.dev/auth/authkit/add-to-app

Configure the server GET handler using handleCallbackRoute() to process OAuth redirect callbacks from WorkOS in TanStack Start.

```typescript

import { createFileRoute } from '@tanstack/react-router';  

import { handleCallbackRoute } from '@workos/authkit-tanstack-react-start';  
  

export const Route = createFileRoute('/callback')({  

  server: {  

    handlers: {  

      GET: handleCallbackRoute(),  

    },  

  },  

});  

```

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

### Run Agent Playground locally

Source: https://docs.convex.dev/agents/playground

Starts the local playground UI using npx. Uses the VITE_CONVEX_URL environment variable, usually pulled automatically from .env.local.

```bash
npx @convex-dev/agent-playground
```

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

### Start MCP server with CONVEX_DEPLOY_KEY

Source: https://docs.convex.dev/ai/convex-mcp-server

Restricts the MCP server to access only a specific deployment using a deploy key instead of global authentication. Note that the insights tool is unavailable when starting the server with a deploy key.

```bash
CONVEX_DEPLOY_KEY="dev:happy-capybara-849|…=" npx -y convex@latest mcp start
```

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

### Install Convex plugin for Codex

Source: https://docs.convex.dev/ai/convex-plugins

Adds the curated Convex plugin from the Codex built-in plugin directory.

```bash
codex plugin add convex@openai-curated
```

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

### GET /v1/models

Source: https://docs.convex.dev/ai-gateway/overview

Lists the available AI models supported by the Convex AI Gateway.

```APIDOC
## GET /v1/models

### Description
List available models.

### Method
GET

### Endpoint
/v1/models
```

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

### get url

Source: https://docs.convex.dev/api/classes/browser.ConvexHttpClient

Returns the address for this client. The returned URL is useful for creating a new client and may be canonicalized.

```APIDOC
### get url(): string

Return the address for this client, useful for creating a new client. Not guaranteed to match the address with which this client was constructed: it may be canonicalized.

#### Returns
- `string`: The client address.
```

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

### Install Convex plugin manually for Cursor

Source: https://docs.convex.dev/ai/convex-plugins

Clones the Convex agent plugins repository into the Cursor plugins directory. Cursor must be restarted after cloning.

```bash
cd ~/.cursor/plugins  

git clone https://github.com/get-convex/convex-agent-plugins convex  

# then restart Cursor
```

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

### Wire up convexVue in src/main.ts

Source: https://docs.convex.dev/quickstart/vue

Install the convexVue plugin onto the Vue application instance using the VITE_CONVEX_URL environment variable.

```typescript
import { convexVue } from 'convex-vue'

import { createApp } from 'vue'

import App from './App.vue'



const app = createApp(App)



app.use(convexVue, {

  url: import.meta.env.VITE_CONVEX_URL,

})



app.mount('#app')
```

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

### Configure CLI for Local Development with AI Gateway

Source: https://docs.convex.dev/ai-gateway/setup

Log in and select the local deployment before starting convex dev. Local development requires Convex 1.46 or later and a project linked to a team with AI Gateway access.

```bash
npx convex login

npx convex deployment select local

npx convex dev
```

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

### Run files:generateImage:replyWithImage via Convex CLI

Source: https://docs.convex.dev/agents/files

Runs the example function that generates an image using OpenAI's DALL-E 2 based on a prompt and saves the result to a thread.

```bash
npx convex run files:generateImage:replyWithImage '{prompt: "make a picture of a cat" }'
```

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

### Create a new npm project

Source: https://docs.convex.dev/quickstart/nodejs

Initializes a new directory and sets up package.json with ES module support.

```shell
mkdir my-project && cd my-project && npm init -y && npm pkg set type="module"
```

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

### Invoke convex-auth skill manually

Source: https://docs.convex.dev/ai/agent-skills

Kicks off Convex auth setup in AI developer tools like Cursor or Claude Code.

```text
/convex-auth
```

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

### Create a SvelteKit app using sv CLI

Source: https://docs.convex.dev/quickstart/svelte

Initializes a new SvelteKit application using the sv command-line tool.

```shell
npx sv@latest create my-app
```

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

### Create a new npm project

Source: https://docs.convex.dev/quickstart/script-tag

Create a new directory and initialize a basic npm project package.json.

```bash
mkdir my-project && cd my-project && npm init -y
```

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

### Create Tasks composable UI component

Source: https://docs.convex.dev/quickstart/android

Subscribe to the tasks:get Convex query and display tasks using a Jetpack Compose LazyColumn.

```kotlin
@Composable

fun Tasks(modifier: Modifier = Modifier) {

    val tasks: Result<List<Task>> by client.subscribe<List<Task>>("tasks:get")

        .collectAsState(Result.success(listOf()))

    LazyColumn(

        modifier = modifier

    ) {

        items(tasks.getOrElse { emptyList() }) { task ->

            Text(text = "Text: ${task.text}, Completed?: ${task.isCompleted}")

        }

    }

}
```

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

### Create a Remix site

Source: https://docs.convex.dev/quickstart/remix

Initialize a new Remix project using create-remix.

```bash
npx create-remix@latest my-remix-app
```

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

### Initialize ConvexReactClient and wrap application with ConvexProvider

Source: https://docs.convex.dev/client/react/overview

Create an instance of `ConvexReactClient` with your backend deployment URL and pass it to `ConvexProvider` wrapping the root component tree.

```javascript
import { ConvexProvider, ConvexReactClient } from "convex/react";



const convex = new ConvexReactClient("https://<your domain here>.convex.cloud");
```

```jsx
reactDOMRoot.render(

  <React.StrictMode>

    <ConvexProvider client={convex}>

      <App />

    </ConvexProvider>

  </React.StrictMode>,

);
```

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

### Add sign-up redirect route with getSignUpUrl in src/routes/sign-up.tsx

Source: https://docs.convex.dev/auth/authkit/add-to-app

Create a dedicated server GET handler that generates the WorkOS sign-up URL with getSignUpUrl() and returns a 307 redirect response.

```typescript

import { createFileRoute } from '@tanstack/react-router';  

import { getSignUpUrl } from '@workos/authkit-tanstack-react-start';  
  

export const Route = createFileRoute('/sign-up')({  

  server: {  

    handlers: {  

      GET: async ({ request }: { request: Request }) => {  

        const returnPathname = new URL(request.url).searchParams.get('returnPathname');  

        const url = await getSignUpUrl(returnPathname ? { data: { returnPathname } } : undefined);  

        return new Response(null, {  

          status: 307,  

          headers: { Location: url },  

        });  

      },  

    },  

  },  

});  

```

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

### getFunctionName(functionReference)

Source: https://docs.convex.dev/api/modules/server

Get the name of a function from a FunctionReference. Returns a string representing the function's identifier, omitting the name if exported as default.

```APIDOC
### getFunctionName(functionReference)

Get the name of a function from a `FunctionReference`.

The name is a string formatted like `"myDir/myModule:myFunction"`. If the exported name of the function is `"default"`, the function name is omitted (e.g. `"myDir/myModule"`).

#### Parameters
- **functionReference** (`FunctionReference<any, any, any, any, undefined | string> | FunctionReference_future<any, any, any, any, undefined | string>`) - Required - A FunctionReference to get the name of.

#### Returns
- `string`: A string of the function's name.
```

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

### Instantiate ConvexClient and render Tasks in MainActivity

Source: https://docs.convex.dev/quickstart/android

Initialize ConvexClient with the deployment URL and set up the Activity content to display the Tasks composable.

```kotlin
val client: ConvexClient by lazy { ConvexClient($YOUR_CONVEX_URL) }



class MainActivity : ComponentActivity() {

  override fun onCreate(savedInstanceState: Bundle?) {

      super.onCreate(savedInstanceState)

      enableEdgeToEdge()

      setContent {

          ConvexQuickstartTheme {

              Scaffold(modifier = Modifier.fillMaxSize()) {

                  Tasks(

                      modifier = Modifier.padding(innerPadding)

                  )

              }

          }

      }

  }

}
```

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

### Deploy with a build command using --cmd

Source: https://docs.convex.dev/cli/overview

Executes a command during deployment with the CONVEX_URL environment variable made available to it.

```shell
npx convex deploy --cmd "npm run build"
```

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

### experimental_startVideo(options)

Source: https://docs.convex.dev/ai-gateway/images-and-videos

Initiates an asynchronous video generation request through the Convex AI Gateway and returns an operation identifier and job metadata.

```APIDOC
### Function
`experimental_startVideo(options: StartVideoOptions): Promise<StartVideoResult>`

### Description
Starts an asynchronous video generation task. Used when actions should return before video generation completes.

### Parameters
- **model** (`VideoModel`) - Required. The configured video model instance, e.g. `convexGateway.videoModel(modelId)`.
- **prompt** (`string`) - Required. Text prompt describing the video to generate.
- **duration** (`number`) - Optional. Duration of the generated video in seconds.
- **webhookUrl** (`string`) - Optional. HTTPS callback URL (`<deployment>.convex.site`) to receive completion notifications.
- **maxRetries** (`number`) - Optional. Number of submission retries (e.g., `0` to prevent automatic duplicate paid jobs).

### Return Value
Returns a promise resolving to an object containing:
- **operation** (`string`) - The operation handle to check status or download the result.
- **providerMetadata.convexGateway.inferenceId** (`string`) - Unique inference ID associated with the job.
- **providerMetadata.convexGateway.webhookSecret** (`string`) - Secret key used to verify incoming webhook callbacks.
```

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

### Run a function on preview deployment with --preview-run

Source: https://docs.convex.dev/cli/overview

Executes a specified Convex function immediately following the creation of a preview deployment.

```shell
npx convex deploy --preview-run myFunction
```

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

### Create a new Cargo project

Source: https://docs.convex.dev/quickstart/rust

Initialize a new Cargo project and navigate into the project directory.

```bash
cargo new my_app

cd my_app
```

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

### Initialize ConvexClient with setupConvex in root layout

Source: https://docs.convex.dev/client/svelte/overview

Calls `setupConvex` in the root layout to initialize the client and make it accessible across child components via Svelte context.

```svelte
<script lang="ts">

  import { setupConvex } from "convex-svelte";

  import { PUBLIC_CONVEX_URL } from "$env/static/public";



  const client = setupConvex(PUBLIC_CONVEX_URL);

</script>
```

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

### Set up Convex in src/routes/+layout.svelte

Source: https://docs.convex.dev/quickstart/svelte

Initializes setupConvex with PUBLIC_CONVEX_URL at the root layout to make Convex available across the entire app.

```svelte
<script lang="ts">

	import { PUBLIC_CONVEX_URL } from '$env/static/public';

	import { setupConvex } from 'convex-svelte';



	const { children } = $props();

	setupConvex(PUBLIC_CONVEX_URL);

</script>



{@render children()}
```

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

### Create a ConvexClient instance

Source: https://docs.convex.dev/client/android/overview

Instantiate ConvexClient with your deployment URL to establish and maintain a connection to the Convex backend.

```kotlin
package com.example.convexapp



import dev.convex.android.ConvexClient



val convex = ConvexClient("https://<your domain here>.convex.cloud")
```

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

### Create a new Convex project with AuthKit

Source: https://docs.convex.dev/auth/authkit

Scaffolds a new Convex project. When prompted by the CLI, select your desired framework and choose AuthKit as the authentication option.

```bash
npm create convex@latest  
```

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

### Run the Python script

Source: https://docs.convex.dev/quickstart/python

Executes main.py to fetch and display the serialized list of tasks from Convex.

```bash
venv/bin/python -m main
```

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

### Select Android Studio wizard options

Source: https://docs.convex.dev/quickstart/android

Configuration choices to use when creating a new Android project in Android Studio.

```text
1. Choose the "Empty Activity" template

2. Name it "Convex Quickstart"

3. Choose min SDK as 26

4. Choose Kotlin as the Gradle DSL
```

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

### GET /v1/models

Source: https://docs.convex.dev/ai-gateway/api

Retrieves the list of available AI models supported by the gateway. Requires Bearer token authentication.

```APIDOC
## GET /v1/models

### Description
Retrieves a list of available models.

### Method
GET

### Endpoint
`/v1/models`

### Parameters
No query parameters or request body required.

### Response
#### Success Response (200)
- **object** (string) - Object type, typically `list`
- **data** (array) - List of model objects
  - **id** (string) - Model identifier (`provider/model` format)
  - **object** (string) - Object type (`model`)
  - **created** (integer) - Unix timestamp for creation
  - **owned_by** (string) - Provider prefix of the model ID

#### Response Example
```json
{
  "object": "list",
  "data": [
    {
      "id": "openai/gpt-4o-mini",
      "object": "model",
      "created": 1715620800,
      "owned_by": "openai"
    }
  ]
}
```
```

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

### GET /v1/models Response

Source: https://docs.convex.dev/ai-gateway/api

JSON response listing available models. The owned_by property corresponds to the provider prefix of id.

```json
{

  "object": "list",

  "data": [

    {

      "id": "openai/gpt-4o-mini",

      "object": "model",

      "created": 1715620800,

      "owned_by": "openai"

    }

  ]

}
```

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

### new ConvexClient(address, options?)

Source: https://docs.convex.dev/api/classes/browser.ConvexClient

Constructs a ConvexClient instance and immediately initiates a WebSocket connection to the specified deployment address.

```APIDOC
## Constructor: new ConvexClient(address, options?)

### Description
Construct a client and immediately initiate a WebSocket connection to the passed address.

### Parameters
- **address** (`string`) - The deployment address (e.g. `https://happy-otter-123.convex.cloud`).
- **options** (`ConvexClientOptions`) - Optional configuration options.

### Example
```javascript
const client = new ConvexClient("https://happy-otter-123.convex.cloud");
```
```

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

### Deploy Configuration to Development Environment

Source: https://docs.convex.dev/auth/authkit/add-to-app

Deploys the configuration and provisions or connects a Convex-managed WorkOS environment.

```bash

npx convex dev


```

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

### agent.deleteMessageRange(ctx, args)

Source: https://docs.convex.dev/agents/messages

Deletes a range of messages in a thread based on order and optional stepOrder (start is inclusive, end is exclusive).

```APIDOC
## agent.deleteMessageRange(ctx, args)

### Description
Deletes messages matching a range defined by `order` and `stepOrder`. The range start is inclusive and the end is exclusive.

### Parameters
- **ctx** (`object`) - Convex context object.
- **args** (`object`) - Method arguments.
  - **threadId** (`string` | `Id`) - Required. The identifier of the thread.
  - **startOrder** (`number`) - Required. Inclusive start order.
  - **endOrder** (`number`) - Required. Exclusive end order.
  - **startStepOrder** (`number`) - Optional. Inclusive starting step order.
  - **endStepOrder** (`number`) - Optional. Exclusive ending step order.

### Usage Examples
```typescript
// Delete all messages with the same order as a given message
await agent.deleteMessageRange(ctx, {
  threadId,
  startOrder: message.order,
  endOrder: message.order + 1,
});

// Delete all messages with order 1 or 2
await agent.deleteMessageRange(ctx, {
  threadId,
  startOrder: 1,
  endOrder: 3,
});

// Delete all messages with order 1 and stepOrder 2-4
await agent.deleteMessageRange(ctx, {
  threadId,
  startOrder: 1,
  startStepOrder: 2,
  endOrder: 2,
  endStepOrder: 5,
});
```
```

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

### useConvexConnectionState

Source: https://docs.convex.dev/api/modules/react

React hook to get the current ConnectionState with the Convex backend and automatically subscribe to changes such as network status or request activity.

```APIDOC
## useConvexConnectionState

### Signature
`useConvexConnectionState(): ConnectionState`

### Description
React hook to get the current ConnectionState and subscribe to changes. This hook returns the current connection state and automatically rerenders when any part of the connection state changes (e.g., when going online/offline, when requests start/complete, etc.).

Throws an error if not used under `ConvexProvider`.

### Parameters
None.

### Returns
- `ConnectionState` - The current ConnectionState with the Convex backend.
```

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

### Subscribe to Convex query in SwiftUI ContentView

Source: https://docs.convex.dev/quickstart/swift

Subscribe to `tasks:get` to listen for real-time updates and display todo items in a SwiftUI `List`.

```swift
struct ContentView: View {

  @State private var todos: [Todo] = []



  var body: some View {

    List {

      ForEach(todos, id: \._id) {
 todo in

        Text(todo.text)

      }

    }.task {

      for await todos: [Todo] in convex.subscribe(to: "tasks:get")

        .replaceError(with: []).values

      {

        self.todos = todos

      }

    }.padding()

  }

}
```

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

### Configure and initialize ConvexClient with build-type deployment URLs

Source: https://docs.convex.dev/client/android/overview

Sets different Convex deployment URLs for release and debug builds in build.gradle.kts using resValue and initializes ConvexClient with the generated resource.

```kotlin
// In the android section of build.gradle.kts:

buildTypes {

    release {

        // Snip various other config like ProGuard ...

        resValue("string", "convex_url", "YOUR_PROD.convex.cloud")

    }



    debug {

        resValue("string", "convex_url", "YOUR_DEV.convex.cloud")

    }

}
```

```kotlin
val convex = ConvexClient(context.getString(R.string.convex_url))
```

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

### Open Convex docs with npx convex docs

Source: https://docs.convex.dev/cli/overview

Opens the Convex documentation in your browser.

```shell
npx convex docs
```

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

### Create a Vue project

Source: https://docs.convex.dev/quickstart/vue

Scaffold a new Vue application with TypeScript enabled using create-vue.

```bash
npm create vue@latest my-vue-app
```

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

### Initialize ConvexClient and Router in src/router.tsx

Source: https://docs.convex.dev/quickstart/tanstack-start

Sets up ConvexQueryClient, connects it to QueryClient, and wraps the TanStack router tree in ConvexProvider.

```tsx
import { createRouter } from "@tanstack/react-router";

import { QueryClient } from "@tanstack/react-query";

import { setupRouterSsrQueryIntegration } from "@tanstack/react-router-ssr-query";

import { ConvexQueryClient } from "@convex-dev/react-query";

import { ConvexProvider } from "convex/react";

import { routeTree } from "./routeTree.gen";



export function getRouter() {

  const CONVEX_URL = (import.meta as any).env.VITE_CONVEX_URL!;

  if (!CONVEX_URL) {

    console.error("missing envar VITE_CONVEX_URL");

  }

  const convexQueryClient = new ConvexQueryClient(CONVEX_URL);



  const queryClient: QueryClient = new QueryClient({

    defaultOptions: {

      queries: {

        queryKeyHashFn: convexQueryClient.hashFn(),

        queryFn: convexQueryClient.queryFn(),

      },

    },

  });

  convexQueryClient.connect(queryClient);



  const router = createRouter({

    routeTree,

    defaultPreload: "intent",

    context: { queryClient },

    scrollRestoration: true,

    Wrap: ({ children }) => (

      <ConvexProvider client={convexQueryClient.convexClient}>

        {children}

      </ConvexProvider>

    ),

  });

  setupRouterSsrQueryIntegration({ router, queryClient });



  return router;

}
```

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

### Initialize ConvexClient in ContentView.swift

Source: https://docs.convex.dev/quickstart/swift

Import ConvexMobile and initialize `ConvexClient` with your deployment URL above the `ContentView` struct.

```swift
import SwiftUI

import ConvexMobile



let convex = ConvexClient(deploymentUrl: "YOUR_CONVEX_URL")



struct ContentView: View {

...
```

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

### List messages in a thread with listMessages

Source: https://docs.convex.dev/agents/threads

Retrieves paginated messages from a thread with options such as excluding tool messages. Setting the cursor to null starts from the beginning.

```typescript
import { listMessages } from "@convex-dev/agent";



const messages = await listMessages(ctx, components.agent, {

  threadId,

  excludeToolMessages: true,

  paginationOpts: { cursor: null, numItems: 10 }, // null means start from the beginning

});
```

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

### Deploy Convex application and sync configuration

Source: https://docs.convex.dev/auth/authkit

Run npx convex dev to automatically sync deployment configuration changes to the backend.

```bash
npx convex dev  
```

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

### Create OAuth callback route handler in app/callback/route.ts

Source: https://docs.convex.dev/auth/authkit/add-to-app

Defines the GET route handler using handleAuth to process WorkOS OAuth callback flows.

```typescript

import { handleAuth } from '@workos-inc/authkit-nextjs';  

  

export const GET = handleAuth();  

```

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

### Get stored file URL with ctx.storage.getUrl

Source: https://docs.convex.dev/api/interfaces/server.StorageReader

Fetches a URL for a file in Convex storage by its storage ID. Returns null if the file no longer exists.

```typescript

const url = await ctx.storage.getUrl(storageId);  

```

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

### Create a React Native app with Expo

Source: https://docs.convex.dev/quickstart/react-native

Initializes a new React Native project using create-expo-app.

```shell
npx create-expo-app my-app
```

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

### Enforce User Authentication in a Mutation with getAuthUserId

Source: https://docs.convex.dev/auth/overview

Checks if a user is logged in at the start of a public function. Ensures that only the authenticated user can perform mutations on their own user record.

```typescript
export const removeUserImage = mutation({

  args: {},

  handler: async (ctx) => {

    const userId = await getAuthUserId(ctx);

    if (!userId) {

      return;

    }

    ctx.db.patch("users", userId, { imageId: undefined, image: undefined });

  },

});
```

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

### Run the Rust application

Source: https://docs.convex.dev/quickstart/rust

Execute the Rust app to fetch and display the serialized list of tasks from Convex.

```bash
cargo run
```

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

### POST /alpha/decisions response format

Source: https://docs.convex.dev/ai-gateway/api

Example response containing evaluated answers corresponding to request question keys, including confidence, probabilities, and token usage.

```json
{

  "id": "3f1c8a2e-9b14-4d6a-a7e2-0c5b8d1e4f90",

  "model": "typesafe/jev-1.13",

  "answers": {

    "priority": {

      "type": "choice",

      "choice": "urgent",

      "confidence": 0.9,

      "probabilities": { "urgent": 0.9, "normal": 0.1 }

    }

  },

  "usage": {

    "input_tokens": 21,

    "output_tokens": 3,

    "cost": 0.0042

  }

}
```

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

### Example Convex document structures

Source: https://docs.convex.dev/database/overview

Illustrates valid Convex documents representing JavaScript/JSON objects, including empty objects, flat key-value pairs, and nested objects.

```json
{}

{"name": "Jamie"}

{"name": {"first": "Ari", "second": "Cole"}, "age": 60}
```

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

### Smooth text conditionally with startStreaming based on message status

Source: https://docs.convex.dev/agents/streaming

Pass startStreaming: true when a message's status is streaming to immediately start text smoothing for streaming messages.

```typescript
import { useSmoothText, type UIMessage } from "@convex-dev/agent/react";



function Message({ message }: { message: UIMessage }) {

  const [visibleText] = useSmoothText(message.text, {

    startStreaming: message.status === "streaming",

  });

  return <div>{visibleText}</div>;

}
```

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

### Block rendering in TanStack Start route loader with staleTime static

Source: https://docs.convex.dev/client/tanstack/tanstack-start

Blocks rendering until data is available in the route loader. Requires @tanstack/react-query v5.102.0 or later and pairs with useSuspenseQuery in the component.

```typescript
export const Route = createFileRoute('/posts')({

  loader: async (opts) => {

    await opts.context.queryClient.query({

      ...convexQuery(api.messages.list, {}),

      staleTime: "static",

    });

  },

  component: () => {

    const { data } = useSuspenseQuery(convexQuery(api.messages.list, {}));

    return (

      <div>

        {data.map((message) => (

          <Message key={message._id} post={message} />

        ))}

      </div>

    );

  },

})
```

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

### Create sample data file sampleData.jsonl

Source: https://docs.convex.dev/quickstart/bun

Define sample JSONL records for the tasks table.

```jsonl
{"text": "Buy groceries", "isCompleted": true}

{"text": "Go for a swim", "isCompleted": true}

{"text": "Integrate Convex", "isCompleted": false}
```

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

### Add sign-in redirect route with getSignInUrl in src/routes/sign-in.tsx

Source: https://docs.convex.dev/auth/authkit/add-to-app

Create a dedicated server GET handler that obtains the WorkOS sign-in URL via getSignInUrl() and redirects the client with a 307 status.

```typescript

import { createFileRoute } from '@tanstack/react-router';  

import { getSignInUrl } from '@workos/authkit-tanstack-react-start';  
  

export const Route = createFileRoute('/sign-in')({  

  server: {  

    handlers: {  

      GET: async ({ request }: { request: Request }) => {  

        const returnPathname = new URL(request.url).searchParams.get('returnPathname');  

        const url = await getSignInUrl(returnPathname ? { data: { returnPathname } } : undefined);  

        return new Response(null, {  

          status: 307,  

          headers: { Location: url },  

        });  

      },  

    },  

  },  

});  

```

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

### Configure Clerk production publishable key in .env

Source: https://docs.convex.dev/auth/clerk

Set the Next.js environment variable with your Clerk production Publishable Key, formatted as `pk_live_...`.

```env

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="pk_live_..."  

```

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

### Configure AI files and agent targets in convex.json

Source: https://docs.convex.dev/ai/overview

Sets AI file preferences and customizes target coding agents for skills installation in convex.json. By default, skills target claude-code and codex.

```json
{

  "aiFiles": {

    "enabled": false,

    "skills": {

      "agents": ["claude-code", "codex", "cursor"]

    }

  }

}
```

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

### envList

Source: https://docs.convex.dev/ai/convex-mcp-server

Lists all environment variables configured for a Convex deployment.

```APIDOC
## envList

### Description
Lists all environment variables for a deployment.
```

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

### Create a Python virtual environment

Source: https://docs.convex.dev/quickstart/python

Creates a virtual environment folder for the Python application.

```bash
python3 -m venv my-app/venv
```

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

### Create a React app with Vite

Source: https://docs.convex.dev/quickstart/react

Scaffold a new TypeScript React application using Vite.

```bash
npm create vite@latest my-app -- --template react-ts
```
Tokens:
Raw