Serve static files and server-rendered pages directly from your Convex deployment using Cloudflare Workers asset rules, with a TanStack Start adapter included.
npm install @samebase/convex-hostingThe convex-hosting component (@samebase/convex-hosting) lets you serve static files and server-rendered pages from your Convex deployment at https://<deployment>.convex.site. You mount the component in convex.config.ts, register all routes via routeAll in convex/http.ts, and run npx convex-hosting deploy to build, upload, and push in one step.
The @samebase/convex-hosting-tanstack-start adapter wires TanStack Start into a Convex HTTP action, supporting streamed pages, server functions, server routes, request middleware, and cookie sessions. Pass the app's server entry object (with a fetch method) as the fourth argument to routeAll in convex/http.ts.
convex-hosting runs Cloudflare's asset Worker code inside a Convex HTTP action, so _headers, _redirects, .assetsignore, html_handling, and not_found_handling behave exactly as they do on Cloudflare Workers. The package's CI runs Cloudflare's own conformance tests, covering 196 cases for html_handling and path encoding.
convex-hosting achieves atomic version switching by uploading files as a versioned object in Convex storage, writing the version ID to .convex-hosting/version.js, and importing that file when pushing functions. The push itself is the switch: no pointer moves in a second step, so there is no moment when new code serves old files or references assets not yet uploaded.
Convex's static-hosting component serves files only. convex-hosting (@samebase/convex-hosting) adds server-rendered pages through a fetch handler, uses Cloudflare's asset Worker serving rules (_headers, _redirects, html_handling, not_found_handling), and provides a TanStack Start adapter. A migration guide is available in the repository at docs/from-static-hosting.md.
convex-hosting requires Node 22 or later and the convex package at version 1.46 or later. Install it with npm install @samebase/convex-hosting, then mount the component in convex/convex.config.ts and register routes in convex/http.ts using routeAll.
On a fresh clone, convex/http.ts imports .convex-hosting/version.js, which is only written by a deploy. The first npx convex dev will error on that missing file. Run npx convex dev in one terminal to create the deployment, then run npx convex-hosting deploy --dev in a second terminal. The deploy writes the version file and pushes; after that, the watcher in the first terminal resumes normal operation.
A Cloudflare Worker runs at the data center nearest the visitor, has access to Node's built-in modules, an edge cache, and WebSockets. convex-hosting runs inside a Convex HTTP action and does not provide these capabilities. The repository documents the full list with specifics at docs/workers.md, and a Worker twin of the TanStack Start example is deployed side by side so the difference can be observed.
Yes. The convex-hosting deploy command supports deploy keys and CI usage. The repository documents previews, deploy keys, and CI configuration at docs/deploy.md. The one constraint is that only one deploy should run at a time per deployment, as documented in the design notes.