convex-quickstart

Name: convex-quickstart
Author: get-convex

byget-convex· 29 skills

Installs

93k

Stars

Forks

How to install convex-quickstart?

get-convex/agent-skills/convex-quickstart

$npx -y skills add get-convex/agent-skills --skill convex-quickstart

Installs into the current project.

›Prefer a prompt? Paste this to your agent

Use this skill

Run `npx skills use "https://github.com/get-convex/agent-skills" --skill "get-convex/agent-skills/convex-quickstart"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the whole pack

Use the skills in "https://github.com/get-convex/agent-skills" that are relevant to the current task. Run `npx skills add "https://github.com/get-convex/agent-skills"` and select the relevant skills, then follow their instructions.

Files · 1

View on GitHub

SKILL.md

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

6 picks

Type

Run `npx skills use "https://github.com/get-convex/agent-skills" --skill "get-convex/agent-skills/convex-quickstart"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the skills in "https://github.com/get-convex/agent-skills" that are relevant to the current task. Run `npx skills add "https://github.com/get-convex/agent-skills"` and select the relevant skills, then follow their instructions.

convex-quickstart

How to install convex-quickstart?

Related

convex-quickstart

How to install convex-quickstart?

Related