32
{userId ?
40
);
41
}
```
### Populate `ctx` with middleware
[Section titled “Populate ctx with middleware”](#populate-ctx-with-middleware)
RedwoodSDK keeps the familiar request/response contract. Middleware receives the same `Request` object the platform provides, so you can read headers (`request.headers.get("cookie")`) or parse cookies exactly as you would in any web app. The `response.headers` object on `requestInfo` is mutable, which lets middleware append headers or set cookies that the final response will include.
`ctx` is the request-scoped object that RedwoodSDK passes to middleware, routes, React Server Components, and Server Actions. Populate it inside middleware so every downstream handler sees the same session data. Place middleware near the top of `defineApp` so it runs before any route handlers. The snippet below uses the `sessionStore` defined earlier in this guide.
Per-route interruptors work the same way. When you pass an array to `route()`, every function before the final handler is treated as a route-scoped middleware. These interruptors run after the global middleware, can mutate `ctx`, can read or write headers, and can short-circuit a request by returning or throwing a `Response`.
src/worker.tsx
```tsx
1
import { defineApp, ErrorResponse } from "rwsdk/worker";
2
import { route } from "rwsdk/router";
3
4
export default defineApp([
5
async function sessionMiddleware({ request, ctx }) {
6
const session = await sessionStore.load(request);
7
ctx.session = session ?? { userId: null };
8
},
9
async function requireUser({ ctx }) {
10
if (!ctx.session?.userId) {
11
throw new ErrorResponse(401, "Unauthorized");
12
}
13
},
14
route("/dashboard", ({ ctx }) => {
15
return new Response(`User: ${ctx.session.userId}`);
16
}),
17
]);
```
When a middleware throws an `ErrorResponse`, RedwoodSDK stops the pipeline and returns the contained status code and message. Throwing a `Response` has the same effect. Throwing any other error causes the worker to log the error and rethrow, which surfaces as an unhandled exception.
# Cron Triggers
> Schedule background tasks
If you want to schedule a background task, Cloudflare supports [Cron Triggers](https://developers.cloudflare.com/workers/configuration/cron-triggers/).
ℹ️ **Important:** Cron triggers only fire automatically after you deploy to Cloudflare. The local dev server does not schedule jobs for you, but you can still trigger the scheduled cron handler manually (see [Testing locally](#testing-locally) below).
## Setup
[Section titled “Setup”](#setup)
Within your `wrangler.jsonc` file, add a new section called `triggers`:
wrangler.jsonc
```jsonc
"triggers": {
"crons": ["* * * * *"]
}
```
Where `crons` includes an array of cron schedules.
After updating `wrangler.jsonc`, run `pnpm generate` to update the generated type definitions.
Within your `worker.tsx` file, adjust your `defineApp` function:
```tsx
1
const app = defineApp([
2
...
3
]);
4
5
export default {
6
fetch: app.fetch,
7
async scheduled(controller: ScheduledController) {
8
switch (controller.cron) {
9
case "* * * * *": {
10
console.log("🧹 Run minute-by-minute cleanups");
11
break;
12
}
13
case "0 * * * *": {
14
console.log("📈 Aggregate hourly metrics");
15
break;
16
}
17
case "0 21 * * *": {
18
console.log("🌙 Kick off nightly billing at 9 PM UTC");
19
break;
20
}
21
default: {
22
console.warn(`Unhandled cron: ${controller.cron}`);
23
}
24
}
25
console.log("⏰ cron processed");
26
},
27
} satisfies ExportedHandlerLogged in as: {userId}
:Not logged in
} 33 36 39Hello, from the server!
;
3
}
```
When a user needs to interact with your component: clicking a button, setting state, etc, then you must use a client component. Mark the client component with the `"use client"` directive. This will be hydrated by React in the browser.
```tsx
1
"use client";
2
3
export default function MyClientComponent() {
4
return ;
5
}
```
## Fetching and displaying data
[Section titled “Fetching and displaying data”](#fetching-and-displaying-data)
React Server Components run on the server, they can easily fetch data and make it part of the payload that’s sent to the client.
src/app/pages/todos/TodoPage.tsx
```tsx
1
export async function Todos({ ctx }) {
2
const todos = await db.todo.findMany({ where: { userId: ctx.user.id } });
3
return (
4
-
5
{todos.map((todo) => (
6
- {todo.title} 7 ))} 8
15
Loading...
}>
17
Todos
16Hello, {name}!
;
6
});
```
To get multiple values for a single key (e.g., `?tag=js&tag=react`):
```tsx
1
route("/posts", ({ request }) => {
2
const url = new URL(request.url);
3
const tags = url.searchParams.getAll("tag"); // ["js", "react"]
4
5
return Filtering by tags: {tags.join(", ")}
;
6
});
```
***
## Request Handlers
[Section titled “Request Handlers”](#request-handlers)
The request handler is a function, or array of functions (See [Interrupters](#interrupters)), that are executed when a request is matched.
src/worker.tsx
```tsx
1
import { route } from "rwsdk/router";
2
3
defineApp([
4
route("/a-standard-response", ({ request, params, ctx }) => {
5
return new Response("Hello, world!");
6
}),
7
route("/a-jsx-response", () => {
8
return Hello, JSX world!
;
9
}),
10
]);
```
***
The request handler function takes a [RequestInfo](#request-info) object as its parameter.
Return values:
* `Response`: A standard response object.
* `JSX`: A React component, which is rendered to HTML on the server and **streamed** to the client. This allows the browser to progressively render the page before it is hydrated on the client side.
***
## HTTP Method Routing
[Section titled “HTTP Method Routing”](#http-method-routing)
You can handle different HTTP methods (GET, POST, PUT, DELETE, etc.) on the same path by passing an object with method keys:
```tsx
1
route("/api/users", {
2
get: () => new Response(JSON.stringify(users)),
3
post: ({ request }) => new Response("User created", { status: 201 }),
4
delete: () => new Response("User deleted", { status: 204 }),
5
});
```
Method handlers can also be arrays of functions, allowing you to use [interrupters](#interrupters) per method:
```tsx
1
route("/api/users", {
2
get: [isAuthenticated, () => new Response(JSON.stringify(users))],
3
post: [isAuthenticated, validateUser, createUserHandler],
4
});
```
**Standard HTTP Methods**: `delete`, `get`, `head`, `patch`, `post`, `put`
**Custom Methods**: Use the `custom` key for non-standard methods (case-insensitive):
```tsx
1
route("/api/search", {
2
custom: {
3
report: () => new Response("Report data"),
4
},
5
});
```
**Automatic OPTIONS & 405 Support**: By default, OPTIONS requests return `204 No Content` with an `Allow` header, and unsupported methods return `405 Method Not Allowed`.
**Configuration**: Disable automatic behaviors:
```tsx
1
route("/api/users", {
2
get: () => new Response("OK"),
3
config: {
4
disableOptions: true, // OPTIONS returns 405
5
disable405: true, // Unsupported methods fall through to 404
6
},
7
});
```
HEAD Requests
Unlike in Express.js, you must explicitly provide a HEAD handler. HEAD requests are not automatically mapped to GET handlers:
```tsx
1
route("/api/users", {
2
get: getHandler,
3
head: getHandler, // Explicitly reuse handler
4
});
```
***
### Interrupters
[Section titled “Interrupters”](#interrupters)
Interrupters are an array of functions that are executed in sequence for each matched request. They can be used to modify the request, context, or to short-circuit the response. A typical use-case is to check for authentication on a per-request basis, as an example you’re trying to ensure that a specific user can access a specific resource.
src/worker.tsx
```tsx
2 collapsed lines
1
import { defineApp } from "rwsdk/worker";
2
import { route } from "rwsdk/router";
3
import { EditBlogPage } from "src/pages/blog/EditBlogPage";
4
5
function isAuthenticated({ request, ctx }) {
6
// Ensure that this user is authenticated
7
if (!ctx.user) {
8
return new Response("Unauthorized", { status: 401 });
9
}
10
}
11
12
defineApp([route("/blog/:slug/edit", [isAuthenticated, EditBlogPage])]);
```
***
For the `/blog/:slug/edit` route, the `isAuthenticated` function will be executed first, if the user is not authenticated, the response will be a 401 Unauthorized. If the user is authenticated, the `EditBlogPage` component will be rendered. Therefore the flow is interrupted. The `isAuthenticated` function can be shared across multiple routes.
***
## Middleware & Context
[Section titled “Middleware & Context”](#middleware--context)
The context object (`ctx`) is a mutable object that is passed to each request handler, interrupters, and React Server Functions. It’s used to share data between the different parts of your application. You populate the context on a per-request basis via Middleware.
Middleware runs before the request is matched to a route. You can specify multiple middleware functions, they’ll be executed in the order they are defined.
Server Actions
Requests made by Server Actions also pass through the middleware pipeline. This means you can rely on middleware to populate context or perform checks for your actions, just as you would for page requests.
src/worker.tsx
```tsx
1
import { defineApp } from "rwsdk/worker";
2
import { route } from "rwsdk/router";
3
import { env } from "cloudflare:workers";
4
5
defineApp([
6
sessionMiddleware,
7
async function getUserMiddleware({ request, ctx }) {
8
if (ctx.session.userId) {
9
ctx.user = await db.user.find({ where: { id: ctx.session.userId } });
10
}
11
},
12
route("/hello", [
13
function ({ ctx }) {
14
if (!ctx.user) {
15
return new Response("Unauthorized", { status: 401 });
16
}
17
},
18
function ({ ctx }) {
19
return new Response(`Hello ${ctx.user.username}!`);
20
},
21
]),
22
]);
```
***
The context object:
1. `sessionMiddleware` is a function that is used to populate the `ctx.session` object
2. `getUserMiddleware` is a middleware function that is used to populate the `ctx.user` object
3. `"/hello"` is a an array of route handlers that are executed when “/hello” is matched:
* if the user is not authenticated the request will be interrupted and a 401 Unauthorized response will be returned
* if the user is authenticated the request will be passed to the next request handler and `"Hello {ctx.user.username}!"` will be returned
***
### Extending App Context Types
[Section titled “Extending App Context Types”](#extending-app-context-types)
To get full type safety for your custom context data (like `ctx.user`), you can extend the `DefaultAppContext` interface in a `global.d.ts` file in your project’s root.
global.d.ts
```typescript
import { User } from "@db/index";
import { DefaultAppContext } from "rwsdk/worker";
interface AppContext {
user?: User;
session?: { userId: string | null };
}
declare module "rwsdk/worker" {
interface DefaultAppContext extends AppContext {}
}
```
Now, whenever you access `ctx` in your handlers or via `getRequestInfo().ctx`, TypeScript will know about the `user` and `session` properties without needing manual casting.
***
## Documents
[Section titled “Documents”](#documents)
Documents are how you define the “shell” of your application’s html: the ``, ``, `` tags, scripts, stylesheets, ``, and where in the `` your actual page content is rendered. In RedwoodSDK, you tell it which document to use with the `render()` function in `defineApp`. In other words, you’re asking RedwoodSDK to “render” the document.
src/worker.tsx
```tsx
1
import { defineApp } from "rwsdk/worker";
2
import { route, render } from "rwsdk/router";
3
4
import { Document } from "@/pages/document";
5
import { HomePage } from "@/pages/home-page";
6
7
export default defineApp([render(Document, [route("/", HomePage)])]);
```
***
The `render` function takes a React component and an array of route handlers. The document will be applied to all the routes that are passed to it.
This component will be rendered on the server side when the page loads. When defining this component, you’d add:
* Your application’s stylesheets and scripts
***
src/pages/document.tsx
```tsx
1
export const Document = ({ children }) => (
2
3
4
5
6
7
8
{children}
9
10
11
);
```
Client Side Hydration
You must include the client side hydration script in your document, otherwise the React components will not be hydrated.
## Request Info
[Section titled “Request Info”](#request-info)
The `requestInfo` object and `getRequestInfo()` function are available in server functions and provide access to the current request’s context. Import them from `rwsdk/worker`:
```tsx
1
import { requestInfo, getRequestInfo } from "rwsdk/worker";
2
3
export async function myServerFunction() {
4
// Option 1: Using the requestInfo object
5
const { request, response, ctx } = requestInfo;
6
7
// Option 2: Using the getRequestInfo() function (recommended for actions)
8
const info = getRequestInfo();
9
// info.request, info.response, info.ctx.user
10
}
```
Note
`getRequestInfo()` will throw an error if called outside of a request lifecycle, whereas `requestInfo` will return `undefined` for its properties.
***
The `requestInfo` object contains:
* `request`: The incoming HTTP [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object
* `response`: A [ResponseInit](https://fetch.spec.whatwg.org/#responseinit) object used to configure the status and headers of the response
* `ctx`: The app context (same as what’s passed to components)
* `rw`: RedwoodSDK-specific context
* `cf`: Cloudflare’s Execution Context API
You can mutate the `response` object to configure the status and headers. For example:
```tsx
1
import { requestInfo } from "rwsdk/worker";
2
import { route } from "rwsdk/router";
3
4
const NotFound = () => Not Found
;
5
6
export default defineApp([
7
route("/some-resource", async () => {
8
// some logic to determine if the resource is not found
9
10
response.status = 404;
11
response.headers.set("Cache-Control", "no-store");
12
13
return
12
15
);
16
};
```
Open this component in two different browser windows. When you click increment in one, it updates in the other instantly!
### Rooms: Scoping State to Different Groups
[Section titled “Rooms: Scoping State to Different Groups”](#rooms-scoping-state-to-different-groups)
By default, state is global. But you can scope state to different “rooms” by passing a room ID as the third argument. This is useful for features like chat rooms, game sessions, or collaborative documents.
src/components/RoomCounter.tsx
```tsx
1
"use client";
2
3
import { useSyncedState } from "rwsdk/use-synced-state/client";
4
5
export const RoomCounter = ({ roomId }: { roomId: string }) => {
6
// State is scoped to this specific room
7
// Users in different rooms won't see each other's updates
8
const [count, setCount] = useSyncedState(0, "counter", roomId);
9
10
return (
11
Count: {count}
13 14
12
16
);
17
};
```
When you use a room ID, state is isolated to that room. Users in `"room-1"` won’t see updates from users in `"room-2"`.
***
## Advanced: Scoping and Persistence
[Section titled “Advanced: Scoping and Persistence”](#advanced-scoping-and-persistence)
### Scoping State with Room IDs vs Key Handlers
[Section titled “Scoping State with Room IDs vs Key Handlers”](#scoping-state-with-room-ids-vs-key-handlers)
There are two ways to scope state:
1. **Room IDs** (client-side): Pass a room ID as the third argument to `useSyncedState`. This is the simplest way to isolate state between different groups.
2. **Key Handlers** (server-side): Transform keys on the server to add prefixes or scoping logic. This is useful when you need server-enforced scoping based on authentication or other server-side data.
#### Using Room IDs (Client-Side)
[Section titled “Using Room IDs (Client-Side)”](#using-room-ids-client-side)
src/components/ChatRoom.tsx
```tsx
1
"use client";
2
3
import { useSyncedState } from "rwsdk/use-synced-state/client";
4
5
export const ChatRoom = ({ roomId }: { roomId: string }) => {
6
// Each room has its own isolated state
7
const [messages, setMessages] = useSyncedStateRoom: {roomId}
13Count: {count}
14 15Pong!
; + }), ]), ]); ``` Now when you navigate toHello {name}
;
};
const { data, error } = await resend.emails.send({
from: "Acme Hello World
", }); ``` ## Test Emails [Section titled “Test Emails”](#test-emails) > Resend provides a set of safe email addresses specifically designed for testing, ensuring that you can simulate different email events without affecting your domain’s reputation. [Resend Documentation](https://resend.com/docs/knowledge-base/what-email-addresses-to-use-for-testing#list-of-addresses-to-use) A lot of developers will use `@example.com` or `@test.com` for testing. However, these addresses will often reject messages, leading to bounces. A high bounce rate can negatively impact your sender reputation and affect future deliverability. Therefore, Resend will return a `422` error if you attempt to use these addresses. Instead, Resend provides the following addresses: | **Address** | **Delivery Event Simulated** | | ---------------------- | ---------------------------- | | `delivered@resend.dev` | Email was delivered | | `bounced@resend.dev` | Email was bounced | ## Constants File [Section titled “Constants File”](#constants-file) We recommend creating a constants file to store reusable values. Inside your `src/app/shared` directory, create a new file called `constants.ts`. * src/ * app/ * shared/ * constants.ts Inside the `constants.ts` file, add the following: ```tsx 1 export const CONSTANTS = Object.freeze({ 2 FROM_EMAIL: "Acme{children}
23
24
25
26
Cancel
27
28
29
6
Welcome to Chakra UI v3
7
8
9
10
11
12
);
13
}
```
8. Run Development Server
* npm
```sh
npm run dev
```
* pnpm
```sh
pnpm run dev
```
* yarn
```sh
yarn run dev
```
## Customizing Chakra UI
[Section titled “Customizing Chakra UI”](#customizing-chakra-ui)
Chakra UI v3 uses a completely new theming system based on the `createSystem` API, inspired by Panda CSS. The old `extendTheme` approach from v2 is no longer used.
### Creating a Custom System
[Section titled “Creating a Custom System”](#creating-a-custom-system)
Create a theme configuration file:
src/theme.ts
```ts
1
import { createSystem, defaultConfig, defineConfig } from "@chakra-ui/react";
2
3
const customConfig = defineConfig({
4
theme: {
5
tokens: {
6
colors: {
7
brand: {
8
50: { value: "#e6f7ff" },
9
100: { value: "#bae7ff" },
10
200: { value: "#91d5ff" },
11
300: { value: "#69c0ff" },
12
400: { value: "#40a9ff" },
13
500: { value: "#1890ff" },
14
600: { value: "#096dd9" },
15
700: { value: "#0050b3" },
16
800: { value: "#003a8c" },
17
900: { value: "#002766" },
18
},
19
},
20
fonts: {
21
heading: { value: "'Inter', sans-serif" },
22
body: { value: "'Inter', sans-serif" },
23
},
24
},
25
semanticTokens: {
26
colors: {
27
"bg.primary": {
28
value: { _light: "{colors.white}", _dark: "{colors.gray.900}" },
29
},
30
"text.primary": {
31
value: { _light: "{colors.gray.900}", _dark: "{colors.gray.100}" },
32
},
33
},
34
},
35
},
36
});
37
38
export const system = createSystem(defaultConfig, customConfig);
```
### Using Your Custom System
[Section titled “Using Your Custom System”](#using-your-custom-system)
Update the provider to use your custom system:
src/components/ui/provider.tsx
```diff
1
import { ChakraProvider } from "@chakra-ui/react";
2
+import { system } from "@/theme";
3
import { ColorModeProvider } from "@/components/ui/color-mode";
4
5
export function Provider(props: { children: React.ReactNode }) {
6
+return (
7
Welcome
14 18 19 ); 20 } ``` ### Prefetching from Navigation Links [Section titled “Prefetching from Navigation Links”](#prefetching-from-navigation-links) A common pattern is to prefetch routes that are linked from the current page: Prefetching linked routes ```tsx 1 import { link } from "@/shared/links"; 2 3 export function BlogListPage({ posts }) { 4 return ( 5 <> 6 {posts.map((post) => { 7 const postHref = link("/blog/:slug", { slug: post.slug }); 8 return ( 9
70
Current theme: {theme}
71
78
79
);
80
}
```
Tailwind Dark Mode
This example uses Tailwind’s `dark:` variant. Make sure you have dark mode configured in your Tailwind setup. With Tailwind v4, you can use the `@custom-variant dark` directive in your CSS file.
5. **Use the theme toggle in your pages**
Pass the theme from the context to your toggle component:
src/app/pages/Home.tsx
```tsx
1
import { RequestInfo } from "rwsdk/worker";
2
import { ThemeToggle } from "../components/ThemeToggle";
3
4
export function Home({ ctx }: RequestInfo) {
5
const theme = ctx.theme || "system";
6
7
return (
8
9
12
);
13
}
```
## Reading the Current Theme
[Section titled “Reading the Current Theme”](#reading-the-current-theme)
The `ThemeToggle` component above includes a display of the current theme. If you need to read the current theme in a separate client component, you can check the DOM directly:
src/app/components/MyComponent.tsx
```tsx
1
"use client";
2
3
import { useEffect, useState } from "react";
4
5
export function MyComponent() {
6
const [isDark, setIsDark] = useState(false);
7
8
useEffect(() => {
9
// Check if dark class is present
10
setIsDark(document.documentElement.classList.contains("dark"));
11
12
// Optional: Listen for changes
13
const observer = new MutationObserver(() => {
14
setIsDark(document.documentElement.classList.contains("dark"));
15
});
16
17
observer.observe(document.documentElement, {
18
attributes: true,
19
attributeFilter: ["class"],
20
});
21
22
return () => observer.disconnect();
23
}, []);
24
25
return (
26
Welcome
10
27
29
);
30
}
```
## CSS Styling
[Section titled “CSS Styling”](#css-styling)
With Tailwind CSS, you can use the `dark:` variant to style elements differently in dark mode:
src/app/styles.css
```css
1
@import "tailwindcss";
2
3
@custom-variant dark (&:is(.dark *));
4
5
/* Your custom styles */
6
.my-component {
7
background-color: white;
8
color: black;
9
}
10
11
.dark .my-component {
12
background-color: #1a1a1a;
13
color: white;
14
}
```
Or with Tailwind utility classes:
```tsx
1
Current theme: {isDark ? "dark" : "light"}
28
2
Content
3
```
## Alternative: Data Attributes
[Section titled “Alternative: Data Attributes”](#alternative-data-attributes)
If you prefer using data attributes instead of class names, you can modify the `Document` and toggle component:
src/app/Document.tsx
```tsx
1
// In the script
2
document.documentElement.setAttribute("data-theme", theme);
```
src/app/components/ThemeToggle.tsx
```tsx
1
// In the useEffect
2
root.setAttribute("data-theme", theme);
```
Then in your CSS:
```css
1
[data-theme="dark"] .my-component {
2
background-color: #1a1a1a;
3
}
```
## Further Reading
[Section titled “Further Reading”](#further-reading)
* [Dark Mode Playground](https://github.com/redwoodjs/sdk/tree/main/playground/dark-mode) - Complete working example
* [Tailwind CSS Dark Mode](https://tailwindcss.com/docs/dark-mode)
# Documents
> How to create custom HTML documents for different routes in your RedwoodSDK project
In RedwoodSDK, Document components give you complete control over the HTML structure of each route. Unlike many frameworks that use a fixed HTML document structure, RedwoodSDK lets you define custom documents per route, controlling everything from the doctype to scripts and hydration strategy.
## A Basic Document
[Section titled “A Basic Document”](#a-basic-document)
1. The starter project comes with a Document component.
src/app/Document.tsx
```tsx
1
export const Document: React.FC<{ children: React.ReactNode }> = ({
2
children,
3
}) => (
4
5
6
7
8
Component
;
12
}
```
### `onCaughtError`
[Section titled “onCaughtError”](#oncaughterror)
Use `onCaughtError` for errors that are caught by error boundaries:
* Component rendering errors
* Errors in component lifecycle methods
* Errors caught by `This won't render
;
11
}
```
## Basic Setup
[Section titled “Basic Setup”](#basic-setup)
1. Import `initClient` from `rwsdk/client`:
src/client.tsx
```tsx
1
import { initClient } from "rwsdk/client";
```
2. Configure error handlers via `hydrateRootOptions`:
src/client.tsx
```tsx
1
initClient({
2
hydrateRootOptions: {
3
onUncaughtError: (error, errorInfo) => {
4
console.error("Uncaught error:", error);
5
console.error("Component stack:", errorInfo.componentStack);
6
},
7
onCaughtError: (error, errorInfo) => {
8
console.error("Caught error:", error);
9
console.error("Component stack:", errorInfo.componentStack);
10
},
11
},
12
});
```
3. The error handlers will now catch and log all React errors in your application.
## Universal Error Handling
[Section titled “Universal Error Handling”](#universal-error-handling)
To ensure that *all* client-side errors (including event handlers, timeouts, and promise rejections) are caught and handled uniformly, you should combine React’s error handlers with global browser listeners.
This pattern is particularly useful for redirecting users to a dedicated error page on any fatal error:
src/client.tsx
```tsx
1
import { initClient } from "rwsdk/client";
2
3
const redirectToError = () => {
4
// Use replace to avoid keeping the broken page in history
5
window.location.replace("/error");
6
};
7
8
// 1. Catch imperative errors (event handlers, timeouts, etc.)
9
window.addEventListener("error", (event) => {
10
console.error("Global error caught:", event.message);
11
redirectToError();
12
});
13
14
// 2. Catch unhandled promise rejections
15
window.addEventListener("unhandledrejection", (event) => {
16
console.error("Unhandled promise rejection:", event.reason);
17
redirectToError();
18
});
19
20
initClient({
21
hydrateRootOptions: {
22
// 3. Catch React-specific uncaught errors (rendering, hydration)
23
onUncaughtError: (error, errorInfo) => {
24
console.error("React uncaught error:", error, errorInfo);
25
redirectToError();
26
},
27
// 4. Catch errors caught by error boundaries
28
onCaughtError: (error, errorInfo) => {
29
console.error("React caught error:", error, errorInfo);
30
redirectToError();
31
},
32
},
33
});
```
## Integration with Monitoring Services
[Section titled “Integration with Monitoring Services”](#integration-with-monitoring-services)
### Sentry
[Section titled “Sentry”](#sentry)
src/client.tsx
```tsx
1
import { initClient } from "rwsdk/client";
2
import * as Sentry from "@sentry/browser";
3
4
initClient({
5
hydrateRootOptions: {
6
onUncaughtError: (error, errorInfo) => {
7
Sentry.captureException(error, {
8
contexts: {
9
react: {
10
componentStack: errorInfo.componentStack,
11
errorBoundary: errorInfo.errorBoundary?.constructor.name,
12
},
13
},
14
tags: { errorType: "uncaught" },
15
});
16
},
17
onCaughtError: (error, errorInfo) => {
18
Sentry.captureException(error, {
19
contexts: {
20
react: {
21
componentStack: errorInfo.componentStack,
22
errorBoundary: errorInfo.errorBoundary?.constructor.name,
23
},
24
},
25
tags: { errorType: "caught" },
26
});
27
},
28
},
29
});
```
### Custom Monitoring Service
[Section titled “Custom Monitoring Service”](#custom-monitoring-service)
src/client.tsx
```tsx
1
import { initClient } from "rwsdk/client";
2
3
function sendToMonitoring(
4
error: unknown,
5
errorInfo: { componentStack: string; errorBoundary?: React.Component | null },
6
type: "uncaught" | "caught",
7
) {
8
fetch("/api/errors", {
9
method: "POST",
10
headers: { "Content-Type": "application/json" },
11
body: JSON.stringify({
12
error: error instanceof Error ? error.message : String(error),
13
stack: error instanceof Error ? error.stack : undefined,
14
componentStack: errorInfo.componentStack,
15
errorBoundary: errorInfo.errorBoundary?.constructor.name,
16
type,
17
timestamp: new Date().toISOString(),
18
}),
19
});
20
}
21
22
initClient({
23
hydrateRootOptions: {
24
onUncaughtError: (error, errorInfo) => {
25
sendToMonitoring(error, errorInfo, "uncaught");
26
},
27
onCaughtError: (error, errorInfo) => {
28
sendToMonitoring(error, errorInfo, "caught");
29
},
30
},
31
});
```
## Error Recovery Strategies
[Section titled “Error Recovery Strategies”](#error-recovery-strategies)
### Show User-Friendly Messages
[Section titled “Show User-Friendly Messages”](#show-user-friendly-messages)
src/client.tsx
```tsx
1
import { initClient } from "rwsdk/client";
2
3
function showErrorToast(message: string) {
4
// Your toast implementation
5
console.log("Error:", message);
6
}
7
8
initClient({
9
hydrateRootOptions: {
10
onUncaughtError: (error, errorInfo) => {
11
// Log for debugging
12
console.error("Uncaught error:", error, errorInfo);
13
14
// Show user-friendly message
15
showErrorToast("Something went wrong. Please try again.");
16
17
// Send to monitoring
18
sendToMonitoring(error, errorInfo);
19
},
20
},
21
});
```
### Reload on Critical Errors
[Section titled “Reload on Critical Errors”](#reload-on-critical-errors)
src/client.tsx
```tsx
1
import { initClient } from "rwsdk/client";
2
3
function isCriticalError(error: unknown): boolean {
4
// Define your critical error logic
5
return error instanceof Error && error.message.includes("CRITICAL");
6
}
7
8
initClient({
9
hydrateRootOptions: {
10
onUncaughtError: (error, errorInfo) => {
11
console.error("Uncaught error:", error, errorInfo);
12
13
if (isCriticalError(error)) {
14
// Reload page for critical errors
15
window.location.reload();
16
} else {
17
// Handle non-critical errors gracefully
18
showErrorToast("An error occurred. Please refresh the page.");
19
}
20
},
21
},
22
});
```
## Best Practices
[Section titled “Best Practices”](#best-practices)
### 1. Always Log Errors
[Section titled “1. Always Log Errors”](#1-always-log-errors)
Even if you’re sending errors to a monitoring service, log them locally for debugging:
```tsx
1
onUncaughtError: (error, errorInfo) => {
2
console.error("Uncaught error:", error);
3
console.error("Component stack:", errorInfo.componentStack);
4
// Then send to monitoring
5
};
```
### 2. Include Component Stack
[Section titled “2. Include Component Stack”](#2-include-component-stack)
The `errorInfo.componentStack` provides valuable debugging information. Always include it in your error reports:
```tsx
1
Sentry.captureException(error, {
2
contexts: {
3
react: {
4
componentStack: errorInfo.componentStack,
5
},
6
},
7
});
```
### 3. Distinguish Error Types
[Section titled “3. Distinguish Error Types”](#3-distinguish-error-types)
Use tags or metadata to distinguish between caught and uncaught errors:
```tsx
1
onUncaughtError: (error, errorInfo) => {
2
sendToMonitoring(error, { ...errorInfo, type: "uncaught" });
3
},
4
onCaughtError: (error, errorInfo) => {
5
sendToMonitoring(error, { ...errorInfo, type: "caught" });
6
},
```
### 4. Don’t Block the UI
[Section titled “4. Don’t Block the UI”](#4-dont-block-the-ui)
Error handlers should not throw errors themselves. Keep them lightweight:
```tsx
1
onUncaughtError: (error, errorInfo) => {
2
try {
3
// Safe error handling
4
sendToMonitoring(error, errorInfo);
5
} catch (e) {
6
// Fallback to console if monitoring fails
7
console.error("Error in error handler:", e);
8
}
9
},
```
## Server-Side Error Handling
[Section titled “Server-Side Error Handling”](#server-side-error-handling)
For server-side errors (errors in Server Components, middleware, route handlers, and RSC actions), use the `except` function from `rwsdk/router`. This provides a declarative way to handle errors that integrates with your routing structure.
### Basic Usage
[Section titled “Basic Usage”](#basic-usage)
src/worker.tsx
```tsx
1
import { except, route } from "rwsdk/router";
2
import { defineApp } from "rwsdk/worker";
3
4
export default defineApp([
5
except((error) => {
6
console.error("Server error:", error);
7
return
6
7
11
{requestInfo && (
12
Path: {new URL(requestInfo.request.url).pathname}
13
)}
14
15
{children}
16
17
18
);
19
}
```
2. Use the layout in your routes:
src/app/worker.tsx
```tsx
1
import { layout, route, render } from 'rwsdk/router'
2
import { AppLayout } from './layouts/AppLayout'
3
import HomePage from './pages/HomePage'
4
import AboutPage from './pages/AboutPage'
5
6
export default defineApp([
7
render(Document, [
8
layout(AppLayout, [
9
route("/", HomePage),
10
route("/about", AboutPage),
11
])
12
])
13
])
```
3. Create nested layouts:
src/app/layouts/AdminLayout.tsx
```tsx
1
import type { LayoutProps } from 'rwsdk/router'
2
3
export function AdminLayout({ children }: LayoutProps) {
4
"use client" // Client component example
5
6
return (
7
8
9
11
);
12
}
```
4. Combine layouts with other router functions:
src/app/worker.tsx
```tsx
1
export default defineApp([
2
render(Document, [
3
layout(AppLayout, [
4
route("/", HomePage),
5
prefix("/admin", [
6
layout(AdminLayout, [
7
route("/", AdminDashboard),
8
route("/users", UserManagement),
9
])
10
])
11
])
12
])
13
])
```
Nesting Order
Layouts are applied with outer layouts first. For example:
```tsx
1
layout(Outer, [layout(Inner, [route("/", Page)])])
2
// Results in: {children}
10
Product Name
11 {/* Rest of your component */} 12 13 ); 14 } ``` When this component renders, React will automatically handle updating the document’s `` section. ## Complete SEO Setup [Section titled “Complete SEO Setup”](#complete-seo-setup) Here’s a more comprehensive example including Open Graph and Twitter card meta tags: ```tsx 1 import React from "react"; 2 3 export default function BlogPostPage({ post }) { 4 const { title, description, image, publishDate, author } = post; 5 6 return ( 7 <> 8 {/* Basic Meta Tags */} 9{title}
32 {/* Rest of your blog post content */} 33
8
12
`;
13
14
15
return new ImageResponse(html, {
16
width: 1200,
17
height: 630,
18
});
19
}),
```
In this example, I hard coded the title, `Hello, World!`. However, you can pass parameters through the URL and make database calls to fetch the data you need.
Then, when returning the image, you’ll notice I’m passing in the `html` variable and specifying the `width` and `height` of the image.
Within the browser, you can visit the `/og` route to see the image:
## Using React
[Section titled “Using React”](#using-react)
You can also use a React component, which probably feels more natural, especially for passing around props and parameters.
For this example, I’m going to create a new component inside the `src/app/components` directory, called `Og.tsx`:
src/app/components/Og.tsx
```tsx
1
const Og = ({ title }: { title: string }) => {
2
return (
3
9
11
${title}
10
4
8
)
9
}
10
11
export default Og
```
Using TailwindCSS
Even though these examples are using the `style` attribute, if you’re using TailwindCSS, you should still have access to your classes. These routes are still wrapped in a `Document` component, where Tailwind is being imported. (For reference see the [Tailwind guide](/guides/frontend/tailwind)).
Now, within your `worker.tsx` file, let’s create a new route, called `/og-react`:
src/worker.tsx
```tsx
1
.
2
import Og from "@/app/components/Og";
3
...
4
route("/og-react", () => {
5
6
const title = "Hello, Amy!";
7
const og =
5
7
{title}
6
6
My Application
7
2
```
### Fonts
[Section titled “Fonts”](#fonts)
Host custom font files for your application:
```css
1
/* In your CSS */
2
@font-face {
3
font-family: "BrandFont";
4
src: url("/fonts/brand-font.woff2") format("woff2");
5
font-weight: 400;
6
font-style: normal;
7
}
8
9
/* Then use it with Tailwind */
10
@theme {
11
--font-brand: "BrandFont", sans-serif;
12
}
```
### Favicon and Browser Icons
[Section titled “Favicon and Browser Icons”](#favicon-and-browser-icons)
Store favicon and other browser icons:
```tsx
1
// In your Document.tsx
2
3
4
5
6
```
Security Considerations
Remember that all files in the public directory are accessible to anyone who knows the URL. Don’t store sensitive information in this directory.
## Production Considerations
[Section titled “Production Considerations”](#production-considerations)
In production, files in the public directory:
* Do not go through the JavaScript bundling process
* Maintain their file structure and naming
## Further Reading
[Section titled “Further Reading”](#further-reading)
* [Static File Serving in Vite](https://vitejs.dev/guide/assets.html#the-public-directory)
* [Image Optimization Best Practices](https://web.dev/fast/#optimize-your-images)
* [Web Font Best Practices](https://web.dev/font-best-practices/)
# shadcn/ui
> A comprehensive guide to installing and configuring ShadCN UI components within RedwoodSDK projects, with step-by-step instructions for proper integration with TailwindCSS v4.
## Installing shadcn/ui
[Section titled “Installing shadcn/ui”](#installing-shadcnui)
1. [Install TailwindCSS](/guides/frontend/tailwind).
2. Install shadcn/ui
* npm
```sh
npx shadcn@latest init
```
* pnpm
```sh
pnpx shadcn@latest init
```
* yarn
```sh
yarn dlx shadcn@latest init
```
It will ask you what theme you want to use. 
This command will create a `components.json` file in the root of your project. It contains all the configuration for our shadcn/ui components.
If you want to match RedwoodSDK conventions, add the following aliases to the `components.json` file:
components.json
```json
...
"aliases": {
"components": "@/app/components",
"utils": "@/app/lib/utils",
"ui": "@/app/components/ui",
"lib": "@/app/lib",
"hooks": "@/app/hooks"
},
...
```
shadcn/ui Organization
In our configuration, the `lib` directory is nested inside the `app` directory. The shadcn/ui command line tool may not honor our setup, creating another `lib` directory in the `src` (or `@`) directory. You’ll need to manually move the folder to the `app` directory.
If you’re copying and pasting code from the shadcn/ui website, you’ll also need to update the import paths.
3. Now, you should be able to add components: You can add components in bulk by running:
* npm
```sh
npx shadcn@latest add
```
* pnpm
```sh
pnpx shadcn@latest add
```
* yarn
```sh
yarn dlx shadcn@latest add
```
Or, you can add a single component by running:
* npm
```sh
npx shadcn@latest add
6
12
);
13
}
```
Given that this is very basic, we’d most likely want to build this out a bit more. Storybook is the perfect place to do that! Let’s see what that looks like.
1. Create a new file: `src/app/pages/Home.stories.tsx`
src/app/pages/Home.stories.tsx
```tsx
1
import type { Meta, StoryObj } from "@storybook/react";
2
3
import { Home } from "./Home";
4
5
const meta: Meta7 {ctx.user?.username 8 ? `You are logged in as user ${ctx.user.username}` 9 : "You are not logged in"} 10
11
8
19
);
20
}
```
2. Now, if we go to our Storybook site, we’ll see that it throws an intimidating error. Take a closer look, and we’ll see that it’s coming from the Prisma client: 
3. We need to mock our Prisma client. There are a few ways to do this, and [Storybook](https://storybook.js.org/docs/writing-stories/mocking-data-and-modules/mocking-modules) and [Prisma](https://www.prisma.io/blog/testing-series-1-8eRB5p0Y8o) both have great documentation on this. For the sake of this guide, we’re going to do this the most straightforward way. First, we need to create a mocked version of our Prisma client. Create a new file right next to our existing `db.ts` — `src/db.mock.ts`:
src/db.mock.ts
```ts
1
/**
2
* First, mock the imported client.
3
*/
4
export let db: unknown;
5
6
/**
7
* Then, create a function to set the mock client.
8
* We do this so that we can have test-specific mocks,
9
* rather than having only one version of the mocked client.
10
*
11
* @param [dbMock={}] An object to use as the mock client. Be sure to mock any Prisma functions used by the component we're testing.
12
*/
13
export function setupDb(dbMock: unknown = {}) {
14
db = dbMock;
15
}
```
4. Now, we need to tell Storybook to use this mocked version of the Prisma client. We’ll do this using [a Vite alias](https://storybook.js.org/docs/writing-stories/mocking-data-and-modules/mocking-modules#builder-aliases).\
(We can instead use [subpath imports](https://storybook.js.org/docs/writing-stories/mocking-data-and-modules/mocking-modules#subpath-imports), but it requires a bit more setup — we’d need to change any existing imports.)
One of the Storybook config files is [`.storybook/main.ts`](https://storybook.js.org/docs/api/main-config/main-config) — this defines the behavior of our Storybook project. Open it up and add the following:
.storybook/main.ts
```diff
1
import type { StorybookConfig } from "@storybook/react-vite";
2
+import { mergeConfig } from "vite";
3
+import path from "path";
4
5
const config: StorybookConfig = {
6
features: {
7
+/**
8
* `experimentalRSC` is required for rendering async server components in Storybook.
9
* It works by wrapping all stories in a Suspense boundary:
10
* https://github.com/storybookjs/storybook/blob/14e18d956fd714c594782fbf23c42765a8b599cd/code/renderers/react/src/entry-preview.tsx#L20-L24
11
*/
12
+ experimentalRSC: true,
13
+ },
14
stories: ["../src/**/*.mdx", "../src/**/*.stories.@(js|jsx|mjs|ts|tsx)"],
15
addons: [
16
"@storybook/addon-essentials",
17
"@storybook/addon-onboarding",
18
"@chromatic-com/storybook",
19
"@storybook/experimental-addon-test",
20
],
21
framework: {
22
name: "@storybook/react-vite",
23
options: {},
24
},
25
+viteFinal: async (config) => {
26
+return mergeConfig(config, {
27
+ resolve: {
28
+ alias: {
29
+"@/db": path.resolve(__dirname, "../src/db.mock.ts"),
30
+ },
31
+ },
32
+ });
33
+ },
34
};
35
export default config;
```
5. Every time we edit one of the Storybook configs, we’ll need to restart the Storybook server. However, if we do this before we finish mocking the Prisma client, [our component will infinitely re-render](https://github.com/storybookjs/storybook/issues/30317). Let’s finish mocking the Prisma client first. Go back to our story, and add the following:
src/app/pages/Home.stories.tsx
```diff
1
import type { Meta, StoryObj } from "@storybook/react";
2
3
+// Must include the `.mock` portion of filename to specify that that's what we want to import
4
+import { setupDb } from "@/db.mock";
5
6
import { Home } from "./Home";
7
8
const meta: Meta9 {ctx.user?.username 10 ? `You are logged in as user ${ctx.user.username}` 11 : "You are not logged in"} 12
13 +-
14
+ {users.map((user) => (
15
+
- {user.username} 16 + ))} 17 +
2
```
## Further reading
[Section titled “Further reading”](#further-reading)
* [TailwindCSS](https://tailwindcss.com/)
* [VS Code, Tailwind CSS IntelliSense Plugin](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss)
# React Compiler
> Enable the React Compiler with RedwoodSDK (Vite)
The React Compiler can optimize your components automatically. RedwoodSDK works with the compiler via Vite — you only need to add the Babel plugin and runtime, and enable it in your Vite config.
Reference
See the related discussion and error context in the GitHub issue comment: [Enabling React Compiler in RedwoodSDK](https://github.com/redwoodjs/sdk/issues/623#issuecomment-3204098488).
## Install
[Section titled “Install”](#install)
First, you’ll need to be on the latest release of RedwoodSDK:
```bash
pnpm add rwsdk@latest
```
Next, install the React Compiler Babel plugin, and Vite’s React plugin.
```bash
pnpm add react@latest react-dom@latest react-server-dom-webpack@latest
pnpm add -D babel-plugin-react-compiler@latest @vitejs/plugin-react@latest
```
Versions
Use React 19, Vite 6+, and the latest RedwoodSDK. The compiler works for both client and server components; no code changes are required.
## Configure Vite
[Section titled “Configure Vite”](#configure-vite)
Enable the compiler by adding the React plugin with the compiler Babel plugin. Place it before the Cloudflare and RedwoodSDK plugins.
vite.config.mts
```diff
1
import { defineConfig } from "vite";
2
import { redwood } from "rwsdk/vite";
3
import { cloudflare } from "@cloudflare/vite-plugin";
4
import react from "@vitejs/plugin-react";
5
6
export default defineConfig({
7
plugins: [
8
+react({
9
+ babel: {
10
+ plugins: ["babel-plugin-react-compiler"],
11
+ },
12
+ }),
13
cloudflare({
14
viteEnvironment: { name: "worker" },
15
}),
16
redwood(),
17
],
18
});
```
If you already have a Vite config, simply add this to your plugins:
```ts
1
react({
2
babel: {
3
plugins: ["babel-plugin-react-compiler"],
4
},
5
}),
```
## Troubleshooting
[Section titled “Troubleshooting”](#troubleshooting)
* After enabling, if HMR behaves oddly, clear Vite cache: `rm -rf node_modules/.vite` and restart the dev server.
## Verify Your Setup
[Section titled “Verify Your Setup”](#verify-your-setup)
Check React DevTools:
1. Install the React Developer Tools browser extension
2. Open your app in development mode
3. Open React DevTools
4. Look for the ✨ emoji next to component names
If the compiler is working:
* Components will show a “Memo ✨” badge in React DevTools
* Expensive calculations will be automatically memoized
* No manual `useMemo` is required
Source: [React Compiler Installation](https://react.dev/learn/react-compiler/installation)
# React Server Function Streams
> Sending chunked stream responses from server function to the client
This pattern is useful for sending partial responses to the client, such as when you’re waiting for data from an external API, like an AI model.
## Example
[Section titled “Example”](#example)
First create a server function that returns a stream. In this example we’re using Cloudflare’s AI, and we’re streaming the response back to the client.
app/pages/Chat/functions.ts
```tsx
1
"use server";
2
3
export async function sendMessage(prompt: string) {
4
console.log("Running AI with Prompt:", prompt);
5
const response = await env.AI.run("@cf/meta/llama-4-scout-17b-16e-instruct", {
6
prompt,
7
stream: true,
8
});
9
return response as unknown as ReadableStream;
10
}
```
Now on the client component, we can use the `consumeEventStream` function to parse the chunks whilst keeping the UI updated.
app/pages/Chat/Chat.tsx
```tsx
1
"use client";
2
3
import { sendMessage } from "./functions";
4
import { useState } from "react";
5
import { consumeEventStream } from "rwsdk/client";
6
7
export function Chat() {
8
const [message, setMessage] = useState("");
9
const [reply, setReply] = useState("");
10
const [isLoading, setIsLoading] = useState(false);
11
const onSubmit = async (e: React.FormEventHello World
3
34
48
);
49
}
```
For a working example, please see the [Chat example](https://github.com/redwoodjs/example-streaming-ai-chat/tree/main).
# Troubleshooting
> Common issues and solutions when building RedwoodSDK applications
## React Server Components Configuration Errors
[Section titled “React Server Components Configuration Errors”](#react-server-components-configuration-errors)
### Error: “A client-only module was incorrectly resolved with the ‘react-server’ condition”
[Section titled “Error: “A client-only module was incorrectly resolved with the ‘react-server’ condition””](#error-a-client-only-module-was-incorrectly-resolved-with-the-react-server-condition)
This error occurs when client-only modules (like `rwsdk/client`, `rwsdk/__ssr`, or `rwsdk/__ssr_bridge`) are being resolved with the `react-server` condition, which they should not be.
#### What This Means
[Section titled “What This Means”](#what-this-means)
RedwoodSDK uses Node.js package.json [export conditions](https://nodejs.org/api/packages.html#conditional-exports) to ensure the correct code is loaded for each environment:
* **Worker environment** (React Server Components): Uses `react-server` condition for server-only modules
* **SSR environment**: Does NOT use `react-server` condition
* **Client environment**: Uses `browser` condition
When client-only modules are incorrectly resolved with `react-server`, it indicates a configuration issue.
#### How to Fix
[Section titled “How to Fix”](#how-to-fix)
1. **Check your Vite configuration**
If you’re using RedwoodSDK’s `configPlugin`, the resolve conditions are set automatically. However, if you’re manually configuring Vite, ensure:
```ts
1
// Worker environment (RSC)
2
resolve: {
3
conditions: ["workerd", "react-server", "module", "node"];
4
}
5
6
// SSR environment
7
resolve: {
8
conditions: ["workerd", "module", "browser"];
9
// Note: NO "react-server" condition
10
}
11
12
// Client environment
13
resolve: {
14
conditions: ["browser", "module"];
15
}
```
2. **Verify you’re not overriding resolve conditions**
Check your `vite.config.ts` or `vite.config.mts` to ensure you’re not manually overriding `resolve.conditions` in a way that conflicts with RedwoodSDK’s configuration.
```ts
1
// ❌ Don't do this
2
export default defineConfig({
3
environments: {
4
ssr: {
5
resolve: {
6
conditions: ["react-server", "workerd"], // Wrong!
7
},
8
},
9
},
10
});
11
12
// ✅ Let RedwoodSDK handle it
13
import { configPlugin } from "rwsdk/vite";
14
export default defineConfig({
15
plugins: [
16
configPlugin({
17
/* ... */
18
}),
19
],
20
});
```
3. **Check for incorrect imports**
Ensure that client-only code is not being imported in server components:
```tsx
1
// ❌ Don't import client-only modules in server components
2
import { initClient } from "rwsdk/client"; // This is client-only!
3
4
export default function ServerComponent() {
5
// This will cause the error
6
return {reply}
35
36
47
Server Component
;
7
}
8
9
// ✅ Client-only imports should only be in client components
10
("use client");
11
import { initClient } from "rwsdk/client";
12
13
export default function ClientComponent() {
14
return Client Component
;
15
}
```
4. **Intermittent errors (race conditions)**
If this error appears intermittently, especially during development server startup, it may indicate a race condition in dependency optimization. This can happen with large libraries.
Try:
* Restarting the dev server
* Clearing Vite’s cache: `rm -rf node_modules/.vite`
* If the issue persists, it may be a bug in RedwoodSDK - please [file an issue](https://github.com/redwoodjs/sdk/issues)
#### Understanding Export Conditions
[Section titled “Understanding Export Conditions”](#understanding-export-conditions)
RedwoodSDK’s package.json uses export conditions to route imports correctly:
```json
{
"exports": {
"./client": {
"react-server": "./dist/runtime/entries/no-react-server.js",
"default": "./dist/runtime/entries/client.js"
},
"./worker": {
"react-server": "./dist/runtime/entries/worker.js",
"default": "./dist/runtime/entries/react-server-only.js"
}
}
}
```
* When `rwsdk/client` is imported with `react-server` condition → throws error (client code shouldn’t run in RSC)
* When `rwsdk/client` is imported with `default` condition → loads client code ✅
* When `rwsdk/worker` is imported with `react-server` condition → loads worker code ✅
* When `rwsdk/worker` is imported with `default` condition → throws error (server code shouldn’t run in client)
The build system automatically selects the correct condition based on the environment, but configuration issues can cause the wrong condition to be used.
***
## Directive Scan Errors
[Section titled “Directive Scan Errors”](#directive-scan-errors)
### Error: “Directive scan failed. This often happens due to syntax errors in files using ‘use client’ or ‘use server’”
[Section titled “Error: “Directive scan failed. This often happens due to syntax errors in files using ‘use client’ or ‘use server’””](#error-directive-scan-failed-this-often-happens-due-to-syntax-errors-in-files-using-use-client-or-use-server)
This error occurs during RedwoodSDK’s initial scan of your codebase to identify files with `"use client"` and `"use server"` directives. The scan uses esbuild to parse and analyze your files, and it can fail if it encounters syntax errors or other issues.
#### What This Means
[Section titled “What This Means”](#what-this-means-1)
RedwoodSDK scans all files in your `src` directory to:
* Identify which files are client components (`"use client"`)
* Identify which files are server functions (`"use server"`)
* Build a dependency graph to classify modules correctly
* Handle MDX files by compiling them
The scan must successfully parse all files to build an accurate picture of your application structure.
#### How to Fix
[Section titled “How to Fix”](#how-to-fix-1)
1. **Check for syntax errors**
The most common cause is syntax errors in files that use directives. Check the error stack trace in the console - it will usually point to the problematic file.
Common syntax errors include:
* Missing closing braces or parentheses
* Incorrect JSX syntax
* TypeScript type errors that prevent parsing
* Invalid import statements
```tsx
1
// ❌ Missing closing brace
2
"use client";
3
export function Component() {
4
return Hello
5
// Missing closing brace and tag
6
}
7
8
// ✅ Correct syntax
9
"use client";
10
export function Component() {
11
return {requestInfo.request.url}
;
7
}
8
9
// ✅ Do this instead - requestInfo is passed as props
10
import type { RequestInfo } from "rwsdk/worker";
11
12
export default function MyPage({ request, ctx }: RequestInfo) {
13
const url = new URL(request.url);
14
return Hello
;
12
}
```
2. **Check MDX files**
If you’re using MDX files, ensure they compile correctly. MDX compilation errors can cause the scan to fail.
```mdx
## // ❌ Invalid MDX syntax
## title: My Page
{url.pathname}
;
15
}
```
2. **In route handlers and middleware**
Route handlers and middleware receive `requestInfo` as a parameter:
```tsx
1
// ✅ Route handler - requestInfo is the parameter
2
import { route } from "rwsdk/router";
3
import type { RequestInfo } from "rwsdk/worker";
4
5
route("/users/:id", ({ params, request, ctx }: RequestInfo) => {
6
// Use params, request, ctx directly
7
return Client
;
8
}
9
10
// ✅ Pass data as props instead
11
("use client");
12
export default function ClientComponent({ userId }: { userId: string }) {
13
return User: {userId}
;
14
}
15
16
// In server component:
17
export default function ServerPage({ ctx }: RequestInfo) {
18
return Page
;
8
}
9
10
// ✅ Move it inside a function that runs during request handling
11
import type { RequestInfo } from "rwsdk/worker";
12
13
export default function Page({ request }: RequestInfo) {
14
// Access request here, inside the component
15
return {request.url}
;
16
}
```
7. **Queue handlers and cron triggers**
Queue handlers and scheduled tasks (cron triggers) run outside of the HTTP request lifecycle, so they don’t have request context:
```tsx
1
// ❌ This won't work - queue handlers don't have request context
2
import { getRequestInfo } from "rwsdk/worker";
3
4
const app = defineApp([
5
/* routes */
6
]);
7
8
export default {
9
fetch: app.fetch,
10
async queue(batch) {
11
const info = getRequestInfo(); // Error! No request context in queue handler
12
for (const message of batch.messages) {
13
// Process message
14
}
15
},
16
};
17
18
// ✅ Pass data through the message body instead
19
const app = defineApp([
20
route("/send-email", ({ ctx }: RequestInfo) => {
21
// Capture data from request context
22
env.QUEUE.send({
23
userId: ctx.user.id,
24
email: ctx.user.email,
25
// ... other data you need
26
});
27
return new Response("Queued");
28
}),
29
]);
30
31
export default {
32
fetch: app.fetch,
33
async queue(batch) {
34
for (const message of batch.messages) {
35
const { userId, email } = message.body as {
36
userId: number;
37
email: string;
38
};
39
// Use the data from the message, not request context
40
await sendEmail(email);
41
}
42
},
43
};
```
The same applies to cron triggers:
```tsx
1
// ❌ This won't work
2
import { getRequestInfo } from "rwsdk/worker";
3
4
export default {
5
fetch: app.fetch,
6
async scheduled(controller) {
7
const info = getRequestInfo(); // Error! No request context in cron
8
// ... scheduled task
9
},
10
};
11
12
// ✅ Cron triggers don't have request context - they're background tasks
13
export default {
14
fetch: app.fetch,
15
async scheduled(controller) {
16
// Do your scheduled work without request context
17
await cleanupOldData();
18
await generateReports();
19
},
20
};
```
#### Understanding Request Context
[Section titled “Understanding Request Context”](#understanding-request-context)
RedwoodSDK uses Node.js `AsyncLocalStorage` to provide request-scoped data. This means:
1. **Request context is set** when a request starts (in the router’s `handle` method)
2. **Context is available** to all code that runs synchronously within that request
3. **Context is lost** when:
* The request completes
* Code runs in a different async context (like `setTimeout`, `setInterval`)
* Code runs in a client component (browser environment)
The `requestInfo` import works in server functions because they’re called during the request lifecycle. The `getRequestInfo()` function throws an error if called outside this context to prevent bugs from accessing stale or missing data.
Tip
If you need to pass request data to code that runs outside the request context, capture the specific values you need as variables before the context is lost.
# Vitest
> Learn how to write integration tests for your RedwoodSDK application.
RedwoodSDK supports integration testing using **Vitest** and **Cloudflare Workers Pool**.
## The “Test Bridge” Pattern
[Section titled “The “Test Bridge” Pattern”](#the-test-bridge-pattern)
Since tests run in an isolated worker process (powered by `vitest-pool-workers`), they cannot directly access your running application’s state or database bindings in the same way a unit test might.
To bridge this gap, this guide uses a pattern where the test runner communicates with your worker via a special HTTP route (`/_test`).
1. **Test Side**: Uses an `vitestInvoke` helper to send a POST request with the action name and arguments.
2. **Worker Side**: A `handleVitestRequest` handler receives the request, executes the actual Server Action within the worker’s context (with full access to `ctx`, D1, KV, etc.), and returns the result.
You can interpret this as “RPC from Test Runner to Worker”.
## 1. Configure Vitest
[Section titled “1. Configure Vitest”](#1-configure-vitest)
Note
Currently, tests must run against the **built worker** to handle RSC transforms correctly.
You will need two things in your `vitest.config.ts`:
1. Use `defineWorkersConfig` from `@cloudflare/vitest-pool-workers/config`.
2. Point the pool to your **built** `wrangler.json`.
vitest.config.ts
```ts
1
import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";
2
3
export default defineWorkersConfig({
4
test: {
5
include: ["src/**/*.test.{ts,tsx}"],
6
poolOptions: {
7
workers: {
8
wrangler: {
9
// Use the built worker output so `rwsdk/worker` and RSCs resolve correctly.
10
configPath: "./dist/worker/wrangler.json",
11
},
12
},
13
},
14
},
15
});
```
## 2. Setup the Test Bridge
[Section titled “2. Setup the Test Bridge”](#2-setup-the-test-bridge)
Expose a `/_test` route in your `src/worker.tsx` to handle incoming test requests using `rwsdk-community`.
You can find a complete working example in our [Vitest Playground](https://github.com/redwoodjs/sdk/tree/main/community/playground/vitest-showcase).
src/worker.tsx
```tsx
1
import { render, route } from "rwsdk/router";
2
import { defineApp } from "rwsdk/worker";
3
import { handleVitestRequest } from "rwsdk-community/worker";
4
import * as appActions from "./app/actions";
5
import * as testUtils from "./app/test-utils";
6
7
export default defineApp([
8
// ... other middleware
9
10
// 1. Expose the test bridge route
11
route("/_test", {
12
post: ({ request }) => handleVitestRequest(request, {
13
...appActions,
14
...testUtils // Optional: expose specific test utilities
15
}),
16
}),
17
18
// ... your application routeswe use
19
render(Document, [route("/", Home)]),
20
]);
```
## 3. Write a Test
[Section titled “3. Write a Test”](#3-write-a-test)
Use the `vitestInvoke` helper from `rwsdk-community/test` to call your exposed actions.
src/tests/example.test.ts
```ts
1
import { expect, it, describe, beforeAll } from "vitest";
2
import { vitestInvoke } from "rwsdk-community/test";
3
4
describe("Integration Test", () => {
5
it("should create an item", async () => {
6
// 1. Call a server action via the bridge
7
const id = await vitestInvoke
7
10
);
11
}
12
13
export default defineApp([
14
except((error) => {
15
return Error
8{error instanceof Error ? error.message : "An error occurred"}
9