@rangojs/router 0.0.0-experimental.tapabs2 → 0.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.tapabs2",
+  "version": "0.1.0",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -37,144 +37,150 @@
   "type": "module",
   "exports": {
     ".": {
-      "types": "./src/index.rsc.ts",
+      "types": "./dist/types/index.rsc.d.ts",
       "react-server": "./src/index.rsc.ts",
       "default": "./src/index.ts"
     },
     "./server": {
-      "types": "./src/server.ts",
+      "types": "./dist/types/server.d.ts",
       "import": "./src/server.ts"
     },
     "./client": {
-      "types": "./src/client.tsx",
+      "types": "./dist/types/client.d.ts",
       "react-server": "./src/client.rsc.tsx",
       "default": "./src/client.tsx"
     },
     "./browser": {
-      "types": "./src/browser/index.ts",
+      "types": "./dist/types/browser/index.d.ts",
       "default": "./src/browser/index.ts"
     },
     "./ssr": {
-      "types": "./src/ssr/index.tsx",
+      "types": "./dist/types/ssr/index.d.ts",
       "default": "./src/ssr/index.tsx"
     },
     "./rsc": {
-      "types": "./src/rsc/index.ts",
+      "types": "./dist/types/rsc/index.d.ts",
       "react-server": "./src/rsc/index.ts",
       "default": "./src/rsc/index.ts"
     },
     "./vite": {
-      "types": "./src/vite/index.ts",
+      "types": "./dist/types/vite/index.d.ts",
       "import": "./dist/vite/index.js"
     },
     "./types": {
       "types": "./src/vite/plugins/version.d.ts"
     },
     "./__internal": {
-      "types": "./src/__internal.ts",
+      "types": "./dist/types/__internal.d.ts",
       "default": "./src/__internal.ts"
     },
     "./internal/deps/browser": {
-      "types": "./src/deps/browser.ts",
+      "types": "./dist/types/deps/browser.d.ts",
       "default": "./src/deps/browser.ts"
     },
     "./internal/deps/ssr": {
-      "types": "./src/deps/ssr.ts",
+      "types": "./dist/types/deps/ssr.d.ts",
       "default": "./src/deps/ssr.ts"
     },
     "./internal/deps/rsc": {
-      "types": "./src/deps/rsc.ts",
+      "types": "./dist/types/deps/rsc.d.ts",
       "react-server": "./src/deps/rsc.ts",
       "default": "./src/deps/rsc.ts"
     },
     "./internal/deps/html-stream-client": {
-      "types": "./src/deps/html-stream-client.ts",
+      "types": "./dist/types/deps/html-stream-client.d.ts",
       "default": "./src/deps/html-stream-client.ts"
     },
     "./internal/deps/html-stream-server": {
-      "types": "./src/deps/html-stream-server.ts",
+      "types": "./dist/types/deps/html-stream-server.d.ts",
       "default": "./src/deps/html-stream-server.ts"
     },
     "./internal/rsc-handler": {
-      "types": "./src/rsc/handler.ts",
+      "types": "./dist/types/rsc/handler.d.ts",
       "react-server": "./src/rsc/handler.ts",
       "default": "./src/rsc/handler.ts"
     },
     "./cache": {
-      "types": "./src/cache/index.ts",
+      "types": "./dist/types/cache/index.d.ts",
       "react-server": "./src/cache/index.ts",
       "default": "./src/cache/index.ts"
     },
     "./cache-runtime": {
-      "types": "./src/cache/cache-runtime.ts",
+      "types": "./dist/types/cache/cache-runtime.d.ts",
       "react-server": "./src/cache/cache-runtime.ts",
       "default": "./src/cache/cache-runtime.ts"
     },
     "./cloudflare": {
-      "types": "./src/cloudflare/index.ts",
+      "types": "./dist/types/cloudflare/index.d.ts",
       "react-server": "./src/cloudflare/index.ts",
       "default": "./src/cloudflare/index.ts"
     },
     "./vercel": {
-      "types": "./src/vercel/index.ts",
+      "types": "./dist/types/vercel/index.d.ts",
       "react-server": "./src/vercel/index.ts",
       "default": "./src/vercel/index.ts"
     },
     "./theme": {
-      "types": "./src/theme/index.ts",
+      "types": "./dist/types/theme/index.d.ts",
       "default": "./src/theme/index.ts"
     },
     "./build": {
-      "types": "./src/build/index.ts",
+      "types": "./dist/types/build/index.d.ts",
       "import": "./src/build/index.ts"
     },
+    "./build/shell-capture": {
+      "types": "./dist/types/prerender/build-shell-capture.d.ts",
+      "react-server": "./src/prerender/build-shell-capture.ts",
+      "import": "./src/prerender/build-shell-capture.ts"
+    },
     "./host": {
-      "types": "./src/host/index.ts",
+      "types": "./dist/types/host/index.d.ts",
       "react-server": "./src/host/index.ts",
       "default": "./src/host/index.ts"
     },
     "./host/testing": {
-      "types": "./src/host/testing.ts",
+      "types": "./dist/types/host/testing.d.ts",
       "default": "./src/host/testing.ts"
     },
     "./testing": {
-      "types": "./src/testing/index.ts",
+      "types": "./dist/types/testing/index.d.ts",
       "default": "./src/testing/index.ts"
     },
     "./testing/vitest": {
-      "types": "./src/testing/vitest.ts",
+      "types": "./dist/types/testing/vitest.d.ts",
       "default": "./dist/testing/vitest.js"
     },
     "./testing/dom": {
-      "types": "./src/testing/dom.entry.ts",
+      "types": "./dist/types/testing/dom.entry.d.ts",
       "default": "./src/testing/dom.entry.ts"
     },
     "./testing/e2e": {
-      "types": "./src/testing/e2e/index.ts",
+      "types": "./dist/types/testing/e2e/index.d.ts",
       "default": "./src/testing/e2e/index.ts"
     },
     "./testing/flight": {
-      "types": "./src/testing/flight.entry.ts",
+      "types": "./dist/types/testing/flight.entry.d.ts",
       "react-server": "./src/testing/flight.entry.ts",
       "default": "./src/testing/flight.entry.ts"
     },
     "./testing/flight-matchers": {
-      "types": "./src/testing/flight-matchers.ts",
+      "types": "./dist/types/testing/flight-matchers.d.ts",
       "default": "./src/testing/flight-matchers.ts"
     }
   },
   "publishConfig": {
     "access": "public",
-    "tag": "experimental"
+    "tag": "latest"
   },
   "scripts": {
-    "build": "pnpm exec esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm exec esbuild src/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && pnpm exec esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
+    "build": "pnpm run build:types && pnpm exec esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm exec esbuild src/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && pnpm exec esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
+    "build:types": "rm -rf dist/types && pnpm exec tsc -p tsconfig.types.json",
     "prepublishOnly": "pnpm build",
     "typecheck": "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
     "test": "playwright test",
     "test:ui": "playwright test --ui",
     "test:hmr-local": "playwright test --project=dev-warmup --project=hmr-routes --project=hmr-basename --project=hmr-prerender --no-deps --workers=1",
-    "test:unit": "vitest run",
+    "test:unit": "pnpm run build:types && vitest run",
     "test:unit:watch": "vitest",
     "test:unit:rsc": "vitest run --config vitest.rsc.config.ts"
   },
@@ -243,6 +249,6 @@
     }
   },
   "engines": {
-    "node": "^20.19.0 || >=22.12.0"
+    "node": ">=24.0.0"
   }
 }

package/skills/catalog.json

@@ -33,6 +33,12 @@
       "argumentHint": "[setup]",
       "path": "skills/caching/SKILL.md"
     },
+    {
+      "name": "cloudflare",
+      "description": "Deploy and operate @rangojs/router on Cloudflare Workers with the Cloudflare Vite plugin, typed D1/KV bindings, local migrations, secrets, streaming, preview parity, and built-worker deployment. Use when creating a Cloudflare Rango app, moving a Rango app to Workers, wiring D1 or KV, debugging dev/preview differences, or preparing a Worker deployment.",
+      "argumentHint": "",
+      "path": "skills/cloudflare/SKILL.md"
+    },
     {
       "name": "comparison",
       "description": "Compare Rango with Next.js App Router, TanStack Start, and Waku. Use when evaluating React frameworks, explaining why Rango, writing positioning or adoption guidance, answering migration questions, or checking claims about Rango's routing, loaders, caching, rendering, prefetching, safety, testing, observability, and production behavior.",

package/skills/cloudflare/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: cloudflare
+description: Deploy and operate @rangojs/router on Cloudflare Workers with the Cloudflare Vite plugin, typed D1/KV bindings, local migrations, secrets, streaming, preview parity, and built-worker deployment. Use when creating a Cloudflare Rango app, moving a Rango app to Workers, wiring D1 or KV, debugging dev/preview differences, or preparing a Worker deployment.
+---
+
+# Cloudflare Workers deployment
+
+Use the Cloudflare Vite plugin as the runtime bridge. It runs the real Worker
+entry in workerd during `vite dev` and `vite preview`, supplies bindings, and
+emits the deployable Worker configuration during `vite build`.
+
+## Install and configure
+
+```bash
+pnpm add @rangojs/router react react-dom
+pnpm add -D vite @vitejs/plugin-react @cloudflare/vite-plugin \
+  @cloudflare/workers-types wrangler typescript
+```
+
+Keep plugin order stable: React first, then Rango, then Cloudflare.
+
+```typescript
+// vite.config.ts
+import { cloudflare } from "@cloudflare/vite-plugin";
+import react from "@vitejs/plugin-react";
+import { rango } from "@rangojs/router/vite";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [
+    react(),
+    rango({ preset: "cloudflare", buildEnv: "auto" }),
+    cloudflare({
+      configPath: "./wrangler.json",
+      viteEnvironment: { name: "rsc", childEnvironments: ["ssr"] },
+    }),
+  ],
+});
+```
+
+`buildEnv: "auto"` exposes build-safe bindings to static/prerender collection.
+Omit it when build rendering must not access bindings.
+
+```json
+{
+  "name": "my-rango-app",
+  "compatibility_date": "2025-10-01",
+  "compatibility_flags": ["nodejs_compat", "nodejs_als"],
+  "main": "./src/worker.rsc.tsx",
+  "assets": { "directory": "./dist/client" }
+}
+```
+
+## Type bindings once
+
+```typescript
+// src/env.ts
+/// <reference types="@cloudflare/workers-types" />
+
+export interface AppBindings {
+  DB: D1Database;
+  CACHE_KV: KVNamespace;
+}
+
+declare global {
+  namespace Rango {
+    interface Env extends AppBindings {}
+  }
+}
+```
+
+Rango's runtime entries stay as TypeScript source for Vite to bundle, while its
+package `types` conditions point to emitted declarations. A Workers-only app
+does not need `@types/node` just to type-check Rango:
+
+```json
+{
+  "compilerOptions": {
+    "types": ["@cloudflare/workers-types", "vite/client"]
+  }
+}
+```
+
+## Preserve the response stream
+
+```typescript
+// src/worker.rsc.tsx
+/// <reference types="@cloudflare/workers-types" />
+import { router } from "./router.js";
+import type { AppBindings } from "./env.js";
+
+export default {
+  fetch(request, env, ctx) {
+    return router.fetch(request, { env, ctx });
+  },
+} satisfies ExportedHandler<AppBindings>;
+```
+
+Do not call `response.text()` or `response.arrayBuffer()` on the Rango response
+in a custom Worker entry. That drains RSC/SSR streaming. Rewrap
+`new Response(response.body, response)` when only headers must change.
+
+## Choose the next reference
+
+- D1/KV setup, local migrations, `.dev.vars`, and parity tests: read
+  [references/d1-and-local-dev.md](references/d1-and-local-dev.md).
+- Streaming diagnostics, preview behavior, CORS, and deploy output: read
+  [references/streaming-and-deploy.md](references/streaming-and-deploy.md).
+- Raw-body webhooks, WebCrypto, and Stripe-on-Workers notes: read
+  [references/webhooks-and-crypto.md](references/webhooks-and-crypto.md).
+
+## Cache on Workers
+
+Use the Cache API as L1 and KV as optional cross-colo L2:
+
+```typescript
+import { CFCacheStore } from "@rangojs/router/cache";
+
+export const router = createRouter<AppBindings>({
+  document: Document,
+  urls: urlpatterns,
+  cache: (env, ctx) => ({
+    store: new CFCacheStore({
+      ctx,
+      kv: env.CACHE_KV,
+      defaults: { ttl: 60, swr: 300 },
+    }),
+  }),
+});
+```
+
+KV is required for durable PPR shells. `CFCacheStore` without `kv` can still
+cache segment/response entries in the Cache API, but its shell family is inert.
+
+## Commands
+
+```jsonc
+{
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build",
+    "preview": "vite preview",
+    "deploy": "wrangler deploy -c dist/rsc/wrangler.json",
+  },
+}
+```
+
+Use `vite dev` and `vite preview` for local RSC work. Reserve Wrangler for
+resource provisioning, migrations, secrets, and deployment.

package/skills/cloudflare/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Cloudflare deployment"
+  short_description: "Deploy Rango on Cloudflare Workers with D1 and KV"
+  default_prompt: "Use $cloudflare to configure and deploy a Rango app on Cloudflare Workers with typed bindings."

package/skills/cloudflare/references/d1-and-local-dev.md

@@ -0,0 +1,131 @@
+# D1, KV, and local parity
+
+## Contents
+
+- [Provision bindings](#provision-bindings)
+- [Apply D1 migrations](#apply-d1-migrations)
+- [Use bindings](#use-bindings)
+- [Load local secrets](#load-local-secrets)
+- [Test dev and production-shaped preview](#test-dev-and-production-shaped-preview)
+
+## Provision bindings
+
+Create real resource IDs before the first deploy:
+
+```bash
+pnpm exec wrangler d1 create my-app
+pnpm exec wrangler kv namespace create CACHE_KV
+```
+
+Copy the returned IDs into `wrangler.json`:
+
+```json
+{
+  "d1_databases": [
+    {
+      "binding": "DB",
+      "database_name": "my-app",
+      "database_id": "<d1-id>",
+      "migrations_dir": "migrations"
+    }
+  ],
+  "kv_namespaces": [{ "binding": "CACHE_KV", "id": "<kv-id>" }]
+}
+```
+
+Do not deploy placeholder IDs. Keep binding names identical in `wrangler.json`
+and `AppBindings`; `ctx.env.DB` is the configured binding, not a global.
+
+## Apply D1 migrations
+
+```bash
+# Generate SQL with your migration tool first, then:
+pnpm exec wrangler d1 migrations apply my-app --local
+pnpm exec wrangler d1 migrations apply my-app --remote
+```
+
+The Cloudflare Vite plugin and `wrangler d1 ... --local` use the same local
+Miniflare persistence for the project. A migration applied through the CLI is
+therefore visible to both `vite dev` and `vite preview`; treat the internal
+`.wrangler/state` layout as an implementation detail.
+
+Add a real handler probe while setting up the binding, then remove it after the
+first production-shaped test:
+
+```typescript
+path.json("/__db-check", async (ctx) => {
+  const row = await ctx.env.DB.prepare(
+    "SELECT COUNT(*) AS n FROM users",
+  ).first<{
+    n: number;
+  }>();
+  return { ok: true, users: row?.n ?? 0 };
+});
+```
+
+## Use bindings
+
+Handlers, loaders, and middleware all receive the same typed bindings:
+
+```typescript
+export const UserLoader = createLoader(async (ctx) =>
+  ctx.env.DB.prepare("SELECT * FROM users WHERE id = ?")
+    .bind(ctx.params.id)
+    .first(),
+);
+
+export const requireSession: Middleware = async (ctx, next) => {
+  const token = cookies().get("session")?.value;
+  const session = token
+    ? await ctx.env.DB.prepare("SELECT * FROM sessions WHERE token = ?")
+        .bind(token)
+        .first()
+    : null;
+  if (!session) return redirect("/login");
+  return next();
+};
+```
+
+D1 has no Postgres RLS. Moving from an RLS-backed database requires an
+authorization-aware data-access layer that checks actor/tenant membership as
+part of every query. Do not translate SQL tables while silently dropping RLS.
+
+## Load local secrets
+
+Keep `.dev.vars` out of git and commit `.dev.vars.example` with names only:
+
+```dotenv
+SESSION_SECRET=
+STRIPE_WEBHOOK_SECRET=
+```
+
+Loading differs by command:
+
+| Command        | Source                                                      |
+| -------------- | ----------------------------------------------------------- |
+| `vite dev`     | live project `.dev.vars`                                    |
+| `vite preview` | `dist/<environment>/.dev.vars` copied during the last build |
+| `wrangler dev` | project `.dev.vars`                                         |
+
+Rebuild after changing `.dev.vars` before testing preview. Use
+`wrangler secret put NAME` for production secrets; `.dev.vars` is local only.
+
+Keep behavior-forcing e2e flags separate from a developer's default local
+profile. A copied `.dev.vars.example` that enables every production gate makes
+the documented "easy local dev" mode false.
+
+## Test dev and production-shaped preview
+
+Run the same behavior suite twice:
+
+1. `vite dev` against the source/module-runner path.
+2. `vite build`, then `vite preview` against the bundled Worker in workerd.
+
+Seed external-provider state offline where possible. For example, sign a test
+webhook with a fixed local webhook secret and assert the real D1 effect instead
+of provisioning a live payment account.
+
+When Playwright manages the servers, run dev and preview sequentially if they
+share the build directory or local D1 state. Set `inspectorPort: false` in the
+Cloudflare plugin for automated runs that do not use the debugger, or assign
+explicit distinct ports.

package/skills/cloudflare/references/streaming-and-deploy.md

@@ -0,0 +1,107 @@
+# Streaming, preview, and deployment
+
+## Contents
+
+- [Keep streamed responses intact](#keep-streamed-responses-intact)
+- [Use Vite for local RSC work](#use-vite-for-local-rsc-work)
+- [Handle route-owned CORS](#handle-route-owned-cors)
+- [Deploy the built Worker](#deploy-the-built-worker)
+- [Debug a dev-preview difference](#debug-a-dev-preview-difference)
+
+## Keep streamed responses intact
+
+Anything that awaits the full Rango response body removes streaming:
+
+```typescript
+// Wrong: drains the stream.
+const response = await router.fetch(request, { env, ctx });
+const html = await response.text();
+return new Response(rewrite(html), response);
+
+// Correct: preserve the body stream while changing headers.
+const response = await router.fetch(request, { env, ctx });
+const headers = new Headers(response.headers);
+headers.set("X-App", "worker");
+return new Response(response.body, {
+  status: response.status,
+  statusText: response.statusText,
+  headers,
+});
+```
+
+Keep buffering on a legacy proxy branch if it is required there, but never run
+it on the `router.fetch()` branch.
+
+## Use Vite for local RSC work
+
+Use `vite dev` and `vite preview`. The Cloudflare Vite plugin runs the Worker
+inside Miniflare/workerd with the same binding shape as deployment.
+
+Avoid diagnosing streaming with `wrangler dev`: local gzip compression can
+buffer the response. If that tool is unavoidable, compare
+`Accept-Encoding: identity` and `Accept-Encoding: gzip` before blaming the
+router. Deployed Cloudflare compression streams.
+
+Verify first-byte behavior directly:
+
+```bash
+curl --no-buffer --raw -H 'Accept-Encoding: identity' http://localhost:5173/slow
+```
+
+## Handle route-owned CORS
+
+Vite's CORS middleware answers preflight `OPTIONS` before the Worker in both
+`vite dev` and `vite preview` by default. A preview preflight therefore does not
+prove that the deployed route's own `OPTIONS` branch works.
+
+When the Worker must own exact CORS headers, disable the outer Vite CORS layer
+in both modes:
+
+```typescript
+export default defineConfig({
+  server: { cors: false },
+  preview: { cors: false },
+  // plugins...
+});
+```
+
+Assert the full CORS set on a real non-preflight response as well as the route's
+`OPTIONS` response. Keep a deployed smoke check for the final edge behavior.
+
+## Deploy the built Worker
+
+`vite build` writes client assets to `dist/client` and a deployable Worker
+configuration under the RSC environment output, normally
+`dist/rsc/wrangler.json`. That generated config points at the bundled Worker and
+sets the client asset directory correctly.
+
+```bash
+pnpm exec vite build
+pnpm exec wrangler deploy -c dist/rsc/wrangler.json
+```
+
+Do not deploy the source `main` from the root config after building. Wrangler's
+bundler cannot reconstruct Rango's Vite virtual modules. If the RSC environment
+has a custom name, use its matching `dist/<name>/wrangler.json` path.
+
+Before deployment:
+
+- replace placeholder D1/KV IDs;
+- apply remote D1 migrations;
+- provision each production secret with `wrangler secret put`;
+- run the preview parity suite against a fresh build;
+- confirm no server-only secret appears in `dist/client`;
+- smoke-test streaming and redirects on the deployed edge.
+
+## Debug a dev-preview difference
+
+1. Build immediately before preview; stale `dist` output invalidates the test.
+2. Compare the actual `.dev.vars`/bindings visible in each mode.
+3. Send `Accept: text/html` or no `Accept` for a document request; send
+   `Accept: text/x-component` only when testing Flight.
+4. Disable automatic redirect following when inspecting a 3xx.
+5. Test the target URL first on a fresh preview process, then after the redirect.
+6. Capture both curl timing and the Worker's request log. A request absent from
+   the Worker log is stuck in the outer Vite/Cloudflare layer.
+7. Reduce the case to one route before assigning ownership to Rango, Vite, or
+   the Cloudflare plugin.