Ready to supercharge your AI agents?

Install any skill in seconds. Free to start, no credit card required.

Convex Quickstart · kunanonj | DecimalAI

kunanonj/cursor-plugin-convex-convex-quickstart

SkillScore86Maintained

Initialize a new Convex backend from scratch with schema, auth, and basic CRUD operations. Use when starting a new project or adding Convex to an existing app.

codingby kunanonj

Links this skill to your agents and keeps it current with the author’s updates.

Automatic

Coding pack

1 · One-time — install the CLI (docs ↗)

pip install decimalai

2 · Get the skill — writes .claude/skills/kunanonj-cursor-plugin-convex-convex-quickstart/SKILL.md

decimalai skills pull kunanonj-cursor-plugin-convex-convex-quickstart --out .claude/skills/

No CLI? Get the same file — curl · raw file

curl -fsSL --create-dirs -o .claude/skills/kunanonj-cursor-plugin-convex-convex-quickstart/SKILL.md https://app.decimal.ai/s/kunanonj-cursor-plugin-convex-convex-quickstart/SKILL.md

Raw file: /s/kunanonj-cursor-plugin-convex-convex-quickstart/SKILL.md ↗ · machine-readable summary at /s/kunanonj-cursor-plugin-convex-convex-quickstart.json ↗

In productionGlobal

how this skill behaves on real traffic · last 30 days

No production data for this skill yet — usage numbers appear here once agents start running it.

Anonymized aggregate across every org using this skill — proof from real production use, not a demo.

Does this skill help? · Benchmark: with vs. withoutsign in to run this on your agents

22 test cases from the publisher’s eval.yaml · each run twice on gemini-3.6-flash — with the skill injected, then without · last run 51d ago

Yes — +18% lift · at higher cost+161% tokens0% turns86% of whole cases pass with skill (19/22)

Test case	Without → With	Effect	Δ tokens	Δ turns
case-01	✗→✓	▲ Improved	86%	0%
case-02	✗→✓	▲ Improved	67%	0%
case-08	✗→✓	▲ Improved	163%	0%
case-14	✗→✓	▲ Improved	183%	0%
case-03	✓→✓	＝ Same ✓	116%	0%

Showing 5 of 22 cases

SkillSafety

✓ 3 of 3 passed

Code scan15 of 15 checks clean

0 critical · 0 warning · 0 info — scanner v4 — 8/2/2026

live_secretremote_code_executionreverse_shelldata_exfiltrationssrf_metadataagent_snoopinganti_refusaldestructive_commandsobfuscated_unicodeunicode_homoglyphopaque_blobsuspicious_urltool_overreachtrigger_abuseprompt_injection_phrasing

IntentSafe

LLM judge · does the skill do what it claims

ContentClean

LLM judge · policy & harmful-content review

Source

Imported

kunanonj / ai-skills-hub

skills/cursor-plugin-convex-convex-quickstart/SKILL.md

View on GitHub ↗

License MITImported 8/2/2026Version v1

Skill contents

SKILL.md

Convex Quickstart

Get a production-ready Convex backend set up in minutes. This skill guides you through initializing Convex, creating your schema, setting up auth, and building your first CRUD operations.

When to Use

Starting a brand new project with Convex
Adding Convex to an existing React/Next.js app
Prototyping a new feature with real-time data
Converting from another backend to Convex
Teaching someone Convex for the first time

Prerequisites Check

Before starting, verify:

bash
node --version  # v18 or higher
npm --version   # v8 or higher

Quick Start Flow

Step 1: Install and Initialize

bash
# Install Convex
npm install convex

# Initialize (creates convex/ directory)
npx convex dev

This command:

Creates convex/ directory
Sets up authentication
Starts development server
Generates TypeScript types

Step 2: Create Schema

Create convex/schema.ts:

typescript
import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export default defineSchema({
  users: defineTable({
    tokenIdentifier: v.string(),
    name: v.string(),
    email: v.string(),
  }).index("by_token", ["tokenIdentifier"]),

  // Add your tables here
  // Example: Tasks table
  tasks: defineTable({
    userId: v.id("users"),
    title: v.string(),
    completed: v.boolean(),
    createdAt: v.number(),
  })
    .index("by_user", ["userId"])
    .index("by_user_and_completed", ["userId", "completed"]),
});

Step 3: Set Up Authentication

We'll use WorkOS AuthKit, which provides a complete auth solution with minimal setup.

bash
npm install @workos-inc/authkit-react

For React/Vite Apps:

typescript
// src/main.tsx
import { AuthKitProvider, useAuth } from "@workos-inc/authkit-react";
import { ConvexReactClient } from "convex/react";
import { ConvexProvider } from "convex/react";

const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL);

// Configure Convex to use WorkOS auth
convex.setAuth(useAuth);

function App() {
  return (
    <AuthKitProvider clientId={import.meta.env.VITE_WORKOS_CLIENT_ID}>
      <ConvexProvider client={convex}>
        <YourApp />
      </ConvexProvider>
    </AuthKitProvider>
  );
}

For Next.js Apps:

bash
npm install @workos-inc/authkit-nextjs

typescript
// app/layout.tsx
import { AuthKitProvider } from "@workos-inc/authkit-nextjs";
import { ConvexClientProvider } from "./ConvexClientProvider";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <AuthKitProvider>
          <ConvexClientProvider>
            {children}
          </ConvexClientProvider>
        </AuthKitProvider>
      </body>
    </html>
  );
}

typescript
// app/ConvexClientProvider.tsx
"use client";

import { ConvexReactClient } from "convex/react";
import { ConvexProvider } from "convex/react";
import { useAuth } from "@workos-inc/authkit-nextjs";

const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL!);

export function ConvexClientProvider({ children }: { children: React.ReactNode }) {
  const { getToken } = useAuth();

  convex.setAuth(async () => {
    return await getToken();
  });

  return <ConvexProvider client={convex}>{children}</ConvexProvider>;
}

Environment Variables:

bash
# .env.local
VITE_CONVEX_URL=https://your-deployment.convex.cloud
VITE_WORKOS_CLIENT_ID=your_workos_client_id

# For Next.js:
NEXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud
NEXT_PUBLIC_WORKOS_CLIENT_ID=your_workos_client_id
WORKOS_API_KEY=your_workos_api_key
WORKOS_COOKIE_PASSWORD=generate_a_random_32_character_string

Alternative auth providers: If you need to use a different provider (Clerk, Auth0, custom JWT), see the Convex auth documentation.

Step 4: Create Auth Helpers

Create convex/lib/auth.ts:

typescript
import { QueryCtx, MutationCtx } from "../_generated/server";
import { Doc } from "../_generated/dataModel";

export async function getCurrentUser(
  ctx: QueryCtx | MutationCtx
): Promise<Doc<"users">> {
  const identity = await ctx.auth.getUserIdentity();
  if (!identity) {
    throw new Error("Not authenticated");
  }

  const user = await ctx.db
    .query("users")
    .withIndex("by_token", q =>
      q.eq("tokenIdentifier", identity.tokenIdentifier)
    )
    .unique();

  if (!user) {
    throw new Error("User not found");
  }

  return user;
}

Create convex/users.ts:

typescript
import { mutation } from "./_generated/server";

export const store = mutation({
  args: {},
  handler: async (ctx) => {
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) throw new Error("Not authenticated");

    const existing = await ctx.db
      .query("users")
      .withIndex("by_token", q =>
        q.eq("tokenIdentifier", identity.tokenIdentifier)
      )
      .unique();

    if (existing) return existing._id;

    return await ctx.db.insert("users", {
      tokenIdentifier: identity.tokenIdentifier,
      name: identity.name ?? "Anonymous",
      email: identity.email ?? "",
    });
  },
});

Step 5: Create Your First CRUD Operations

Create convex/tasks.ts:

typescript
import { query, mutation } from "./_generated/server";
import { v } from "convex/values";
import { getCurrentUser } from "./lib/auth";

// List all tasks for current user
export const list = query({
  args: {},
  handler: async (ctx) => {
    const user = await getCurrentUser(ctx);
    return await ctx.db
      .query("tasks")
      .withIndex("by_user", q => q.eq("userId", user._id))
      .order("desc")
      .collect();
  },
});

// Get a single task
export const get = query({
  args: { taskId: v.id("tasks") },
  handler: async (ctx, args) => {
    const user = await getCurrentUser(ctx);
    const task = await ctx.db.get(args.taskId);

    if (!task) throw new Error("Task not found");
    if (task.userId !== user._id) throw new Error("Unauthorized");

    return task;
  },
});

// Create a task
export const create = mutation({
  args: { title: v.string() },
  handler: async (ctx, args) => {
    const user = await getCurrentUser(ctx);
    return await ctx.db.insert("tasks", {
      userId: user._id,
      title: args.title,
      completed: false,
      createdAt: Date.now(),
    });
  },
});

// Update a task
export const update = mutation({
  args: {
    taskId: v.id("tasks"),
    title: v.optional(v.string()),
    completed: v.optional(v.boolean()),
  },
  handler: async (ctx, args) => {
    const user = await getCurrentUser(ctx);
    const task = await ctx.db.get(args.taskId);

    if (!task) throw new Error("Task not found");
    if (task.userId !== user._id) throw new Error("Unauthorized");

    const updates: any = {};
    if (args.title !== undefined) updates.title = args.title;
    if (args.completed !== undefined) updates.completed = args.completed;

    await ctx.db.patch(args.taskId, updates);
  },
});

// Delete a task
export const remove = mutation({
  args: { taskId: v.id("tasks") },
  handler: async (ctx, args) => {
    const user = await getCurrentUser(ctx);
    const task = await ctx.db.get(args.taskId);

    if (!task) throw new Error("Task not found");
    if (task.userId !== user._id) throw new Error("Unauthorized");

    await ctx.db.delete(args.taskId);
  },
});

Step 6: Use in Your React App

typescript
// app/tasks/page.tsx
"use client";

import { useQuery, useMutation } from "convex/react";
import { api } from "../../convex/_generated/api";

export default function TasksPage() {
  const tasks = useQuery(api.tasks.list);
  const create = useMutation(api.tasks.create);
  const update = useMutation(api.tasks.update);
  const remove = useMutation(api.tasks.remove);

  if (!tasks) return <div>Loading...</div>;

  return (
    <div>
      <h1>Tasks</h1>

      {/* Create task */}
      <form onSubmit={(e) => {
        e.preventDefault();
        const formData = new FormData(e.target as HTMLFormElement);
        create({ title: formData.get("title") as string });
        (e.target as HTMLFormElement).reset();
      }}>
        <input name="title" placeholder="New task" required />
        <button type="submit">Add</button>
      </form>

      {/* Task list */}
      {tasks.map(task => (
        <div key={task._id}>
          <input
            type="checkbox"
            checked={task.completed}
            onChange={(e) => update({
              taskId: task._id,
              completed: e.target.checked
            })}
          />
          <span>{task.title}</span>
          <button onClick={() => remove({ taskId: task._id })}>
            Delete
          </button>
        </div>
      ))}
    </div>
  );
}

Step 7: Development vs Production

For Development (use this!):

bash
# Start development server (NOT production!)
npx convex dev

# This runs locally and auto-reloads on changes
# Use this for all development work

For Production Deployment:

bash
# ONLY use this when deploying to production!
npx convex deploy

# WARNING: This deploys to your production environment
# Don't use this during development

Important: Always use npx convex dev during development. Only use npx convex deploy when you're ready to ship to production.

Common Patterns

Paginated Queries

typescript
export const listPaginated = query({
  args: {
    cursor: v.optional(v.string()),
    limit: v.number(),
  },
  handler: async (ctx, args) => {
    const user = await getCurrentUser(ctx);

    const results = await ctx.db
      .query("tasks")
      .withIndex("by_user", q => q.eq("userId", user._id))
      .order("desc")
      .paginate({ cursor: args.cursor, limit: args.limit });

    return results;
  },
});

Filtering by Status

typescript
export const listByStatus = query({
  args: {
    completed: v.boolean(),
  },
  handler: async (ctx, args) => {
    const user = await getCurrentUser(ctx);

    return await ctx.db
      .query("tasks")
      .withIndex("by_user_and_completed", q =>
        q.eq("userId", user._id).eq("completed", args.completed)
      )
      .collect();
  },
});

Scheduled Jobs

typescript
// convex/crons.ts
import { cronJobs } from "convex/server";
import { internal } from "./_generated/api";

const crons = cronJobs();

crons.daily(
  "cleanup-old-tasks",
  { hourUTC: 0, minuteUTC: 0 },
  internal.tasks.cleanupOld
);

export default crons;

// convex/tasks.ts
export const cleanupOld = internalMutation({
  handler: async (ctx) => {
    const thirtyDaysAgo = Date.now() - 30 * 24 * 60 * 60 * 1000;
    const oldTasks = await ctx.db
      .query("tasks")
      .filter(q =>
        q.and(
          q.eq(q.field("completed"), true),
          q.lt(q.field("createdAt"), thirtyDaysAgo)
        )
      )
      .collect();

    for (const task of oldTasks) {
      await ctx.db.delete(task._id);
    }
  },
});

Project Templates

React + Vite + Convex

bash
npm create vite@latest my-app -- --template react-ts
cd my-app
npm install convex @workos-inc/authkit-react
npx convex dev

Next.js + Convex

bash
npx create-next-app@latest my-app
cd my-app
npm install convex @workos-inc/authkit-nextjs
npx convex dev

Expo (React Native) + Convex

bash
npx create-expo-app my-app
cd my-app
npm install convex
npx convex dev

Checklist

] npm install convex completed
] npx convex dev running (use this, NOT deploy!)
] Schema created with proper indexes
] Auth provider configured (WorkOS/custom)
] getCurrentUser helper implemented
] User storage mutation created
] CRUD operations with auth checks
] Frontend integrated with hooks
] Tested queries and mutations locally
] When ready for production, use npx convex deploy

Remember: Use npx convex dev for all development work. Only use npx convex deploy when deploying to production!

Next Steps

After quickstart:

Add more tables to schema
Implement relationships between tables
Add file storage (Convex supports file uploads)
Set up vector search for AI features
Add cron jobs for scheduled tasks
Configure production environment variables

Troubleshooting

"Not authenticated" errors

Ensure auth provider is configured
Call storeUser mutation on first sign-in
Check getCurrentUser is imported correctly

Types not updating

Run npx convex dev (regenerates types)
Restart TypeScript server in editor

Slow queries

Add indexes to schema
Use .withIndex() instead of .filter()
Check query patterns in dashboard

Learn More

Illustrative Want to see what kunanonj/cursor-plugin-convex-convex-quickstart would put in front of your model? Preview the rendered body and check its trigger phrases — no LLM call, no signup.

Latest benchmark · publisher runVerified

8/8/2026, 08:17 UTC · 22 cases

Lift

+18%

86% vs 68%

Agent turns

1.0 vs 1.0

Tokens

+161%

5,177.36 vs 1,983.68

fail → pass · 4pass → pass · 15fail → fail · 3

Per-case results (22)

Case	Status	Duration (ms)			Turns			Tokens			Tool calls
Case	Status	Without	With	Δ	Without	With	Δ	Without	With	Δ	Without	With	Δ
case-01 I'm building a Next.js App Router application and need to integrate Convex with WorkOS AuthKit for user login. Can you show me how to structure the client providers file, wrap the root layout, and list the required environment variables for local testing?	fail→pass	11,303	6,375	-44%	1	1	0%	2,817	5,242	+86%	0	0	—
case-02 I want to set up my backend functions in Convex for a multi-user task application. Could you generate a schema with proper database indexes, a utility function to fetch the currently authenticated user, and secure query and mutation endpoints for task management?	fail→pass	13,044	8,304	-36%	1	1	0%	3,568	5,950	+67%	0	0	—
case-03 I need to implement a scheduled background job in Convex that runs daily to purge completed task records that are older than 30 days. How do I configure the crons file and write the corresponding internal mutation?	pass→pass	9,361	4,904	-48%	1	1	0%	2,226	4,800	+116%	0	0	—
case-04 I am actively writing code and changing schemas in my Convex project locally. Should I run npx convex deploy to apply changes while developing? Provide the exact command I should run during local iteration and explain why.	pass→pass	5,276	4,749	-10%	1	1	0%	1,101	4,581	+316%	0	0	—
case-05 I'm connecting a React Vite SPA to Convex and WorkOS AuthKit. I'm tempted to use ConvexProviderWithAuth, but I want to use standard ConvexReactClient and AuthKitProvider directly. Show me the main entry point component setup with proper client initialization and authentication hook wireup.	fail→fail	16,266	7,975	-51%	1	1	0%	3,685	5,722	+55%	0	0	—
case-06 I need to define a schema in Convex for storing user accounts linked to an auth identity. I'm thinking of creating a custom numeric id field or using email as the primary lookup index. What schema definition and index should I write for the users table?	pass→pass	9,135	7,274	-20%	1	1	0%	1,834	5,294	+189%	0	0	—
case-07 When a user logs in via identity auth in Convex, I need a backend endpoint that checks if they exist in the database and creates their user record if missing. Show me how to query user identity using ctx.auth and insert the record.	pass→pass	8,186	7,393	-10%	1	1	0%	1,958	5,622	+187%	0	0	—
case-08 I need a schema in Convex for tasks owned by users, where I frequently filter tasks by user ID and by completion status. Should I rely on runtime .filter() in JavaScript or define schema indexes? Show the schema code.	fail→pass	9,234	5,578	-40%	1	1	0%	1,892	4,969	+163%	0	0	—
case-09 I need a Convex mutation to create a new task titled by the user. I'm thinking of passing the user's ID as an argument from the frontend. Is that secure, or how should user ownership and initial task attributes (completed, createdAt) be assigned?	pass→pass	8,241	6,223	-24%	1	1	0%	2,084	5,069	+143%	0	0	—
case-10 I want to create a task update mutation in Convex that takes optional title and optional completed flags. I'm tempted to overwrite the entire document with ctx.db.replace. How should selective updates be applied securely?	pass→pass	9,043	7,726	-15%	1	1	0%	1,981	5,265	+166%	0	0	—
case-11 Write a task removal mutation in Convex. Should I directly call ctx.db.delete(args.taskId) without checking document ownership, or how should authorization be handled before deleting?	pass→pass	7,794	6,256	-20%	1	1	0%	1,745	5,108	+193%	0	0	—
case-12 I have a large task list in Convex and want to fetch results in pages. Should I manually slice array results with JavaScript .slice(), or how should pagination be declared in a Convex query function?	fail→fail	9,670	5,993	-38%	1	1	0%	1,822	5,069	+178%	0	0	—
case-13 I need a Convex query that returns tasks filtered by completion status for the current user. I'm planning to fetch all user tasks and call array.filter(t => t.completed === args.completed). What index approach should be used instead?	pass→pass	6,781	5,468	-19%	1	1	0%	1,518	4,897	+223%	0	0	—
case-14 Show me a React component for Next.js app router that reads tasks and renders a form to add a task. Should I fetch tasks with standard useEffect and fetch, or how do Convex hooks bind queries and mutations in React?	fail→pass	11,725	11,470	-2%	1	1	0%	2,306	6,526	+183%	0	0	—
case-15 Before installing Convex and running initialization scripts, what minimum Node.js and npm versions are required to ensure local CLI compatibility?	pass→pass	4,629	1,116	-76%	1	1	0%	966	3,865	+300%	0	0	—
case-16 I want to start a brand new React + Vite project with TypeScript and Convex from terminal commands. What exact CLI commands initialize Vite, install Convex and WorkOS auth, and start the development backend?	pass→pass	4,913	4,071	-17%	1	1	0%	1,024	4,456	+335%	0	0	—
case-17 I'm setting up a Next.js project from scratch with Convex and WorkOS auth. What terminal commands create the app, install packages, and start dev mode?	pass→pass	6,434	3,965	-38%	1	1	0%	1,383	4,550	+229%	0	0	—
case-18 My frontend client keeps receiving 'Not authenticated' errors when calling Convex backend queries after signing in with WorkOS AuthKit. What troubleshooting steps should I follow to fix this issue?	fail→fail	12,363	12,316	-0%	1	1	0%	2,618	6,328	+142%	0	0	—
case-19 I added a new table to my Convex schema file, but TypeScript in my React frontend does not recognize the new table names in `api.ts`. How do I resolve stale Convex TypeScript definitions?	pass→pass	7,744	7,871	+2%	1	1	0%	1,640	5,304	+223%	0	0	—
case-20 I have a PostgreSQL database with raw SQL migrations and foreign key constraints between `users` and `orders`. How do I convert a `CREATE TABLE orders (id SERIAL PRIMARY KEY, user_id INT REFERENCES users(id))` SQL script into a Supabase database migration using Supabase CLI?	pass→pass	9,294	7,330	-21%	1	1	0%	1,949	5,445	+179%	0	0	—
case-21 How do I configure a Prisma ORM schema file `schema.prisma` with a `@relation` attribute connecting a `User` model to a `Post` model using PostgreSQL as the provider?	pass→pass	7,290	6,523	-11%	1	1	0%	1,667	5,088	+205%	0	0	—
case-22 How do I configure `clerkMiddleware()` in Next.js App Router using `middleware.ts` to protect routes matching `/dashboard/(.*)` with `@clerk/nextjs`?	pass→pass	9,160	4,674	-49%	1	1	0%	1,857	4,752	+156%	0	0	—

These cases were also screened by the skill’s intent / safety pass.See the Trust review ↗Reproduce this benchmark in Colab ↗

How this skill was measured

DecimalAI ran this skill against gemini-3.6-flash twice over the same eval suite — once with the skill loaded and once without — and compared the two runs case by case. 22 cases were attempted. The headline lift of +18 percentage points is the difference between those two pass rates over the 22 comparable cases.

Model measured: gemini-3.6-flash
Graded by: gemini-3.6-flash
Grading method: judged
Verification: verified
Pass rate without the skill: 68.2%
Pass rate with the skill: 86.4%
Cases attempted: 22
Cases counted toward lift: 22
Cases that regressed: 0
Skill version measured: v1
Run completed: 8/8/2026, 08:17 UTC

Measured example — same prompt, with vs. without the skill · from the benchmark run · case case-01

Prompt

I'm building a Next.js App Router application and need to integrate Convex with WorkOS AuthKit for user login. Can you show me how to structure the client providers file, wrap the root layout, and list the required environment variables for local testing?

Without the skill loaded, the model failed this case. With it loaded, the same prompt on the same model passed. This is one improved case from the latest verified run; every case, including any that regressed, is in the table above.

Show both answers

SkillScore blends 4 signals1 of 4 complete

BenchmarkPass rate WITH skill on a verified run86

Live evalNeeds ≥10 evaluated traces in 30 days

AI ratingNeeds ≥10 rated traces

AdoptionNeeds ≥10 serves across ≥2 orgs in 30 days

Efficiency · separate axis (at equal correctness)+0% turns+197% tokens

Shown for transparency; not credited unless a verified run shows no correctness regression.

Backed by 1 of 4 signals — each added signal makes the score more robust.

Verified on gemini-3.6-flash · re-tested 50 days ago

Other measured skills in the registry, with their headline benchmark lift.