Request Handling & Routing

The request/response paradigm is at the heart of web development - when a browser makes a request, your server needs to respond with content. RedwoodSDK makes this easy with the defineApp function, which lets you elegantly handle incoming requests and return the right responses.

src/worker.tsx

import { defineApp } from "@redwoodjs/sdk/worker";
import { route } from "@redwoodjs/sdk/router";

export default defineApp([
  // Middleware
  function middleware({ request, env, appContext }) { /* Modify context */ },
  function middleware({ request, env, appContext }) { /* Modify context */ },
  // Request Handlers
  route("/", function handler({ request, env, appContext }) {
    return new Response("Hello, world!")
  }),
  route("/ping", function handler({ request, env, appContext }) {
    return new Response("Pong!")
  }),
]);

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

Routes are matched in the order they are defined. You define routes using the route function. Trailing slashes are optional and normalized internally.

src/worker.tsx

import { route } from "@redwoodjs/sdk/router";

defineApp([
  route("/match-this", () => new Response("Hello, world!"))
])

route parameters:

1. The matching pattern string
2. The request handler function

There are three matching patterns:

Static

Match exact pathnames.

route("/", ...)
route("/about", ...)
route("/contact", ...)

Parameter

Match dynamic segments marked with a colon (:). The values are available in the route handler via params (params.id and params.groupId).

route("/users/:id", ...)
route("/users/:id/edit", ...)
route("/users/:id/addToGroup/:groupId", ...)

Wildcard

Match all remaining segments after the prefix, the values are available in the route handler via params.$0, params.$1, etc.

route("/files/*", ...)
route("/files/*/preview", ...)
route("/files/*/download/*", ...)

Request Handlers

The request handler is a function, or array of functions (See Interruptors), that are executed when a request is matched.

src/worker.tsx

import { route } from "@redwoodjs/sdk/router";

defineApp([
  route("/a-standard-response", ({ request, params, env, appContext }) => {
    return new Response("Hello, world!")
  }),
  route('/a-jsx-response', () => {
    return <div>Hello, JSX world!</div>
  }),
])

The request handler function takes in the following options:

1. request: The request object.
2. params: The matched parameters from the request URL.
3. env: The Cloudflare environment.
4. appContext: The context object (See Middleware & AppContext).
5. cf: Cloudflare's Execution Context API methods, e.g. waitUntil()

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.

Interruptors

Interruptors 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

import { defineApp } from "@redwoodjs/sdk/worker";
import { route } from "@redwoodjs/sdk/router";
import { EditBlogPage } from "src/pages/blog/EditBlogPage";

function isAuthenticated({ request, env, appContext }) {
  // Ensure that this user is authenticated
  if (!appContext.user) {
    return new Response("Unauthorized", { status: 401 })
  }
}

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 & AppContext

appContext is a mutable object that is passed to each request handler, interruptors, 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.

src/worker.tsx

import { defineApp } from "@redwoodjs/sdk/worker";
import { route } from "@redwoodjs/sdk/router";

defineApp([
  sessionMiddleware,
  async function getUserMiddleware({ request, env, appContext }) {
    if (appContext.session.userId) {
      appContext.user = await db.user.find({ where: { id: appContext.session.userId } });
    }
  },
  route("/hello", [
    function ({ appContext }) {
      if (!appContext.user) {
        return new Response("Unauthorized", { status: 401 });
      }
    },
    function ({ appContext }) {
      return new Response(`Hello ${appContext.user.username}!`);
    },
  ]),
]);

The appContext object:

1. sessionMiddleware is a function that is used to populate the appContext.session object
2. getUserMiddleware is a middleware function that is used to populate the appContext.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 {appContext.user.username}!" will be returned

Documents

Documents are how you define the “shell” of your application’s html: the <html>, <head>, <meta> tags, scripts, stylesheets, <body>, and where in the <body> 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

import { defineApp } from "@redwoodjs/sdk/worker";
import { route, render } from "@redwoodjs/sdk/router";

import { Document } from "@/pages/Document";
import { HomePage } from "@/pages/HomePage";

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
• 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.

src/pages/Document.tsx

export const Document = ({ children }) => (
  <html lang="en">
    <head>
      <meta charSet="utf-8" />
      <script type="module" src="/src/client.tsx"></script>
    </head>
    <body>
      <div id="root">{children}</div>
    </body>
  </html>
);

Client Side Hydration

You must include the client side hydration script in your document, otherwise the React components will not be hydrated.