@rangojs/router 0.0.0-experimental.2

package/package.json

@@ -0,0 +1,140 @@
+{
+  "name": "@rangojs/router",
+  "version": "0.0.0-experimental.2",
+  "type": "module",
+  "description": "Django-inspired RSC router with composable URL patterns",
+  "author": "Ivo Todorov",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ivogt/vite-rsc.git",
+    "directory": "packages/rangojs-router"
+  },
+  "homepage": "https://github.com/ivogt/vite-rsc#readme",
+  "bugs": {
+    "url": "https://github.com/ivogt/vite-rsc/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "experimental"
+  },
+  "keywords": [
+    "react",
+    "rsc",
+    "react-server-components",
+    "router",
+    "vite"
+  ],
+  "exports": {
+    ".": {
+      "react-server": "./src/index.rsc.ts",
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./server": {
+      "types": "./src/server.ts",
+      "import": "./src/server.ts"
+    },
+    "./client": {
+      "react-server": "./src/client.rsc.tsx",
+      "types": "./src/client.tsx",
+      "default": "./src/client.tsx"
+    },
+    "./browser": {
+      "types": "./src/browser/index.ts",
+      "default": "./src/browser/index.ts"
+    },
+    "./ssr": {
+      "types": "./src/ssr/index.tsx",
+      "default": "./src/ssr/index.tsx"
+    },
+    "./rsc": {
+      "react-server": "./src/rsc/index.ts",
+      "types": "./src/rsc/index.ts",
+      "default": "./src/rsc/index.ts"
+    },
+    "./vite": {
+      "types": "./src/vite/index.ts",
+      "import": "./dist/vite/index.js"
+    },
+    "./types": {
+      "types": "./src/vite/version.d.ts"
+    },
+    "./internal/deps/browser": {
+      "types": "./src/deps/browser.ts",
+      "default": "./src/deps/browser.ts"
+    },
+    "./internal/deps/ssr": {
+      "types": "./src/deps/ssr.ts",
+      "default": "./src/deps/ssr.ts"
+    },
+    "./internal/deps/rsc": {
+      "react-server": "./src/deps/rsc.ts",
+      "types": "./src/deps/rsc.ts",
+      "default": "./src/deps/rsc.ts"
+    },
+    "./internal/deps/html-stream-client": {
+      "types": "./src/deps/html-stream-client.ts",
+      "default": "./src/deps/html-stream-client.ts"
+    },
+    "./internal/deps/html-stream-server": {
+      "types": "./src/deps/html-stream-server.ts",
+      "default": "./src/deps/html-stream-server.ts"
+    },
+    "./cache": {
+      "react-server": "./src/cache/index.ts",
+      "types": "./src/cache/index.ts",
+      "default": "./src/cache/index.ts"
+    },
+    "./theme": {
+      "types": "./src/theme/index.ts",
+      "default": "./src/theme/index.ts"
+    }
+  },
+  "files": [
+    "src",
+    "dist",
+    "skills",
+    "CLAUDE.md",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "@cloudflare/vite-plugin": "^1.21.0",
+    "@vitejs/plugin-rsc": "^0.5.14",
+    "react": "^18.0.0 || ^19.0.0",
+    "vite": "^7.3.0"
+  },
+  "peerDependenciesMeta": {
+    "@cloudflare/vite-plugin": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@vitejs/plugin-rsc": "^0.5.14",
+    "magic-string": "^0.30.17",
+    "rsc-html-stream": "^0.0.7"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.49.1",
+    "@types/node": "^24.10.1",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "react": "^19.2.1",
+    "react-dom": "^19.2.1",
+    "esbuild": "^0.27.0",
+    "tinyexec": "^0.3.2",
+    "typescript": "^5.3.0",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "pnpm dlx esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external",
+    "typecheck": "tsc --noEmit",
+    "test": "playwright test",
+    "test:ui": "playwright test --ui",
+    "test:unit": "vitest run",
+    "test:unit:watch": "vitest"
+  }
+}

package/skills/caching/SKILL.md

@@ -0,0 +1,319 @@
+---
+name: caching
+description: Configure segment caching with memory or Cloudflare KV stores in rsc-router
+argument-hint: [setup]
+---
+
+# Caching
+
+rsc-router supports segment-level caching with stale-while-revalidate (SWR) for optimal performance.
+
+## Router Cache Configuration
+
+Configure caching in `createRSCRouter`:
+
+```typescript
+import { createRSCRouter } from "rsc-router/server";
+import { MemorySegmentCacheStore } from "rsc-router/cache";
+
+const store = new MemorySegmentCacheStore({
+  defaults: { ttl: 60, swr: 300 }
+});
+
+const router = createRSCRouter<AppEnv>({
+  document: Document,
+  cache: {
+    store,
+    enabled: true,
+  },
+});
+```
+
+### Dynamic Cache Configuration
+
+Use a factory function for environment-based config:
+
+```typescript
+const router = createRSCRouter<AppEnv>({
+  document: Document,
+  cache: (env) => ({
+    store: new CFCacheStore({
+      baseUrl: env.Bindings.CACHE_URL,
+      waitUntil: (fn) => env.ctx.waitUntil(fn),
+    }),
+    enabled: env.Bindings.CACHE_ENABLED === "true",
+  }),
+});
+```
+
+## Cache Stores
+
+### Memory Store (Development)
+
+```typescript
+import { MemorySegmentCacheStore } from "rsc-router/cache";
+
+const store = new MemorySegmentCacheStore({
+  defaults: { ttl: 60, swr: 300 }
+});
+
+// Debug cache stats
+console.log(store.getStats());
+```
+
+Features:
+- Survives HMR in development
+- No true SWR (entries expire at TTL)
+- Good for development and single-instance deployments
+
+### Cloudflare Cache Store (Production)
+
+```typescript
+import { CFCacheStore } from "rsc-router/cache/cf";
+
+const store = new CFCacheStore({
+  namespace: "rsc-cache",              // Optional, uses caches.default
+  baseUrl: "https://cache.example.com/",
+  defaults: { ttl: 3600, swr: 7200 },
+  waitUntil: (fn) => ctx.waitUntil(fn),
+  version: "1.0.0",                    // For cache invalidation on deploy
+});
+```
+
+Features:
+- Cloudflare Cache API integration
+- True SWR with atomic revalidation (prevents thundering herd)
+- Non-blocking writes via `waitUntil`
+- Version-based cache invalidation
+
+## Cache Options
+
+```typescript
+interface CacheOptions {
+  // Time-to-live in seconds
+  ttl: number;
+
+  // Stale-while-revalidate window (seconds after TTL)
+  swr?: number;
+
+  // Override cache store for this boundary
+  store?: SegmentCacheStore;
+
+  // Conditional caching
+  condition?: (ctx) => boolean;
+
+  // Custom cache key
+  key?: (ctx) => string | Promise<string>;
+
+  // Tags for invalidation
+  tags?: string[] | ((ctx) => string[]);
+}
+```
+
+## Route-Level Caching
+
+Use `cache()` in handlers to set cache boundaries:
+
+```typescript
+import { map } from "rsc-router/server";
+
+export default map<typeof routes>(({ route, layout, cache }) => [
+  // Cache entire layout and children
+  cache({ ttl: 3600, swr: 7200 }, () => [
+    layout(<StaticLayout />, () => [
+      route("about", AboutPage),
+      route("contact", ContactPage),
+    ]),
+  ]),
+
+  // Different cache settings per route
+  cache({ ttl: 60 }, () => [
+    route("dashboard", DashboardPage),
+  ]),
+
+  // No caching (default)
+  route("checkout", CheckoutPage),
+]);
+```
+
+## Conditional Caching
+
+Skip cache based on request context:
+
+```typescript
+cache({
+  ttl: 3600,
+  condition: (ctx) => {
+    // Don't cache for authenticated users
+    const hasAuth = ctx.request.headers.has("Authorization");
+    return !hasAuth;
+  },
+}, () => [
+  route("products", ProductList),
+])
+```
+
+## Custom Cache Keys
+
+Override the default cache key:
+
+```typescript
+cache({
+  ttl: 3600,
+  key: (ctx) => {
+    // Include user segment in cache key
+    const segment = ctx.request.headers.get("x-user-segment") || "default";
+    return `${segment}:products:${ctx.params.category}`;
+  },
+}, () => [
+  route("products.category", CategoryPage),
+])
+```
+
+Store-level key modification:
+
+```typescript
+const store = new CFCacheStore({
+  keyGenerator: (ctx, defaultKey) => {
+    const region = ctx.request.cf?.colo || "unknown";
+    return `${region}:${defaultKey}`;
+  },
+});
+```
+
+## Stale-While-Revalidate (SWR)
+
+SWR serves stale content while fetching fresh data in the background:
+
+```
+Timeline:
+├─ 0 to TTL ─────────┤ Fresh content served
+├─ TTL to TTL+SWR ───┤ Stale content served, revalidation in background
+├─ After TTL+SWR ────┤ Cache expired, new fetch required
+```
+
+```typescript
+cache({
+  ttl: 60,      // Fresh for 60 seconds
+  swr: 300,     // Stale-but-usable for 5 more minutes
+}, () => [
+  route("feed", FeedPage),
+])
+```
+
+## Multi-Store Setup
+
+Use different stores for different data patterns:
+
+```typescript
+const hotStore = new MemorySegmentCacheStore({
+  defaults: { ttl: 10 }
+});
+
+const coldStore = new CFCacheStore({
+  defaults: { ttl: 3600, swr: 7200 }
+});
+
+export default map<typeof routes>(({ route, cache }) => [
+  // Frequently changing data - short TTL, memory
+  cache({ store: hotStore, ttl: 10 }, () => [
+    route("dashboard", DashboardPage),
+    route("notifications", NotificationsPage),
+  ]),
+
+  // Rarely changing data - long TTL, edge cache
+  cache({ store: coldStore, ttl: 3600 }, () => [
+    route("archive", ArchivePage),
+    route("docs", DocsPage),
+  ]),
+]);
+```
+
+## Cache Invalidation
+
+### Version-Based (Cloudflare)
+
+```typescript
+import packageJson from "./package.json";
+
+const store = new CFCacheStore({
+  version: packageJson.version,  // All cache invalidated on deploy
+});
+```
+
+### Tag-Based (Future)
+
+```typescript
+cache({
+  tags: (ctx) => [`product:${ctx.params.id}`, "products"],
+}, () => [
+  route("products.detail", ProductDetail),
+])
+
+// Invalidate by tag
+await store.invalidateTag("products");
+```
+
+## Complete Production Example
+
+```typescript
+// router.tsx
+import { createRSCRouter } from "rsc-router/server";
+import { CFCacheStore } from "rsc-router/cache/cf";
+import packageJson from "./package.json";
+
+const router = createRSCRouter<AppEnv>({
+  document: Document,
+  cache: (env) => ({
+    store: new CFCacheStore({
+      baseUrl: "https://rsc-cache.internal/",
+      defaults: { ttl: 300, swr: 3600 },
+      waitUntil: (fn) => env.ctx.waitUntil(fn),
+      version: packageJson.version,
+    }),
+    enabled: env.Bindings.NODE_ENV === "production",
+  }),
+});
+
+// handlers/shop.tsx
+export default map<typeof shopRoutes>(({ route, layout, cache }) => [
+  // Static pages - aggressive caching
+  cache({ ttl: 86400, swr: 604800 }, () => [
+    route("shop.about", AboutPage),
+    route("shop.terms", TermsPage),
+  ]),
+
+  // Product listing - moderate caching
+  cache({ ttl: 300, swr: 3600 }, () => [
+    route("shop.products", ProductList),
+  ]),
+
+  // Product detail - cache with product-specific key
+  cache({
+    ttl: 600,
+    swr: 3600,
+    key: (ctx) => `product:${ctx.params.slug}`,
+  }, () => [
+    route("shop.product", ProductDetail),
+  ]),
+
+  // User-specific pages - no caching
+  route("shop.cart", CartPage),
+  route("shop.checkout", CheckoutPage),
+]);
+```
+
+## Cache Headers (Cloudflare)
+
+CFCacheStore sets these headers for debugging:
+
+- `x-edge-cache-status`: `HIT` or `REVALIDATING`
+- `x-edge-cache-stale-at`: Timestamp when entry becomes stale
+
+## What Gets Cached
+
+- Route segments (components, layouts, loading states)
+- Handle data (breadcrumbs, metadata)
+- **Not cached by default**: Loader data (fetched fresh each request)
+
+To cache loader results, use loader-level caching or external caching strategies.

package/skills/document-cache/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: document-cache
+description: Cache full HTTP responses at the edge with Cache-Control headers
+argument-hint: [setup]
+---
+
+# Document Cache
+
+Caches complete HTTP responses (HTML/RSC) at the edge based on Cache-Control headers. Routes opt-in by setting `s-maxage`.
+
+## Setup
+
+Add middleware to router:
+
+```typescript
+import { createRSCRouter, createDocumentCacheMiddleware } from "@rangojs/router/server";
+import { CFCacheStore } from "@rangojs/router/cache/cf";
+
+const router = createRSCRouter<AppEnv>({
+  document: Document,
+  cache: (env) => ({
+    store: new CFCacheStore({ ctx: env.ctx }),
+  }),
+})
+  .use(createDocumentCacheMiddleware())
+  .routes(routes);
+```
+
+## Route Opt-In
+
+Routes opt-in by setting `Cache-Control` with `s-maxage`:
+
+```typescript
+route("home", (ctx) => {
+  ctx.headers.set("Cache-Control", "s-maxage=60, stale-while-revalidate=300");
+  return <HomePage />;
+});
+```
+
+## Middleware Options
+
+```typescript
+createDocumentCacheMiddleware({
+  // Skip specific paths
+  skipPaths: ["/api", "/admin"],
+
+  // Custom cache key
+  keyGenerator: (url) => url.pathname,
+
+  // Conditional caching
+  isEnabled: (ctx) => !ctx.request.headers.has("x-preview"),
+
+  // Debug logging
+  debug: true,
+});
+```
+
+## How It Works
+
+```
+Request → Check Cache
+           ↓
+    ┌──────┴──────┐
+    │             │
+  HIT           MISS
+    │             │
+    ↓             ↓
+  Fresh?      Run handler
+    │             │
+   Yes → Return   Has s-maxage?
+    │             │
+   No (stale)    Yes → Cache + Return
+    │             │
+    ↓            No → Return (no cache)
+  Return stale,
+  revalidate in
+  background (SWR)
+```
+
+## Cache Status Header
+
+Response includes `x-document-cache-status`:
+- `HIT` - Fresh cache hit
+- `STALE` - Served stale, revalidating in background
+- `MISS` - Cache miss, response was generated fresh
+
+## Cache Key Generation
+
+Default keys differentiate:
+- HTML requests: `{pathname}:html`
+- RSC partials: `{pathname}:{segmentHash}:rsc`
+
+Segment hash ensures different cached responses for navigations from different source pages (with different layouts).
+
+## What Gets Cached
+
+- Full HTML responses (document requests)
+- RSC payloads (client navigation)
+- Only 200 OK responses with `s-maxage`
+
+## What's NOT Cached
+
+- Server actions (`_rsc_action`)
+- Loader requests (`_rsc_loader`)
+- Responses without `s-maxage`
+- Non-200 responses
+
+## Complete Example
+
+```typescript
+// router.tsx
+const router = createRSCRouter<AppEnv>({
+  document: Document,
+  cache: (env) => ({
+    store: new CFCacheStore({ ctx: env.ctx }),
+  }),
+})
+  .use(createDocumentCacheMiddleware({
+    skipPaths: ["/api"],
+    debug: process.env.NODE_ENV === "development",
+  }))
+  .routes(routes);
+
+// handlers.tsx
+route("blog", (ctx) => {
+  // Cache for 5 min, serve stale for 1 hour while revalidating
+  ctx.headers.set("Cache-Control", "s-maxage=300, stale-while-revalidate=3600");
+  return <BlogIndex />;
+});
+
+route("blog.post", (ctx) => {
+  // Long cache for individual posts
+  ctx.headers.set("Cache-Control", "s-maxage=3600, stale-while-revalidate=86400");
+  return <BlogPost slug={ctx.params.slug} />;
+});
+
+route("dashboard", (ctx) => {
+  // No cache header = not cached
+  return <Dashboard />;
+});
+```
+
+## Document Cache vs Segment Cache
+
+| Feature | Document Cache | Segment Cache |
+|---------|---------------|---------------|
+| Granularity | Full response | Individual segments |
+| Opt-in | `s-maxage` header | `cache()` DSL |
+| Use case | Static pages | Dynamic compositions |
+| Key includes | URL + segment hash | Route params |
+
+Use document cache for mostly-static pages. Use segment cache when different parts of a page have different cache requirements.