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 to connect a deployment and start the dev loop
5. Verify the setup works

Path 1: New Project (Recommended)

Pick a template

Default to react-vite-shadcn for simple apps or nextjs-shadcn for apps that need SSR or API routes.

Scaffold the project

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

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

Start the dev loop

Ask the user to run npx convex dev in their terminal. On first run it will prompt them to log in or develop anonymously. Once running, it will:

• Create a Convex project and dev deployment
• Write the deployment URL to .env.local
• Create the convex/ directory with generated types
• Watch for changes and sync continuously

Path 2: Add Convex to an Existing App

Install

bashCopy code
npm install convex

Wire up the provider

React (Vite)

tsxCopy code
// 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)

tsxCopy code
// 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>;
}

Environment variables

Writing Your First Function

convex/schema.ts:

tsCopy code
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:

tsCopy code
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:

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

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
• User has npx convex dev running and connected to a deployment
• convex/_generated/ directory exists with types
• .env.local has the deployment URL
• Verified a basic query/mutation round-trip works

Source: https://github.com/get-convex/agent-skills