[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M79C2QNEAVSB9Y02YT50M8GP":3,"skill-same:01M79C2QNEAVSB9Y02YT50M8GP":56},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":23,"commitSha":24,"skillDirectory":25,"forksCount":13,"repositoryHtmlUrl":26,"repositoryHomepageUrl":27,"ownerHtmlUrl":28,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":29,"install":30,"resources":43},"01M79C2QNEAVSB9Y02YT50M8GP","convex-quickstart",null,"Creates or adds Convex to an app. Use for new Convex projects, npm create convex@latest, frontend setup, env vars, or the first npx convex dev run.","jackwynne\u002Ffinance-tracking","jackwynne","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F6869144?v=4","01M79BWEB0X3CFN7YRKDN5H4GR","01M79BWEBZKSJH7P1JW70H9MQS",0,"MIT","https:\u002F\u002Fgithub.com\u002Fjackwynne\u002Ffinance-tracking\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fconvex-quickstart\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: convex-quickstart\ndescription:\n  Creates or adds Convex to an app. Use for new Convex projects, npm create\n  convex@latest, frontend setup, env vars, or the first npx convex dev run.\n---\n\n# Convex Quickstart\n\nSet up a working Convex project as fast as possible.\n\n## When to Use\n\n- Starting a brand new project with Convex\n- Adding Convex to an existing React, Next.js, Vue, Svelte, or other app\n- Scaffolding a Convex app for prototyping\n\n## When Not to Use\n\n- The project already has Convex installed and `convex\u002F` exists - just start\n  building\n- You only need to add auth to an existing Convex app - use the\n  `convex-setup-auth` skill\n\n## Workflow\n\n1. Determine the starting point: new project or existing app\n2. If new project, pick a template and scaffold with `npm create convex@latest`\n3. If existing app, install `convex` and wire up the provider\n4. Run `npx convex dev --once` to provision a local anonymous deployment, push\n   the current `convex\u002F` code, typecheck it, and regenerate types — all in one\n   shot, exiting cleanly. The output tells the agent whether the schema and\n   functions are valid.\n5. Ask the user (or, for cloud agents, start in the background) `npm run dev` —\n   Convex templates wire the watcher and the frontend into a single command. If\n   the project has no combined dev script, use `npx convex dev` for the watcher\n   and run the frontend separately.\n6. Verify the setup works\n\n## Path 1: New Project (Recommended)\n\nUse the official scaffolding tool. It creates a complete project with the\nfrontend framework, Convex backend, and all config wired together.\n\n### Pick a template\n\n| Template                   | Stack                                     |\n| -------------------------- | ----------------------------------------- |\n| `react-vite-shadcn`        | React + Vite + Tailwind + shadcn\u002Fui       |\n| `nextjs-shadcn`            | Next.js App Router + Tailwind + shadcn\u002Fui |\n| `react-vite-clerk-shadcn`  | React + Vite + Clerk auth + shadcn\u002Fui     |\n| `nextjs-clerk`             | Next.js + Clerk auth                      |\n| `nextjs-convexauth-shadcn` | Next.js + Convex Auth + shadcn\u002Fui         |\n| `nextjs-lucia-shadcn`      | Next.js + Lucia auth + shadcn\u002Fui          |\n| `bare`                     | Convex backend only, no frontend          |\n\nIf the user has not specified a preference, default to `react-vite-shadcn` for\nsimple apps or `nextjs-shadcn` for apps that need SSR or API routes.\n\nYou can also use any GitHub repo as a template:\n\n```bash\nnpm create convex@latest my-app -- -t owner\u002Frepo\nnpm create convex@latest my-app -- -t owner\u002Frepo#branch\n```\n\n### Scaffold the project\n\nAlways pass the project name and template flag to avoid interactive prompts:\n\n```bash\nnpm create convex@latest my-app -- -t react-vite-shadcn\ncd my-app\nnpm install\n```\n\nThe scaffolding tool creates files but does not run `npm install`, so you must\nrun it yourself.\n\nTo scaffold in the current directory (if it is empty):\n\n```bash\nnpm create convex@latest . -- -t react-vite-shadcn\nnpm install\n```\n\n### Provision the deployment and push code\n\nRun this yourself — it is a one-shot command that exits cleanly:\n\n```bash\nnpx convex dev --once\n```\n\nIn a non-TTY environment (which is true for almost every agent run), this:\n\n- Provisions an _anonymous_ local Convex backend bound to `127.0.0.1`. No\n  browser login, no team\u002Fproject prompts.\n- Writes `CONVEX_DEPLOYMENT` and the framework's `*_CONVEX_URL` variables to\n  `.env.local`.\n- Generates `convex\u002F_generated\u002F`.\n- Pushes the current `convex\u002F` code to the deployment, **typechecks it**, and\n  **validates the schema**. The agent reads this output to find out if the code\n  it just wrote is broken.\n\nTo be explicit (recommended), set `CONVEX_AGENT_MODE=anonymous` so the behavior\ndoes not depend on TTY detection:\n\n```bash\nCONVEX_AGENT_MODE=anonymous npx convex dev --once\n```\n\nThe deployment lives under `~\u002F.convex\u002F` and persists across runs. Re-running\n`convex dev --once` after editing `convex\u002F` files is the agent's main feedback\nloop while the user-launched `npm run dev` is not in use.\n\nIf the template's `package.json` defines a `predev` script (Convex Auth\ntemplates and similar do), `npm run predev` runs `convex init` plus any one-time\nsetup (e.g. minting auth keys). Use it _in addition to_ `convex dev --once` when\npresent — `predev` handles the one-time setup, `convex dev --once` pushes and\nvalidates the code.\n\n### Start the dev loop\n\nIn most Convex templates, `npm run dev` runs both the Convex watcher and the\nfrontend dev server together (typically `convex dev --start 'vite --open'` or\nthe Next.js equivalent). That is what the user should run.\n\n```bash\nnpm run dev\n```\n\nIf the project does not have a combined `dev` script — e.g. the `bare` template,\nor an existing app where you haven't wired the frontend dev server into Convex's\n`--start` flag — the user can run the Convex watcher directly:\n\n```bash\nnpx convex dev\n```\n\n`npx convex dev` is the same long-running watcher `npm run dev` invokes under\nthe hood; it just doesn't start the frontend. Use it when there is no frontend,\nor when the user prefers to run the frontend in a separate terminal.\n\nEither way, the agent should not invoke the watcher in the foreground because it\ndoes not exit. Two options:\n\n- **Local development (user is at the keyboard):** ask the user to run\n  `npm run dev` (or `npx convex dev`) in a terminal. The deployment provisioned\n  by `convex dev --once` above is already selected, so the watcher picks up\n  immediately with no prompts.\n- **Cloud or headless agents:** start `npm run dev` (or `npx convex dev`) in the\n  background.\n\nVite apps serve on `http:\u002F\u002Flocalhost:5173`, Next.js on `http:\u002F\u002Flocalhost:3000`.\n\n### What you get\n\nAfter scaffolding, the project structure looks like:\n\n```\nmy-app\u002F\n  convex\u002F           # Backend functions and schema\n    _generated\u002F     # Auto-generated types (check this into git)\n    schema.ts       # Database schema (if template includes one)\n  src\u002F              # Frontend code (or app\u002F for Next.js)\n  package.json\n  .env.local        # CONVEX_URL \u002F VITE_CONVEX_URL \u002F NEXT_PUBLIC_CONVEX_URL\n```\n\nThe template already has:\n\n- `ConvexProvider` wired into the app root\n- Correct env var names for the framework\n- Tailwind and shadcn\u002Fui ready (for shadcn templates)\n- Auth provider configured (for auth templates)\n\nProceed to adding schema, functions, and UI.\n\n## Path 2: Add Convex to an Existing App\n\nUse this when the user already has a frontend project and wants to add Convex as\nthe backend.\n\n### Install\n\n```bash\nnpm install convex\n```\n\n### Provision and push\n\nRun `npx convex dev --once` yourself to provision a local anonymous deployment,\nwrite `.env.local`, generate types, push the current `convex\u002F` code, and\ntypecheck it. This is one-shot and exits:\n\n```bash\nnpx convex dev --once\n```\n\nThe output tells you whether the schema and functions are valid — use it as your\nfeedback loop while iterating.\n\nThen ask the user to start the watcher (or, for cloud\u002Fheadless agents, start it\nin the background). You have two options:\n\n- **Wire Convex into `npm run dev`** — change the existing app's `dev` script to\n  `convex dev --start '\u003Cexisting dev command>'`. That's the standard pattern\n  Convex templates use; the user then runs a single `npm run dev` to start both.\n- **Run them separately** — leave `npm run dev` for the frontend and tell the\n  user to run `npx convex dev` in a second terminal for the Convex watcher.\n\nSee \"Start the dev loop\" above for why the agent should not run the watcher in\nthe foreground.\n\n### Wire up the provider\n\nThe Convex client must wrap the app at the root. The setup varies by framework.\n\nCreate the `ConvexReactClient` at module scope, not inside a component:\n\n```tsx\n\u002F\u002F Bad: re-creates the client on every render\nfunction App() {\n  const convex = new ConvexReactClient(\n    import.meta.env.VITE_CONVEX_URL as string,\n  );\n  return \u003CConvexProvider client={convex}>...\u003C\u002FConvexProvider>;\n}\n\n\u002F\u002F Good: created once at module scope\nconst convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL as string);\nfunction App() {\n  return \u003CConvexProvider client={convex}>...\u003C\u002FConvexProvider>;\n}\n```\n\n#### React (Vite)\n\n```tsx\n\u002F\u002F src\u002Fmain.tsx\nimport { StrictMode } from \"react\";\nimport { createRoot } from \"react-dom\u002Fclient\";\nimport { ConvexProvider, ConvexReactClient } from \"convex\u002Freact\";\nimport App from \".\u002FApp\";\n\nconst convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL as string);\n\ncreateRoot(document.getElementById(\"root\")!).render(\n  \u003CStrictMode>\n    \u003CConvexProvider client={convex}>\n      \u003CApp \u002F>\n    \u003C\u002FConvexProvider>\n  \u003C\u002FStrictMode>,\n);\n```\n\n#### Next.js (App Router)\n\n```tsx\n\u002F\u002F app\u002FConvexClientProvider.tsx\n\"use client\";\n\nimport { ConvexProvider, ConvexReactClient } from \"convex\u002Freact\";\nimport { ReactNode } from \"react\";\n\nconst convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL!);\n\nexport function ConvexClientProvider({ children }: { children: ReactNode }) {\n  return \u003CConvexProvider client={convex}>{children}\u003C\u002FConvexProvider>;\n}\n```\n\n```tsx\n\u002F\u002F app\u002Flayout.tsx\nimport { ConvexClientProvider } from \".\u002FConvexClientProvider\";\n\nexport default function RootLayout({\n  children,\n}: {\n  children: React.ReactNode;\n}) {\n  return (\n    \u003Chtml lang=\"en\">\n      \u003Cbody>\n        \u003CConvexClientProvider>{children}\u003C\u002FConvexClientProvider>\n      \u003C\u002Fbody>\n    \u003C\u002Fhtml>\n  );\n}\n```\n\n#### Other frameworks\n\nFor Vue, Svelte, React Native, TanStack Start, Remix, and others, follow the\nmatching quickstart guide:\n\n- [Vue](https:\u002F\u002Fdocs.convex.dev\u002Fquickstart\u002Fvue)\n- [Svelte](https:\u002F\u002Fdocs.convex.dev\u002Fquickstart\u002Fsvelte)\n- [React Native](https:\u002F\u002Fdocs.convex.dev\u002Fquickstart\u002Freact-native)\n- [TanStack Start](https:\u002F\u002Fdocs.convex.dev\u002Fquickstart\u002Ftanstack-start)\n- [Remix](https:\u002F\u002Fdocs.convex.dev\u002Fquickstart\u002Fremix)\n- [Node.js (no frontend)](https:\u002F\u002Fdocs.convex.dev\u002Fquickstart\u002Fnodejs)\n\n### Environment variables\n\nThe env var name depends on the framework:\n\n| Framework    | Variable                 |\n| ------------ | ------------------------ |\n| Vite         | `VITE_CONVEX_URL`        |\n| Next.js      | `NEXT_PUBLIC_CONVEX_URL` |\n| Remix        | `CONVEX_URL`             |\n| React Native | `EXPO_PUBLIC_CONVEX_URL` |\n\n`npx convex dev` writes the correct variable to `.env.local` automatically.\n\n## Agent Mode\n\n`CONVEX_AGENT_MODE=anonymous` forces an unauthenticated local backend. It is\nalready the implicit default for any non-TTY run of `npx convex init` or\n`npx convex dev`, but set it explicitly so the behavior does not depend on TTY\ndetection:\n\n```bash\nCONVEX_AGENT_MODE=anonymous npx convex dev --once\n```\n\nUse it for:\n\n- Any AI coding agent (local or cloud).\n- CI-like setup scripts.\n- Cases where the user is logged in but you do not want to touch their personal\n  dev deployment.\n\nThe resulting backend runs on `127.0.0.1` and is not associated with any team or\nproject until the user later claims it via `npx convex login` and the\n`npx convex deployment` commands.\n\n## Verify the Setup\n\nAfter setup, confirm everything is working:\n\n1. `npx convex dev --once` exited without errors (deployment provisioned, code\n   pushed, schema validated, typecheck clean)\n2. The `convex\u002F_generated\u002F` directory exists and has `api.ts` and `server.ts`\n3. `.env.local` contains a `CONVEX_DEPLOYMENT` value and the framework's\n   `*_CONVEX_URL` variable\n4. (If applicable) `npm run dev` (or `npx convex dev` for the watcher alone) is\n   running without errors in another terminal or in the background\n\n## Writing Your First Function\n\nOnce the project is set up, create a schema and a query to verify the full loop\nworks.\n\n`convex\u002Fschema.ts`:\n\n```ts\nimport { defineSchema, defineTable } from \"convex\u002Fserver\";\nimport { v } from \"convex\u002Fvalues\";\n\nexport default defineSchema({\n  tasks: defineTable({\n    text: v.string(),\n    completed: v.boolean(),\n  }),\n});\n```\n\n`convex\u002Ftasks.ts`:\n\n```ts\nimport { query, mutation } from \".\u002F_generated\u002Fserver\";\nimport { v } from \"convex\u002Fvalues\";\n\nexport const list = query({\n  args: {},\n  handler: async (ctx) => {\n    return await ctx.db.query(\"tasks\").collect();\n  },\n});\n\nexport const create = mutation({\n  args: { text: v.string() },\n  handler: async (ctx, args) => {\n    await ctx.db.insert(\"tasks\", { text: args.text, completed: false });\n  },\n});\n```\n\nUse in a React component (adjust the import path based on your file location\nrelative to `convex\u002F`):\n\n```tsx\nimport { useQuery, useMutation } from \"convex\u002Freact\";\nimport { api } from \"..\u002Fconvex\u002F_generated\u002Fapi\";\n\nfunction Tasks() {\n  const tasks = useQuery(api.tasks.list);\n  const create = useMutation(api.tasks.create);\n\n  return (\n    \u003Cdiv>\n      \u003Cbutton onClick={() => create({ text: \"New task\" })}>Add\u003C\u002Fbutton>\n      {tasks?.map((t) => (\n        \u003Cdiv key={t._id}>{t.text}\u003C\u002Fdiv>\n      ))}\n    \u003C\u002Fdiv>\n  );\n}\n```\n\n## Development vs Production\n\nAlways use `npx convex dev` during development. It runs against your personal\ndev deployment and syncs code on save.\n\nWhen ready to ship, deploy to production:\n\n```bash\nnpx convex deploy\n```\n\nThis pushes to the production deployment, which is separate from dev. Do not use\n`deploy` during development.\n\n## Next Steps\n\n- Add authentication: use the `convex-setup-auth` skill\n- Design your schema: see\n  [Schema docs](https:\u002F\u002Fdocs.convex.dev\u002Fdatabase\u002Fschemas)\n- Build components: use the `convex-create-component` skill\n- Plan a migration: use the `convex-migration-helper` skill\n- Add file storage: see\n  [File Storage docs](https:\u002F\u002Fdocs.convex.dev\u002Ffile-storage)\n- Set up cron jobs: see [Scheduling docs](https:\u002F\u002Fdocs.convex.dev\u002Fscheduling)\n\n## Checklist\n\n- [ ] Determined starting point: new project or existing app\n- [ ] If new project: scaffolded with `npm create convex@latest` using\n      appropriate template\n- [ ] If existing app: installed `convex` and wired up the provider\n- [ ] Agent ran `npx convex dev --once`: deployment provisioned, code pushed,\n      typecheck clean\n- [ ] `npm run dev` (or `npx convex dev` for the watcher alone) is running —\n      user-launched terminal, or background for cloud agents\n- [ ] `convex\u002F_generated\u002F` directory exists with types\n- [ ] `.env.local` has the deployment URL\n- [ ] Verified a basic query\u002Fmutation round-trip works\n","# Convex Quickstart\n\nSet up a working Convex project as fast as possible.\n\n## When to Use\n\n- Starting a brand new project with Convex\n- Adding Convex to an existing React, Next.js, Vue, Svelte, or other app\n- Scaffolding a Convex app for prototyping\n\n## When Not to Use\n\n- The project already has Convex installed and `convex\u002F` exists - just start\n  building\n- You only need to add auth to an existing Convex app - use the\n  `convex-setup-auth` skill\n\n## Workflow\n\n1. Determine the starting point: new project or existing app\n2. If new project, pick a template and scaffold with `npm create convex@latest`\n3. If existing app, install `convex` and wire up the provider\n4. Run `npx convex dev --once` to provision a local anonymous deployment, push\n   the current `convex\u002F` code, typecheck it, and regenerate types — all in one\n   shot, exiting cleanly. The output tells the agent whether the schema and\n   functions are valid.\n5. Ask the user (or, for cloud agents, start in the background) `npm run dev` —\n   Convex templates wire the watcher and the frontend into a single command. If\n   the project has no combined dev script, use `npx convex dev` for the watcher\n   and run the frontend separately.\n6. Verify the setup works\n\n## Path 1: New Project (Recommended)\n\nUse the official scaffolding tool. It creates a complete project with the\nfrontend framework, Convex backend, and all config wired together.\n\n### Pick a template\n\n| Template                   | Stack                                     |\n| -------------------------- | ----------------------------------------- |\n| `react-vite-shadcn`        | React + Vite + Tailwind + shadcn\u002Fui       |\n| `nextjs-shadcn`            | Next.js App Router + Tailwind + shadcn\u002Fui |\n| `react-vite-clerk-shadcn`  | React + Vite + Clerk auth + shadcn\u002Fui     |\n| `nextjs-clerk`             | Next.js + Clerk auth                      |\n| `nextjs-convexauth-shadcn` | Next.js + Convex Auth + shadcn\u002Fui         |\n| `nextjs-lucia-shadcn`      | Next.js + Lucia auth + shadcn\u002Fui          |\n| `bare`                     | Convex backend only, no frontend          |\n\nIf the user has not specified a preference, default to `react-vite-shadcn` for\nsimple apps or `nextjs-shadcn` for apps that need SSR or API routes.\n\nYou can also use any GitHub repo as a template:\n\n```bash\nnpm create convex@latest my-app -- -t owner\u002Frepo\nnpm create convex@latest my-app -- -t owner\u002Frepo#branch\n```\n\n### Scaffold the project\n\nAlways pass the project name and template flag to avoid interactive prompts:\n\n```bash\nnpm create convex@latest my-app -- -t react-vite-shadcn\ncd my-app\nnpm install\n```\n\nThe scaffolding tool creates files but does not run `npm install`, so you must\nrun it yourself.\n\nTo scaffold in the current directory (if it is empty):\n\n```bash\nnpm create convex@latest . -- -t react-vite-shadcn\nnpm install\n```\n\n### Provision the deployment and push code\n\nRun this yourself — it is a one-shot command that exits cleanly:\n\n```bash\nnpx convex dev --once\n```\n\nIn a non-TTY environment (which is true for almost every agent run), this:\n\n- Provisions an _anonymous_ local Convex backend bound to `127.0.0.1`. No\n  browser login, no team\u002Fproject prompts.\n- Writes `CONVEX_DEPLOYMENT` and the framework's `*_CONVEX_URL` variables to\n  `.env.local`.\n- Generates `convex\u002F_generated\u002F`.\n- Pushes the current `convex\u002F` code to the deployment, **typechecks it**, and\n  **validates the schema**. The agent reads this output to find out if the code\n  it just wrote is broken.\n\nTo be explicit (recommended), set `CONVEX_AGENT_MODE=anonymous` so the behavior\ndoes not depend on TTY detection:\n\n```bash\nCONVEX_AGENT_MODE=anonymous npx convex dev --once\n```\n\nThe deployment lives under `~\u002F.convex\u002F` and persists across runs. Re-running\n`convex dev --once` after editing `convex\u002F` files is the agent's main feedback\nloop while the user-launched `npm run dev` is not in use.\n\nIf the template's `package.json` defines a `predev` script (Convex Auth\ntemplates and similar do), `npm run predev` runs `convex init` plus any one-time\nsetup (e.g. minting auth keys). Use it _in addition to_ `convex dev --once` when\npresent — `predev` handles the one-time setup, `convex dev --once` pushes and\nvalidates the code.\n\n### Start the dev loop\n\nIn most Convex templates, `npm run dev` runs both the Convex watcher and the\nfrontend dev server together (typically `convex dev --start 'vite --open'` or\nthe Next.js equivalent). That is what the user should run.\n\n```bash\nnpm run dev\n```\n\nIf the project does not have a combined `dev` script — e.g. the `bare` template,\nor an existing app where you haven't wired the frontend dev server into Convex's\n`--start` flag — the user can run the Convex watcher directly:\n\n```bash\nnpx convex dev\n```\n\n`npx convex dev` is the same long-running watcher `npm run dev` invokes under\nthe hood; it just doesn't start the frontend. Use it when there is no frontend,\nor when the user prefers to run the frontend in a separate terminal.\n\nEither way, the agent should not invoke the watcher in the foreground because it\ndoes not exit. Two options:\n\n- **Local development (user is at the keyboard):** ask the user to run\n  `npm run dev` (or `npx convex dev`) in a terminal. The deployment provisioned\n  by `convex dev --once` above is already selected, so the watcher picks up\n  immediately with no prompts.\n- **Cloud or headless agents:** start `npm run dev` (or `npx convex dev`) in the\n  background.\n\nVite apps serve on `http:\u002F\u002Flocalhost:5173`, Next.js on `http:\u002F\u002Flocalhost:3000`.\n\n### What you get\n\nAfter scaffolding, the project structure looks like:\n\n```\nmy-app\u002F\n  convex\u002F           # Backend functions and schema\n    _generated\u002F     # Auto-generated types (check this into git)\n    schema.ts       # Database schema (if template includes one)\n  src\u002F              # Frontend code (or app\u002F for Next.js)\n  package.json\n  .env.local        # CONVEX_URL \u002F VITE_CONVEX_URL \u002F NEXT_PUBLIC_CONVEX_URL\n```\n\nThe template already has:\n\n- `ConvexProvider` wired into the app root\n- Correct env var names for the framework\n- Tailwind and shadcn\u002Fui ready (for shadcn templates)\n- Auth provider configured (for auth templates)\n\nProceed to adding schema, functions, and UI.\n\n## Path 2: Add Convex to an Existing App\n\nUse this when the user already has a frontend project and wants to add Convex as\nthe backend.\n\n### Install\n\n```bash\nnpm install convex\n```\n\n### Provision and push\n\nRun `npx convex dev --once` yourself to provision a local anonymous deployment,\nwrite `.env.local`, generate types, push the current `convex\u002F` code, and\ntypecheck it. This is one-shot and exits:\n\n```bash\nnpx convex dev --once\n```\n\nThe output tells you whether the schema and functions are valid — use it as your\nfeedback loop while iterating.\n\nThen ask the user to start the watcher (or, for cloud\u002Fheadless agents, start it\nin the background). You have two options:\n\n- **Wire Convex into `npm run dev`** — change the existing app's `dev` script to\n  `convex dev --start '\u003Cexisting dev command>'`. That's the standard pattern\n  Convex templates use; the user then runs a single `npm run dev` to start both.\n- **Run them separately** — leave `npm run dev` for the frontend and tell the\n  user to run `npx convex dev` in a second terminal for the Convex watcher.\n\nSee \"Start the dev loop\" above for why the agent should not run the watcher in\nthe foreground.\n\n### Wire up the provider\n\nThe Convex client must wrap the app at the root. The setup varies by framework.\n\nCreate the `ConvexReactClient` at module scope, not inside a component:\n\n```tsx\n\u002F\u002F Bad: re-creates the client on every render\nfunction App() {\n  const convex = new ConvexReactClient(\n    import.meta.env.VITE_CONVEX_URL as string,\n  );\n  return \u003CConvexProvider client={convex}>...\u003C\u002FConvexProvider>;\n}\n\n\u002F\u002F Good: created once at module scope\nconst convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL as string);\nfunction App() {\n  return \u003CConvexProvider client={convex}>...\u003C\u002FConvexProvider>;\n}\n```\n\n#### React (Vite)\n\n```tsx\n\u002F\u002F src\u002Fmain.tsx\nimport { StrictMode } from \"react\";\nimport { createRoot } from \"react-dom\u002Fclient\";\nimport { ConvexProvider, ConvexReactClient } from \"convex\u002Freact\";\nimport App from \".\u002FApp\";\n\nconst convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL as string);\n\ncreateRoot(document.getElementById(\"root\")!).render(\n  \u003CStrictMode>\n    \u003CConvexProvider client={convex}>\n      \u003CApp \u002F>\n    \u003C\u002FConvexProvider>\n  \u003C\u002FStrictMode>,\n);\n```\n\n#### Next.js (App Router)\n\n```tsx\n\u002F\u002F app\u002FConvexClientProvider.tsx\n\"use client\";\n\nimport { ConvexProvider, ConvexReactClient } from \"convex\u002Freact\";\nimport { ReactNode } from \"react\";\n\nconst convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL!);\n\nexport function ConvexClientProvider({ children }: { children: ReactNode }) {\n  return \u003CConvexProvider client={convex}>{children}\u003C\u002FConvexProvider>;\n}\n```\n\n```tsx\n\u002F\u002F app\u002Flayout.tsx\nimport { ConvexClientProvider } from \".\u002FConvexClientProvider\";\n\nexport default function RootLayout({\n  children,\n}: {\n  children: React.ReactNode;\n}) {\n  return (\n    \u003Chtml lang=\"en\">\n      \u003Cbody>\n        \u003CConvexClientProvider>{children}\u003C\u002FConvexClientProvider>\n      \u003C\u002Fbody>\n    \u003C\u002Fhtml>\n  );\n}\n```\n\n#### Other frameworks\n\nFor Vue, Svelte, React Native, TanStack Start, Remix, and others, follow the\nmatching quickstart guide:\n\n- [Vue](https:\u002F\u002Fdocs.convex.dev\u002Fquickstart\u002Fvue)\n- [Svelte](https:\u002F\u002Fdocs.convex.dev\u002Fquickstart\u002Fsvelte)\n- [React Native](https:\u002F\u002Fdocs.convex.dev\u002Fquickstart\u002Freact-native)\n- [TanStack Start](https:\u002F\u002Fdocs.convex.dev\u002Fquickstart\u002Ftanstack-start)\n- [Remix](https:\u002F\u002Fdocs.convex.dev\u002Fquickstart\u002Fremix)\n- [Node.js (no frontend)](https:\u002F\u002Fdocs.convex.dev\u002Fquickstart\u002Fnodejs)\n\n### Environment variables\n\nThe env var name depends on the framework:\n\n| Framework    | Variable                 |\n| ------------ | ------------------------ |\n| Vite         | `VITE_CONVEX_URL`        |\n| Next.js      | `NEXT_PUBLIC_CONVEX_URL` |\n| Remix        | `CONVEX_URL`             |\n| React Native | `EXPO_PUBLIC_CONVEX_URL` |\n\n`npx convex dev` writes the correct variable to `.env.local` automatically.\n\n## Agent Mode\n\n`CONVEX_AGENT_MODE=anonymous` forces an unauthenticated local backend. It is\nalready the implicit default for any non-TTY run of `npx convex init` or\n`npx convex dev`, but set it explicitly so the behavior does not depend on TTY\ndetection:\n\n```bash\nCONVEX_AGENT_MODE=anonymous npx convex dev --once\n```\n\nUse it for:\n\n- Any AI coding agent (local or cloud).\n- CI-like setup scripts.\n- Cases where the user is logged in but you do not want to touch their personal\n  dev deployment.\n\nThe resulting backend runs on `127.0.0.1` and is not associated with any team or\nproject until the user later claims it via `npx convex login` and the\n`npx convex deployment` commands.\n\n## Verify the Setup\n\nAfter setup, confirm everything is working:\n\n1. `npx convex dev --once` exited without errors (deployment provisioned, code\n   pushed, schema validated, typecheck clean)\n2. The `convex\u002F_generated\u002F` directory exists and has `api.ts` and `server.ts`\n3. `.env.local` contains a `CONVEX_DEPLOYMENT` value and the framework's\n   `*_CONVEX_URL` variable\n4. (If applicable) `npm run dev` (or `npx convex dev` for the watcher alone) is\n   running without errors in another terminal or in the background\n\n## Writing Your First Function\n\nOnce the project is set up, create a schema and a query to verify the full loop\nworks.\n\n`convex\u002Fschema.ts`:\n\n```ts\nimport { defineSchema, defineTable } from \"convex\u002Fserver\";\nimport { v } from \"convex\u002Fvalues\";\n\nexport default defineSchema({\n  tasks: defineTable({\n    text: v.string(),\n    completed: v.boolean(),\n  }),\n});\n```\n\n`convex\u002Ftasks.ts`:\n\n```ts\nimport { query, mutation } from \".\u002F_generated\u002Fserver\";\nimport { v } from \"convex\u002Fvalues\";\n\nexport const list = query({\n  args: {},\n  handler: async (ctx) => {\n    return await ctx.db.query(\"tasks\").collect();\n  },\n});\n\nexport const create = mutation({\n  args: { text: v.string() },\n  handler: async (ctx, args) => {\n    await ctx.db.insert(\"tasks\", { text: args.text, completed: false });\n  },\n});\n```\n\nUse in a React component (adjust the import path based on your file location\nrelative to `convex\u002F`):\n\n```tsx\nimport { useQuery, useMutation } from \"convex\u002Freact\";\nimport { api } from \"..\u002Fconvex\u002F_generated\u002Fapi\";\n\nfunction Tasks() {\n  const tasks = useQuery(api.tasks.list);\n  const create = useMutation(api.tasks.create);\n\n  return (\n    \u003Cdiv>\n      \u003Cbutton onClick={() => create({ text: \"New task\" })}>Add\u003C\u002Fbutton>\n      {tasks?.map((t) => (\n        \u003Cdiv key={t._id}>{t.text}\u003C\u002Fdiv>\n      ))}\n    \u003C\u002Fdiv>\n  );\n}\n```\n\n## Development vs Production\n\nAlways use `npx convex dev` during development. It runs against your personal\ndev deployment and syncs code on save.\n\nWhen ready to ship, deploy to production:\n\n```bash\nnpx convex deploy\n```\n\nThis pushes to the production deployment, which is separate from dev. Do not use\n`deploy` during development.\n\n## Next Steps\n\n- Add authentication: use the `convex-setup-auth` skill\n- Design your schema: see\n  [Schema docs](https:\u002F\u002Fdocs.convex.dev\u002Fdatabase\u002Fschemas)\n- Build components: use the `convex-create-component` skill\n- Plan a migration: use the `convex-migration-helper` skill\n- Add file storage: see\n  [File Storage docs](https:\u002F\u002Fdocs.convex.dev\u002Ffile-storage)\n- Set up cron jobs: see [Scheduling docs](https:\u002F\u002Fdocs.convex.dev\u002Fscheduling)\n\n## Checklist\n\n- [ ] Determined starting point: new project or existing app\n- [ ] If new project: scaffolded with `npm create convex@latest` using\n      appropriate template\n- [ ] If existing app: installed `convex` and wired up the provider\n- [ ] Agent ran `npx convex dev --once`: deployment provisioned, code pushed,\n      typecheck clean\n- [ ] `npm run dev` (or `npx convex dev` for the watcher alone) is running —\n      user-launched terminal, or background for cloud agents\n- [ ] `convex\u002F_generated\u002F` directory exists with types\n- [ ] `.env.local` has the deployment URL\n- [ ] Verified a basic query\u002Fmutation round-trip works\n",{"name":5,"description":7},"main","e0702036cb52e7ea4069290826f12c74e8416c42",".claude\u002Fskills\u002Fconvex-quickstart","https:\u002F\u002Fgithub.com\u002Fjackwynne\u002Ffinance-tracking","https:\u002F\u002Ffinance-tracking-wine.vercel.app","https:\u002F\u002Fgithub.com\u002Fjackwynne","2026-10-03 09:46:58",{"source":8,"skillName":5,"commands":31,"prompt":41,"zipAvailable":42},[32,35,38],{"tool":33,"command":34},"npx","npx skills add jackwynne\u002Ffinance-tracking --skill convex-quickstart",{"tool":36,"command":37},"bunx","bunx skills add jackwynne\u002Ffinance-tracking --skill convex-quickstart",{"tool":39,"command":40},"pnpm","pnpm dlx skills add jackwynne\u002Ffinance-tracking --skill convex-quickstart","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fjackwynne\u002Ffinance-tracking\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fconvex-quickstart\u002FSKILL.md",true,[44,50],{"path":45,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":48,"sourceHtmlUrl":49},"agents\u002Fopenai.yaml","REFERENCE","参考文档",477,"https:\u002F\u002Fgithub.com\u002Fjackwynne\u002Ffinance-tracking\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fconvex-quickstart\u002Fagents\u002Fopenai.yaml",{"path":51,"resourceType":52,"resourceTypeDesc":53,"sizeBytes":54,"sourceHtmlUrl":55},"assets\u002Ficon.svg","ASSET","资产文件",435,"https:\u002F\u002Fgithub.com\u002Fjackwynne\u002Ffinance-tracking\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fconvex-quickstart\u002Fassets\u002Ficon.svg",[57,64,71,78,85,92],{"skillNo":58,"name":59,"nameZh":6,"description":60,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":61,"categories":62,"keywords":63,"publishedAt":18},"01M79C2ZP0JW4JE4RJ2WPK3MWE","finance-updates","Review Koru spending, bank exports, dated holdings and monthly purchase emails, then prepare proposals for the user's review. Use with a Koru review bundle or connected Koru MCP tools.","https:\u002F\u002Fgithub.com\u002Fjackwynne\u002Ffinance-tracking\u002Fblob\u002Fmain\u002Fplugins\u002Fkoru\u002Fskills\u002Ffinance-updates\u002FSKILL.md",[],[],{"skillNo":65,"name":66,"nameZh":6,"description":67,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":68,"categories":69,"keywords":70,"publishedAt":18},"01M79C2XPQ5EASBQKAWTW8PCRD","convex","Routes general Convex requests to the right project skill. Use when the user asks which Convex skill to use or gives an underspecified Convex app task.","https:\u002F\u002Fgithub.com\u002Fjackwynne\u002Ffinance-tracking\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fconvex\u002FSKILL.md",[],[],{"skillNo":72,"name":73,"nameZh":6,"description":74,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":75,"categories":76,"keywords":77,"publishedAt":18},"01M79C2V0EVRQ82YA2GXGGJX4C","convex-setup-auth","Sets up Convex auth, identity mapping, and access control. Use for login, auth providers, users tables, protected functions, or roles in a Convex app.","https:\u002F\u002Fgithub.com\u002Fjackwynne\u002Ffinance-tracking\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fconvex-setup-auth\u002FSKILL.md",[],[],{"skillNo":79,"name":80,"nameZh":6,"description":81,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":82,"categories":83,"keywords":84,"publishedAt":18},"01M79C2KH6CEQ9CA2G8QA3PBST","convex-performance-audit","Audits Convex performance for reads, subscriptions, write contention, and function limits. Use for slow features, insights findings, OCC conflicts, or read amplification.","https:\u002F\u002Fgithub.com\u002Fjackwynne\u002Ffinance-tracking\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fconvex-performance-audit\u002FSKILL.md",[],[],{"skillNo":86,"name":87,"nameZh":6,"description":88,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":89,"categories":90,"keywords":91,"publishedAt":18},"01M79C2FDTVEFFDZM2W9FXPEAD","convex-migration-helper","Plans Convex schema and data migrations with widen-migrate-narrow and @convex-dev\u002Fmigrations. Use for breaking schema changes, backfills, table reshaping, or zero-downtime rollouts.","https:\u002F\u002Fgithub.com\u002Fjackwynne\u002Ffinance-tracking\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fconvex-migration-helper\u002FSKILL.md",[],[],{"skillNo":93,"name":94,"nameZh":6,"description":95,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":96,"categories":97,"keywords":98,"publishedAt":18},"01M79C2CAM7Y9WS7C29X0J0MPF","convex-create-component","Builds reusable Convex components with isolated tables and app-facing APIs. Use for new components, reusable backend modules, integrations, or component boundary work.","https:\u002F\u002Fgithub.com\u002Fjackwynne\u002Ffinance-tracking\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fconvex-create-component\u002FSKILL.md",[],[]]