Convex Quickstart
Bootstrap a new Convex backend or add Convex to an existing React, Next.js, Vue, or Svelte app and verify dev with one-shot provisioning.
Overview
Convex Quickstart is an agent skill for the Build phase that scaffolds or adds Convex and validates setup with npx convex dev --once before full local dev.
Install
npx skills add https://github.com/get-convex/agent-skills --skill convex-quickstartWhat is this skill?
- Six-step workflow: starting point, scaffold or install, npx convex dev --once, combined dev script, verification
- Supports npm create convex@latest for greenfield apps and convex package install for brownfield frontends
- npx convex dev --once provisions anonymous deployment, pushes convex/, typechecks, and regenerates types in one exit
- Explicit when-not-to-use: skip if convex/ already exists; use convex-setup-auth for auth-only adds
- 6-step workflow including verify setup
Adoption & trust: 62.6k installs on skills.sh; 31 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You want Convex in your app but stall on create vs install paths, env vars, and whether your convex/ folder actually typechecks against a deployment.
Who is it for?
First-time Convex adopters on React/Next/Vue/Svelte stacks who need a deterministic bootstrap checklist.
Skip if: Repos that already have convex/ and a working dev loop, or tasks that only add OAuth or auth providers to an existing Convex app.
When should I use this skill?
Starting a new Convex project, adding Convex to an existing app, or scaffolding Convex for prototyping; not when convex/ already exists or only auth is needed.
What do I get? / Deliverables
You end with a provisioned Convex project, pushed functions, regenerated types, and a verified dev command ready for feature work—or a clear signal to use convex-setup-auth instead.
- Installed Convex dependency and provider wiring
- Validated convex/ folder after npx convex dev --once with regenerated types
Recommended Skills
Journey fit
Build is the right shelf because the skill scaffolds backend infrastructure and local dev wiring before ship or launch work. Backend matches npm create convex, convex/ functions, schema push, and type generation—not frontend polish alone.
How it compares
Use for one-time Convex project bootstrap, not as a replacement for Convex auth-only or deep schema migration skills.
Common Questions / FAQ
Who is convex-quickstart for?
Indie builders and small teams bringing Convex online for the first time on a web frontend stack who want official scaffolding steps instead of ad-hoc copy-paste.
When should I use convex-quickstart?
Use it in Build when creating a new Convex app, adding Convex to an existing SPA or full-stack framework, or prototyping before you write business logic.
Is convex-quickstart safe to install?
Check the Security Audits panel on this Prism page; the workflow runs npm/npx and may touch cloud Convex deployments during dev --once.
SKILL.md
READMESKILL.md - Convex Quickstart
# 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 1. Determine the starting point: new project or existing app 2. If new project, pick a template and scaffold with `npm create convex@latest` 3. If existing app, install `convex` and wire up the provider 4. 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. 5. 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. 6. 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: ```bash 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: ```bash 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): ```bash 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: ```bash 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: ```bash 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 i