convex-quickstart

SKILL.md

Convex Quickstart

Set up a working Convex project as fast as possible.

When to Use

Starting a brand new project with Convex

Adding Convex to an existing React, Next.js, Vue, Svelte, or other app

Scaffolding a Convex app for prototyping

When Not to Use

The project already has Convex installed and convex/ exists - just start
building

You only need to add auth to an existing Convex app - use the
convex-setup-auth skill

Workflow

Determine the starting point: new project or existing app

If new project, pick a template and scaffold with npm create convex@latest

If existing app, install convex and wire up the provider

Run npx convex dev --once to provision a local anonymous deployment, push
the current convex/ code, typecheck it, and regenerate types — all in one
shot, exiting cleanly. The output tells the agent whether the schema and
functions are valid.

Ask the user (or, for cloud agents, start in the background) npm run dev —
Convex templates wire the watcher and the frontend into a single command. If
the project has no combined dev script, use npx convex dev for the watcher
and run the frontend separately.

Verify the setup works

Path 1: New Project (Recommended)

Use the official scaffolding tool. It creates a complete project with the
frontend framework, Convex backend, and all config wired together.

Pick a template

Template
Stack

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

nextjs-lucia-shadcn
Next.js + Lucia auth + shadcn/ui

bare
Convex backend only, no frontend

If the user has not specified a preference, default to react-vite-shadcn for
simple apps or nextjs-shadcn for apps that need SSR or API routes.

You can also use any GitHub repo as a template:

npm create convex@latest my-app -- -t owner/repo
npm create convex@latest my-app -- -t owner/repo#branch

Scaffold the project

Always pass the project name and template flag to avoid interactive prompts:

npm create convex@latest my-app -- -t react-vite-shadcn
cd my-app
npm install

The scaffolding tool creates files but does not run npm install, so you must
run it yourself.

To scaffold in the current directory (if it is empty):

npm create convex@latest . -- -t react-vite-shadcn
npm install

Provision the deployment and push code

Run this yourself — it is a one-shot command that exits cleanly:

npx convex dev --once

In a non-TTY environment (which is true for almost every agent run), this:

Provisions an anonymous local Convex backend bound to 127.0.0.1. No
browser login, no team/project prompts.

Writes CONVEX_DEPLOYMENT and the framework's *_CONVEX_URL variables to
.env.local.

Generates convex/_generated/.

Pushes the current convex/ code to the deployment, typechecks it, and
validates the schema. The agent reads this output to find out if the code
it just wrote is broken.

To be explicit (recommended), set CONVEX_AGENT_MODE=anonymous so the behavior
does not depend on TTY detection:

CONVEX_AGENT_MODE=anonymous npx convex dev --once

The deployment lives under ~/.convex/ and persists across runs. Re-running
convex dev --once after editing convex/ files is the agent's main feedback
loop while the user-launched npm run dev is not in use.

If the template's package.json defines a predev script (Convex Auth
templates and similar do), npm run predev runs convex init plus any one-time
setup (e.g. minting auth keys). Use it in addition to convex dev --once when
present — predev handles the one-time setup, convex dev --once pushes and
validates the code.

Start the dev loop

In most Convex templates, npm run dev runs both the Convex watcher and the
frontend dev server together (typically convex dev --start 'vite --open' or
the Next.js equivalent). That is what the user should run.

npm run dev

If the project does not have a combined dev script — e.g. the bare template,
or an existing app where you haven't wired the frontend dev server into Convex's
--start flag — the user can run the Convex watcher directly:

npx convex dev

npx convex dev is the same long-running watcher npm run dev invokes under
the hood; it just doesn't start the frontend. Use it when there is no frontend,
or when the user prefers to run the frontend in a separate terminal.

Either way, the agent should not invoke the watcher in the foreground because it
does not exit. Two options:

Local development (user is at the keyboard): ask the user to run
npm run dev (or npx convex dev) in a terminal. The deployment provisioned
by convex dev --once above is already selected, so the watcher picks up
immediately with no prompts.

Cloud or headless agents: start npm run dev (or npx convex dev) in the
background.

Vite apps serve on http://localhost:5173, Next.js on http://localhost:3000.

What you get

After scaffolding, the project structure looks like:

my-app/
  convex/           # Backend functions and schema
    _generated/     # Auto-generated types (check this into git)
    schema.ts       # Database schema (if template includes one)
  src/              # Frontend code (or app/ for Next.js)
  package.json
  .env.local        # CONVEX_URL / VITE_CONVEX_URL / NEXT_PUBLIC_CONVEX_URL

The template already has:

ConvexProvider wired into the app root

Correct env var names for the framework

Tailwind and shadcn/ui ready (for shadcn templates)

Auth provider configured (for auth templates)

Proceed to adding schema, functions, and UI.

Path 2: Add Convex to an Existing App

Use this when the user already has a frontend project and wants to add Convex as
the backend.

Install

npm install convex

Provision and push

Run npx convex dev --once yourself to provision a local anonymous deployment,
write .env.local, generate types, push the current convex/ code, and
typecheck it. This is one-shot and exits:

npx convex dev --once

The output tells you whether the schema and functions are valid — use it as your
feedback loop while iterating.

Then ask the user to start the watcher (or, for cloud/headless agents, start it
in the background). You have two options:

Wire Convex into npm run dev — change the existing app's dev script to
convex dev --start '<existing dev command>'. That's the standard pattern
Convex templates use; the user then runs a single npm run dev to start both.

Run them separately — leave npm run dev for the frontend and tell the
user to run npx convex dev in a second terminal for the Convex watcher.

See "Start the dev loop" above for why the agent should not run the watcher in
the foreground.

Wire up the provider

The Convex client must wrap the app at the root. The setup varies by framework.

Create the ConvexReactClient at module scope, not inside a component:

// Bad: re-creates the client on every render
function App() {
  const convex = new ConvexReactClient(
    import.meta.env.VITE_CONVEX_URL as string,
  );
  return <ConvexProvider client={convex}>...</ConvexProvider>;
}

// Good: created once at module scope
const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL as string);
function App() {
  return <ConvexProvider client={convex}>...</ConvexProvider>;
}

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>;
}

// app/layout.tsx
import { ConvexClientProvider } from "./ConvexClientProvider";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <ConvexClientProvider>{children}</ConvexClientProvider>
      </body>
    </html>
  );
}

Other frameworks

For Vue, Svelte, React Native, TanStack Start, Remix, and others, follow the
matching quickstart guide:

Vue

Svelte

React Native

TanStack Start

Remix

Node.js (no frontend)

Environment variables

The env var name depends on the framework:

Framework
Variable

Vite
VITE_CONVEX_URL

Next.js
NEXT_PUBLIC_CONVEX_URL

Remix
CONVEX_URL

React Native
EXPO_PUBLIC_CONVEX_URL

npx convex dev writes the correct variable to .env.local automatically.

Agent Mode

CONVEX_AGENT_MODE=anonymous forces an unauthenticated local backend. It is
already the implicit default for any non-TTY run of npx convex init or
npx convex dev, but set it explicitly so the behavior does not depend on TTY
detection:

CONVEX_AGENT_MODE=anonymous npx convex dev --once

Use it for:

Any AI coding agent (local or cloud).

CI-like setup scripts.

Cases where the user is logged in but you do not want to touch their personal
dev deployment.

The resulting backend runs on 127.0.0.1 and is not associated with any team or
project until the user later claims it via npx convex login and the
npx convex deployment commands.

Verify the Setup

After setup, confirm everything is working:

npx convex dev --once exited without errors (deployment provisioned, code
pushed, schema validated, typecheck clean)

The convex/_generated/ directory exists and has api.ts and server.ts

.env.local contains a CONVEX_DEPLOYMENT value and the framework's
*_CONVEX_URL variable

(If applicable) npm run dev (or npx convex dev for the watcher alone) is
running without errors in another terminal or in the background

Writing Your First Function

Once the project is set up, create a schema and a query to verify the full loop
works.

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 });
  },
});

Use in a React component (adjust the import path based on your file location
relative to convex/):

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>
  );
}

Development vs Production

Always use npx convex dev during development. It runs against your personal
dev deployment and syncs code on save.

When ready to ship, deploy to production:

npx convex deploy

This pushes to the production deployment, which is separate from dev. Do not use
deploy during development.

Next Steps

Add authentication: use the convex-setup-auth skill

Design your schema: see
Schema docs

Build components: use the convex-create-component skill

Plan a migration: use the convex-migration-helper skill

Add file storage: see
File Storage docs

Set up cron jobs: see Scheduling docs

Checklist

 Determined starting point: new project or existing app

 If new project: scaffolded with npm create convex@latest using
appropriate template

 If existing app: installed convex and wired up the provider

 Agent ran npx convex dev --once: deployment provisioned, code pushed,
typecheck clean

 npm run dev (or npx convex dev for the watcher alone) is running —
user-launched terminal, or background for cloud agents

 convex/_generated/ directory exists with types

 .env.local has the deployment URL

 Verified a basic query/mutation round-trip works