SuperAPI AI 工具集

convex-quickstart

编程与开发

查看项目

更新于 10-16 09:12

技能介绍

Convex Quickstart 的目标是尽可能快地搭建出一个可正常工作的 Convex 项目。

用途

该技能适用于以下场景:

  • 使用 Convex 启动一个全新的项目。
  • 将 Convex 添加到已有的 React、Next.js、Vue、Svelte 或其他应用中。
  • 为原型开发搭建 Convex 应用的脚手架。

以下情况不建议使用:

  • 项目已经安装 Convex 且已存在 convex/ 目录,此时直接开始构建即可。
  • 只需为已有 Convex 应用添加认证,应改用 convex-setup-auth 技能。

工作流程

  1. 确定起点:新项目还是已有应用。
  2. 如果是新项目,选择模板并使用 npm create convex@latest 创建脚手架。
  3. 如果是已有应用,安装 convex 并接入 Provider。
  4. 运行 npx convex dev 连接部署并启动开发循环。
  5. 验证安装是否正常工作。

路径一:新项目(推荐)

选择模板

技能给出的模板与对应技术栈如下:

  • 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
  • [ ] 已验证基本的查询/变更往返可正常工作

限制

资料未提供有关收费、价格、性能指标或平台支持范围的具体信息。