1---
2name: convex-quickstart
3description:
4  Creates or adds Convex to an app. Use for new Convex projects, npm create
5  convex@latest, frontend setup, env vars, or the first npx convex dev run.
6---
7 
8# Convex Quickstart
9 
10Set up a working Convex project as fast as possible.
11 
12## When to Use
13 
14- Starting a brand new project with Convex
15- Adding Convex to an existing React, Next.js, Vue, Svelte, or other app
16- Scaffolding a Convex app for prototyping
17 
18## When Not to Use
19 
20- The project already has Convex installed and `convex/` exists - just start
21  building
22- You only need to add auth to an existing Convex app - use the
23  `convex-setup-auth` skill
24 
25## Workflow
26 
271. Determine the starting point: new project or existing app
282. If new project, pick a template and scaffold with `npm create convex@latest`
293. If existing app, install `convex` and wire up the provider
304. Run `npx convex dev --once` to provision a local anonymous deployment, push
31   the current `convex/` code, typecheck it, and regenerate types — all in one
32   shot, exiting cleanly. The output tells the agent whether the schema and
33   functions are valid.
345. Ask the user (or, for cloud agents, start in the background) `npm run dev` —
35   Convex templates wire the watcher and the frontend into a single command. If
36   the project has no combined dev script, use `npx convex dev` for the watcher
37   and run the frontend separately.
386. Verify the setup works
39 
40## Path 1: New Project (Recommended)
41 
42Use the official scaffolding tool. It creates a complete project with the
43frontend framework, Convex backend, and all config wired together.
44 
45### Pick a template
46 
47| Template                   | Stack                                     |
48| -------------------------- | ----------------------------------------- |
49| `react-vite-shadcn`        | React + Vite + Tailwind + shadcn/ui       |
50| `nextjs-shadcn`            | Next.js App Router + Tailwind + shadcn/ui |
51| `react-vite-clerk-shadcn`  | React + Vite + Clerk auth + shadcn/ui     |
52| `nextjs-clerk`             | Next.js + Clerk auth                      |
53| `nextjs-convexauth-shadcn` | Next.js + Convex Auth + shadcn/ui         |
54| `nextjs-lucia-shadcn`      | Next.js + Lucia auth + shadcn/ui          |
55| `bare`                     | Convex backend only, no frontend          |
56 
57If the user has not specified a preference, default to `react-vite-shadcn` for
58simple apps or `nextjs-shadcn` for apps that need SSR or API routes.
59 
60You can also use any GitHub repo as a template:
61 
62```bash
63npm create convex@latest my-app -- -t owner/repo
64npm create convex@latest my-app -- -t owner/repo#branch
65```
66 
67### Scaffold the project
68 
69Always pass the project name and template flag to avoid interactive prompts:
70 
71```bash
72npm create convex@latest my-app -- -t react-vite-shadcn
73cd my-app
74npm install
75```
76 
77The scaffolding tool creates files but does not run `npm install`, so you must
78run it yourself.
79 
80To scaffold in the current directory (if it is empty):
81 
82```bash
83npm create convex@latest . -- -t react-vite-shadcn
84npm install
85```
86 
87### Provision the deployment and push code
88 
89Run this yourself — it is a one-shot command that exits cleanly:
90 
91```bash
92npx convex dev --once
93```
94 
95In a non-TTY environment (which is true for almost every agent run), this:
96 
97- Provisions an _anonymous_ local Convex backend bound to `127.0.0.1`. No
98  browser login, no team/project prompts.
99- Writes `CONVEX_DEPLOYMENT` and the framework's `*_CONVEX_URL` variables to
100  `.env.local`.
101- Generates `convex/_generated/`.
102- Pushes the current `convex/` code to the deployment, **typechecks it**, and
103  **validates the schema**. The agent reads this output to find out if the code
104  it just wrote is broken.
105 
106To be explicit (recommended), set `CONVEX_AGENT_MODE=anonymous` so the behavior
107does not depend on TTY detection:
108 
109```bash
110CONVEX_AGENT_MODE=anonymous npx convex dev --once
111```
112 
113The deployment lives under `~/.convex/` and persists across runs. Re-running
114`convex dev --once` after editing `convex/` files is the agent's main feedback
115loop while the user-launched `npm run dev` is not in use.
116 
117If the template's `package.json` defines a `predev` script (Convex Auth
118templates and similar do), `npm run predev` runs `convex init` plus any one-time
119setup (e.g. minting auth keys). Use it _in addition to_ `convex dev --once` when
120present — `predev` handles the one-time setup, `convex dev --once` pushes and
121validates the code.
122 
123### Start the dev loop
124 
125In most Convex templates, `npm run dev` runs both the Convex watcher and the
126frontend dev server together (typically `convex dev --start 'vite --open'` or
127the Next.js equivalent). That is what the user should run.
128 
129```bash
130npm run dev
131```
132 
133If the project does not have a combined `dev` script — e.g. the `bare` template,
134or an existing app where you haven't wired the frontend dev server into Convex's
135`--start` flag — the user can run the Convex watcher directly:
136 
137```bash
138npx convex dev
139```
140 
141`npx convex dev` is the same long-running watcher `npm run dev` invokes under
142the hood; it just doesn't start the frontend. Use it when there is no frontend,
143or when the user prefers to run the frontend in a separate terminal.
144 
145Either way, the agent should not invoke the watcher in the foreground because it
146does not exit. Two options:
147 
148- **Local development (user is at the keyboard):** ask the user to run
149  `npm run dev` (or `npx convex dev`) in a terminal. The deployment provisioned
150  by `convex dev --once` above is already selected, so the watcher picks up
151  immediately with no prompts.
152- **Cloud or headless agents:** start `npm run dev` (or `npx convex dev`) in the
153  background.
154 
155Vite apps serve on `http://localhost:5173`, Next.js on `http://localhost:3000`.
156 
157### What you get
158 
159After scaffolding, the project structure looks like:
160 
161```
162my-app/
163  convex/           # Backend functions and schema
164    _generated/     # Auto-generated types (check this into git)
165    schema.ts       # Database schema (if template includes one)
166  src/              # Frontend code (or app/ for Next.js)
167  package.json
168  .env.local        # CONVEX_URL / VITE_CONVEX_URL / NEXT_PUBLIC_CONVEX_URL
169```
170 
171The template already has:
172 
173- `ConvexProvider` wired into the app root
174- Correct env var names for the framework
175- Tailwind and shadcn/ui ready (for shadcn templates)
176- Auth provider configured (for auth templates)
177 
178Proceed to adding schema, functions, and UI.
179 
180## Path 2: Add Convex to an Existing App
181 
182Use this when the user already has a frontend project and wants to add Convex as
183the backend.
184 
185### Install
186 
187```bash
188npm install convex
189```
190 
191### Provision and push
192 
193Run `npx convex dev --once` yourself to provision a local anonymous deployment,
194write `.env.local`, generate types, push the current `convex/` code, and
195typecheck it. This is one-shot and exits:
196 
197```bash
198npx convex dev --once
199```
200 
201The output tells you whether the schema and functions are valid — use it as your
202feedback loop while iterating.
203 
204Then ask the user to start the watcher (or, for cloud/headless agents, start it
205in the background). You have two options:
206 
207- **Wire Convex into `npm run dev`** — change the existing app's `dev` script to
208  `convex dev --start '<existing dev command>'`. That's the standard pattern
209  Convex templates use; the user then runs a single `npm run dev` to start both.
210- **Run them separately** — leave `npm run dev` for the frontend and tell the
211  user to run `npx convex dev` in a second terminal for the Convex watcher.
212 
213See "Start the dev loop" above for why the agent should not run the watcher in
214the foreground.
215 
216### Wire up the provider
217 
218The Convex client must wrap the app at the root. The setup varies by framework.
219 
220Create the `ConvexReactClient` at module scope, not inside a component:
221 
222```tsx
223// Bad: re-creates the client on every render
224function App() {
225  const convex = new ConvexReactClient(
226    import.meta.env.VITE_CONVEX_URL as string,
227  );
228  return <ConvexProvider client={convex}>...</ConvexProvider>;
229}
230 
231// Good: created once at module scope
232const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL as string);
233function App() {
234  return <ConvexProvider client={convex}>...</ConvexProvider>;
235}
236```
237 
238#### React (Vite)
239 
240```tsx
241// src/main.tsx
242import { StrictMode } from "react";
243import { createRoot } from "react-dom/client";
244import { ConvexProvider, ConvexReactClient } from "convex/react";
245import App from "./App";
246 
247const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL as string);
248 
249createRoot(document.getElementById("root")!).render(
250  <StrictMode>
251    <ConvexProvider client={convex}>
252      <App />
253    </ConvexProvider>
254  </StrictMode>,
255);
256```
257 
258#### Next.js (App Router)
259 
260```tsx
261// app/ConvexClientProvider.tsx
262"use client";
263 
264import { ConvexProvider, ConvexReactClient } from "convex/react";
265import { ReactNode } from "react";
266 
267const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL!);
268 
269export function ConvexClientProvider({ children }: { children: ReactNode }) {
270  return <ConvexProvider client={convex}>{children}</ConvexProvider>;
271}
272```
273 
274```tsx
275// app/layout.tsx
276import { ConvexClientProvider } from "./ConvexClientProvider";
277 
278export default function RootLayout({
279  children,
280}: {
281  children: React.ReactNode;
282}) {
283  return (
284    <html lang="en">
285      <body>
286        <ConvexClientProvider>{children}</ConvexClientProvider>
287      </body>
288    </html>
289  );
290}
291```
292 
293#### Other frameworks
294 
295For Vue, Svelte, React Native, TanStack Start, Remix, and others, follow the
296matching quickstart guide:
297 
298- [Vue](https://docs.convex.dev/quickstart/vue)
299- [Svelte](https://docs.convex.dev/quickstart/svelte)
300- [React Native](https://docs.convex.dev/quickstart/react-native)
301- [TanStack Start](https://docs.convex.dev/quickstart/tanstack-start)
302- [Remix](https://docs.convex.dev/quickstart/remix)
303- [Node.js (no frontend)](https://docs.convex.dev/quickstart/nodejs)
304 
305### Environment variables
306 
307The env var name depends on the framework:
308 
309| Framework    | Variable                 |
310| ------------ | ------------------------ |
311| Vite         | `VITE_CONVEX_URL`        |
312| Next.js      | `NEXT_PUBLIC_CONVEX_URL` |
313| Remix        | `CONVEX_URL`             |
314| React Native | `EXPO_PUBLIC_CONVEX_URL` |
315 
316`npx convex dev` writes the correct variable to `.env.local` automatically.
317 
318## Agent Mode
319 
320`CONVEX_AGENT_MODE=anonymous` forces an unauthenticated local backend. It is
321already the implicit default for any non-TTY run of `npx convex init` or
322`npx convex dev`, but set it explicitly so the behavior does not depend on TTY
323detection:
324 
325```bash
326CONVEX_AGENT_MODE=anonymous npx convex dev --once
327```
328 
329Use it for:
330 
331- Any AI coding agent (local or cloud).
332- CI-like setup scripts.
333- Cases where the user is logged in but you do not want to touch their personal
334  dev deployment.
335 
336The resulting backend runs on `127.0.0.1` and is not associated with any team or
337project until the user later claims it via `npx convex login` and the
338`npx convex deployment` commands.
339 
340## Verify the Setup
341 
342After setup, confirm everything is working:
343 
3441. `npx convex dev --once` exited without errors (deployment provisioned, code
345   pushed, schema validated, typecheck clean)
3462. The `convex/_generated/` directory exists and has `api.ts` and `server.ts`
3473. `.env.local` contains a `CONVEX_DEPLOYMENT` value and the framework's
348   `*_CONVEX_URL` variable
3494. (If applicable) `npm run dev` (or `npx convex dev` for the watcher alone) is
350   running without errors in another terminal or in the background
351 
352## Writing Your First Function
353 
354Once the project is set up, create a schema and a query to verify the full loop
355works.
356 
357`convex/schema.ts`:
358 
359```ts
360import { defineSchema, defineTable } from "convex/server";
361import { v } from "convex/values";
362 
363export default defineSchema({
364  tasks: defineTable({
365    text: v.string(),
366    completed: v.boolean(),
367  }),
368});
369```
370 
371`convex/tasks.ts`:
372 
373```ts
374import { query, mutation } from "./_generated/server";
375import { v } from "convex/values";
376 
377export const list = query({
378  args: {},
379  handler: async (ctx) => {
380    return await ctx.db.query("tasks").collect();
381  },
382});
383 
384export const create = mutation({
385  args: { text: v.string() },
386  handler: async (ctx, args) => {
387    await ctx.db.insert("tasks", { text: args.text, completed: false });
388  },
389});
390```
391 
392Use in a React component (adjust the import path based on your file location
393relative to `convex/`):
394 
395```tsx
396import { useQuery, useMutation } from "convex/react";
397import { api } from "../convex/_generated/api";
398 
399function Tasks() {
400  const tasks = useQuery(api.tasks.list);
401  const create = useMutation(api.tasks.create);
402 
403  return (
404    <div>
405      <button onClick={() => create({ text: "New task" })}>Add</button>
406      {tasks?.map((t) => (
407        <div key={t._id}>{t.text}</div>
408      ))}
409    </div>
410  );
411}
412```
413 
414## Development vs Production
415 
416Always use `npx convex dev` during development. It runs against your personal
417dev deployment and syncs code on save.
418 
419When ready to ship, deploy to production:
420 
421```bash
422npx convex deploy
423```
424 
425This pushes to the production deployment, which is separate from dev. Do not use
426`deploy` during development.
427 
428## Next Steps
429 
430- Add authentication: use the `convex-setup-auth` skill
431- Design your schema: see
432  [Schema docs](https://docs.convex.dev/database/schemas)
433- Build components: use the `convex-create-component` skill
434- Plan a migration: use the `convex-migration-helper` skill
435- Add file storage: see
436  [File Storage docs](https://docs.convex.dev/file-storage)
437- Set up cron jobs: see [Scheduling docs](https://docs.convex.dev/scheduling)
438 
439## Checklist
440 
441- [ ] Determined starting point: new project or existing app
442- [ ] If new project: scaffolded with `npm create convex@latest` using
443      appropriate template
444- [ ] If existing app: installed `convex` and wired up the provider
445- [ ] Agent ran `npx convex dev --once`: deployment provisioned, code pushed,
446      typecheck clean
447- [ ] `npm run dev` (or `npx convex dev` for the watcher alone) is running —
448      user-launched terminal, or background for cloud agents
449- [ ] `convex/_generated/` directory exists with types
450- [ ] `.env.local` has the deployment URL
451- [ ] Verified a basic query/mutation round-trip works
452