@samebase/convex-hosting 0.0.0-stage → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,127 @@
+# Changelog
+
+## 0.3.0
+
+First release as `@samebase/convex-hosting`, Samebase's fork of `@convex-dev/static-hosting`. See
+"Switching from @convex-dev/static-hosting" in the README.
+
+- The package, the CLI command (`convex-hosting`), the component (`hosting`), the default deployment
+  query module (`convex/hosting.ts`), and the `CONVEX_HOSTING_BASE_PATH` build variable share one
+  name. The CLI still finds an instance named `staticHosting`.
+- `serveStaticAsset` serves one uploaded file from your own HTTP route, for custom routing and
+  server rendering.
+- `upload --preview-name` uploads to a named preview deployment.
+- Replaced files stay available for at least seven days, so pages that are already open can still
+  load their scripts.
+- The `setup` and `init` commands are removed. The README describes the setup steps.
+
+Versions up to 0.2.1 were released as `@convex-dev/static-hosting`.
+
+## 0.2.1
+
+- Smoother migration story, with more automatic fallbacks to the old component name.
+
+## 0.2.0
+
+Component-owned HTTP and storage.
+
+**Breaking — redeploy your static assets after upgrading.**
+
+See the [0.1.x to 0.2.x migration guide](./MIGRATION.md) before upgrading an existing deployment.
+
+- The component now hosts its own HTTP endpoints and owns the file storage that serves them. Wire it
+  up with `app.use(staticHosting, { httpPrefix: "/" })` and delete related code in`convex/http.ts` +
+  the upload-API re-exports from `convex/staticHosting.ts`.
+- Removed `exposeUploadApi` from the client API. Uploads and file lifecycle are now handled by
+  private component functions.
+- `registerStaticRoutes` remains as a compatibility mode for apps that need to keep existing auth,
+  webhook, or API routes at the root. It serves the new component-owned files from the app's
+  existing `convex/http.ts` catch-all. During a same-name v1→v2 migration it also serves inherited
+  v1 files straight from the app's own storage, so the live site stays up with no re-upload gap.
+  Mounting the component's own handler is still the faster default.
+- `exposeDeploymentQuery` and `getConvexUrl` remain if you use the UpdateBanner.
+- The component is now named `staticHosting` (previously `selfHosting`). The CLI invokes it directly
+  via `npx convex run --component staticHosting lib:...`. If you mount the component under a
+  different name, pass `--component <your-name>`. For a smooth upgrade, pass {name: "selfHosting} to
+  `app.use(staticHosting, { name: "selfHosting" })`
+- `useDeploymentUpdates` / `UpdateBanner` use `useQuery_experimental` and default to
+  `api.staticHosting.getCurrentDeployment`. If you don't surface deployment updates, you no longer
+  need to expose anything.
+- Assets uploaded under 0.1.x lived in the app's storage — the component-owned HTTP handler can't
+  resolve those references in 0.2.x. Run `npx @convex-dev/static-hosting deploy` to repopulate. (In
+  app-owned root routing the app-side handler keeps serving those v1 files from app storage until
+  the first upload replaces them, so that mode has no asset-less window.) The first 0.2.x upload
+  safely discards those legacy storage references instead of trying to delete them from component
+  storage. The old blobs remain in app storage until you explicitly clean them up after the rollback
+  window. Older 0.1.x deploys may also have left historical blobs that the current asset manifest no
+  longer lists, so follow the migration guide's app-storage audit before cleanup.
+- Default setup prefixes your own HTTP routes with `defineApp({ httpPrefix: "/api" })` so the static
+  site can own the root without the catch-all route shadowing them. Use `registerStaticRoutes` when
+  those existing root route URLs cannot move.
+- SPA fallback is now configurable per deployment. Deploy with `--no-spa` (`deploy` or `upload`) to
+  make extension-less misses return 404 instead of `index.html`. The setting is stored on the
+  deployment record, so it travels with the code you ship.
+- Hashed-asset caching recognizes Vite's base64url hashes (including `-`) and numeric extensions
+  such as `.woff2`. HTML always uses revalidation, even if its filename looks content-hashed.
+- The `cdnBaseUrl` override remains available in `registerStaticRoutes` compatibility mode.
+  Component-owned HTTP routes redirect CDN blobs to the deployment's own `{origin}/fs/blobs`.
+- `--cdn` is now documented as a legacy option. Its setup guide targeted an old unauthenticated
+  convex-fs API and does not work with current ConvexFS. New integrations should use Convex storage
+  until authenticated CDN uploads are designed.
+- Storage and legacy CDN assets, deployment settings, and old-file cleanup are published in one
+  atomic mutation after all uploads finish. New HTML cannot race ahead of its referenced asset
+  records, and a failed publish leaves the previous deployment live. Replaced CDN blob IDs are
+  retained for cleanup.
+- Upload errors now report the failing file and HTTP status. Oversized manifests fail with a clear
+  size error, and newly uploaded component files are removed after a failed upload or publish.
+- Static handlers decode percent-encoded paths, accept weak or listed ETags, and return a
+  non-cacheable HTTP 503 setup page until the first upload succeeds.
+- Removed the install-time console banner.
+
+## 0.1.5
+
+- Forward-compatibility for 0.2.x rollbacks. The `deploymentInfo` schema and the
+  `getCurrentDeployment` return validator now allow the optional `spaFallback` (boolean) and
+  `pendingBlobCleanupCount` (number) fields that 0.2.x writes to the deployment record. 0.1.5
+  ignores them, but allowing them means a deployment upgraded to 0.2.x and later rolled back to
+  0.1.x keeps validating. No behavior change for 0.1.x users; upgrade to 0.1.5 before trying 0.2.x
+  if you want a clean rollback path. (0.2.x also creates additional tables such as `stagedAssets`
+  and `cleanupState`; extra tables don't fail 0.1.x schema validation, so they need no entry here.)
+
+## 0.1.4
+
+- Added support for Windows
+
+## 0.1.3
+
+- Fix missing README in published package
+
+## 0.1.2
+
+- Rename package from `@convex-dev/self-hosting` to `@convex-dev/static-hosting`
+
+## 0.1.1-alpha.0
+
+- Add optional convex-fs CDN mode for static asset serving (`--cdn` flag)
+- Non-HTML assets can be served from CDN edge network via convex-fs
+- New `cdnBaseUrl` option on `registerStaticRoutes`
+- Schema: `storageId` now optional, new `blobId` field for CDN assets
+- `gcOldAssets` returns `{ deleted, blobIds }` (breaking change from number return)
+
+## 0.1.2-alpha.1
+
+removed cloudflare for now.
+
+## 0.1.1
+
+- Setup wizard now configures custom domains for Cloudflare Workers
+- Added note about running `convex dev` for HTTP actions error
+- Added documentation for non-Vite bundlers (Expo, Next.js)
+
+## 0.1.0
+
+- Migrated from Cloudflare Pages to Workers Static Assets
+
+## 0.0.0
+
+- Initial release.

package/INTEGRATION.md

@@ -0,0 +1,399 @@
+# Integration Guide: @samebase/convex-hosting
+
+This guide walks you through hosting a static React/Vite app on Convex using the
+`@samebase/convex-hosting` component. Your frontend ends up at `https://<deployment>.convex.site`,
+served alongside your Convex backend with SPA routing and smart caching.
+
+## What this component gives you
+
+- A drop-in HTTP handler that serves your static files from Convex storage
+- One CLI command (`deploy`) that builds, deploys the backend, and uploads files
+- SPA fallback to `index.html` for client-side routing
+- Long-term cache headers on hashed assets and ETag-based revalidation on HTML
+- Optional live-reload notifications when a new deploy ships
+- Authenticated uploads via the Convex CLI (no public upload endpoint)
+
+## Quick Start
+
+```bash
+npm install @samebase/convex-hosting
+```
+
+Register the component and add a `deploy` script as described in [Manual Setup](#manual-setup).
+Then:
+
+```bash
+npm run deploy
+```
+
+## Manual Setup
+
+### `convex/convex.config.ts`
+
+The default setup mounts the component's HTTP handler at the root and moves app-owned routes under
+`/api`.
+
+```typescript
+import { defineApp } from "convex/server";
+import hosting from "@samebase/convex-hosting/convex.config";
+
+// Serve your own HTTP endpoints (convex/http.ts) 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 because the component reads its storage directly. It is appropriate
+for new apps and apps whose HTTP routes can live under `/api`.
+
+If existing webhook, auth, or API routes must stay at the root, use
+[App-owned root routing](#app-owned-root-routing). To host the static site under a sub-path, see
+[Mounting under a sub-path](#mounting-under-a-sub-path).
+
+> Run `npx convex dev` after editing `convex.config.ts` so codegen picks up the component.
+
+### App-owned root routing
+
+Keep the app in control of `convex/http.ts` when changing existing route URLs would break clients or
+third-party callbacks.
+
+`convex/convex.config.ts`:
+
+```typescript
+import { defineApp } from "convex/server";
+import hosting from "@samebase/convex-hosting/convex.config";
+
+const app = defineApp();
+app.use(hosting); // no httpPrefix
+
+export default app;
+```
+
+`convex/http.ts`:
+
+```typescript
+import { httpRouter } from "convex/server";
+import { registerStaticRoutes } from "@samebase/convex-hosting";
+import { components } from "./_generated/api";
+
+const http = httpRouter();
+
+// Keep existing exact routes at their current URLs.
+// auth.addHttpRoutes(http);
+registerStaticRoutes(http, components.hosting);
+
+export default http;
+```
+
+Exact routes win over the static catch-all. Uploads, deployment metadata, SPA configuration, and
+file storage remain inside the component, so you can remove the old `exposeUploadApi` wrappers.
+During a same-name 0.1.x→0.2.x migration this mode also keeps serving your existing v1 files from
+app storage until the first 0.2.x upload, so the live site never drops to the setup page. This
+compatibility mode adds an internal query and storage fetch on uncached requests. Use the
+component-owned handler when preserving root-level app routes is not necessary.
+
+### `package.json`
+
+```json
+{
+  "scripts": {
+    "deploy": "npx @samebase/convex-hosting deploy"
+  }
+}
+```
+
+## Deployment
+
+```bash
+# First time
+npx convex login
+
+# Build + backend deploy + upload static files
+npx @samebase/convex-hosting deploy
+```
+
+Two-step alternative:
+
+```bash
+npx convex deploy
+npx @samebase/convex-hosting upload --build --prod
+```
+
+Your app is live at `https://<deployment>.convex.site`.
+
+## Development workflow
+
+Do not use uploaded static files as the main development loop. Run the normal frontend dev server
+alongside Convex:
+
+```bash
+npx convex dev
+npm run dev
+```
+
+Vite keeps HMR, source maps, and transient UI state intact. Agent-written code does not change that
+tradeoff. HMR may matter less while code is being produced, but it still matters when a person
+verifies visuals and debugs interactions.
+
+Use the hosted development deployment as a smoke-test target before release:
+
+```bash
+npx @samebase/convex-hosting upload --build
+```
+
+That catches differences in HTTP routing, cache headers, SPA fallback, and base paths. Production
+remains the one-command `deploy` flow.
+
+## Live reload banner (optional)
+
+Show users a banner when a new version is deployed:
+
+### `convex/hosting.ts`
+
+```typescript
+import { exposeDeploymentQuery } from "@samebase/convex-hosting";
+import { components } from "./_generated/api";
+
+export const { getCurrentDeployment } = exposeDeploymentQuery(components.hosting);
+```
+
+### Frontend
+
+```tsx
+import { UpdateBanner } from "@samebase/convex-hosting/react";
+
+function App() {
+  return (
+    <>
+      <UpdateBanner message="New version available!" buttonText="Reload" />
+      {/* rest of app */}
+    </>
+  );
+}
+```
+
+`UpdateBanner` resolves `api.hosting.getCurrentDeployment` by default. To re-export the query under
+a different module, pass the reference explicitly:
+
+```tsx
+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();
+```
+
+## Legacy CDN mode
+
+Do not use `--cdn` for a new integration. It targets an older, unauthenticated `convex-fs` HTTP API.
+Current ConvexFS releases require app-owned routes and upload authentication, which this CLI does
+not yet provide.
+
+Existing deployments that already expose the legacy routes can keep using the flag during migration,
+but they must use app-owned root compatibility mode. `/fs/upload` and `/fs/blobs/*` are app routes,
+so component-owned root mode would break both upload and serving. Everyone else should use the
+default Convex storage mode. Supporting current ConvexFS properly needs a separate authenticated
+upload and garbage-collection design, not a copy-paste configuration snippet.
+
+The CLI uploads every file before atomically publishing the mixed storage/CDN manifest and
+deployment settings while queuing exact old-file IDs for bounded follow-up cleanup. New HTML does
+not point at asset records that are still missing, and a failed publish leaves the previous
+deployment live. Failure cleanup removes new files only after it can prove publication did not win
+the transaction race; otherwise later maintenance recovers them. Failed legacy CDN uploads can only
+be cleaned automatically when `--cdn-delete-function` is configured. Old CDN IDs are kept in a
+private cleanup queue until that function succeeds, so a lost publish response does not make them
+unrecoverable.
+
+## Non-Vite bundlers
+
+The `deploy` build step and `upload --build` set `VITE_CONVEX_URL`. To forward it to another env var
+(Expo, Next.js, etc.), wrap your build script:
+
+```text
+Expo build script:
+EXPO_PUBLIC_CONVEX_URL=${VITE_CONVEX_URL:-$EXPO_PUBLIC_CONVEX_URL} npx expo export --platform web
+
+Next.js build script:
+NEXT_PUBLIC_CONVEX_URL=${VITE_CONVEX_URL:-$NEXT_PUBLIC_CONVEX_URL} next build
+```
+
+## Security
+
+Upload functions are **internal** to the component. They can only be called via:
+
+- `npx convex run` (requires Convex CLI authentication)
+- Other Convex functions (server-side only)
+
+This means unauthorized users cannot upload files, even if they know your Convex URL.
+
+## CLI Reference
+
+```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
+      --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                 Upload non-HTML assets to convex-fs CDN
+      --cdn-delete-function App function path 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                 Upload non-HTML assets to convex-fs CDN
+      --cdn-delete-function App function path that deletes CDN blobs
+  -j, --concurrency <n>     Parallel upload workers (default: 5)
+```
+
+The complete manifest is staged in small, portable command-line chunks after all uploads finish. One
+final mutation atomically publishes the manifest and deployment settings. Replaced files stay in
+component storage for at least seven days. A request for a missing file with an extension, except
+HTML, gets the newest replaced copy, so pages that are already open can still load their scripts.
+Files remain available until a later upload removes expired files in bounded cleanup transactions.
+Legacy CDN blobs are not retained. A failed attempt leaves the previous deployment live and removes
+only new files that are not referenced by the live manifest. The supported maximum is 1,800 files
+and 2 MiB of serialized manifest metadata, which keeps the atomic switch below Convex transaction
+limits. Upload URLs are generated in bounded batches. Later uploads recover component files and
+staging records left unreferenced for more than 24 hours after an interrupted CLI.
+
+Convex HTTP routers currently expose GET but not HEAD routes. Uptime monitors must use a lightweight
+GET request.
+
+## Mounting under a sub-path
+
+To mount under `/app/` (for example, if you have other HTTP routes at the root):
+
+```typescript
+app.use(hosting, { httpPrefix: "/app/" });
+```
+
+The bundler also needs to know 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:
+
+```typescript
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  base: process.env.CONVEX_HOSTING_BASE_PATH ?? "/",
+});
+```
+
+Root-mounted apps don't need this; the default is `/`. Webpack/Next.js equivalents: `publicPath` and
+`assetPrefix`.
+
+## SPA routing
+
+Requests for an extension-less path that doesn't match an uploaded file fall back to `index.html`,
+so client-side routes survive a reload. Paths with an extension (e.g. `/missing.js`) always 404 when
+not found. To turn the fallback off for a multi-page app (unknown paths become real 404s), deploy
+with `--no-spa`:
+
+```bash
+npx @samebase/convex-hosting deploy --no-spa
+# or: npx @samebase/convex-hosting upload --no-spa
+```
+
+The flag is stored on the deployment record (the `deploymentInfo` table), so the serving behavior
+travels with the code you ship rather than living in a separate env var. Re-deploy without
+`--no-spa` or with `--spa` to turn it back on.
+
+## Switching from @convex-dev/static-hosting
+
+Follow
+[Switching from @convex-dev/static-hosting](./README.md#switching-from-convex-devstatic-hosting) in
+the README. Mount the component with `{ name: "staticHosting" }` to keep the uploaded files and
+URLs. An app on 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).
+
+## Troubleshooting
+
+### 404s on every path
+
+Run `npx convex dev` (or `npx convex deploy`) after adding the component. In component-owned mode,
+verify its `httpPrefix`. In app-owned mode, verify that `registerStaticRoutes` is called from
+`convex/http.ts` and the component itself has no `httpPrefix`.
+
+### Wrong `VITE_CONVEX_URL` in the built bundle
+
+```bash
+# Right: CLI sets VITE_CONVEX_URL for the target deployment
+npx @samebase/convex-hosting deploy
+
+# Wrong: uses VITE_CONVEX_URL from .env.local
+npm run build && npx @samebase/convex-hosting upload --prod
+```
+
+### "Cannot find module convex.config"
+
+Make sure you've installed the package and it's listed in `package.json`:
+
+```bash
+npm install @samebase/convex-hosting
+```
+
+### Component name mismatch
+
+If you've renamed the component instance with `app.use(hosting, { name: "custom" })`, pass it to the
+CLI and replace every generated `components.hosting` reference with `components.custom`:
+
+```bash
+npx @samebase/convex-hosting upload --component custom
+```
+
+## API Reference
+
+### `registerStaticRoutes(http, component, options?)`
+
+Registers a static catch-all in the app's `convex/http.ts`. Use it when exact app routes must remain
+at the same root. `pathPrefix`, `spaFallback`, and `cdnBaseUrl` are supported. The component must be
+installed without an `httpPrefix` so only the app owns that URL space.
+
+### `serveStaticAsset(ctx, component, request, options?)`
+
+Serves an uploaded file from an app-owned HTTP action, or returns `null` when no file matches so the
+action can continue with its own routing (server rendering, prerendered pages, redirects). Responses
+match `registerStaticRoutes`. The lookup is exact: `/` is not mapped to `/index.html`, and
+`spaFallback` defaults to `false`. `path` (the decoded file path, defaulting to the decoded request
+path, starting with `/` and without your route's prefix), `spaFallback`, and `cdnBaseUrl` are
+supported. A request path with malformed percent-encoding returns `null`. A found file whose storage
+can't be read gets a 500 response. The component must be installed without an `httpPrefix`.
+
+### `decodeRequestPath(pathname)`
+
+Decodes a URL pathname the way the static handlers do. Returns `null` for malformed
+percent-encoding.
+
+### `exposeDeploymentQuery(component)`
+
+Returns `{ getCurrentDeployment }`: a public query that wraps the component's deployment singleton.
+Add this only if you use `<UpdateBanner />` or `useDeploymentUpdates`.
+
+### `getConvexUrl()`
+
+Browser-only. Returns `https://<deployment>.convex.cloud` when the page is served from
+`<deployment>.convex.site`.
+
+## Additional Resources
+
+- [README](./README.md)
+- [Upstream 0.1.x to 0.2.x migration guide](https://github.com/get-convex/static-hosting/blob/main/MIGRATION.md)
+- [`examples/spa`](https://github.com/samebase/convex-hosting/tree/main/examples/spa): Working
+  example app
+- [Component source](https://github.com/samebase/convex-hosting/tree/main/packages/convex-hosting/src/component)