convex-quickstart by get-convex/agent-skills
npx skills add https://github.com/get-convex/agent-skills --skill convex-quickstart以最快速度搭建一个可运行的 Convex 项目。
convex/ 目录已存在 - 直接开始构建即可convex-setup-auth 技能npm create convex@latest 搭建convex 并配置 Providernpx convex dev 以连接部署并启动开发循环使用官方的脚手架工具。它会创建一个包含前端框架、Convex 后端以及所有配置都已连接好的完整项目。
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
| 模板 | 技术栈 |
|---|---|
react-vite-shadcn | React + Vite + Tailwind + shadcn/ui |
nextjs-shadcn | Next.js App Router + Tailwind + shadcn/ui |
react-vite-clerk-shadcn | React + Vite + Clerk 身份验证 + shadcn/ui |
nextjs-clerk | Next.js + Clerk 身份验证 |
nextjs-convexauth-shadcn | Next.js + Convex Auth + shadcn/ui |
nextjs-lucia-shadcn | Next.js + Lucia 身份验证 + shadcn/ui |
bare | 仅 Convex 后端,无前端 |
如果用户未指定偏好,对于简单应用默认使用 react-vite-shadcn,对于需要 SSR 或 API 路由的应用默认使用 nextjs-shadcn。
您也可以使用任何 GitHub 仓库作为模板:
npm create convex@latest my-app -- -t owner/repo
npm create convex@latest my-app -- -t owner/repo#branch
始终传递项目名称和模板标志以避免交互式提示:
npm create convex@latest my-app -- -t react-vite-shadcn
cd my-app
npm install
脚手架工具会创建文件但不会运行 npm install,因此您必须自己运行它。
要在当前目录(如果为空)中搭建:
npm create convex@latest . -- -t react-vite-shadcn
npm install
npx convex dev 是一个长期运行的监听进程,每次保存时都会将后端代码同步到 Convex 部署。首次运行时还需要身份验证(基于浏览器的 OAuth)。这两点都使得它不适合由代理直接运行。
请用户自行运行此命令:
告知用户在终端中运行 npx convex dev。首次运行时,它会提示用户登录或匿名开发。运行后,它将:
.env.localconvex/ 目录当您编写代码时,用户应保持 npx convex dev 在后台运行。监听器会自动获取您在 convex/ 中创建或编辑的任何文件。
例外情况 - 云端或无头代理: 无法打开浏览器进行交互式登录的环境应使用代理模式(见下文)以无需用户交互的方式匿名运行。
用户还应在另一个单独的终端中运行前端开发服务器:
npm run dev
Vite 应用运行在 http://localhost:5173,Next.js 运行在 http://localhost:3000。
搭建完成后,项目结构如下:
my-app/
convex/ # 后端函数和模式
_generated/ # 自动生成的类型(提交到 git)
schema.ts # 数据库模式(如果模板包含)
src/ # 前端代码(Next.js 则为 app/)
package.json
.env.local # CONVEX_URL / VITE_CONVEX_URL / NEXT_PUBLIC_CONVEX_URL
模板已包含:
ConvexProvider 已连接到应用根目录接下来可以添加模式、函数和 UI。
当用户已有一个前端项目并希望添加 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>,
);
// 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项目设置完成后,创建一个模式和一个查询来验证整个循环是否正常工作。
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 });
},
});
在 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。它针对您的个人开发部署运行,并在保存时同步代码。
准备发布时,部署到生产环境:
npx convex deploy
这将推送到生产部署,该部署与开发部署是分开的。在开发过程中不要使用 deploy。
npm create convex@latest 搭建convex 并配置了 Providernpx convex dev 并连接到部署convex/_generated/ 目录存在且包含类型定义.env.local 包含部署 URL每周安装量
6.4K
仓库
GitHub 星标数
15
首次出现
2026年2月18日
安全审计
安装于
codex6.4K
github-copilot6.4K
kimi-cli6.4K
opencode6.4K
gemini-cli6.4K
amp6.4K
Set up a working Convex project as fast as possible.
convex/ exists - just start buildingconvex-setup-auth skillnpm create convex@latestconvex and wire up the providernpx convex dev to connect a deployment and start the dev loopUse the official scaffolding tool. It creates a complete project with the frontend framework, Convex backend, and all config wired together.
| 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
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
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:
.env.localconvex/ directory with generated typesThe 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.
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.
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 rootProceed to adding schema, functions, and UI.
Use this when the user already has a frontend project and wants to add Convex as the backend.
npm install convex
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.
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>;
}
// 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>,
);
// 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>
);
}
For Vue, Svelte, React Native, TanStack Start, Remix, and others, follow the matching quickstart guide:
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.
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.
After setup, confirm everything is working:
npx convex dev is running without errorsconvex/_generated/ directory exists and has api.ts and server.ts.env.local contains the deployment URLOnce 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>
);
}
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.
convex-setup-auth skillconvex-create-component skillconvex-migration-helper skillnpm create convex@latest using appropriate templateconvex and wired up the providernpx convex dev running and connected to a deploymentconvex/_generated/ directory exists with types.env.local has the deployment URLWeekly Installs
6.4K
Repository
GitHub Stars
15
First Seen
Feb 18, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
codex6.4K
github-copilot6.4K
kimi-cli6.4K
opencode6.4K
gemini-cli6.4K
amp6.4K
99,500 周安装
| Next.js + Lucia auth + shadcn/ui |
bare | Convex backend only, no frontend |