fix: Update starters and docs to not use deprecated headers api (#652)

We introduced the awesome `response.headers` in #603, but we have not yet updated starters and docs to use it.

Author: justinvdm

docs/src/content/docs/core/routing.mdx

@@ -28,7 +28,6 @@ export default defineApp([
 ---
 The `defineApp` function takes an array of middleware and route handlers that are executed in the order they are defined. In this example the request is passed through two middleware functions before being "matched" by the route handlers.
 ---
-```
 
 ## Matching Patterns
 
@@ -46,7 +45,6 @@ defineApp([
 1. The matching pattern string
 2. The request handler function
 ---
-```
 
 There are three matching patterns:
 
@@ -103,7 +101,6 @@ Return values:
 - `Response`: A standard response object.
 - `JSX`: A React component, which is statically rendered to HTML on the server, streamed to the client, and then hydrated on the client side.
 ---
-```
 
 ### Interrupters
 
@@ -128,7 +125,6 @@ defineApp([
 ---
 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
 
@@ -170,7 +166,6 @@ The context object:
   - if the user is authenticated the request will be passed to the next request handler and `"Hello {ctx.user.username}!"` will be returned
 
 ---
-```
 
 ## Documents
 
@@ -194,7 +189,6 @@ This component will be rendered on the server side when the page loads. When def
 * Your application's stylesheets and scripts
 * A mount point for your page content (`id="root"` in the code below): this is where your actual page will be rendered - the "dynamic stuff" which updates using React Server Components.
 ---
-```
 
 ```tsx title="src/pages/Document.tsx" mark={7}
 export const Document = ({ children }) => (
@@ -223,15 +217,32 @@ The `requestInfo` object is available in server functions and provides access to
 import { requestInfo } from "rwsdk/worker";
 
 export async function myServerFunction() {
-  const { request, headers, ctx } = requestInfo;
-  // Use request, headers, or ctx as needed
+  const { request, response, ctx } = requestInfo;
+  // Use request, response, or ctx as needed
 }
 ```
 
 The `requestInfo` object contains:
 
-- `request`: The incoming HTTP Request object
-- `headers`: Response headers
+- `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
+import { route } from "rwsdk/router";
+
+const NotFound = () => <div>Not Found</div>;
+
+route('/some-resource', async ({ response }) => {
+  // some logic to determine if the resource is not found
+  
+  response.status = 404;
+  response.headers.set('Cache-Control', 'no-store');
+
+  return <NotFound />;
+});
+```

docs/src/content/docs/reference/sdk-worker.mdx

@@ -83,12 +83,8 @@ export default defineApp([
 
 The `requestInfo` object is used to get information about the current request. It's a singleton that's populated for each request, and constains the following information.
 
-```ts
-import { requestInfo } from "rwsdk/worker";
-
-requestInfo.request.url;
-requestInfo.request.method;
-requestInfo.request.body;
-requestInfo.ctx;
-requestInfo.headers;
-```
+- `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

docs/src/content/docs/tutorial/full-stack-app/2-create-app.mdx

@@ -264,29 +264,29 @@ import { RouteMiddleware } from "rwsdk/router";
 
 export const setCommonHeaders =
 (): RouteMiddleware =>
-({ headers, rw: { nonce } }) => {
+({ response, rw: { nonce } }) => {
   if (!import.meta.env.VITE_IS_DEV_SERVER) {
     // Forces browsers to always use HTTPS for a specified time period (2 years)
-    headers.set(
+    response.headers.set(
       "Strict-Transport-Security",
       "max-age=63072000; includeSubDomains; preload"
     );
   }
 
   // Forces browser to use the declared content-type instead of trying to guess/sniff it
-  headers.set("X-Content-Type-Options", "nosniff");
+  response.headers.set("X-Content-Type-Options", "nosniff");
 
   // Stops browsers from sending the referring webpage URL in HTTP headers
-  headers.set("Referrer-Policy", "no-referrer");
+  response.headers.set("Referrer-Policy", "no-referrer");
 
   // Explicitly disables access to specific browser features/APIs
-  headers.set(
+  response.headers.set(
     "Permissions-Policy",
     "geolocation=(), microphone=(), camera=()"
   );
 
   // Defines trusted sources for content loading and script execution:
-  headers.set(
+  response.headers.set(
     "Content-Security-Policy",
     `default-src 'self'; script-src 'self' 'nonce-${nonce}' https://challenges.cloudflare.com; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; font-src 'self' https://fonts.gstatic.com; frame-src https://challenges.cloudflare.com; object-src 'none';`
   );

docs/src/content/docs/tutorial/full-stack-app/8-jobs-details.mdx

@@ -203,8 +203,8 @@ const Details = async ({ params }: RequestInfo) => {
 
 <Aside type="tip" title="RequestInfo">
 The `RequestInfo` object contains:
-- `request`: The incoming HTTP Request object
-- `headers`: Response headers
+- `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
 
 [You can find more information here.](/reference/sdk-worker/#requestinfo-requestinfo)

sdk/src/runtime/requestInfo/types.ts

@@ -14,5 +14,6 @@ export interface RequestInfo<Params = any, AppContext = DefaultAppContext> {
   headers: Headers;
   rw: RwContext;
   cf: ExecutionContext;
-  response: ResponseInit;
+  // context(justinvdm, 2025-08-18): Ensure headers is always available
+  response: ResponseInit & { headers: Headers };
 }

sdk/src/runtime/worker.tsx

@@ -71,7 +71,7 @@ export const defineApp = <
           pageRouteResolved: undefined,
         };
 
-        const userResponseInit: ResponseInit = {
+        const userResponseInit: ResponseInit & { headers: Headers } = {
           status: 200,
           headers: new Headers(),
         };

starters/minimal/src/app/headers.ts

@@ -2,29 +2,29 @@ import { RouteMiddleware } from "rwsdk/router";
 
 export const setCommonHeaders =
   (): RouteMiddleware =>
-  ({ headers, rw: { nonce } }) => {
+  ({ response, rw: { nonce } }) => {
     if (!import.meta.env.VITE_IS_DEV_SERVER) {
       // Forces browsers to always use HTTPS for a specified time period (2 years)
-      headers.set(
+      response.headers.set(
         "Strict-Transport-Security",
         "max-age=63072000; includeSubDomains; preload",
       );
     }
 
     // Forces browser to use the declared content-type instead of trying to guess/sniff it
-    headers.set("X-Content-Type-Options", "nosniff");
+    response.headers.set("X-Content-Type-Options", "nosniff");
 
     // Stops browsers from sending the referring webpage URL in HTTP headers
-    headers.set("Referrer-Policy", "no-referrer");
+    response.headers.set("Referrer-Policy", "no-referrer");
 
     // Explicitly disables access to specific browser features/APIs
-    headers.set(
+    response.headers.set(
       "Permissions-Policy",
       "geolocation=(), microphone=(), camera=()",
     );
 
     // Defines trusted sources for content loading and script execution:
-    headers.set(
+    response.headers.set(
       "Content-Security-Policy",
       `default-src 'self'; script-src 'self' 'nonce-${nonce}' https://challenges.cloudflare.com; style-src 'self' 'unsafe-inline'; frame-src https://challenges.cloudflare.com; object-src 'none';`,
     );

starters/standard/src/app/headers.ts

@@ -2,29 +2,29 @@ import { RouteMiddleware } from "rwsdk/router";
 
 export const setCommonHeaders =
   (): RouteMiddleware =>
-  ({ headers, rw: { nonce } }) => {
+  ({ response, rw: { nonce } }) => {
     if (!import.meta.env.VITE_IS_DEV_SERVER) {
       // Forces browsers to always use HTTPS for a specified time period (2 years)
-      headers.set(
+      response.headers.set(
         "Strict-Transport-Security",
         "max-age=63072000; includeSubDomains; preload",
       );
     }
 
     // Forces browser to use the declared content-type instead of trying to guess/sniff it
-    headers.set("X-Content-Type-Options", "nosniff");
+    response.headers.set("X-Content-Type-Options", "nosniff");
 
     // Stops browsers from sending the referring webpage URL in HTTP headers
-    headers.set("Referrer-Policy", "no-referrer");
+    response.headers.set("Referrer-Policy", "no-referrer");
 
     // Explicitly disables access to specific browser features/APIs
-    headers.set(
+    response.headers.set(
       "Permissions-Policy",
       "geolocation=(), microphone=(), camera=()",
     );
 
     // Defines trusted sources for content loading and script execution:
-    headers.set(
+    response.headers.set(
       "Content-Security-Policy",
       `default-src 'self'; script-src 'self' 'nonce-${nonce}' https://challenges.cloudflare.com; style-src 'self' 'unsafe-inline'; frame-src https://challenges.cloudflare.com; object-src 'none';`,
     );

starters/standard/src/app/pages/user/functions.ts

@@ -26,7 +26,7 @@ function getWebAuthnConfig(request: Request) {
 
 export async function startPasskeyRegistration(username: string) {
   const { rpName, rpID } = getWebAuthnConfig(requestInfo.request);
-  const { headers } = requestInfo;
+  const { response } = requestInfo;
 
   const options = await generateRegistrationOptions({
     rpName,
@@ -40,7 +40,7 @@ export async function startPasskeyRegistration(username: string) {
     },
   });
 
-  await sessions.save(headers, { challenge: options.challenge });
+  await sessions.save(response.headers, { challenge: options.challenge });
 
   return options;
 }