Convex 快速入门指南：5分钟搭建全栈应用，支持React/Next.js/Vue/Svelte

convex-quickstart by get-convex/agent-skills

6,400 周安装量

15 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/get-convex/agent-skills --skill convex-quickstart

开发云服务

🇨🇳中文介绍

Convex 快速入门

以最快速度搭建一个可运行的 Convex 项目。

使用场景

使用 Convex 启动一个全新的项目
将 Convex 添加到现有的 React、Next.js、Vue、Svelte 或其他应用中
为原型设计搭建一个 Convex 应用

不适用场景

项目已安装 Convex 且 convex/ 目录已存在 - 直接开始构建即可
您只需要为现有的 Convex 应用添加身份验证 - 请使用 convex-setup-auth 技能

工作流程

确定起点：新项目还是现有应用
如果是新项目，选择一个模板并使用 npm create convex@latest 搭建
如果是现有应用，安装 convex 并配置 Provider
运行 npx convex dev 以连接部署并启动开发循环
验证设置是否正常工作

路径一：新项目（推荐）

使用官方的脚手架工具。它会创建一个包含前端框架、Convex 后端以及所有配置都已连接好的完整项目。

选择模板

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

路径二：将 Convex 添加到现有应用

当用户已有一个前端项目并希望添加 Convex 作为后端时使用此方法。

npm install convex

初始化并启动开发循环

请用户在终端中运行 npx convex dev。这会处理登录、创建 convex/ 目录、将部署 URL 写入 .env.local 并启动文件监听器。关于为什么代理不应直接运行此命令的说明，请参见路径一中的注释。

Convex 客户端必须在根目录包装应用。具体设置因框架而异。

在模块作用域创建 ConvexReactClient，不要在组件内部创建：

// 错误：每次渲染都会重新创建客户端
function App() {
  const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL as string);
  return <ConvexProvider client={convex}>...</ConvexProvider>;
}

// 正确：在模块作用域创建一次
const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL as string);
function App() {
  return <ConvexProvider client={convex}>...</ConvexProvider>;
}

// src/main.tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { ConvexProvider, ConvexReactClient } from "convex/react";
import App from "./App";

const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL as string);

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <ConvexProvider client={convex}>
      <App />
    </ConvexProvider>
  </StrictMode>,
);

Next.js (App Router)

// app/ConvexClientProvider.tsx
"use client";

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

const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL!);

export function ConvexClientProvider({ children }: { children: ReactNode }) {
  return <ConvexProvider client={convex}>{children}</ConvexProvider>;
}

// app/layout.tsx
import { ConvexClientProvider } from "./ConvexClientProvider";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <ConvexClientProvider>{children}</ConvexClientProvider>
      </body>
    </html>
  );
}

对于 Vue、Svelte、React Native、TanStack Start、Remix 等，请遵循相应的快速入门指南：

环境变量名称取决于框架：

框架	变量
Vite	`VITE_CONVEX_URL`
Next.js	`NEXT_PUBLIC_CONVEX_URL`
Remix	`CONVEX_URL`
React Native	`EXPO_PUBLIC_CONVEX_URL`

npx convex dev 会自动将正确的变量写入 .env.local。

代理模式（云端和无头代理）

在无法进行交互式浏览器登录的云端或无头代理环境中运行时，设置 CONVEX_AGENT_MODE=anonymous 以使用本地匿名部署。

将 CONVEX_AGENT_MODE=anonymous 添加到 .env.local，或内联设置：

CONVEX_AGENT_MODE=anonymous npx convex dev

这会在虚拟机上运行一个本地 Convex 后端，无需身份验证，并避免与用户的个人开发部署冲突。

设置完成后，确认一切正常：

用户确认 npx convex dev 正在运行且无错误
convex/_generated/ 目录存在且包含 api.ts 和 server.ts
.env.local 包含部署 URL

编写您的第一个函数

项目设置完成后，创建一个模式和一个查询来验证整个循环是否正常工作。

import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export default defineSchema({
  tasks: defineTable({
    text: v.string(),
    completed: v.boolean(),
  }),
});

import { query, mutation } from "./_generated/server";
import { v } from "convex/values";

export const list = query({
  args: {},
  handler: async (ctx) => {
    return await ctx.db.query("tasks").collect();
  },
});

export const create = mutation({
  args: { text: v.string() },
  handler: async (ctx, args) => {
    await ctx.db.insert("tasks", { text: args.text, completed: false });
  },
});

在 React 组件中使用（根据您的文件相对于 convex/ 的位置调整导入路径）：

import { useQuery, useMutation } from "convex/react";
import { api } from "../convex/_generated/api";

function Tasks() {
  const tasks = useQuery(api.tasks.list);
  const create = useMutation(api.tasks.create);

  return (
    <div>
      <button onClick={() => create({ text: "New task" })}>添加</button>
      {tasks?.map((t) => <div key={t._id}>{t.text}</div>)}
    </div>
  );
}

在开发过程中始终使用 npx convex dev。它针对您的个人开发部署运行，并在保存时同步代码。

准备发布时，部署到生产环境：

这将推送到生产部署，该部署与开发部署是分开的。在开发过程中不要使用 deploy。

添加身份验证：使用 convex-setup-auth 技能
设计您的模式：参见模式文档
构建组件：使用 convex-create-component 技能
规划迁移：使用 convex-migration-helper 技能
添加文件存储：参见文件存储文档
设置定时任务：参见调度文档

确定了起点：新项目还是现有应用
如果是新项目：使用合适的模板通过 npm create convex@latest 搭建
如果是现有应用：安装了 convex 并配置了 Provider
用户已运行 npx convex dev 并连接到部署
convex/_generated/ 目录存在且包含类型定义
.env.local 包含部署 URL
已验证基本的查询/变更往返工作正常

🇺🇸English

Convex Quickstart

Set up a working Convex project as fast as possible.

When to Use

Starting a brand new project with Convex
Adding Convex to an existing React, Next.js, Vue, Svelte, or other app
Scaffolding a Convex app for prototyping

When Not to Use

The project already has Convex installed and convex/ exists - just start building
You only need to add auth to an existing Convex app - use the convex-setup-auth skill

Workflow

Determine the starting point: new project or existing app
If new project, pick a template and scaffold with npm create convex@latest
If existing app, install convex and wire up the provider
Run npx convex dev to connect a deployment and start the dev loop
Verify the setup works

Path 1: New Project (Recommended)

Use the official scaffolding tool. It creates a complete project with the frontend framework, Convex backend, and all config wired together.

Pick a template

Template	Stack
`react-vite-shadcn`	React + Vite + Tailwind + shadcn/ui
`nextjs-shadcn`	Next.js App Router + Tailwind + shadcn/ui
`react-vite-clerk-shadcn`	React + Vite + Clerk auth + shadcn/ui
`nextjs-clerk`	Next.js + Clerk auth
`nextjs-convexauth-shadcn`	Next.js + Convex Auth + shadcn/ui
`nextjs-lucia-shadcn`

If the user has not specified a preference, default to react-vite-shadcn for simple apps or nextjs-shadcn for apps that need SSR or API routes.

You can also use any GitHub repo as a template:

npm create convex@latest my-app -- -t owner/repo
npm create convex@latest my-app -- -t owner/repo#branch

Scaffold the project

Always pass the project name and template flag to avoid interactive prompts:

npm create convex@latest my-app -- -t react-vite-shadcn
cd my-app
npm install

The scaffolding tool creates files but does not run npm install, so you must run it yourself.

To scaffold in the current directory (if it is empty):

npm create convex@latest . -- -t react-vite-shadcn
npm install

Start the dev loop

npx convex dev is a long-running watcher process that syncs backend code to a Convex deployment on every save. It also requires authentication on first run (browser-based OAuth). Both of these make it unsuitable for an agent to run directly.

Ask the user to run this themselves:

Tell the user to run npx convex dev in their terminal. On first run it will prompt them to log in or develop anonymously. Once running, it will:

Create a Convex project and dev deployment
Write the deployment URL to .env.local
Create the convex/ directory with generated types
Watch for changes and sync continuously

The user should keep npx convex dev running in the background while you work on code. The watcher will automatically pick up any files you create or edit in convex/.

Exception - cloud or headless agents: Environments that cannot open a browser for interactive login should use Agent Mode (see below) to run anonymously without user interaction.

Start the frontend

The user should also run the frontend dev server in a separate terminal:

npm run dev

Vite apps serve on http://localhost:5173, Next.js on http://localhost:3000.

What you get

After scaffolding, the project structure looks like:

my-app/
  convex/           # Backend functions and schema
    _generated/     # Auto-generated types (check this into git)
    schema.ts       # Database schema (if template includes one)
  src/              # Frontend code (or app/ for Next.js)
  package.json
  .env.local        # CONVEX_URL / VITE_CONVEX_URL / NEXT_PUBLIC_CONVEX_URL

The template already has:

ConvexProvider wired into the app root
Correct env var names for the framework
Tailwind and shadcn/ui ready (for shadcn templates)
Auth provider configured (for auth templates)

Proceed to adding schema, functions, and UI.

Path 2: Add Convex to an Existing App

Use this when the user already has a frontend project and wants to add Convex as the backend.

Install

npm install convex

Initialize and start dev loop

Ask the user to run npx convex dev in their terminal. This handles login, creates the convex/ directory, writes the deployment URL to .env.local, and starts the file watcher. See the notes in Path 1 about why the agent should not run this directly.

Wire up the provider

The Convex client must wrap the app at the root. The setup varies by framework.

Create the ConvexReactClient at module scope, not inside a component:

// Bad: re-creates the client on every render
function App() {
  const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL as string);
  return <ConvexProvider client={convex}>...</ConvexProvider>;
}

// Good: created once at module scope
const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL as string);
function App() {
  return <ConvexProvider client={convex}>...</ConvexProvider>;
}

React (Vite)

// src/main.tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { ConvexProvider, ConvexReactClient } from "convex/react";
import App from "./App";

const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL as string);

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <ConvexProvider client={convex}>
      <App />
    </ConvexProvider>
  </StrictMode>,
);

Next.js (App Router)

// app/ConvexClientProvider.tsx
"use client";

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

const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL!);

export function ConvexClientProvider({ children }: { children: ReactNode }) {
  return <ConvexProvider client={convex}>{children}</ConvexProvider>;
}



// app/layout.tsx
import { ConvexClientProvider } from "./ConvexClientProvider";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <ConvexClientProvider>{children}</ConvexClientProvider>
      </body>
    </html>
  );
}

Other frameworks

For Vue, Svelte, React Native, TanStack Start, Remix, and others, follow the matching quickstart guide:

Environment variables

The env var name depends on the framework:

Framework	Variable
Vite	`VITE_CONVEX_URL`
Next.js	`NEXT_PUBLIC_CONVEX_URL`
Remix	`CONVEX_URL`
React Native	`EXPO_PUBLIC_CONVEX_URL`

npx convex dev writes the correct variable to .env.local automatically.

Agent Mode (Cloud and Headless Agents)

When running in a cloud or headless agent environment where interactive browser login is not possible, set CONVEX_AGENT_MODE=anonymous to use a local anonymous deployment.

Add CONVEX_AGENT_MODE=anonymous to .env.local, or set it inline:

CONVEX_AGENT_MODE=anonymous npx convex dev

This runs a local Convex backend on the VM without requiring authentication, and avoids conflicting with the user's personal dev deployment.

Verify the Setup

After setup, confirm everything is working:

The user confirms npx convex dev is running without errors
The convex/_generated/ directory exists and has api.ts and server.ts
.env.local contains the deployment URL

Writing Your First Function

Once the project is set up, create a schema and a query to verify the full loop works.

convex/schema.ts:

import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export default defineSchema({
  tasks: defineTable({
    text: v.string(),
    completed: v.boolean(),
  }),
});

convex/tasks.ts:

import { query, mutation } from "./_generated/server";
import { v } from "convex/values";

export const list = query({
  args: {},
  handler: async (ctx) => {
    return await ctx.db.query("tasks").collect();
  },
});

export const create = mutation({
  args: { text: v.string() },
  handler: async (ctx, args) => {
    await ctx.db.insert("tasks", { text: args.text, completed: false });
  },
});

Use in a React component (adjust the import path based on your file location relative to convex/):

import { useQuery, useMutation } from "convex/react";
import { api } from "../convex/_generated/api";

function Tasks() {
  const tasks = useQuery(api.tasks.list);
  const create = useMutation(api.tasks.create);

  return (
    <div>
      <button onClick={() => create({ text: "New task" })}>Add</button>
      {tasks?.map((t) => <div key={t._id}>{t.text}</div>)}
    </div>
  );
}

Development vs Production

Always use npx convex dev during development. It runs against your personal dev deployment and syncs code on save.

When ready to ship, deploy to production:

npx convex deploy

This pushes to the production deployment, which is separate from dev. Do not use deploy during development.

Next Steps

Add authentication: use the convex-setup-auth skill
Design your schema: see Schema docs
Build components: use the convex-create-component skill
Plan a migration: use the convex-migration-helper skill
Add file storage: see File Storage docs
Set up cron jobs: see Scheduling docs

Checklist

Determined starting point: new project or existing app
If new project: scaffolded with npm create convex@latest using appropriate template
If existing app: installed convex and wired up the provider
User has npx convex dev running and connected to a deployment
convex/_generated/ directory exists with types
.env.local has the deployment URL
Verified a basic query/mutation round-trip works

Weekly Installs

6.4K

Repository

get-convex/agent-skills

GitHub Stars

First Seen

Feb 18, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

codex6.4K

github-copilot6.4K

kimi-cli6.4K

opencode6.4K

gemini-cli6.4K

amp6.4K

Convex 快速入门指南：5分钟搭建全栈应用，支持React/Next.js/Vue/Svelte

🇨🇳中文介绍

Convex 快速入门

使用场景

不适用场景

工作流程

路径一：新项目（推荐）

选择模板

相关 Skills

搭建项目

启动开发循环

启动前端

获得的结果

路径二：将 Convex 添加到现有应用

安装

初始化并启动开发循环

配置 Provider

React (Vite)

Next.js (App Router)

其他框架

环境变量

代理模式（云端和无头代理）

验证设置

编写您的第一个函数

开发与生产

后续步骤

检查清单

🇺🇸English

Convex Quickstart

When to Use

When Not to Use

Workflow

Path 1: New Project (Recommended)

Pick a template

Scaffold the project

Start the dev loop

Start the frontend

What you get

Path 2: Add Convex to an Existing App

Install

Initialize and start dev loop

Wire up the provider

React (Vite)

Next.js (App Router)

Other frameworks

Environment variables

Agent Mode (Cloud and Headless Agents)

Verify the Setup

Writing Your First Function

Development vs Production

Next Steps

Checklist