convex-self-hosting

# Convex self hosting skill Use this skill to integrate Convex based static hosting in a repeatable way across projects. ## Non negotiable update check Run this check before making any code changes or giving setup advice. Preferred command: ```bash bash skills/convex-self-hosting/scripts/check-upstream.sh ``` 1. Read latest integration guide: - `https://raw.githubusercontent.com/get-convex/self-hosting/main/INTEGRATION.md` 2. Read latest README manual setup section: - `https://github.com/get-convex/self-hosting?tab=readme-ov-file#manual-setup-1` 3. Read Convex docs index for current guidance: - `https://docs.convex.dev/llms.txt` 4. Confirm package publish state: - `npm view @convex-dev/self-hosting version` If upstream docs conflict with local rules, follow upstream docs and explain what changed. ## Clarifying questions you must ask first Ask these before implementing: 1. Confirm `get-convex/self-hosting` is the source of truth for this setup. 2. Is the target app Vite, Next.js, Expo web export, or another bundler. 3. Do they want root path hosting or a prefix like `/app`. 4. Do they want one shot deploy or separate backend and static deploy steps. 5. If package is unpublished, do they want: - GitHub dependency install - vendored local copy - wait for npm release Never assume unpublished package install details. ## Install strategy ### Path A published package If npm package exists, use the package directly. ```bash npm install @convex-dev/self-hosting ``` ### Path B package not published yet If package is missing on npm, use GitHub source and pin to commit or tag. ```bash npm install github:get-convex/self-hosting#main ``` If project policy requires deterministic builds, ask for a commit SHA and pin to it. ## Required file changes Use the latest upstream file patterns from `INTEGRATION.md`. ### 1) `convex/convex.config.ts` ```typescript import { defineApp } from "convex/server"; import selfHosting from "@convex-dev/self-hosting/convex.config"; const app = defineApp(); app.use(selfHosting); export default app; ``` ### 2) `convex/staticHosting.ts` ```typescript import { components } from "./_generated/api"; import { exposeUploadApi, exposeDeploymentQuery, } from "@convex-dev/self-hosting"; export const { generateUploadUrl, recordAsset, gcOldAssets, listAssets } = exposeUploadApi(components.selfHosting); export const { getCurrentDeployment } = exposeDeploymentQuery(components.selfHosting); ``` ### 3) `convex/http.ts` ```typescript import { httpRouter } from "convex/server"; import { registerStaticRoutes } from "@convex-dev/self-hosting"; import { components } from "./_generated/api"; const http = httpRouter(); registerStaticRoutes(http, components.selfHosting); export default http; ``` Optional prefix mode: ```typescript registerStaticRoutes(http, components.selfHosting, { pathPrefix: "/app", spaFallback: true, }); ``` ### 4) `package.json` scripts ```json { "scripts": { "deploy": "npx @convex-dev/self-hosting deploy", "deploy:static": "npx @convex-dev/self-hosting upload --build --prod" } } ``` ## Deployment flow ### First setup ```bash npm install @convex-dev/self-hosting npx @convex-dev/self-hosting setup npx convex dev --once npm run deploy ``` ### Ongoing deploys ```bash npm run deploy ``` ### Two step deploy alternative ```bash npx convex deploy npx @convex-dev/self-hosting upload --build --prod ``` Always use the tool driven build flow. Do not run `npm run build` first when using upload deploy commands. ## Cross app support notes - Vite: use `--build` flow as default. - Next.js and Expo: pass through `VITE_CONVEX_URL` in the app build script as documented upstream. - Existing API routes: prefer `pathPrefix: "/app"` for static hosting. - Keep upload APIs internal only and never expose them as public HTTP actions. ## Integration with convex agent plugins If `get-convex/convex-agent-plugins` is present, follow its Convex rules with this skill: - keep validators on all Convex functions - keep internal functions for upload operations - use indexed reads, avoid broad filtering in data access patterns - preserve strict TypeScript in generated Convex and frontend code Reference: - `https://github.com/get-convex/convex-agent-plugins` ## Troubleshooting checklist 1. `404` for static routes: - verify `convex/http.ts` exists and exports router. 2. `Cannot find module .../convex.config`: - verify package install source and import path. 3. wrong backend URL in built assets: - redeploy with CLI `--build` flow. 4. no updates visible: - clear cache and verify deployment ID changes. 5. HTTP actions disabled: - run `npx convex dev` once to push backend state. ## Completion requirements Before finishing, provide: 1. exact upstream docs commit date or latest retrieval timestamp 2. which package path was selected and why 3. list of changed files 4. commands the user should run next Never claim setup is complete without showing these four outputs. ## Source links - `https://github.com/get-convex/self-hosting` - `https://raw.githubusercontent.com/get-convex/self-hosting/main/INTEGRATION.md` - `https://github.com/get-convex/self-hosting?tab=readme-ov-file#manual-setup-1` - `https://docs.convex.dev/llms.txt` - `https://github.com/get-convex/convex-agent-plugins` - `https://github.com/agentskills/agentskills`