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 .agents/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.

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.

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

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

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

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:

registerStaticRoutes(http, components.selfHosting, {
  pathPrefix: "/app",
  spaFallback: true,
});

4) package.json scripts

{
  "scripts": {
    "deploy": "npx @convex-dev/self-hosting deploy",
    "deploy:static": "npx @convex-dev/self-hosting upload --build --prod"
  }
}

Deployment flow

First setup

npm install @convex-dev/self-hosting
npx @convex-dev/self-hosting setup
npx convex dev --once
npm run deploy

Ongoing deploys

npm run deploy

Two step deploy alternative

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