Convex Quickstart 的目标是尽可能快地搭建出一个可正常工作的 Convex 项目。
用途
该技能适用于以下场景:
- 使用 Convex 启动一个全新的项目。
- 将 Convex 添加到已有的 React、Next.js、Vue、Svelte 或其他应用中。
- 为原型开发搭建 Convex 应用的脚手架。
以下情况不建议使用:
- 项目已经安装 Convex 且已存在 convex/ 目录,此时直接开始构建即可。
- 只需为已有 Convex 应用添加认证,应改用 convex-setup-auth 技能。
工作流程
- 确定起点:新项目还是已有应用。
- 如果是新项目,选择模板并使用 npm create convex@latest 创建脚手架。
- 如果是已有应用,安装 convex 并接入 Provider。
- 运行 npx convex dev 连接部署并启动开发循环。
- 验证安装是否正常工作。
路径一:新项目(推荐)
选择模板
技能给出的模板与对应技术栈如下:
- 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
- bare:仅 Convex 后端,无前端
建议:简单应用默认使用 react-vite-shadcn;需要 SSR 或 API 路由的应用默认使用 nextjs-shadcn。
创建脚手架
始终传入项目名和模板标志,以避免交互式提示:
npm create convex@latest my-app -- -t react-vite-shadcn
cd my-app
npm install
启动开发循环
让用户在自己的终端运行 npx convex dev。首次运行时,它会提示登录或以匿名方式开发。运行后,它会:
- 创建 Convex 项目和开发部署。
- 将部署 URL 写入 .env.local。
- 创建带生成类型的 convex/ 目录。
- 持续监视改动并同步。
路径二:将 Convex 添加到已有应用
安装
npm install convex
接入 Provider
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>;
}
环境变量
不同框架使用的变量名:
- Vite:VITE_CONVEX_URL
- Next.js:NEXT_PUBLIC_CONVEX_URL
- Remix:CONVEX_URL
- React Native:EXPO_PUBLIC_CONVEX_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 组件中使用:
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>
);
}
检查清单
- [ ] 已确定起点:新项目还是已有应用
- [ ] 如果是新项目:已使用合适的模板通过 npm create convex@latest 创建脚手架
- [ ] 如果是已有应用:已安装 convex 并接入 Provider
- [ ] 用户已运行 npx convex dev 并连接到部署
- [ ] convex/_generated/ 目录已存在并含有类型
- [ ] .env.local 中已有部署 URL
- [ ] 已验证基本的查询/变更往返可正常工作
限制
资料未提供有关收费、价格、性能指标或平台支持范围的具体信息。