@samebase/convex-hosting 0.3.2 → 0.4.1

package/README.md

@@ -1,472 +1,254 @@
 # Convex Hosting
 
-[![npm version](https://badge.fury.io/js/@samebase%2Fconvex-hosting.svg)](https://badge.fury.io/js/@samebase/convex-hosting)
+Host a web app on Convex, next to its backend: the files of a build and, when the app renders pages,
+those pages. The site is at `https://<deployment>.convex.site`.
 
-A Convex component for hosting static React/Vite apps directly on Convex: no separate hosting
-provider, no DNS to wire up, no second deploy target. Run one command and your frontend is live at
-`https://<deployment>.convex.site` alongside your backend. For server-rendered TanStack Start pages,
-add
-[`@samebase/convex-hosting-tanstack-start`](https://github.com/samebase/convex-hosting/tree/main/packages/convex-hosting-tanstack-start).
-
-This is Samebase's fork of [get-convex/static-hosting](https://github.com/get-convex/static-hosting)
-(Apache-2.0). It is not affiliated with or endorsed by Convex.
-
-## Features
-
-- 🚀 **One-command deploy:** build, push backend, and upload static files in a single step.
-- 🔄 **SPA routing:** paths without an extension fall back to `index.html`.
-- ⚡ **Smart caching:** static files are cached for speed, with safe updates when a new version is
-  deployed.
-- 🔔 **Deployment update notifications:** show connected users a prompt when a new version is ready.
-- 🔒 **Authenticated uploads:** uploads go through the Convex CLI's authenticated session; there's
-  no public upload endpoint.
-- 🧹 **Automatic cleanup:** replaced non-HTML files stay available for at least seven days, so open
-  pages keep working, and a later deploy removes them.
-
-## Quick Start
-
-> **Coming from `@convex-dev/static-hosting`?** See
-> [Switching from @convex-dev/static-hosting](#switching-from-convex-devstatic-hosting).
-
-Follow the three [setup steps](#setup), then run:
-
-```bash
-npm run deploy
-```
-
-Your app is live at `https://<deployment>.convex.site`.
+It works like
+[Cloudflare Workers with static assets](https://developers.cloudflare.com/workers/static-assets/):
+the same `_headers`, `_redirects`, and `.assetsignore` files, the same `html_handling` and
+`not_found_handling` options, and the same responses, computed by Cloudflare's own asset-serving
+code.
 
 ## Setup
 
-### 1. Install
-
-```bash
-npm install @samebase/convex-hosting
-```
-
-### 2. Register the component
+Requires `convex` 1.46 or later.
 
-`convex/convex.config.ts`:
+1. Install:
 
-```ts
-import { defineApp } from "convex/server";
-import hosting from "@samebase/convex-hosting/convex.config";
-
-// Your own HTTP endpoints (convex/http.ts) are served under /api so the
-// static site can own the root.
-const app = defineApp({ httpPrefix: "/api" });
-app.use(hosting, { httpPrefix: "/" });
-
-export default app;
-```
-
-This is the fastest serving mode. The component owns `/`, while your app's `convex/http.ts` routes
-move under `/api/...`.
-
-If existing callbacks or auth routes must stay at the root, use
-[app-owned root routing](#keep-existing-http-routes-at-the-root). To host the site under a sub-path,
-see [Mounting under a sub-path](#mounting-under-a-sub-path).
-
-### 3. Add a deploy script
-
-```json
-{
-  "scripts": {
-    "deploy": "npx @samebase/convex-hosting deploy"
-  }
-}
-```
-
-That's it.
+   ```sh
+   npm install @samebase/convex-hosting
+   ```
 
-### Keep existing HTTP routes at the root
+2. `convex/convex.config.ts` mounts the component:
 
-Do not move stable webhook, auth, or API URLs just to add hosting. Leave the component's HTTP routes
-unmounted and register the static catch-all in your existing router.
+   ```ts
+   import { defineApp } from "convex/server";
+   import hosting from "@samebase/convex-hosting/convex.config";
 
-`convex/convex.config.ts`:
+   const app = defineApp();
+   app.use(hosting);
 
-```ts
-import { defineApp } from "convex/server";
-import hosting from "@samebase/convex-hosting/convex.config";
+   export default app;
+   ```
 
-const app = defineApp();
-app.use(hosting); // no httpPrefix
+3. `convex/http.ts` has one `GET` route for the site. Convex answers `HEAD` through it.
 
-export default app;
-```
+   ```ts
+   import { httpRouter } from "convex/server";
+   import { serveAsset } from "@samebase/convex-hosting";
+   import { components } from "./_generated/api.js";
+   import { httpAction } from "./_generated/server.js";
+   import { versionId } from "../.convex-hosting/version.js";
+
+   const http = httpRouter();
+
+   http.route({
+     pathPrefix: "/",
+     method: "GET",
+     handler: httpAction(async (ctx, request) => {
+       const asset = await serveAsset(ctx, components.hosting, request, versionId);
+       if (asset) return asset;
+       // A static site: 404. A server-rendered site: render the page here, also with `no-store`.
+       // The deployment's Cloudflare front caches answers on static-looking paths.
+       return new Response(null, { status: 404, headers: { "Cache-Control": "no-store" } });
+     }),
+   });
+
+   export default http;
+   ```
 
-`convex/http.ts`:
+4. Run `convex-hosting init` before `npx convex dev`, once per clone. `convex/http.ts` imports
+   `.convex-hosting/version.js`, which only a deploy writes, so without it `npx convex dev` fails
+   with `Could not resolve "../.convex-hosting/version.js"`. `init` writes the file with no site
+   version and keeps an existing one. Put it in the script that starts `npx convex dev`:
+
+   ```json
+   {
+     "scripts": {
+       "predev": "convex-hosting init",
+       "dev": "convex dev"
+     }
+   }
+   ```
 
-```ts
-import { httpRouter } from "convex/server";
-import { registerStaticRoutes } from "@samebase/convex-hosting";
-import { components } from "./_generated/api";
+   Until the first deploy, the site answers 404.
 
-const http = httpRouter();
+5. Deploy, from CI or a terminal:
 
-// Register exact app routes first. Existing auth/webhook helpers can stay here.
-// auth.addHttpRoutes(http);
-registerStaticRoutes(http, components.hosting);
+   ```sh
+   npx convex-hosting deploy --build "vite build" --dist dist --not-found-handling single-page-application
+   ```
 
-export default http;
-```
+`convex-hosting` keeps its state in `.convex-hosting/` at the project root, next to `convex/`, like
+Wrangler's `.wrangler/`. The folder has its own `.gitignore`, so git ignores it. The package
+declares the type of `.convex-hosting/version.js`, so the app typechecks without it.
+
+## Rules
 
-Exact routes win over the static catch-all, so existing URLs keep working. The component still owns
-uploads, deployment state, and file storage. This mode adds an internal query and storage fetch on
-an uncached request, so prefer the component-owned mode when you do not need root-level app routes.
+- Deploy production and previews with `convex-hosting deploy`, never with a plain
+  `npx convex deploy`. A plain push sends whatever version `.convex-hosting/version.js` names, and
+  after `init` that is none: the site answers 404 until the next `convex-hosting deploy`.
+- Do not commit `.convex-hosting/`. It ignores itself.
+- Do not change directory in `--build`. The build and the upload run in the project directory.
+- Answer a miss in `convex/http.ts` with `Cache-Control: no-store`, as in step 3.
 
-### Using non-Vite bundlers
+## Deploy
 
-The `deploy` build step and `upload --build` set `VITE_CONVEX_URL`. For bundlers that use different
-environment variable conventions, wrap your build script to pass through the value:
+`deploy` runs `npx convex deploy` with your build and the upload of `--dist` as its `--cmd`. The
+pushed code names the version it was built with, so the push switches the site, and the command
+ends. The first request that the new code serves marks its version live, which deletes the versions
+that were live before it. A version that never becomes live, from a deploy that failed, is deleted
+when it is a day old, with the stored files that no version uses. Nothing is deleted while a site
+gets no request.
 
-**For Expo:**
+`deploy` goes to production. `--preview-name <name>` sends it to that preview (with a login or a
+project's preview deploy key; always pass the name with that key), and `--dev` to the development
+deployment (see [Development](#development)). A deploy key in `CONVEX_DEPLOY_KEY` or
+`CONVEX_DEPLOYMENT_TOKEN` (from the environment or `.env.local`) selects its own deployment instead,
+and so does `CONVEX_SELF_HOSTED_URL` for a self-hosted deployment.
 
-```json
-{
-  "scripts": {
-    "build": "EXPO_PUBLIC_CONVEX_URL=${VITE_CONVEX_URL:-$EXPO_PUBLIC_CONVEX_URL} npx expo export --platform web"
-  }
-}
-```
+The first deploy to a deployment pushes the component, then uploads the files. Until that upload
+ends, the site answers 404. Two deploys that overlap both complete, and the last push wins.
 
-**For Next.js:**
+## Deploy tools and CI
 
-```json
-{
-  "scripts": {
-    "build": "NEXT_PUBLIC_CONVEX_URL=${VITE_CONVEX_URL:-$NEXT_PUBLIC_CONVEX_URL} next build"
-  }
-}
-```
+- **A tool that runs `convex deploy` itself**, such as Alchemy's `Convex.Code`, has no place for the
+  upload, which must happen between the build and the push. Run `convex-hosting deploy` in place of
+  that tool's push step, with the deploy key in `CONVEX_DEPLOY_KEY`.
+- **A deploy key limited to some actions** needs `deployment:deploy`,
+  `deployment:functions:runInternalQueries`, `deployment:functions:runInternalMutations`,
+  `deployment:functions:runInternalActions` (the upload calls one internal action), and
+  `deployment:functions:runTestQuery` (the first-install check is an inline query).
+- **Checks that must stop a release** run before `convex-hosting deploy`, because its push switches
+  the site. Checks that need the new functions run after it.
 
-The pattern `${VITE_CONVEX_URL:-$VAR}` uses `VITE_CONVEX_URL` if set by the CLI and otherwise falls
-back to your bundler-specific variable. This keeps both the CLI-driven build and standalone
-`npm run build` working.
+## Development
 
-## Deployment
+The inner loop is your framework's dev server, such as Vite's, which serves the frontend locally
+with hot reload against the development deployment's URL from `.env.local`, plus `npx convex dev`,
+which pushes your function changes. Neither needs a deploy.
 
-Deploy both Convex backend and static files with a single command:
+When the development deployment should serve the current build, run the one-shot command:
 
-```bash
-npx convex login           # first time only
-npx @samebase/convex-hosting deploy
+```sh
+npx convex-hosting deploy --dev --build "vite build" --dist dist --not-found-handling single-page-application
 ```
 
-The `deploy` command:
-
-1. Builds your frontend with the production `VITE_CONVEX_URL`.
-2. Deploys the Convex backend.
-3. Uploads `dist/` to Convex. It skips `_headers` and `_redirects` at the root of `dist/`:
-   Cloudflare and Netlify read these files as hosting rules, and this package does not apply them.
+`deploy --dev` goes to the development deployment of this checkout, the one in `.env.local`. It runs
+the build itself, uploads `--dist`, writes `.convex-hosting/version.js`, and pushes with
+`npx convex run --push`, which works whether or not `npx convex dev` runs. The build runs with your
+environment, so the framework reads the deployment's URL from `.env.local` (Vite reads
+`VITE_CONVEX_URL`). Against an anonymous local deployment, `deploy --dev` needs `npx convex dev`
+running, because without it every Convex CLI call starts and stops its own backend and the upload's
+requests find nothing; cloud development deployments do not have this constraint. There is no watch
+mode: a build, an upload, and a push per change is not an inner loop, and Cloudflare's own tooling
+works the same way, with a local dev server and a push on demand.
 
-For more control, you can run the two halves separately:
+Two cases are transient:
 
-```bash
-npx convex deploy
-npx @samebase/convex-hosting upload --build --prod
-```
+- A server-rendered app imports `dist/server` in `convex/http.ts`, so a running `npx convex dev`
+  pushes after the build, before `deploy --dev` writes the new version. Until `deploy --dev` ends,
+  the new pages refer to files that answer 404.
+- A production deploy writes production's version to the version file, and a running
+  `npx convex dev` pushes it to the development deployment, where that version does not exist, until
+  the next `deploy --dev`. Run production deploys in CI or in a separate checkout.
 
-Your app is live at `https://<deployment>.convex.site`.
+## Options
 
-## Development workflow
+| Option                         | Values                                                                                 |
+| ------------------------------ | -------------------------------------------------------------------------------------- |
+| `--dev`                        | The development deployment of this checkout, instead of production                     |
+| `--preview-name <name>`        | The preview deployment with this name, instead of production                           |
+| `--html-handling <value>`      | `auto-trailing-slash` (default), `force-trailing-slash`, `drop-trailing-slash`, `none` |
+| `--not-found-handling <value>` | `none` (default), `single-page-application`, `404-page`                                |
+| `--component <name>`           | The component instance, `hosting` by default                                           |
 
-Use your normal frontend dev server during development:
+The two handling options work as
+[Cloudflare documents them](https://developers.cloudflare.com/workers/static-assets/routing/).
 
-```bash
-# Terminal 1
-npx convex dev
+Each file of `--dist` must be 25 MiB or smaller, and the CLI names a file that is larger. This is
+Cloudflare's limit per asset, and the HTTP action that serves a file cannot answer more than
+Convex's 100 MiB response limit anyway.
 
-# Terminal 2
-npm run dev
-```
+## `_headers`, `_redirects`, and `.assetsignore`
 
-For Vite, that keeps HMR and fast local feedback. The hosting component is the deploy target, not a
-replacement dev server. Uploading every edit to a development deployment is slower and loses HMR,
-even when an agent writes most of the code. Humans still need the quick loop for visual checks,
-transient UI state, and debugging.
+Put them at the root of `--dist`, as for Cloudflare:
+[`_headers`](https://developers.cloudflare.com/workers/static-assets/headers/),
+[`_redirects`](https://developers.cloudflare.com/workers/static-assets/redirects/), and
+[`.assetsignore`](https://developers.cloudflare.com/workers/static-assets/binding/#ignoring-assets).
+For a Vite app, put them in `public/`, which Vite copies into `dist/`. They are not served. Symbolic
+links in `--dist` are followed, as Wrangler follows them, also when they point outside the folder; a
+link to nothing, or back into a folder already included, is skipped with a message. `.assetsignore`
+excludes what a link should not publish.
 
-Before release, run one hosted smoke test against the development deployment:
+Every asset has `Cache-Control: public, max-age=0, must-revalidate` and an `ETag`. To cache hashed
+files for a year, add a `_headers` rule:
 
-```bash
-npx @samebase/convex-hosting upload --build
 ```
-
-Then use `deploy` for production. This split keeps the dev loop fast while still testing the real
-HTTP, caching, base-path, and SPA behavior before shipping.
-
-## CLI options
-
-```bash
-npx @samebase/convex-hosting deploy [options]
-  -d, --dist <path>         Path to dist directory (default: ./dist)
-  -c, --component <name>    Component instance name (default: hosting)
-      --skip-build          Skip the build step (use existing dist)
-      --skip-convex         Skip Convex backend deployment
-      --build-command <cmd> Build command to run (default: 'npm run build')
-      --no-spa              Disable SPA fallback (404 instead of /index.html)
-      --spa                 Enable SPA fallback (default)
-      --cdn                 Use the legacy convex-fs integration
-      --cdn-delete-function Legacy app function that deletes CDN blobs
-
-npx @samebase/convex-hosting upload [options]
-  -d, --dist <path>         Path to dist directory (default: ./dist)
-  -c, --component <name>    Component instance name (default: hosting)
-      --prod                Deploy to production deployment
-      --preview-name <name> Upload to the named preview deployment
-  -b, --build               Run 'npm run build' with VITE_CONVEX_URL set
-      --build-command <cmd> Override the build command; implies --build
-      --no-spa              Disable SPA fallback (404 instead of /index.html)
-      --spa                 Enable SPA fallback (default)
-      --cdn                 Use the legacy convex-fs integration
-      --cdn-delete-function Legacy app function that deletes CDN blobs
-  -j, --concurrency <n>     Parallel upload workers (default: 5)
+/assets/*
+  Cache-Control: public, max-age=31536000, immutable
 ```
 
-`--preview-name` selects the deployment the same way as `npx convex run --preview-name`, so a dev or
-production `CONVEX_DEPLOY_KEY` takes precedence over it.
+## Routing
 
-Each upload is published atomically, so visitors never see a page that refers to assets that are not
-available yet. Failed uploads leave the previous deployment live. Replaced non-HTML files stay
-available for at least seven days, so pages that are already open can still load their scripts. A
-later upload removes expired files. See [INTEGRATION.md](./INTEGRATION.md) for upload limits and
-lifecycle details.
+`serveAsset` returns the asset's response, or `null` when no asset matches, so your route continues.
+When the version does not exist or is still uploading, it returns a 404 response that names the
+version. At the first request for a new version, it marks the version live.
 
-Convex HTTP routes currently support GET but not HEAD. Configure uptime checks to make a lightweight
-GET request rather than a HEAD request.
+`not_found_handling` applies to navigation requests (`Sec-Fetch-Mode: navigate`) only, as on
+Cloudflare when a Worker runs: other requests that match no file reach your code. Browsers send that
+header whenever they open a page. `curl`, `fetch` in scripts and tests, uptime monitors, and
+link-preview bots do not, so they get your route's answer for a deep link of a single-page app,
+a 404. To test a deep link as a browser opens it, send the header:
+`curl -H "Sec-Fetch-Mode: navigate"`, or `node:http` in Node, whose `fetch` refuses to set it.
 
-If you mount the component under a different name with `app.use(hosting, { name: "custom" })`, pass
-`--component custom` and replace every generated `components.hosting` reference with
-`components.custom`.
+Two differences from Cloudflare follow from Convex's router:
 
-Do not use `--cdn` for a new integration. It targets an older ConvexFS HTTP API and is retained only
-for existing deployments. Legacy CDN users must keep app-owned root routing because `/fs/upload` and
-`/fs/blobs/*` are root app routes. See `INTEGRATION.md` for the current limitation.
+- An exact route in `convex/http.ts` wins over an asset at the same path.
+- On a static site, a request that is not a navigation and matches no file (`curl /missing`) answers
+  404, not the single-page fallback.
 
-## Security
+## Open tabs after a deploy
 
-The upload API uses **internal functions** in the Component that can only be called via:
-
-- `npx convex run` (requires Convex CLI authentication)
-- Other Convex functions in the Component (server-side only)
-
-This means unauthorized users **cannot** upload files to your site, even if they know your Convex
-URL.
-
-## Reload prompt after deploy (optional)
-
-If you want a banner that prompts users to reload when a new deployment ships, expose the deployment
-query in your app and drop in `<UpdateBanner />`:
-
-`convex/hosting.ts`:
+A page opened before a deploy keeps asking for its hashed files, which now answer 404, as on
+Cloudflare. To reload open tabs on a new version, add a query that returns the bundled version:
 
 ```ts
-import { exposeDeploymentQuery } from "@samebase/convex-hosting";
-import { components } from "./_generated/api";
+// convex/siteVersion.ts
+import { v } from "convex/values";
+import { query } from "./_generated/server.js";
+import { versionId } from "../.convex-hosting/version.js";
 
-export const { getCurrentDeployment } = exposeDeploymentQuery(components.hosting);
+export const get = query({ args: {}, returns: v.string(), handler: () => versionId });
 ```
 
-`src/App.tsx`:
-
-```tsx
-import { UpdateBanner } from "@samebase/convex-hosting/react";
-
-function App() {
-  return (
-    <>
-      <UpdateBanner message="New version!" buttonText="Reload" />
-      {/* ... */}
-    </>
-  );
-}
-```
-
-`UpdateBanner` resolves `api.hosting.getCurrentDeployment` automatically. If you re-export the query
-under a different module name, pass it explicitly:
+and reload when its value changes after the first one:
 
 ```tsx
+import { useQuery } from "convex/react";
+import { useEffect, useRef } from "react";
 import { api } from "../convex/_generated/api";
-<UpdateBanner getCurrentDeployment={api.myModule.getCurrentDeployment} />;
-```
-
-For custom UI, use the hook:
-
-```tsx
-import { useDeploymentUpdates } from "@samebase/convex-hosting/react";
-
-const { updateAvailable, reload, dismiss } = useDeploymentUpdates();
-```
-
-## Mounting under a sub-path
-
-Mount the static site under a sub-path if you have other routes at the root:
-
-```ts
-app.use(hosting, { httpPrefix: "/app/" });
-```
-
-You'll also need to tell your bundler about the base path so the emitted HTML references the right
-URLs. The CLI sets a `CONVEX_HOSTING_BASE_PATH` env var matching the component's mount when it runs
-your build, so `vite.config.ts` can read it directly:
-
-```ts
-import { defineConfig } from "vite";
-
-export default defineConfig({
-  base: process.env.CONVEX_HOSTING_BASE_PATH ?? "/",
-});
-```
-
-Root-mounted apps don't need this; the default is `/`. For webpack use `publicPath`, for Next.js
-`assetPrefix`.
-
-## SPA routing
-
-By default, requests for a path with no file extension that doesn't match an uploaded file fall back
-to `index.html`, so client-side routes like `/dashboard/settings` work on reload. For a multi-page
-app where unknown paths should be a real 404, deploy with `--no-spa`:
-
-```bash
-npx @samebase/convex-hosting deploy --no-spa
-```
-
-The setting is stored with the deployment, so it travels with the code you ship rather than living
-in a separate env var. Requests for paths with an extension (e.g. `/missing.js`) always 404 when not
-found, regardless of this setting.
-
-## Custom routing (SSR, prerendered pages)
-
-`registerStaticRoutes` decides what every unmatched path returns. When your app needs to decide
-instead, for example to server-render pages, serve prerendered pages next to an SPA shell, or
-redirect to canonical URLs, write the catch-all route yourself and call `serveStaticAsset` for
-uploaded files. Install the component without `httpPrefix`, as in
-[Keep existing HTTP routes at the root](#keep-existing-http-routes-at-the-root).
-
-```ts
-import { httpRouter } from "convex/server";
-import { decodeRequestPath, serveStaticAsset } from "@samebase/convex-hosting";
-import { components } from "./_generated/api";
-import { httpAction } from "./_generated/server";
-
-const http = httpRouter();
-
-http.route({
-  pathPrefix: "/",
-  method: "GET",
-  handler: httpAction(async (ctx, request) => {
-    const file = await serveStaticAsset(ctx, components.hosting, request);
-    if (file) return file;
-
-    // A missing bundle file is a 404, not a page.
-    const path = decodeRequestPath(new URL(request.url).pathname);
-    if (path === null || path.startsWith("/assets/")) {
-      return new Response("Not Found", {
-        status: 404,
-        headers: { "Cache-Control": "no-store" },
-      });
-    }
-    return await renderPage(request);
-  }),
-});
-
-export default http;
-```
-
-`serveStaticAsset` returns the file with the same headers as `registerStaticRoutes`, or `null` when
-no file matches, including a request path with malformed percent-encoding. It never returns the
-setup page or a 404, so your code decides what happens next. Only a found file whose storage can't
-be read gets an error response (500). The lookup is exact: `/` is not mapped to `/index.html`, and
-SPA fallback is off unless you pass `spaFallback: true`.
-
-Pass `path` to serve a different file, such as a prerendered page or the SPA shell. It is the
-decoded path of the uploaded file, starting with `/`. If your route has a prefix, remove it from
-`path`:
-
-```ts
-const page = await serveStaticAsset(ctx, components.hosting, request, {
-  path: "/about/index.html",
-});
-const shell = await serveStaticAsset(ctx, components.hosting, request, {
-  path: "/index.html",
-});
-```
 
-When the backend renders your pages, pushing the backend and uploading files are separate steps, so
-right after a deploy a page can briefly refer to scripts that are not uploaded yet. That is why the
-missing-asset response above uses `Cache-Control: no-store`: a CDN would otherwise keep serving
-the 404.
-
-Use `decodeRequestPath` for your own path checks, so an encoded request such as `/%61ssets/app.js`
-still matches `/assets/`.
-
-See
-[`examples/tanstack-ssr/`](https://github.com/samebase/convex-hosting/tree/main/examples/tanstack-ssr)
-for TanStack Start pages rendered in a Convex HTTP action this way.
-
-## Switching from @convex-dev/static-hosting
-
-This package continues `@convex-dev/static-hosting` 0.2. To switch an app:
-
-1. Replace the dependency with `@samebase/convex-hosting`, and change every import from
-   `@convex-dev/static-hosting` to `@samebase/convex-hosting`, including `/convex.config` and
-   `/react`.
-2. Keep the existing component instance, so the uploaded files and the site URLs stay:
-
-   ```ts
-   import hosting from "@samebase/convex-hosting/convex.config";
-
-   app.use(hosting, { name: "staticHosting", httpPrefix: "/" });
-   ```
-
-   Keep the `httpPrefix` the app used before. The code keeps using `components.staticHosting`, and
-   the CLI finds this instance without `--component`. It prints a note that the default name is now
-   `hosting`.
-
-3. Rename `convex/staticHosting.ts` to `convex/hosting.ts`. `<UpdateBanner />` and
-   `useDeploymentUpdates()` look up `api.hosting.getCurrentDeployment` by default. To keep the old
-   file, pass `api.staticHosting.getCurrentDeployment` to them instead.
-4. In package scripts, replace `@convex-dev/static-hosting` with `@samebase/convex-hosting` (for
-   example `npx @samebase/convex-hosting deploy`) and the bare `static-hosting` command with
-   `convex-hosting`. In the bundler config, replace `STATIC_HOSTING_BASE_PATH` with
-   `CONVEX_HOSTING_BASE_PATH`.
-5. Deploy as usual.
-
-To use the new default name instead, remove `name: "staticHosting"`, replace
-`components.staticHosting` with `components.hosting`, and deploy. The new instance starts empty, so
-the deploy uploads the files again.
-
-An app on `@convex-dev/static-hosting` 0.1.x first follows upstream's
-[0.1.x to 0.2.x migration guide](https://github.com/get-convex/static-hosting/blob/main/MIGRATION.md),
-because 0.2 moved the files into the component.
-
-## How it works
-
-1. **Build:** your bundler emits `dist/`.
-2. **Upload:** the CLI uses your authenticated Convex session to generate signed upload URLs, push
-   files to Convex storage, record metadata, and GC old deployments.
-3. **Serve:** an HTTP action looks up the requested path, streams the file with the right
-   `Content-Type`, applies long-term caching for hashed assets, and falls back to `index.html` for
-   SPA routes.
-
-## Example
-
-See [`examples/spa/`](https://github.com/samebase/convex-hosting/tree/main/examples/spa) for a
-complete Vite + React app, and
-[`examples/tanstack-ssr/`](https://github.com/samebase/convex-hosting/tree/main/examples/tanstack-ssr)
-for server rendering with TanStack Start.
-
-```bash
-pnpm install
-cd examples/spa
-pnpm run dev
+export function useReloadOnNewVersion() {
+  const versionId = useQuery(api.siteVersion.get);
+  const first = useRef<string | undefined>(undefined);
+  useEffect(() => {
+    if (versionId === undefined) return;
+    first.current ??= versionId;
+    if (versionId !== first.current) location.reload();
+  }, [versionId]);
+}
 ```
 
-## Contributing
+## Server-rendered pages
 
-See [CONTRIBUTING.md](https://github.com/samebase/convex-hosting/blob/main/CONTRIBUTING.md).
+[`@samebase/convex-hosting-tanstack-start`](https://github.com/samebase/convex-hosting/tree/main/packages/convex-hosting-tanstack-start)
+renders TanStack Start pages in the same route, after `serveAsset`. See the
+[TanStack Start example](https://github.com/samebase/convex-hosting/tree/main/examples/tanstack-ssr).
 
 ## License
 
-Apache-2.0
+Apache-2.0, with the notices in
+[NOTICE](https://github.com/samebase/convex-hosting/blob/main/NOTICE). Not affiliated with or
+endorsed by Convex. To work on this repository, see
+[CONTRIBUTING.md](https://github.com/samebase/convex-hosting/blob/main/CONTRIBUTING.md).