rwsdk 0.1.16 → 0.1.17

package/dist/llms/rules/interruptors.js

@@ -0,0 +1,243 @@
+export const interruptors = `
+
+# RedwoodSDK: Request Interruptors
+
+You're an expert at Cloudflare, TypeScript, and building web apps with RedwoodSDK. Generate high quality **RedwoodSDK interruptors** (middleware functions) that adhere to the following best practices:
+
+## Guidelines
+
+1. Create focused, single-responsibility interruptors
+2. Organize interruptors in dedicated files (e.g., \`interruptors.ts\`, \`interceptors.ts\`, or \`middleware.ts\`)
+3. Compose interruptors to create more complex validation chains
+4. Use typed parameters and return values
+5. Include clear error handling and user feedback
+
+## What are Interruptors?
+
+Interruptors are middleware functions that run before your route handlers. They can:
+
+- Validate user authentication and authorization
+- Transform request data
+- Validate inputs
+- Rate limit requests
+- Log activity
+- Redirect users based on conditions
+- Short-circuit request handling with early responses
+
+## Example Templates
+
+### Basic Interruptor Structure
+
+\`\`\`tsx
+async function myInterruptor({ request, params, ctx }) {
+  // Perform checks or transformations here
+
+  // Return modified context to pass to the next interruptor or handler
+  ctx.someAddedData = "value";
+
+  // OR return a Response to short-circuit the request
+  // return new Response('Unauthorized', { status: 401 });
+}
+\`\`\`
+
+### Authentication Interruptors
+
+\`\`\`tsx
+export async function requireAuth({ request, ctx }) {
+  if (!ctx.user) {
+    return new Response(null, {
+      status: 302,
+      headers: { Location: "/user/login" },
+    });
+  }
+}
+
+export async function requireAdmin({ request, ctx }) {
+  if (!ctx?.user?.isAdmin) {
+    return new Response(null, {
+      status: 302,
+      headers: { Location: "/user/login" },
+    });
+  }
+}
+\`\`\`
+
+### Input Validation Interruptor
+
+\`\`\`tsx
+import { z } from "zod";
+
+// Create a reusable validator interruptor
+export function validateInput(schema) {
+  return async function validateInputInterruptor({ request, ctx }) {
+    try {
+      const data = await request.json();
+      const validated = (ctx.data = schema.parse(data));
+    } catch (error) {
+      return Response.json(
+        { error: "Validation failed", details: error.errors },
+        { status: 400 },
+      );
+    }
+  };
+}
+
+// Usage example with a Zod schema
+const userSchema = z.object({
+  name: z.string().min(2),
+  email: z.string().email(),
+  age: z.number().min(18).optional(),
+});
+
+export const validateUser = validateInput(userSchema);
+\`\`\`
+
+### Logging Interruptor
+
+\`\`\`tsx
+export async function logRequests({ request, ctx }) {
+  const start = Date.now();
+
+  // Add a function to the context that will log when called
+  ctx.logCompletion: (response) => {
+      const duration = Date.now() - start;
+      const status = response.status;
+      console.log(
+        \`\${request.method} \${request.url} - \${status} (\${duration}ms)\`,
+      );
+    },
+  };
+}
+
+// Usage in a route handler
+route('/', [
+  logRequests,
+  async ({request, ctx}) => {
+    // Call the logging function
+    ctx.logCompletion(response);
+    return Response.json({ success: true });;
+  },
+]);
+\`\`\`
+
+### Composing Multiple Interruptors
+
+\`\`\`tsx
+import { route } from "rwsdk/router";
+import {
+  requireAuth,
+  validateUser,
+  apiRateLimit,
+  logRequests,
+} from "@/app/interruptors";
+
+// Combine multiple interruptors
+route("/api/users", [
+    logRequests, // Log all requests
+    requireAuth, // Ensure user is authenticated
+    validateUser, // Validate user input
+    async ({ request, ctx }) => {
+      // Handler receives validated data and session from interruptors
+      const newUser = await db.user.create({
+        data: {
+          /* ... */,
+          createdBy: ctx.user.userId,
+        },
+      });
+
+      return Response.json(newUser, { status: 201 });
+    },
+  ],
+});
+\`\`\`
+
+### Role-Based Access Control
+
+\`\`\`tsx
+import { getSession } from "rwsdk/auth";
+
+// Create a function that generates role-based interruptors
+export function hasRole(allowedRoles) {
+  return async function hasRoleInterruptor({ request, ctx }) {
+    const session = await getSession(request);
+
+    if (!session) {
+      return Response.redirect("/login");
+    }
+
+    if (!allowedRoles.includes(session.role)) {
+      return Response.json({ error: "Unauthorized" }, { status: 403 });
+    }
+
+    return { ...ctx, session };
+  };
+}
+
+// Create specific role-based interruptors
+export const isAdmin = hasRole(["ADMIN"]);
+export const isEditor = hasRole(["ADMIN", "EDITOR"]);
+export const isUser = hasRole(["ADMIN", "EDITOR", "USER"]);
+\`\`\`
+
+### Organization with Co-located Interruptors
+
+Create a file at \`./src/app/interruptors.ts\`:
+
+\`\`\`tsx
+import { getSession } from "rwsdk/auth";
+
+// Authentication interruptors
+export async function requireAuth({ request, ctx }) {
+  const session = await getSession(request);
+
+  if (!session) {
+    return Response.redirect("/login");
+  }
+
+  return { ...ctx, session };
+}
+
+// Role-based interruptors
+export function hasRole(allowedRoles) {
+  return async function hasRoleInterruptor({ request, ctx }) {
+    const session = await getSession(request);
+
+    if (!session) {
+      return Response.redirect("/login");
+    }
+
+    if (!allowedRoles.includes(session.role)) {
+      return Response.json({ error: "Unauthorized" }, { status: 403 });
+    }
+
+    return { ...ctx, session };
+  };
+}
+
+export const isAdmin = hasRole(["ADMIN"]);
+export const isEditor = hasRole(["ADMIN", "EDITOR"]);
+
+// Other common interruptors
+export async function logRequests({ request, ctx }) {
+  console.log(\`\${request.method} \${request.url}\`);
+  return ctx;
+}
+\`\`\`
+
+Then import these interruptors in your route files:
+
+\`\`\`tsx
+// src/app/pages/admin/routes.ts
+import { route } from "rwsdk/router";
+import { isAdmin, logRequests } from "@/app/interruptors";
+
+import { AdminDashboard } from "./AdminDashboard";
+import { UserManagement } from "./UserManagement";
+
+export const routes = [
+  route("/", [isAdmin, logRequests, AdminDashboard]),
+  route("/users", [isAdmin, logRequests, UserManagement]),
+];
+\`\`\`
+
+`;

package/dist/llms/rules/middleware.d.ts

@@ -0,0 +1 @@
+export declare const middleware = "\n\n# RedwoodSDK: Middleware\n\nYou're an expert at Cloudflare, TypeScript, and building web apps with RedwoodSDK. Generate high quality **RedwoodSDK middleware** that adhere to the following best practices:\n\n## Guidelines\n\n1. Create focused, single-responsibility middleware functions\n2. Organize middleware in dedicated files (e.g., `middleware.ts`, `middleware.tsx`)\n3. Use typed parameters and return values\n4. Include clear error handling and logging\n5. Follow the principle of least privilege\n6. Implement proper security headers and CORS policies\n7. Optimize for performance with caching strategies\n\n## What is Middleware?\n\nMiddleware functions in RedwoodSDK are functions that run on every request before your route handlers. They can:\n\n- Add security headers\n- Handle CORS\n- Implement caching strategies\n- Add request/response logging\n- Transform request/response data\n- Implement rate limiting\n- Add performance monitoring\n- Handle error boundaries\n- Setup sessions\n- Authenticate users\n\n## Example Templates\n\n### Basic Middleware Structure\n\n```tsx\nexport default defineApp([\n  setCommonHeaders(),\n  async ({ ctx, request, headers }) => {\n    await setupDb(env);\n    setupSessionStore(env);\n    try {\n      // Grab the session's data.\n      ctx.session = await sessions.load(request);\n    } catch (error) {\n      if (error instanceof ErrorResponse && error.code === 401) {\n        await sessions.remove(request, headers);\n        headers.set(\"Location\", \"/user/login\");\n\n        return new Response(null, {\n          status: 302,\n          headers,\n        });\n      }\n\n      throw error;\n    }\n\n    // Populate the ctx with the user's data\n    if (ctx.session?.userId) {\n      ctx.user = await db.user.findUnique({\n        where: {\n          id: ctx.session.userId,\n        },\n      });\n    }\n  },\n  // Route handlers\n]);\n```\n";

package/dist/llms/rules/middleware.js

@@ -0,0 +1,71 @@
+export const middleware = `
+
+# RedwoodSDK: Middleware
+
+You're an expert at Cloudflare, TypeScript, and building web apps with RedwoodSDK. Generate high quality **RedwoodSDK middleware** that adhere to the following best practices:
+
+## Guidelines
+
+1. Create focused, single-responsibility middleware functions
+2. Organize middleware in dedicated files (e.g., \`middleware.ts\`, \`middleware.tsx\`)
+3. Use typed parameters and return values
+4. Include clear error handling and logging
+5. Follow the principle of least privilege
+6. Implement proper security headers and CORS policies
+7. Optimize for performance with caching strategies
+
+## What is Middleware?
+
+Middleware functions in RedwoodSDK are functions that run on every request before your route handlers. They can:
+
+- Add security headers
+- Handle CORS
+- Implement caching strategies
+- Add request/response logging
+- Transform request/response data
+- Implement rate limiting
+- Add performance monitoring
+- Handle error boundaries
+- Setup sessions
+- Authenticate users
+
+## Example Templates
+
+### Basic Middleware Structure
+
+\`\`\`tsx
+export default defineApp([
+  setCommonHeaders(),
+  async ({ ctx, request, headers }) => {
+    await setupDb(env);
+    setupSessionStore(env);
+    try {
+      // Grab the session's data.
+      ctx.session = await sessions.load(request);
+    } catch (error) {
+      if (error instanceof ErrorResponse && error.code === 401) {
+        await sessions.remove(request, headers);
+        headers.set("Location", "/user/login");
+
+        return new Response(null, {
+          status: 302,
+          headers,
+        });
+      }
+
+      throw error;
+    }
+
+    // Populate the ctx with the user's data
+    if (ctx.session?.userId) {
+      ctx.user = await db.user.findUnique({
+        where: {
+          id: ctx.session.userId,
+        },
+      });
+    }
+  },
+  // Route handlers
+]);
+\`\`\`
+`;

package/dist/llms/rules/react.d.ts

@@ -0,0 +1 @@
+export declare const react = "\n# React, React Server Components, and React Server Functions Rules\n\n## React Server Components (RSC)\n\n1. By default, all components are server components unless explicitly marked as client components.\n2. Server components are rendered on the server as HTML and streamed to the browser.\n3. Server components cannot include client-side interactivity (state, effects, event handlers).\n4. Server components can directly fetch data and include it in the initial payload.\n5. Server components can be async and can be wrapped in Suspense boundaries.\n\nExample:\n\n```tsx\nexport default function MyServerComponent() {\n  return <div>Hello, from the server!</div>;\n}\n```\n\n## Client Components\n\n1. Must be explicitly marked with the \"use client\" directive at the top of the file.\n2. Required when the component needs:\n   - Interactivity (click handlers, state management)\n   - Browser APIs\n   - Event listeners\n   - Client-side effects\n   - Client-side routing\n3. Will be hydrated by React in the browser.\n\nExample:\n\n```tsx\n\"use client\";\n\nexport default function MyClientComponent() {\n  return <button onClick={() => console.log(\"clicked\")}>Click me</button>;\n}\n```\n\n## Data Fetching in Server Components\n\n1. Server components can directly fetch data without useEffect or other client-side data fetching methods.\n2. Use Suspense boundaries to handle loading states for async server components.\n3. Pass context (ctx) through props to child components that need it.\n\nExample:\n\n```tsx\nexport async function TodoList({ ctx }) {\n  const todos = await db.todo.findMany({ where: { userId: ctx.user.id } });\n\n  return (\n    <ol>\n      {todos.map((todo) => (\n        <li key={todo.id}>{todo.title}</li>\n      ))}\n    </ol>\n  );\n}\n```\n\n## Server Functions\n\n1. Must be marked with the \"use server\" directive at the top of the file.\n2. Can be imported and used in client components.\n3. Execute on the server when called from client components.\n4. Have access to the request context via requestInfo.ctx.\n5. Can handle form submissions and other server-side operations.\n\nExample:\n\n```tsx\n\"use server\";\n\nimport { requestInfo } from \"rwsdk/worker\";\n\nexport async function addTodo(formData: FormData) {\n  const { ctx } = requestInfo;\n  const title = formData.get(\"title\");\n  await db.todo.create({ data: { title, userId: ctx.user.id } });\n}\n```\n\n## Context Usage\n\n1. Context is available to all server components and server functions.\n2. Access context via:\n   - requestInfo in server functions:\n   ```\n   import { requestInfo } from \"rwsdk/worker\";\n   const { ctx } = requestInfo\n   ```\n3. Context is populated by middleware and interruptors and is request-scoped.\n\n## Best Practices\n\n1. Keep server components as the default choice unless client-side interactivity is needed.\n2. Use client components only when necessary to minimize the JavaScript bundle size.\n3. Leverage server components for data fetching and initial rendering.\n4. Use Suspense boundaries appropriately for loading states.\n5. Keep client components as small as possible, moving server-side logic to server components or server functions.\n6. Always mark client components with \"use client\" directive.\n7. Always mark server functions with \"use server\" directive.\n\n";

package/dist/llms/rules/react.js

@@ -0,0 +1,106 @@
+export const react = `
+# React, React Server Components, and React Server Functions Rules
+
+## React Server Components (RSC)
+
+1. By default, all components are server components unless explicitly marked as client components.
+2. Server components are rendered on the server as HTML and streamed to the browser.
+3. Server components cannot include client-side interactivity (state, effects, event handlers).
+4. Server components can directly fetch data and include it in the initial payload.
+5. Server components can be async and can be wrapped in Suspense boundaries.
+
+Example:
+
+\`\`\`tsx
+export default function MyServerComponent() {
+  return <div>Hello, from the server!</div>;
+}
+\`\`\`
+
+## Client Components
+
+1. Must be explicitly marked with the "use client" directive at the top of the file.
+2. Required when the component needs:
+   - Interactivity (click handlers, state management)
+   - Browser APIs
+   - Event listeners
+   - Client-side effects
+   - Client-side routing
+3. Will be hydrated by React in the browser.
+
+Example:
+
+\`\`\`tsx
+"use client";
+
+export default function MyClientComponent() {
+  return <button onClick={() => console.log("clicked")}>Click me</button>;
+}
+\`\`\`
+
+## Data Fetching in Server Components
+
+1. Server components can directly fetch data without useEffect or other client-side data fetching methods.
+2. Use Suspense boundaries to handle loading states for async server components.
+3. Pass context (ctx) through props to child components that need it.
+
+Example:
+
+\`\`\`tsx
+export async function TodoList({ ctx }) {
+  const todos = await db.todo.findMany({ where: { userId: ctx.user.id } });
+
+  return (
+    <ol>
+      {todos.map((todo) => (
+        <li key={todo.id}>{todo.title}</li>
+      ))}
+    </ol>
+  );
+}
+\`\`\`
+
+## Server Functions
+
+1. Must be marked with the "use server" directive at the top of the file.
+2. Can be imported and used in client components.
+3. Execute on the server when called from client components.
+4. Have access to the request context via requestInfo.ctx.
+5. Can handle form submissions and other server-side operations.
+
+Example:
+
+\`\`\`tsx
+"use server";
+
+import { requestInfo } from "rwsdk/worker";
+
+export async function addTodo(formData: FormData) {
+  const { ctx } = requestInfo;
+  const title = formData.get("title");
+  await db.todo.create({ data: { title, userId: ctx.user.id } });
+}
+\`\`\`
+
+## Context Usage
+
+1. Context is available to all server components and server functions.
+2. Access context via:
+   - requestInfo in server functions:
+   \`\`\`
+   import { requestInfo } from "rwsdk/worker";
+   const { ctx } = requestInfo
+   \`\`\`
+3. Context is populated by middleware and interruptors and is request-scoped.
+
+## Best Practices
+
+1. Keep server components as the default choice unless client-side interactivity is needed.
+2. Use client components only when necessary to minimize the JavaScript bundle size.
+3. Leverage server components for data fetching and initial rendering.
+4. Use Suspense boundaries appropriately for loading states.
+5. Keep client components as small as possible, moving server-side logic to server components or server functions.
+6. Always mark client components with "use client" directive.
+7. Always mark server functions with "use server" directive.
+
+`;

package/dist/llms/rules/request-response.d.ts

@@ -0,0 +1 @@
+export declare const requestResponse = "\n# RedwoodSDK: Request handling and responses\n\nYou're an expert at Cloudflare, TypeScript, and building web apps in React. Generate high quality **RedwoodSDK route handlers** that adhere to the following best practices:\n\n## Guidelines\n\n1. Try to use Web APIs instead of external dependencies (e.g. use fetch instead of Axios, use WebSockets API instead of node-ws)\n2. Co-locate related routes into a separate `routes.ts` file in `./src/app/pages/<section>` (e.g. keep all \"user\" routes in `./src/app/pages/user/routes.ts`, all \"blog\" routes in `./src/app/pages/blog/routes.ts`), and then import them into `defineApp` with the `prefix` function\n4. Structure response data consistently with proper status codes\n5. Handle errors gracefully and return appropriate error responses\n\n## Example Templates\n\n### Basic Routing\n\nRoutes are matched in the order they are defined. Define routes using the `route` function. Trailing slashes are optional and normalized internally.\n\n#### Static Path Matching\n\n```tsx\n// Match exact pathnames\nroute(\"/\", function handler() {\n  return <>Home Page</>\n})\n\nroute(\"/about\", function handler() {\n  return <>About Page</>\n})\n\nroute(\"/contact\", function handler() {\n  return <>Contact Page</>\n})\n```\n\n#### Dynamic Path Parameters\n\n```tsx\n// Match dynamic segments marked with a colon (:)\nroute(\"/users/:id\", function handler({ params }) {\n  // params.id contains the value from the URL\n  return <>User profile for {params.id}</>\n})\n\nroute(\"/posts/:postId/comments/:commentId\", function handler({ params }) {\n  // Access multiple parameters\n  return <>Comment {params.commentId} on Post {params.postId}</>\n})\n```\n\n#### Wildcard Path Matching\n\n```tsx\n// Match all remaining segments after the prefix\nroute(\"/files/*\", function handler({ params }) {\n  // params.$0 contains the wildcard value\n  return <>File: {params.$0}</>\n})\n\nroute(\"/docs/*/version/*\", function handler({ params }) {\n  // Multiple wildcards available as params.$0, params.$1, etc.\n  return <>Document: {params.$0}, Version: {params.$1}</>\n})\n```\n\n### Response Types\n\n#### Plain Text Response\n\n```tsx\nimport { route } from \"rwsdk/router\";\n\nroute(\"/api/status\", function handler() {\n  return new Response(\"OK\", {\n    status: 200,\n    headers: { \"Content-Type\": \"text/plain\" }\n  })\n})\n```\n\n#### JSON Response\n\n```tsx\nimport { route } from \"rwsdk/router\";\n\nroute(\"/api/users/:id\", function handler({ params }) {\n  const userData = { id: params.id, name: \"John Doe\", email: \"john@example.com\" }\n\n  return Response.json(userData, {\n    status: 200,\n    headers: {\n      \"Cache-Control\": \"max-age=60\"\n    }\n  })\n})\n```\n\n#### JSX/React Components Response\n\n```tsx\nimport { route } from \"rwsdk/router\";\nimport { UserProfile } from '@/app/components/UserProfile'\n\nroute(\"/users/:id\", function handler({ params }) {\n  return <UserProfile userId={params.id} />\n})\n```\n\n#### Custom Document Template\n\n```tsx\nimport { render, route } from \"rwsdk/router\";\nimport { Document } from '@/app/Document'\n\nrender(Document, [\n  route(\"/\", function handler() {\n    return <>Home Page</>\n  }),\n  route(\"/about\", function handler() {\n    return <>About Page</>\n  })\n])\n```\n\n### Error Handling\n\n```tsx\nimport { route } from \"rwsdk/router\";\n\nroute(\"/api/posts/:id\", async function handler({ params }) {\n  try {\n    const post = await db.post.findUnique({ where: { id: params.id } })\n\n    if (!post) {\n      return Response.json(\n        { error: \"Post not found\" },\n        { status: 404 }\n      )\n    }\n\n    return Response.json(post)\n  } catch (error) {\n    console.error(error)\n    return Response.json(\n      { error: \"Failed to retrieve post\" },\n      { status: 500 }\n    )\n  }\n})\n```\n\n### Organization with Co-located Routes\n\nCreate a file at `./src/app/pages/blog/routes.ts`:\n\n```tsx\nimport { route } from \"rwsdk/router\";\nimport { isAdminUser } from '@/app/interceptors'\n\nimport { BlogLandingPage } from './BlogLandingPage'\nimport { BlogPostPage } from './BlogPostPage'\nimport { BlogAdminPage } from './BlogAdminPage'\n\nexport const routes = [\n  route('/', BlogLandingPage),\n  route('/post/:postId', BlogPostPage),\n  route('/post/:postId/edit', [isAdminUser, BlogAdminPage])\n]\n```\n\nThen import these routes in your main worker file:\n\n```tsx\n// src/worker.tsx\nimport { defineApp, render, route, prefix } from \"rwsdk/router\";\nimport { Document } from '@/app/Document'\nimport { HomePage } from '@/app/pages/home/HomePage'\nimport { routes as blogRoutes } from '@/app/pages/blog/routes'\n\nexport default defineApp([\n  /* middleware */\n  render(Document, [\n    route('/', HomePage),\n    prefix('/blog', blogRoutes)\n  ]),\n])\n```\n\n### Advanced: Route with Query Parameters\n\n```tsx\nimport { route } from \"rwsdk/router\";\n\nroute(\"/api/search\", function handler({ request }) {\n  const url = new URL(request.url)\n  const query = url.searchParams.get('q') || ''\n  const page = parseInt(url.searchParams.get('page') || '1')\n  const limit = parseInt(url.searchParams.get('limit') || '10')\n\n  return Response.json({\n    query,\n    page,\n    limit,\n    results: [] // Your search results would go here\n  })\n})\n```\n\n";

package/dist/llms/rules/request-response.js

@@ -0,0 +1,209 @@
+export const requestResponse = `
+# RedwoodSDK: Request handling and responses
+
+You're an expert at Cloudflare, TypeScript, and building web apps in React. Generate high quality **RedwoodSDK route handlers** that adhere to the following best practices:
+
+## Guidelines
+
+1. Try to use Web APIs instead of external dependencies (e.g. use fetch instead of Axios, use WebSockets API instead of node-ws)
+2. Co-locate related routes into a separate \`routes.ts\` file in \`./src/app/pages/<section>\` (e.g. keep all "user" routes in \`./src/app/pages/user/routes.ts\`, all "blog" routes in \`./src/app/pages/blog/routes.ts\`), and then import them into \`defineApp\` with the \`prefix\` function
+4. Structure response data consistently with proper status codes
+5. Handle errors gracefully and return appropriate error responses
+
+## Example Templates
+
+### Basic Routing
+
+Routes are matched in the order they are defined. Define routes using the \`route\` function. Trailing slashes are optional and normalized internally.
+
+#### Static Path Matching
+
+\`\`\`tsx
+// Match exact pathnames
+route("/", function handler() {
+  return <>Home Page</>
+})
+
+route("/about", function handler() {
+  return <>About Page</>
+})
+
+route("/contact", function handler() {
+  return <>Contact Page</>
+})
+\`\`\`
+
+#### Dynamic Path Parameters
+
+\`\`\`tsx
+// Match dynamic segments marked with a colon (:)
+route("/users/:id", function handler({ params }) {
+  // params.id contains the value from the URL
+  return <>User profile for {params.id}</>
+})
+
+route("/posts/:postId/comments/:commentId", function handler({ params }) {
+  // Access multiple parameters
+  return <>Comment {params.commentId} on Post {params.postId}</>
+})
+\`\`\`
+
+#### Wildcard Path Matching
+
+\`\`\`tsx
+// Match all remaining segments after the prefix
+route("/files/*", function handler({ params }) {
+  // params.$0 contains the wildcard value
+  return <>File: {params.$0}</>
+})
+
+route("/docs/*/version/*", function handler({ params }) {
+  // Multiple wildcards available as params.$0, params.$1, etc.
+  return <>Document: {params.$0}, Version: {params.$1}</>
+})
+\`\`\`
+
+### Response Types
+
+#### Plain Text Response
+
+\`\`\`tsx
+import { route } from "rwsdk/router";
+
+route("/api/status", function handler() {
+  return new Response("OK", {
+    status: 200,
+    headers: { "Content-Type": "text/plain" }
+  })
+})
+\`\`\`
+
+#### JSON Response
+
+\`\`\`tsx
+import { route } from "rwsdk/router";
+
+route("/api/users/:id", function handler({ params }) {
+  const userData = { id: params.id, name: "John Doe", email: "john@example.com" }
+
+  return Response.json(userData, {
+    status: 200,
+    headers: {
+      "Cache-Control": "max-age=60"
+    }
+  })
+})
+\`\`\`
+
+#### JSX/React Components Response
+
+\`\`\`tsx
+import { route } from "rwsdk/router";
+import { UserProfile } from '@/app/components/UserProfile'
+
+route("/users/:id", function handler({ params }) {
+  return <UserProfile userId={params.id} />
+})
+\`\`\`
+
+#### Custom Document Template
+
+\`\`\`tsx
+import { render, route } from "rwsdk/router";
+import { Document } from '@/app/Document'
+
+render(Document, [
+  route("/", function handler() {
+    return <>Home Page</>
+  }),
+  route("/about", function handler() {
+    return <>About Page</>
+  })
+])
+\`\`\`
+
+### Error Handling
+
+\`\`\`tsx
+import { route } from "rwsdk/router";
+
+route("/api/posts/:id", async function handler({ params }) {
+  try {
+    const post = await db.post.findUnique({ where: { id: params.id } })
+
+    if (!post) {
+      return Response.json(
+        { error: "Post not found" },
+        { status: 404 }
+      )
+    }
+
+    return Response.json(post)
+  } catch (error) {
+    console.error(error)
+    return Response.json(
+      { error: "Failed to retrieve post" },
+      { status: 500 }
+    )
+  }
+})
+\`\`\`
+
+### Organization with Co-located Routes
+
+Create a file at \`./src/app/pages/blog/routes.ts\`:
+
+\`\`\`tsx
+import { route } from "rwsdk/router";
+import { isAdminUser } from '@/app/interceptors'
+
+import { BlogLandingPage } from './BlogLandingPage'
+import { BlogPostPage } from './BlogPostPage'
+import { BlogAdminPage } from './BlogAdminPage'
+
+export const routes = [
+  route('/', BlogLandingPage),
+  route('/post/:postId', BlogPostPage),
+  route('/post/:postId/edit', [isAdminUser, BlogAdminPage])
+]
+\`\`\`
+
+Then import these routes in your main worker file:
+
+\`\`\`tsx
+// src/worker.tsx
+import { defineApp, render, route, prefix } from "rwsdk/router";
+import { Document } from '@/app/Document'
+import { HomePage } from '@/app/pages/home/HomePage'
+import { routes as blogRoutes } from '@/app/pages/blog/routes'
+
+export default defineApp([
+  /* middleware */
+  render(Document, [
+    route('/', HomePage),
+    prefix('/blog', blogRoutes)
+  ]),
+])
+\`\`\`
+
+### Advanced: Route with Query Parameters
+
+\`\`\`tsx
+import { route } from "rwsdk/router";
+
+route("/api/search", function handler({ request }) {
+  const url = new URL(request.url)
+  const query = url.searchParams.get('q') || ''
+  const page = parseInt(url.searchParams.get('page') || '1')
+  const limit = parseInt(url.searchParams.get('limit') || '10')
+
+  return Response.json({
+    query,
+    page,
+    limit,
+    results: [] // Your search results would go here
+  })
+})
+\`\`\`
+
+`;

package/dist/runtime/client.d.ts

@@ -0,0 +1,17 @@
+import { type CallServerCallback } from "react-server-dom-webpack/client.browser";
+import { type HydrationOptions } from "react-dom/client";
+export type ActionResponse<Result> = {
+    node: React.ReactNode;
+    actionResult: Result;
+};
+type TransportContext = {
+    setRscPayload: <Result>(v: Promise<ActionResponse<Result>>) => void;
+};
+export type Transport = (context: TransportContext) => CallServerCallback;
+export type CreateCallServer = (context: TransportContext) => <Result>(id: null | string, args: null | unknown[]) => Promise<Result>;
+export declare const fetchTransport: Transport;
+export declare const initClient: ({ transport, hydrateRootOptions, }?: {
+    transport?: Transport;
+    hydrateRootOptions?: HydrationOptions;
+}) => Promise<void>;
+export {};