convex-nextjs

📁 tristanmanchester/agent-skills 📅 9 days ago

总安装量

周安装量

#31863

全站排名

安装命令

npx skills add https://github.com/tristanmanchester/agent-skills --skill convex-nextjs

Agent 安装分布

amp 9

github-copilot 9

codex 9

kimi-cli 9

gemini-cli 9

opencode 9

Skill 文档

Convex + Next.js skill

What this skill optimises for

End-to-end features: schema â functions â UI wiring, with type safety.
Correct Next.js boundaries: keep reactive Convex hooks in Client Components; use convex/nextjs helpers for SSR/server code.
Low surprise deployments: predictable environment variables and convex deploy flows.

Default choices (override if the user says otherwise)

Next.js App Router + TypeScript (Pages Router still supported).
Reactive UI via ConvexReactClient + <ConvexProvider> + hooks.
Validation-first Convex functions: always define args validators and basic access control for any public function.

Workflow 0 â Decide the starting point

Brand new project? Prefer npm create convex@latest (template-based scaffolding).
Existing Next.js app? Add Convex via npm install convex + npx convex dev.
Cloud coding agent / no login possible? Use Agent Mode or local deployments (see references/07-agent-mode-and-local-dev.md).

Workflow 1 â Add Convex to a Next.js app (App Router)

Step 1: Install and initialise Convex

Run:

npm install convex
npx convex dev

Expected results:

Prompts you to log in, create/select a project, and writes your deployment URLs.
Creates a convex/ directory for backend functions.
Keeps running to sync code to your dev deployment.

Step 1b (optional): Seed sample data + expose a first query

If you want a known-good end-to-end smoke test:

Create sampleData.jsonl:

{"text":"Buy groceries","isCompleted":true}
{"text":"Go for a swim","isCompleted":true}
{"text":"Integrate Convex","isCompleted":false}

Import it into a tasks table:

npx convex import --table tasks sampleData.jsonl

Add a query at convex/tasks.ts:

import { query } from "./_generated/server";

export const get = query({
  args: {},
  handler: async (ctx) => {
    return await ctx.db.query("tasks").collect();
  },
});

Step 2: Create a client provider (Client Component)

Create app/ConvexClientProvider.tsx:

"use client";

import { ConvexProvider, ConvexReactClient } from "convex/react";
import type { 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>;
}

Step 3: Wrap your app layout

In app/layout.tsx, wrap the children:

import { ConvexClientProvider } from "./ConvexClientProvider";

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

Step 4: Call your first query from a Client Component

Only call useQuery/useMutation/useAction in files with "use client".
Use the generated api object from convex/_generated/api.

Example:

"use client";
import { useQuery } from "convex/react";
import { api } from "@/convex/_generated/api";

export function Tasks() {
  const tasks = useQuery(api.tasks.get);
  if (tasks === undefined) return <div>Loadingâ¦</div>;
  return <ul>{tasks.map((t) => <li key={t._id}>{t.text}</li>)}</ul>;
}

Workflow 2 â Build a feature end-to-end (schema â functions â UI)

Copy/paste checklist:

Define or update tables and indexes in convex/schema.ts.
Implement queries for reads and mutations for writes (use args validators).
Keep npx convex dev running to regenerate convex/_generated/*.
Call functions from UI using useQuery / useMutation.
Add access control and validate user input for any function callable from clients.

Minimal table + query + mutation pattern

Schema and indexes: see references/02-schema-and-indexes.md
Function patterns: see references/03-functions.md

Workflow 3 â SSR, Server Components, Server Actions (optional)

Use this when you need a faster first paint or want server-only routes:

Reactive after load: preloadQuery in a Server Component + usePreloadedQuery in a Client Component.
Server-only (non-reactive): fetchQuery in a Server Component.
Server Actions / Route Handlers: fetchMutation / fetchAction.

Key constraints:

convex/nextjs helpers assume NEXT_PUBLIC_CONVEX_URL is set, or you pass an explicit url option.
Avoid multiple preloadQuery calls in the same page if you need consistency (see docs caveat).

Details + copy/paste examples:

references/04-nextjs-ssr-and-server.md

Workflow 4 â Authentication (client-only vs server+client)

Client-only auth (simplest):
- Wrap the provider with your auth provider + a ConvexProviderWithâ¦ adapter.
- Use <Authenticated>, <Unauthenticated>, <AuthLoading> from convex/react for UI gates.
Server + client auth (App Router SSR / Server Actions):
- Use your providerâs Next.js SDK to obtain a JWT on the server.
- Pass { token } as the third argument to preloadQuery / fetchQuery.

Details:

references/05-auth.md

Workflow 5 â Deploy (production + previews)

Default production deploy

npx convex deploy

Vercel (recommended)

Set Vercel Build Command to:

npx convex deploy --cmd 'npm run build'

and configure CONVEX_DEPLOY_KEY in Vercel environment variables.

Details:

references/06-deployment-vercel.md

Validation loop (fast sanity checks)

When working in an existing repo:

Make changes

Run the validator:

python {baseDir}/scripts/validate_project.py --root .

Fix any errors/warnings before moving on.

THE EXACT PROMPT â Implement a Convex-backed feature in Next.js

Copy/paste into a coding agent:

You are implementing a feature using Convex in a Next.js (App Router) app.

Requirements:
1) Update convex/schema.ts (tables + indexes) as needed.
2) Add Convex functions (queries/mutations/actions) with argument validators.
3) Keep reactive data fetching in Client Components using convex/react hooks.
4) If SSR is requested, use convex/nextjs preloadQuery + usePreloadedQuery.
5) Include basic access control for any function callable from the client.
6) Ensure convex/_generated is up-to-date (assume npx convex dev is running).

Deliver:
- Exact file paths + code diffs
- Short usage notes (how to run, what env vars are needed)
- Quick test plan (1-3 smoke tests)

Quick search (when debugging)

# Find Convex calls in the frontend
rg "useQuery\(|useMutation\(|useAction\(" .

# Find Convex functions
ls convex

GitHub 仓库 ↗ ← 返回陌讯 Skills 聚合平台