--- name: bijection-samebase-convex-hosting description: "Evaluate and integrate the Hosting component with Bijection." --- # Hosting Static files and server-rendered pages from your backend's Convex deployment. Files follow Cloudflare Workers rules. TanStack Start adapter available. This is an upstream package. It has not been adapted or qualified for Bijection. - Package: @samebase/convex-hosting - Source: https://github.com/samebase/convex-hosting - npm: https://www.npmjs.com/package/%40samebase%2Fconvex-hosting - Directory: https://bijection.com/components/samebase-convex-hosting Read the upstream README for setup, license, and compatibility before using it. ## Integration workflow 1. Read the source README and package manifest at the recorded revision. 2. Confirm the required SDK, dependency availability, and runtime compatibility. 3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name. 4. Keep credentials in the project's existing secret store. 5. Follow the project's execution rules for verification and report what was actually checked. ## Original upstream skill The following guidance describes @samebase/convex-hosting. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately. > Agents: read this skill fully before writing code that uses Hosting. Follow the installation and configuration steps exactly. # Hosting ## Instructions Use Hosting to serve static files and server-rendered pages directly from your convex deployment using cloudflare workers asset rules, with a tanstack start adapter included. This Convex component integrates directly with your backend. ### Installation ```bash npm install @samebase/convex-hosting ``` Current npm version: `@samebase/convex-hosting@0.13.1` ### Capabilities - Eliminate a separate frontend host by serving your entire web app from a single Convex deployment URL - Use Cloudflare Workers file-serving conventions (_headers, _redirects, html_handling) without running a Worker - Deploy static sites or SSR apps with one command that atomically binds uploaded files to pushed backend code - Integrate TanStack Start with streamed pages, server functions, server routes, middleware, and cookie sessions ## Examples ### how to host a frontend on Convex backend deployment The convex-hosting component (@samebase/convex-hosting) lets you serve static files and server-rendered pages from your Convex deployment at https://.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. ### how to run TanStack Start SSR on Convex 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. ### serve static files from Convex with Cloudflare asset rules 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. ### atomic deploy of frontend and backend together on Convex 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. ## When NOT to use - When a simpler built-in solution exists for your specific use case - If you are not using Convex as your backend - When the functionality provided by Hosting is not needed ## Troubleshooting **How is convex-hosting different from Convex's built-in static-hosting component?** 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. **What are the requirements to use convex-hosting?** 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. **How does convex-hosting handle the initial dev setup on a fresh clone?** 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. **What tradeoffs exist compared to deploying on an actual Cloudflare Worker?** 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. **Can convex-hosting be used in CI with deploy keys?** 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. ## Resources - [npm package](https://www.npmjs.com/package/%40samebase%2Fconvex-hosting) - [GitHub repository](https://github.com/samebase/convex-hosting) - [Live demo](https://gallant-llama-40.convex.site) - [Convex Components Directory](https://www.convex.dev/components/samebase/convex-hosting) - [Convex documentation](https://docs.convex.dev)