1---
2name: convex-deploy
3description: |-
4 Implement Convex deployment workflows, environments, and CI/CD configuration. Use for dev/prod/preview
5 deployments, deploy keys, local deployments, environment variables, schema/index rollout safety,
6 and HTTP action URLs. Use proactively when users mention deploy, preview, staging, CI, env vars,
7 or local backend.
8
9 Examples:
10 - user: "Set up Convex deploy in CI" → configure deploy key + npx convex deploy steps
11 - user: "How do preview deployments work?" → explain preview keys, lifecycle, limits
12 - user: "Deploy to prod safely" → list safe schema/function change patterns
13 - user: "Use local convex" → explain npx convex dev --local and limitations
14metadata:
15 source: https://skillmd.com/skills/igorwarzocha/convex-deploy
16---
17
18<overview>
19Cover deployment lifecycle, environments, and safe rollout strategies for Convex backends and full-stack apps.
20</overview>
21
22<context name="Deployment Concepts">
23- Model: one prod deployment per project, one dev deployment per team member, preview deployments per branch.
24- Preview deployments are beta and auto-cleaned; data seeding requires `--preview-run`.
25- Local deployments: `npx convex dev --local --once`, no public URL, Node actions require Node 18.
26- Agent Mode: Use `CONVEX_AGENT_MODE=anonymous` for AI coding agents to limit permissions during development.
27- Env vars are per-deployment; system vars `CONVEX_CLOUD_URL` and `CONVEX_SITE_URL`.
28- Safe change rules: schema MUST match data; use optional/backfill/union migrations; keep functions backwards compatible; scheduled args MUST remain valid.
29- Project config: `convex.json` CAN change functions path, node runtime; static codegen is beta.
30- Pausing deployments returns errors for new calls, queues scheduled jobs, skips crons; You SHOULD test on dev first.
31</context>
32
33<rules>
34
35### Deployment Operations
36- Core commands: `npx convex dev`, `npx convex deploy`, `npx convex codegen`, `npx convex run` (use `--prod` for prod).
37- Agent Mode: You SHOULD use `CONVEX_AGENT_MODE=anonymous npx convex dev --once` when iterating as an AI agent to safely generate codegen artifacts.
38- Deploy target resolution: `CONVEX_DEPLOY_KEY` overrides, else uses production of `CONVEX_DEPLOYMENT` project.
39- Build step: `npx convex deploy --cmd "npm run build"` and `--cmd-url-env-var-name` if needed.
40- Deploy keys: production, preview, dev, admin (You MUST NOT commit/log).
41- Hosting flows:
42 - Vercel/Netlify build command SHOULD use `npx convex deploy --cmd 'npm run build'`.
43 - You MUST set `CONVEX_DEPLOY_KEY` per environment (Preview vs Production).
44 - Preview seeding via `--preview-run 'functionName'`.
45 - Custom hosting: deploy backend, host frontend elsewhere; custom domains require overriding `CONVEX_CLOUD_URL` and redeploying; optional `CONVEX_SITE_URL`.
46
47### Required Outputs
48- You MUST use exact CLI commands and flags from docs.
49- You MUST state target deployment resolution (deploy key vs CONVEX_DEPLOYMENT).
50- You MUST call out deploy-side effects: schema validation, index backfill, codegen, bundling.
51- You SHOULD always mention `.convex.site` vs `.convex.cloud` URL usage where relevant.
52
53### Deployment Model
54- Each project has one production deployment and one cloud dev deployment per team member.
55- Preview deployments are per-branch and are auto-cleaned after a time window.
56- Local deployments are dev-only and run as subprocesses of `npx convex dev`.
57
58### CLI Workflow
59
60#### Dev
61- `npx convex dev`:
62 - Watches files, pushes changes to dev deployment.
63 - Regenerates `convex/_generated/*`.
64 - You SHOULD use `--tail-logs` to control log output.
65- Local dev:
66 - `npx convex dev --local --once` for local backend.
67 - Note: No public URL; HTTP requests need a proxy (e.g., ngrok).
68 - Node actions require Node 18 locally.
69
70#### Deploy
71- `npx convex deploy`:
72 - Typechecks functions.
73 - Regenerates codegen.
74 - Bundles and pushes functions, schema, and indexes.
75- Deploy target resolution:
76 - If `CONVEX_DEPLOY_KEY` is set, deploys to that key's target.
77 - Else uses the production deployment of `CONVEX_DEPLOYMENT`'s project.
78- Optional build command:
79 - `npx convex deploy --cmd "npm run build"`
80 - Use `--cmd-url-env-var-name` to customize env var name.
81
82### Deploy Keys
83- Production deploy key: targets project production deployment (typical CI).
84- Preview deploy key: creates preview deployment per branch.
85- Dev deploy key: scoped to a single dev deployment.
86- Admin key: full control; used for anonymous local deployments.
87- **Security**: You MUST NOT paste deploy keys into code or commit history.
88
89### Preview Deployments
90- Beta feature, lifecycle auto-cleans (5 days default).
91- Preview deployment name is tied to branch; redeploy replaces previous preview.
92- Data seeding requires running a function during deploy (`--preview-run`).
93
94### Environment Variables
95- You MUST set per-deployment via dashboard or `npx convex env`.
96- Same key MAY require values in both dev and prod.
97- System vars:
98 - `CONVEX_CLOUD_URL` for client RPCs.
99 - `CONVEX_SITE_URL` for HTTP actions.
100- You MUST NOT branch exports on `process.env` at runtime; functions set at deploy time.
101
102### Safe Rollout Rules
103- Schema MUST match existing data; deploy blocks on validation failures.
104- Safe schema changes:
105 - Add tables.
106 - Add optional fields, backfill, then make required.
107 - Widen via `v.union`, backfill, then narrow.
108- Functions MUST remain backward compatible while old clients are running.
109- Scheduled functions MUST accept previously scheduled args.
110
111### Index Backfill
112- New indexes backfill during deploy; CAN slow production push.
113- You SHOULD use staged indexes (including search/vector) for large tables.
114- Removing indexes deletes them on deploy; You MUST ensure no code paths depend on them.
115
116### URLs
117- HTTP actions: `https://<deployment>.convex.site`.
118- Client URLs: `https://<deployment>.convex.cloud` (via `CONVEX_CLOUD_URL`).
119- You SHOULD warn about mixing `.convex.site` and `.convex.cloud`.
120
121### Response Checklist
122- [ ] State environment (dev/prod/preview/local).
123- [ ] Provide exact commands and required env vars.
124- [ ] List safety considerations (schema, functions, scheduled).
125- [ ] Mention logs location (CLI or dashboard) when troubleshooting.
126
127</rules>