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` to connect a deployment and start the dev loop
315. Verify the setup works
32 
33## Path 1: New Project (Recommended)
34 
35Use the official scaffolding tool. It creates a complete project with the
36frontend framework, Convex backend, and all config wired together.
37 
38### Pick a template
39 
40| Template                   | Stack                                     |
41| -------------------------- | ----------------------------------------- |
42| `react-vite-shadcn`        | React + Vite + Tailwind + shadcn/ui       |
43| `nextjs-shadcn`            | Next.js App Router + Tailwind + shadcn/ui |
44| `react-vite-clerk-shadcn`  | React + Vite + Clerk auth + shadcn/ui     |
45| `nextjs-clerk`             | Next.js + Clerk auth                      |
46| `nextjs-convexauth-shadcn` | Next.js + Convex Auth + shadcn/ui         |
47| `nextjs-lucia-shadcn`      | Next.js + Lucia auth + shadcn/ui          |
48| `bare`                     | Convex backend only, no frontend          |
49 
50If the user has not specified a preference, default to `react-vite-shadcn` for
51simple apps or `nextjs-shadcn` for apps that need SSR or API routes.
52 
53You can also use any GitHub repo as a template:
54 
55```bash
56npm create convex@latest my-app -- -t owner/repo
57npm create convex@latest my-app -- -t owner/repo#branch
58```
59 
60### Scaffold the project
61 
62Always pass the project name and template flag to avoid interactive prompts:
63 
64```bash
65npm create convex@latest my-app -- -t react-vite-shadcn
66cd my-app
67npm install
68```
69 
70The scaffolding tool creates files but does not run `npm install`, so you must
71run it yourself.
72 
73To scaffold in the current directory (if it is empty):
74 
75```bash
76npm create convex@latest . -- -t react-vite-shadcn
77npm install
78```
79 
80### Start the dev loop
81 
82`npx convex dev` is a long-running watcher process that syncs backend code to a
83Convex deployment on every save. It also requires authentication on first run
84(browser-based OAuth). Both of these make it unsuitable for an agent to run
85directly.
86 
87**Ask the user to run this themselves:**
88 
89Tell the user to run `npx convex dev` in their terminal. On first run it will
90prompt them to log in or develop anonymously. Once running, it will:
91 
92- Create a Convex project and dev deployment
93- Write the deployment URL to `.env.local`
94- Create the `convex/` directory with generated types
95- Watch for changes and sync continuously
96 
97The user should keep `npx convex dev` running in the background while you work
98on code. The watcher will automatically pick up any files you create or edit in
99`convex/`.
100 
101**Exception - cloud or headless agents:** Environments that cannot open a
102browser for interactive login should use Agent Mode (see below) to run
103anonymously without user interaction.
104 
105### Start the frontend
106 
107The user should also run the frontend dev server in a separate terminal:
108 
109```bash
110npm run dev
111```
112 
113Vite apps serve on `http://localhost:5173`, Next.js on `http://localhost:3000`.
114 
115### What you get
116 
117After scaffolding, the project structure looks like:
118 
119```
120my-app/
121  convex/           # Backend functions and schema
122    _generated/     # Auto-generated types (check this into git)
123    schema.ts       # Database schema (if template includes one)
124  src/              # Frontend code (or app/ for Next.js)
125  package.json
126  .env.local        # CONVEX_URL / VITE_CONVEX_URL / NEXT_PUBLIC_CONVEX_URL
127```
128 
129The template already has:
130 
131- `ConvexProvider` wired into the app root
132- Correct env var names for the framework
133- Tailwind and shadcn/ui ready (for shadcn templates)
134- Auth provider configured (for auth templates)
135 
136Proceed to adding schema, functions, and UI.
137 
138## Path 2: Add Convex to an Existing App
139 
140Use this when the user already has a frontend project and wants to add Convex as
141the backend.
142 
143### Install
144 
145```bash
146npm install convex
147```
148 
149### Initialize and start dev loop
150 
151Ask the user to run `npx convex dev` in their terminal. This handles login,
152creates the `convex/` directory, writes the deployment URL to `.env.local`, and
153starts the file watcher. See the notes in Path 1 about why the agent should not
154run this directly.
155 
156### Wire up the provider
157 
158The Convex client must wrap the app at the root. The setup varies by framework.
159 
160Create the `ConvexReactClient` at module scope, not inside a component:
161 
162```tsx
163// Bad: re-creates the client on every render
164function App() {
165  const convex = new ConvexReactClient(
166    import.meta.env.VITE_CONVEX_URL as string,
167  );
168  return <ConvexProvider client={convex}>...</ConvexProvider>;
169}
170 
171// Good: created once at module scope
172const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL as string);
173function App() {
174  return <ConvexProvider client={convex}>...</ConvexProvider>;
175}
176```
177 
178#### React (Vite)
179 
180```tsx
181// src/main.tsx
182import { StrictMode } from "react";
183import { createRoot } from "react-dom/client";
184import { ConvexProvider, ConvexReactClient } from "convex/react";
185import App from "./App";
186 
187const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL as string);
188 
189createRoot(document.getElementById("root")!).render(
190  <StrictMode>
191    <ConvexProvider client={convex}>
192      <App />
193    </ConvexProvider>
194  </StrictMode>,
195);
196```
197 
198#### Next.js (App Router)
199 
200```tsx
201// app/ConvexClientProvider.tsx
202"use client";
203 
204import { ConvexProvider, ConvexReactClient } from "convex/react";
205import { ReactNode } from "react";
206 
207const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL!);
208 
209export function ConvexClientProvider({ children }: { children: ReactNode }) {
210  return <ConvexProvider client={convex}>{children}</ConvexProvider>;
211}
212```
213 
214```tsx
215// app/layout.tsx
216import { ConvexClientProvider } from "./ConvexClientProvider";
217 
218export default function RootLayout({
219  children,
220}: {
221  children: React.ReactNode;
222}) {
223  return (
224    <html lang="en">
225      <body>
226        <ConvexClientProvider>{children}</ConvexClientProvider>
227      </body>
228    </html>
229  );
230}
231```
232 
233#### Other frameworks
234 
235For Vue, Svelte, React Native, TanStack Start, Remix, and others, follow the
236matching quickstart guide:
237 
238- [Vue](https://docs.convex.dev/quickstart/vue)
239- [Svelte](https://docs.convex.dev/quickstart/svelte)
240- [React Native](https://docs.convex.dev/quickstart/react-native)
241- [TanStack Start](https://docs.convex.dev/quickstart/tanstack-start)
242- [Remix](https://docs.convex.dev/quickstart/remix)
243- [Node.js (no frontend)](https://docs.convex.dev/quickstart/nodejs)
244 
245### Environment variables
246 
247The env var name depends on the framework:
248 
249| Framework    | Variable                 |
250| ------------ | ------------------------ |
251| Vite         | `VITE_CONVEX_URL`        |
252| Next.js      | `NEXT_PUBLIC_CONVEX_URL` |
253| Remix        | `CONVEX_URL`             |
254| React Native | `EXPO_PUBLIC_CONVEX_URL` |
255 
256`npx convex dev` writes the correct variable to `.env.local` automatically.
257 
258## Agent Mode (Cloud and Headless Agents)
259 
260When running in a cloud or headless agent environment where interactive browser
261login is not possible, set `CONVEX_AGENT_MODE=anonymous` to use a local
262anonymous deployment.
263 
264Add `CONVEX_AGENT_MODE=anonymous` to `.env.local`, or set it inline:
265 
266```bash
267CONVEX_AGENT_MODE=anonymous npx convex dev
268```
269 
270This runs a local Convex backend on the VM without requiring authentication, and
271avoids conflicting with the user's personal dev deployment.
272 
273## Verify the Setup
274 
275After setup, confirm everything is working:
276 
2771. The user confirms `npx convex dev` is running without errors
2782. The `convex/_generated/` directory exists and has `api.ts` and `server.ts`
2793. `.env.local` contains the deployment URL
280 
281## Writing Your First Function
282 
283Once the project is set up, create a schema and a query to verify the full loop
284works.
285 
286`convex/schema.ts`:
287 
288```ts
289import { defineSchema, defineTable } from "convex/server";
290import { v } from "convex/values";
291 
292export default defineSchema({
293  tasks: defineTable({
294    text: v.string(),
295    completed: v.boolean(),
296  }),
297});
298```
299 
300`convex/tasks.ts`:
301 
302```ts
303import { query, mutation } from "./_generated/server";
304import { v } from "convex/values";
305 
306export const list = query({
307  args: {},
308  handler: async (ctx) => {
309    return await ctx.db.query("tasks").collect();
310  },
311});
312 
313export const create = mutation({
314  args: { text: v.string() },
315  handler: async (ctx, args) => {
316    await ctx.db.insert("tasks", { text: args.text, completed: false });
317  },
318});
319```
320 
321Use in a React component (adjust the import path based on your file location
322relative to `convex/`):
323 
324```tsx
325import { useQuery, useMutation } from "convex/react";
326import { api } from "../convex/_generated/api";
327 
328function Tasks() {
329  const tasks = useQuery(api.tasks.list);
330  const create = useMutation(api.tasks.create);
331 
332  return (
333    <div>
334      <button onClick={() => create({ text: "New task" })}>Add</button>
335      {tasks?.map((t) => (
336        <div key={t._id}>{t.text}</div>
337      ))}
338    </div>
339  );
340}
341```
342 
343## Development vs Production
344 
345Always use `npx convex dev` during development. It runs against your personal
346dev deployment and syncs code on save.
347 
348When ready to ship, deploy to production:
349 
350```bash
351npx convex deploy
352```
353 
354This pushes to the production deployment, which is separate from dev. Do not use
355`deploy` during development.
356 
357## Next Steps
358 
359- Add authentication: use the `convex-setup-auth` skill
360- Design your schema: see
361  [Schema docs](https://docs.convex.dev/database/schemas)
362- Build components: use the `convex-create-component` skill
363- Plan a migration: use the `convex-migration-helper` skill
364- Add file storage: see
365  [File Storage docs](https://docs.convex.dev/file-storage)
366- Set up cron jobs: see [Scheduling docs](https://docs.convex.dev/scheduling)
367 
368## Checklist
369 
370- [ ] Determined starting point: new project or existing app
371- [ ] If new project: scaffolded with `npm create convex@latest` using
372      appropriate template
373- [ ] If existing app: installed `convex` and wired up the provider
374- [ ] User has `npx convex dev` running and connected to a deployment
375- [ ] `convex/_generated/` directory exists with types
376- [ ] `.env.local` has the deployment URL
377- [ ] Verified a basic query/mutation round-trip works
378