react-router-effect 2.0.0 → 2.2.0

package/README.md

@@ -1,225 +1,778 @@
 # react-router-effect
 
-Wrap [React Router](https://reactrouter.com) framework-mode loaders, actions, and middleware with
-[Effect](https://effect.website), and get **typed, declarative error handling** for free.
+Serve a [React Router](https://reactrouter.com) framework-mode app from [Effect](https://effect.website)'s
+HTTP router, on Node or on Cloudflare Workers. Write its loaders, actions and middleware as Effects.
 
-Write your loader/action/middleware as an `Effect`. When it short-circuits with a tagged error,
-the library decides — based on handlers you register once — whether to **recover** (return data
-the component reads via `useLoaderData`) or **throw** (send it to the error boundary or issue
-a redirect). The resolved type of every loader/action reflects exactly what it can return.
+A route function that returns an `Effect` runs with your app's services. When it fails with a tagged
+error, the route factory you configure once decides what happens: recover with data for
+`useLoaderData`, send the error to the error boundary, or redirect. The type of the route's data
+lists what the route can return.
 
 ```ts
-const loader = makeLoader((args: Route.LoaderArgs) =>
-  Effect.gen(function* () {
-    const user = yield* getUser(args); // may fail with your domain errors
-    if (!user.onboarded) {
-      yield* Respond.redirect("/onboarding"); // throw → redirect
-    }
-    return { user };
-  }),
-);
-// loader: (args) => Promise<{ user: User } /* | recovered shapes */>
+export const loader = Effect.fn("loader.profile")(function* ({
+  params,
+}: EffectRouteArgs<Route.LoaderArgs>) {
+  const profile = yield* (yield* Profiles).get(params.id); // fails with your domain errors
+  if (!profile.public) yield* Respond.early({ restricted: true }); // recover with typed data
+  return { profile };
+});
+// Route.ComponentProps["loaderData"]: { profile: Profile } | { restricted: boolean }
 ```
 
+If your app does not serve React Router from an Effect HTTP server, read
+[Without the Effect HTTP server](#without-the-effect-http-server).
+
 ## Install
 
+On Node:
+
 ```bash
-vp add react-router-effect effect react-router
+vp add react-router-effect effect react-router @effect/platform-node
 ```
 
-`effect` and `react-router` are peer dependencies. The library requires Effect 4 (`effect@^4.0.0`).
+`effect`, `react-router` and `@effect/platform-node` are peer dependencies. The library requires
+Effect 4.1 (`effect@^4.1.0`) and Node 22 or later. Only `react-router-effect/vite` imports
+`@effect/platform-node`, so another platform does not need it. The README of each example lists the
+packages of its platform. Read [Platforms](#platforms).
 
-## Concepts
+## Get started
 
-A loader/action effect can short-circuit in three ways, via the `Respond` helpers:
+These steps serve an app on Node in production. [`examples/node`](examples/node) is an app with
+these files. It also has development with Vite, tests against the production build, and benchmarks.
 
-| Helper                         | Outcome     | Where it lands                                      |
-| ------------------------------ | ----------- | --------------------------------------------------- |
-| `Respond.early(value, init?)`  | **recover** | resolves with `data(value, init)` → `useLoaderData` |
-| `Respond.throw(value, init?)`  | **throw**   | rejects with `data(value, init)` → error boundary   |
-| `Respond.redirect(url, init?)` | **throw**   | rejects with a redirect `Response`                  |
+### 1. Create the route factory
 
-You declare your app's **domain errors** as a type argument to the factory, and may register a
-handler per domain error. A handler _remaps_ an error by returning either:
+The route factory has what every route Effect needs: the runtime that provides your services, and
+the handlers for your domain errors.
 
-- a library route error — `Respond.early(...)` / `Respond.throw(...)` / `Respond.redirect(...)`; or
-- an `Effect` — `Effect.succeed(value)` to **recover** with `value`, or `Effect.fail(response)`
-  to **throw** a `Response` / `DataWithResponseInit`.
+```ts
+// app/lib/route-factory.server.ts
+import { ManagedRuntime } from "effect";
+import { makeEffectRouteFactory } from "react-router-effect";
+
+import { InvalidTodo, Todos } from "./services.server";
 
-A **declared domain error** may be left unhandled:
+export const runtime = ManagedRuntime.make(Todos.layer);
 
-- if it implements [`HttpServerRespondable`](https://effect.website) it's rendered automatically
-  from its own response;
-- otherwise it falls through to a **500**.
+// Pin the domain errors, then the handler types are inferred.
+export const routeFactory = makeEffectRouteFactory<InvalidTodo>()((Respond) => ({
+  runtime,
+  errorHandlers: {
+    // A form error goes back to the form as data, with a 422.
+    InvalidTodo: (error) => Respond.early({ error: error.message }, 422),
+  },
+}));
 
-**Any other error** a route consumes — a service-specific error that isn't a declared domain
-error — **must be handled** in the loader/action (caught or mapped), or `makeLoader`/`makeAction`
-fails to type-check with a message naming the unhandled error(s). This gives app-wide defaults for
-declared errors while enforcing explicit handling of feature/service-specific ones. (Likewise, an
-effect that requires a service neither the `runtime` nor the `requestContext` provides fails to
-type-check with a message naming the missing service.)
+// Routes import this `Respond`. No library export has the same name.
+export const { Respond } = routeFactory;
+```
 
-## Usage
+### 2. Create the server app
 
-### 1. Configure the factory once
+`App` is a layer of routes on Effect's `HttpRouter`. `ReactRouter.layer` loads the build with your
+route factory. `ReactRouter.routes` registers React Router as the catch-all route.
+`ReactRouterAssets.layer` registers the files of the client build. Your own routes and middleware go
+in the same `Layer.mergeAll`.
+
+```ts
+// server/app.ts
+import { Layer } from "effect";
+import { ReactRouter, ReactRouterAssets } from "react-router-effect/server";
+
+import { routeFactory } from "../app/lib/route-factory.server";
+
+export const App = Layer.mergeAll(ReactRouter.routes, ReactRouterAssets.layer).pipe(
+  Layer.provide(
+    ReactRouter.layer({
+      build: () => import("virtual:react-router/server-build"),
+      factory: routeFactory,
+      mode: import.meta.env.MODE,
+    }),
+  ),
+);
+```
+
+### 3. Serve it
+
+`server.js` serves `App` with `HttpRouter.serve`, which also logs each request. When the server
+starts, `App` loads the build and reads the client build. If the server cannot read the client
+build, it fails to start with a `ClientBuildError` that names the resolved directory.
+
+```js
+// server.js
+import { createServer } from "node:http";
+
+import * as NodeHttpServer from "@effect/platform-node/NodeHttpServer";
+import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
+import { Layer } from "effect";
+import { HttpRouter } from "effect/http";
+
+import { App } from "./build/server/index.js";
+
+NodeRuntime.runMain(
+  Layer.launch(
+    HttpRouter.serve(App).pipe(
+      Layer.provide(NodeHttpServer.layer(() => createServer(), { port: 3000 })),
+    ),
+  ),
+);
+```
+
+### 4. Build the server
+
+Make `server/app.ts` the entry of the server build. `react-router build` then writes `App` to
+`build/server/index.js`.
+
+```ts
+// vite.config.ts
+import { reactRouter } from "@react-router/dev/vite";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [reactRouter()],
+  environments: { ssr: { build: { rollupOptions: { input: "./server/app.ts" } } } },
+});
+```
+
+```bash
+react-router build
+NODE_ENV=production node server.js   # React's server build reads NODE_ENV
+```
+
+For development with Vite, the Node example's `server.js` serves the app through
+`ReactRouterVite.layer`. Read [Development with Vite](examples/node/README.md#development-with-vite).
+
+### 5. Write routes as Effects
+
+A loader, action or middleware is an `Effect.fn`. It needs no wrapper. The adapter runs it with the
+factory's runtime and error handlers.
+
+```ts
+// app/routes/todos.tsx
+import { Effect } from "effect";
+import { data } from "react-router";
+import type { EffectRouteArgs } from "react-router-effect";
+
+import type { Route } from "./+types/todos";
+
+import { Todos } from "../lib/services.server";
+
+export const loader = Effect.fn("loader.todos")(function* () {
+  return { todos: yield* (yield* Todos).list };
+});
+
+// `InvalidTodo` is not handled here. The route factory turns it into `{ error }` data with a 422.
+export const action = Effect.fn("action.todos")(function* ({
+  request,
+}: EffectRouteArgs<Route.ActionArgs>) {
+  const form = yield* Effect.promise(() => request.formData());
+  const todo = yield* (yield* Todos).add(String(form.get("title")));
+  return data({ todo }, { status: 201 });
+});
+```
+
+`EffectRouteArgs` keeps hooks that take `typeof action` or `typeof loader` typed, such as
+`useFetcher<typeof action>()`. [Plain Effect loaders, actions and
+middleware](#plain-effect-loaders-actions-and-middleware) explains why. A route function that does
+not return an Effect passes through to React Router unchanged, so promise loaders keep working in
+the same app.
+
+## Platforms
+
+`App` is the same layer on every platform. Only the file that serves it changes. Effect has two
+functions that serve it:
+
+- `HttpRouter.serve(App)` with a server layer, such as `NodeHttpServer.layer` on Node.
+- `HttpRouter.toWebHandler(App)`, which returns a fetch handler, such as a Cloudflare Worker's.
+
+| Platform           | Example                                      | Serves `App` with                             |
+| ------------------ | -------------------------------------------- | --------------------------------------------- |
+| Node               | [`examples/node`](examples/node)             | `HttpRouter.serve` and `NodeHttpServer.layer` |
+| Cloudflare Workers | [`examples/cloudflare`](examples/cloudflare) | `HttpRouter.toWebHandler`                     |
+
+The README of each example has the details of its platform. These rules apply on every platform:
+
+- App-wide services go in the route factory's `runtime`. Read
+  [App-wide services with a runtime](#app-wide-services-with-a-runtime).
+- Per-request services go in a router middleware. Read [Per-request services](#per-request-services).
+- A platform service, such as a tracer, goes where the serve function reads it. `HttpRouter.serve`
+  reads the services that `Layer.provide` gives to its layer. `HttpRouter.toWebHandler` reads the
+  services that `Layer.provideMerge` adds to the layer that it gets.
+
+## Handle errors
+
+An Effect can short-circuit in three ways, with the `Respond` helpers:
+
+| Helper                         | Outcome | Where it lands                                      |
+| ------------------------------ | ------- | --------------------------------------------------- |
+| `Respond.early(value, init?)`  | recover | resolves with `data(value, init)` → `useLoaderData` |
+| `Respond.throw(value, init?)`  | throw   | rejects with `data(value, init)` → error boundary   |
+| `Respond.redirect(url, init?)` | throw   | rejects with a redirect `Response`                  |
+
+Declare your app's domain errors as the type argument of `makeEffectRouteFactory`. You can register
+one handler for each. A handler remaps its error. It returns one of these:
+
+- A library route error: `Respond.early(...)`, `Respond.throw(...)` or `Respond.redirect(...)`.
+- An `Effect`: `Effect.succeed(value)` recovers with `value`, and `Effect.fail(response)` throws a
+  `Response` or `DataWithResponseInit`.
 
 ```ts
-// app/route.server.ts
 import { Data, Effect } from "effect";
-import { makeEffectRouteFactory } from "react-router-effect";
 
 class FormError extends Data.TaggedError("FormError")<{ reply: SubmissionResponse }> {}
 class BadInputError extends Data.TaggedError("BadInputError")<{ message: string }> {}
 class DbError extends Data.TaggedError("DbError")<{ query: string }> {}
 
-// Declare every error your app handles app-wide. `DbError` has no handler below,
-// so it falls through to the 500 default.
+// `DbError` has no handler below, so it falls through to the 500 default.
 type DomainErrors = FormError | BadInputError | DbError;
 
-// Curried: pin the domain errors, then the handler types are inferred. The config
-// is a *builder* — it receives `Respond` (the library's `early`/`throw`/`redirect`)
-// so your handlers can recover/throw, and the factory hands back a single `Respond`
-// for your routes to import (no auto-import ambiguity with a library export).
-export const { makeLoader, makeAction, Respond } = makeEffectRouteFactory<DomainErrors>()(
-  (Respond) => ({
-    // App-specific helpers — merged onto the returned `Respond` (base helpers win):
-    respond: {
-      formError: (reply: SubmissionResponse) => new FormError({ reply }),
-    },
-    errorHandlers: {
-      // keys autocomplete to your domain-error tags; `error` is typed from its key.
-      // recover: short-circuit and hand the reply to the component
-      FormError: (error) => Respond.early({ reply: error.reply }),
-      // throw: send to the error boundary
-      BadInputError: (error) => Effect.fail(new Response(error.message, { status: 400 })),
-    },
-  }),
-);
+export const routeFactory = makeEffectRouteFactory<DomainErrors>()((Respond) => ({
+  // App-specific helpers. The returned `Respond` has them next to the base helpers.
+  respond: {
+    formError: (reply: SubmissionResponse) => new FormError({ reply }),
+  },
+  errorHandlers: {
+    // Keys autocomplete to your domain-error tags, and `error` is typed from its key.
+    // Recover: pass the reply to the component.
+    FormError: (error) => Respond.early({ reply: error.reply }),
+    // Throw: send to the error boundary.
+    BadInputError: (error) => Effect.fail(new Response(error.message, { status: 400 })),
+  },
+}));
+```
+
+A declared domain error can have no handler. If it implements `HttpServerRespondable`, it renders
+its own response. A registered handler still takes precedence. Otherwise it falls through to a 500.
+
+```ts
+import { HttpServerRespondable, HttpServerResponse } from "effect/http";
+
+class NotAuthorizedError extends Data.TaggedError("NotAuthorizedError")<{}> {
+  [HttpServerRespondable.symbol]() {
+    return HttpServerResponse.json({ error: "Not authorized" }, { status: 403 }).pipe(Effect.orDie);
+  }
+}
 ```
 
-> **One `Respond`, no annotations.** Your routes import the `Respond` returned here — there's
-> no library-level `Respond` to clash with it on auto-import. Handler keys autocomplete to your
-> declared domain-error tags, each `error` parameter is typed from its key, and the precise
-> recover types are derived from each handler's return.
+Any other error that a route consumes must be handled in the route. This includes a
+service-specific error that is not a declared domain error. Catch it or map it. This gives the app
+defaults for declared errors. The errors of one feature or service need explicit handling.
+[The route check](#the-route-check) reports an unhandled error at compile time.
 
-### 2. Write loaders/actions as effects
+## Provide services
+
+### App-wide services with a runtime
+
+The `runtime` is an Effect [`ManagedRuntime`](https://effect.website). The factory builds it once and
+reuses it for every request. Route Effects require its services directly, with no `Effect.provide`
+in the route. The runtime's services are the allowed requirements of a route Effect. A route that
+requires another service is a compile error. Without a `runtime`, a route Effect must require
+nothing.
 
 ```ts
-// app/routes/profile.ts
-import { Effect } from "effect";
-import { makeLoader, Respond } from "../route.server.ts";
-import type { Route } from "./+types/profile";
+export const loader = Effect.fn("loader.profile")(function* ({
+  params,
+}: EffectRouteArgs<Route.LoaderArgs>) {
+  const svc = yield* MyService; // the runtime provides MyService
+  return { profile: yield* svc.load(params.id) };
+});
+```
 
-const loaderEffect = ({ params }: Route.LoaderArgs) =>
-  Effect.gen(function* () {
-    const profile = yield* getProfile(params.id); // may fail with FormError / BadInputError
-    if (!profile.public) {
-      yield* Respond.early({ restricted: true }); // recover with typed data
-    }
-    return { profile };
-  });
+`errorHandlers` is optional. A factory can have a runtime only, or nothing:
 
-export const loader = makeLoader((args: Route.LoaderArgs) => loaderEffect(args));
+```ts
+makeEffectRouteFactory()(() => ({ runtime }));
+makeEffectRouteFactory()(() => ({}));
 ```
 
-The resolved type is computed from the effect and your handlers:
+### Per-request services
+
+The runtime provides app-wide services. A request-scoped service is the current user, a request id,
+or a transaction for one request. There are two ways to provide one.
+
+A route-scoped router middleware on `ReactRouter.routes` provides services to React Router's
+requests. Every middleware, loader and action sees them, and no React Router middleware has to set
+them:
 
 ```ts
-type LoaderData = Route.ComponentProps["loaderData"];
-// { profile: Profile } | DataWithResponseInit<{ restricted: boolean }>
-//   ( BadInputError throws, so it never appears here )
+// server/app.ts
+const RequestServices = HttpRouter.middleware((app) =>
+  Effect.provideServiceEffect(
+    app,
+    RequestInfo,
+    HttpServerRequest.HttpServerRequest.use((request) =>
+      Effect.succeed({
+        id: request.headers["x-request-id"] ?? crypto.randomUUID(),
+        startedAt: Date.now(),
+      }),
+    ),
+  ),
+).layer;
+
+export const App = Layer.mergeAll(
+  ReactRouter.routes.pipe(Layer.provide(RequestServices)),
+  ReactRouterAssets.layer,
+).pipe(
+  Layer.provide(
+    ReactRouter.layer({
+      build: () => import("virtual:react-router/server-build"),
+      factory: routeFactory,
+      mode: import.meta.env.MODE,
+    }),
+  ),
+);
 ```
 
-### 3. Write middleware as effects
+A [middleware](https://reactrouter.com/how-to/middleware) can also provide services. An effect
+middleware provides them around `next()`, and everything downstream of `next()` can require them:
 
-`makeMiddleware` wraps a [middleware](https://reactrouter.com/how-to/middleware) function the
-same way, wired to the same `errorHandlers`. Pin it to the route's generated
-`Route.MiddlewareFunction` — middleware has no separate args-only type, so the whole function
-type is the type argument — or omit it to default to React Router's own `MiddlewareFunction`:
+```ts
+// app/root.tsx
+export const middleware = [
+  Effect.fn("middleware.visitor")(function* ({
+    request,
+    next,
+  }: EffectMiddlewareArgs<Route.MiddlewareFunction>) {
+    const name = yield* readVisitor(request);
+    return yield* next().pipe(
+      Effect.provideService(Visitor, { name }),
+      Effect.annotateLogs({ visitor: name }),
+    );
+  }),
+];
+```
+
+Tell the factory which services the request provides with a context key:
 
 ```ts
-// app/routes/profile.ts
-import { Effect } from "effect";
-import { makeMiddleware, Respond } from "../route.server.ts";
-import type { Route } from "./+types/profile";
+// app/lib/route-factory.server.ts
+import { createContext } from "react-router";
+import type { RequestContextKey } from "react-router-effect";
 
-export const middleware: Route.MiddlewareFunction[] = [
-  makeMiddleware<Route.MiddlewareFunction>(({ request }, next) =>
-    Effect.gen(function* () {
-      const user = yield* getUser(request); // may fail with FormError / BadInputError
-      if (!user) yield* Respond.redirect("/login"); // throw → redirect, same as a loader
-      return yield* next(); // run the rest of the chain
+export const requestContext: RequestContextKey<RequestInfo | Visitor> = createContext();
+
+export const routeFactory = makeEffectRouteFactory<DomainErrors>()(() => ({
+  runtime,
+  requestContext,
+}));
+```
+
+A route Effect can then require the runtime's services and the request's services. Any other
+requirement is a compile error. `RequestContextKey<ReqServices>` is an alias of
+`RouterContext<Context.Context<ReqServices>>`.
+
+The adapter sets this key to the request fiber's context before React Router runs. That context
+holds the server span, `HttpServerRequest` and the services of the router middleware. Do not set the
+key to a new context in a React Router middleware, as an app without the adapter does. A new context
+replaces those services for every function after that middleware. Provide request services with a
+router middleware or an effect middleware, as this section shows.
+
+## The adapter
+
+`react-router-effect/server` is a React Router adapter for Effect's HTTP router, on every platform
+that the router runs on. It is the Effect counterpart of `@react-router/express`. It
+handles everything between an `HttpServerRequest` and React Router. That is the Web `Request` and
+its abort signal, the route factory, and the client build. It also converts React Router's
+`Response`, with its streamed body and its cookies. The app keeps its own server, middleware and
+routes.
+
+The adapter's API is unstable, and a minor version can change it. Every export of
+`react-router-effect/server` and `react-router-effect/vite` has the JSDoc tag `@stability unstable`.
+The route factory and the other exports of `react-router-effect` are stable.
+
+React Router keeps doing what it does for any other server adapter: documents, `.data` requests,
+streamed promises, resource routes, the lazy route manifest and middleware. Before React Router
+sees the build, the adapter runs every loader, action and middleware through your route factory:
+
+- A route function that returns an Effect runs with the factory's runtime and request context.
+  Its failures go through the factory's error handlers.
+- Any other route function passes through. Promise loaders and `makeLoader` wrappers keep working.
+
+The layers:
+
+- `ReactRouter.layer(options)` provides the `ReactRouter` service. Its options are these:
+  - `build` is the server build, or a function that loads it.
+  - `factory` is the route factory.
+  - `mode` is React Router's server mode, and you must give it. In a Vite app, pass
+    `import.meta.env.MODE`. React Router runs in production mode for any mode but `development`
+    and `test`, and so does the layer. At layer build, the layer loads a build value once, or a
+    build function in production mode. In `development` and `test`, a build function loads for
+    each request.
+  - `loadContext` makes React Router's load context for each request. Read
+    [The load context](#the-load-context).
+- `ReactRouter.routes` registers React Router as the catch-all route on `*`.
+- `ReactRouterAssets.layer` registers the files of the client build. Read
+  [The client build](#the-client-build).
+- `ReactRouterVite.layer`, from `react-router-effect/vite`, serves the app in development on Node.
+  Read [Development with Vite](examples/node/README.md#development-with-vite).
+
+Provide one value of `ReactRouter.layer` to every layer that reads the service, as `App` does with
+`Layer.provide`. Two values load the build twice.
+
+### The load context
+
+`loadContext` does for the adapter what `getLoadContext` does for `@react-router/express`. It
+returns an Effect of a `RouterContextProvider`. Plain loaders and actions, and `handleRequest` in
+`entry.server.tsx`, read its values with `context.get`. Route Effects read services from their
+Effect context. So give route Effects services with router middleware, not with `loadContext`.
+
+```ts
+ReactRouter.layer({
+  build: () => import("virtual:react-router/server-build"),
+  factory: routeFactory,
+  mode: import.meta.env.MODE,
+  loadContext: (request) =>
+    Effect.sync(() => {
+      const context = new RouterContextProvider();
+      context.set(localeKey, request.headers["accept-language"] ?? "en");
+      return context;
+    }),
+});
+```
+
+The Effect gets the services of the layer and the services of the request. The services of the
+request, such as its scope, win. The adapter adds its own keys to the provider. If the Effect dies,
+the client gets an empty 500.
+
+### Routes and middleware
+
+The route that a request matches decides which middleware runs on it. Effect has three kinds of
+middleware:
+
+- A server middleware, the `middleware` option of `HttpRouter.serve`, wraps every request. It also
+  wraps the send of the response, so a change to the response with `Effect.map` does not reach the
+  client. `HttpMiddleware.compression` works there.
+- A global router middleware, `HttpRouter.middleware(fn, { global: true })`, wraps every route.
+- A route-scoped middleware, `HttpRouter.middleware(fn).layer`, applies only to the routes of the
+  layers that you provide it to.
+
+Route-scoped middleware selects the middleware of each kind of request. `HttpRouter.serve` logs
+every request. To leave file requests out of that log, provide `HttpRouter.disableLogger` to the
+assets layer only:
+
+```ts
+export const App = Layer.mergeAll(
+  ReactRouter.routes.pipe(Layer.provide(RequestServices)),
+  ReactRouterAssets.layer.pipe(Layer.provide(HttpRouter.disableLogger)),
+  HttpRouter.middleware(HttpMiddleware.compression(), { global: true }),
+).pipe(
+  Layer.provide(
+    ReactRouter.layer({
+      build: () => import("virtual:react-router/server-build"),
+      factory: routeFactory,
+      mode: import.meta.env.MODE,
     }),
   ),
-];
+);
+```
+
+The order of two route-scoped middleware layers on one route is not fixed. If the order matters,
+join them into one middleware with `combine`:
+`HttpRouter.middleware(first).combine(HttpRouter.middleware(second)).layer`.
+
+These rules apply to the routes:
+
+- An exact route wins over a route with a parameter, and both win over a wildcard. So your own
+  routes and the files of the client build win over React Router's `*`.
+- A route of your own on `*` or `/*`, for a method that React Router's route has, collides with it.
+  Then the server fails to start. A route of your own with the path of a file of the client build
+  fails the same way.
+- If a HEAD request matches no HEAD route, it uses the GET route of its path. `ReactRouter.routes`
+  registers no HEAD route. So a GET route of your own answers HEAD, as it does in Express.
+- React Router's route takes the methods of `HttpMethod.all`: GET, POST, PUT, DELETE, PATCH,
+  OPTIONS, TRACE and QUERY, and HEAD through GET. A request with another method, such as PROPFIND,
+  gets a 404 from the router.
+- Register `ReactRouter.routes` at the root of the router. Under a prefix, React Router does not
+  get the path that it expects. To serve the app under a path, set React Router's `basename`.
+- The router ignores the case of the path. On a file system that is case-sensitive, a request for a
+  file with the wrong case matches the file's route and gets a 404.
+
+### The client build
+
+`ReactRouterAssets.layer` serves `build.assetsBuildDirectory` under `build.publicPath`, as the two
+`express.static` lines of React Router's Express template do. It needs the platform's file system,
+which `NodeHttpServer.layer` provides. A Cloudflare Worker serves the client build from its static
+assets, and does not use this layer.
+
+- The hashed directory is the directory of the build's manifest URL, such as `/assets`. React
+  Router's build writes files with a content hash in their names there. The layer caches them for a
+  year as immutable. A request under the hashed directory gets a 404 for a file that the directory
+  does not have. A path with `..` does not get out of the hashed directory.
+- Each other file gets its own route for GET and HEAD, and the layer caches it for an hour. At
+  server start, the layer reads the client build. If a file is added outside the hashed directory
+  later, the layer serves it only after a restart.
+- A directory with an `index.html`, such as a prerendered page, serves that file. Its path without
+  the trailing slash redirects to the path with it. A root `index.html`, such as a prerendered home
+  page, serves `/`, and React Router's catch-all yields to it.
+- If the manifest URL is not under `publicPath`, or it is at the root of `publicPath`, there is no
+  hashed directory. Then the layer caches every file for an hour.
+- The layer serves no dotfiles, such as `.vite/manifest.json`, as `express.static` does.
+- The layer registers nothing for a build that loads for each request, such as a development build.
+  Vite serves the client there. It also registers nothing for a `publicPath` on another origin.
+- `assetsBuildDirectory` is relative to the working directory of the server. If the layer cannot
+  read it, the server fails to start with a `ClientBuildError` that names the resolved directory.
+  If a file name has a `*`, the server fails to start with a `ClientBuildError` too, because the
+  router cannot match that name.
+
+### Requests
+
+The Web request comes from `HttpServerRequest.toWeb`, body included. On Effect's Node server, the
+request has the changes that middleware makes to the `HttpServerRequest`, such as the headers of
+`HttpMiddleware.xForwardedHeaders`. On a Web server, such as a Cloudflare Worker, React Router gets
+the runtime's own request. The README of each example describes the requests of its platform.
+
+If the client leaves while React Router runs or while the body streams, the response ends early, and
+the request signal aborts. A completed response never aborts it. On Cloudflare Workers, the abort
+comes from Cloudflare's own request signal. For the conditions of that abort, read the
+[Cloudflare example](examples/cloudflare/README.md#requests).
+
+React Router logs and answers the errors of route code. If the adapter's own steps fail, for example
+a `loadContext` that dies, the adapter logs the error with `Effect.logError`. Then it answers an
+empty 500. The log goes to the loggers of the app's Effect runtime.
+
+### Cookies
+
+Set cookies from route code with React Router's cookie helpers, `createCookie` and the session
+storages, as in any React Router app. The adapter converts React Router's `Set-Cookie` values into
+the response's `cookies`, as `HttpServerResponse.fromWeb` does. A router middleware on
+`ReactRouter.routes` can read and change them like any other cookie. A response that replaces React
+Router's has none of them.
+
+Effect keeps one cookie per name and only the attributes it knows: `Max-Age`, `Domain`, `Path`,
+`Expires`, `HttpOnly`, `Secure`, `Partitioned`, `Priority` and `SameSite`. One response can set the
+same cookie name twice, for example to expire it on one path and set it on another. Then Effect
+sends only the last one.
+
+Effect accepts only cookie names that are RFC 6265 tokens: letters, digits and
+``!#$%&'*+-.^_`|~``. React Router's `createCookie` and session storages also accept other names,
+such as `app/session` or `user:prefs`. The adapter does not send a cookie with such a name. It logs
+an error with the cookie's name instead. Give every cookie a token name.
+
+### Content type
+
+Effect gives a streamed body without a content type `application/octet-stream`. A resource route
+that returns such a body sends that type, and the browser downloads the response. Examples are a
+`ReadableStream`, bytes, or the body of another service's response. With Express, the response has
+no content type, and the browser guesses one. Set `Content-Type` in the route:
+
+```ts
+return new Response(Readable.toWeb(file) as ReadableStream, {
+  headers: { "content-type": "application/pdf" },
+});
+```
+
+### Tracing
+
+When the request has a server span, the adapter traces React Router. If the app provides a tracer
+that exports spans, such as `OtelTracer`, Effect's HTTP server makes the server span. Give the
+tracer where the serve function reads it, as [Platforms](#platforms) tells. Effect serves each
+request with the services of that layer. A tracer that the serve function does not read makes no
+server span, so the adapter adds no spans. The README of each example shows where its tracer goes.
+
+Each middleware, loader and action runs in a span of its own, such as
+`react-router.loader routes/todos`.
+The spans nest as React Router calls the functions. This is the example's `GET /todos`:
+
+```text
+GET                           the server span, with http.route=/todos
+└─ react-router.middleware root
+   └─ middleware.visitor      the Effect middleware's own span, around next()
+      ├─ react-router.loader root
+      │  └─ loader.root       the route Effect's span
+      └─ react-router.loader routes/todos
+         └─ loader.todos
 ```
 
-`next` is handed to the effect as `() => Effect.Effect<Result, FailureResponse>` (React Router's
-own `next: () => Promise<Result>`, wrapped) — call it with `yield*` to run downstream
-loaders/middleware. A downstream throw (e.g. a nested loader's redirect) surfaces as a typed
-failure rather than a rejected promise, so it flows through the same recover/throw handling as
-a loader or action.
+A middleware's span covers everything its `next()` runs: the next middleware, then the loaders and
+the action. Route Effects nest under the span of their function. Effect's OpenTelemetry tracer makes
+the current Effect span the active OpenTelemetry context. So the clients that an OpenTelemetry
+instrumentation traces nest there too, such as a database driver that a promise loader calls.
+Without a server span, or with Effect's native tracer, whose spans go nowhere, the adapter adds no
+spans and no cost.
 
-### Self-rendering domain errors
+The adapter sets `http.route` on the server span to the pattern of the matched routes, such as
+`/todos/:id`, once per request. It does this also for a page that runs no route function. A router
+middleware that opens a span of its own does not change that: the pattern still goes on the server
+span. A request that matches no route keeps the router's `*`. `ReactRouter.layer` reads the tracer
+once, at layer build. So it does not see a tracer that the app provides only inside a request.
 
-If a domain error implements `HttpServerRespondable`, you don't need to register a handler —
-it renders its own response:
+## Route functions
+
+### Plain Effect loaders, actions and middleware
 
 ```ts
-import { HttpServerRespondable, HttpServerResponse } from "effect/http";
+export const loader = Effect.fn("loader.dashboard")(function* () {
+  const { organization } = yield* AuthContext.getScope;
+  return { organization };
+});
+
+export const action = Effect.fn("action.createTax")(function* ({
+  request,
+}: EffectRouteArgs<Route.ActionArgs>) {
+  const submission = yield* parseSubmission(request);
+  return data({ reply: submission.reply() }, { status: 201 });
+});
+
+export const middleware = [
+  Effect.fn("middleware.adminOnly")(function* ({
+    next,
+  }: EffectMiddlewareArgs<Route.MiddlewareFunction>) {
+    const user = yield* AuthContext.getUser;
+    if (user.role !== "admin") return redirect("/settings");
+    return yield* next().pipe(Effect.annotateLogs({ userId: user.id }));
+  }),
+];
+```
 
-class NotAuthorizedError extends Data.TaggedError("NotAuthorizedError")<{}> {
-  [HttpServerRespondable.symbol]() {
-    return HttpServerResponse.json({ error: "Not authorized" }, { status: 403 }).pipe(Effect.orDie);
+- Route data: Effects are branded with React Router's `unstable_SerializesTo`. So
+  `Route.ComponentProps` types the data of an Effect loader or action, including what the factory
+  recovers.
+  - Hooks that take `typeof loader` or `typeof action`, such as `useFetcher<typeof action>()`,
+    read the data through React Router's `SerializeFrom`. It treats a function as a client
+    function when its argument has the members of client loader args, and gives client functions
+    their raw return value. Typegen's `Route.LoaderArgs` and `Route.ActionArgs` have those same
+    members, so for an Effect the hook would type the data as the Effect itself.
+  - Take the args through `EffectRouteArgs<Route.LoaderArgs>`. It makes `pattern` optional, so the
+    argument no longer matches and the hook reads the brand. A loader without args needs nothing.
+  - `RouteData<typeof loader>` reads the brand directly and applies React Router's serialization.
+    The brand records the data before serialization: it has to keep Effect's subtype order, and
+    React Router's `Serialize` does not.
+- Middleware: an effect middleware gets `next` as an effect in its args. Services, log annotations
+  and the span that it provides around `next()` reach every route Effect downstream. `context.set`
+  keeps working. You cannot annotate a route array with an effect middleware as
+  `Route.MiddlewareFunction[]`.
+- Action metadata: `actionMeta` in the factory config is read after every action resolves. The
+  adapter attaches it to the action's data under `__meta`.
+- Tests: `routeFactory.handlers.loader(loader)(args)` runs a route function as the server does.
+
+### Register what the factory recovers
+
+A plain Effect loader cannot see the factory's handlers. Declare what they recover once:
+
+```ts
+declare module "react-router-effect" {
+  interface Register {
+    recover: { FormValidationError: { reply: SubmissionResponse } };
+    actionMeta: { realtimeEventIds: ReadonlyArray<string> };
   }
 }
 ```
 
-A registered handler, if present, still takes precedence over the error's own response.
+Declare the types directly. Reading them from `typeof routeFactory` is circular.
+
+### The route check
 
-### Providing services with a runtime
+`RouteEffectCheck` reads the route modules that React Router's typegen registers. It fails to
+compile in three cases:
 
-Pass a `runtime` (an effect [`ManagedRuntime`](https://effect.website)) and your loaders/actions
-may require its services directly — no per-call `Effect.provide`. The runtime is built once and
-reused for every request:
+- A route Effect can fail with an error that the factory does not handle.
+- A route Effect needs a service that the runtime and the request context do not provide.
+- `Register` disagrees with the factory.
 
 ```ts
-// app/runtime.server.ts
-import { ManagedRuntime } from "effect";
-export const appRuntime = ManagedRuntime.make(AppLayer); // provides Database, MyService, ...
+import type { RouteEffectCheck } from "react-router-effect/server";
 
-// app/route.server.ts
-export const { makeLoader, makeAction } = makeEffectRouteFactory<DomainErrors>()(() => ({
-  runtime: appRuntime,
-  errorHandlers: { ... },
-}));
+export const routeEffects: RouteEffectCheck<typeof routeFactory> = {};
+```
+
+```text
+Type '{}' is missing the following properties from type ...:
+  "routes/billing#loader must handle PlaidApiError",
+  "routes/admin#middleware needs a provider for app/Session"
+```
+
+### Requirements and limits
 
-// app/routes/profile.ts — `MyService` is satisfied by the runtime, not provided here:
-const loader = makeLoader((args: Route.LoaderArgs) =>
+- Effect 4.1 or later, and `skipLibCheck`. The brand augments `Effect`, and TypeScript cannot test
+  the variance annotations of that augmentation.
+- For the adapter, React Router 8.3 or later. The route factory, `makeLoader`, `makeAction` and
+  `makeMiddleware` also support React Router 7.16 or later.
+- A route module export must be a function. A bare `Effect` value is not a loader.
+- Prerendering (`prerender`) and RSC mode call the build without the adapter.
+
+## Without the Effect HTTP server
+
+If your app serves React Router from Express, `@react-router/node`, a serverless platform or another
+server, the adapter does not apply. The same route factory still returns `makeLoader`, `makeAction`
+and `makeMiddleware`. Each wraps one route function. The wrapper runs the Effect with the factory's
+runtime and error handlers, and returns a function that React Router calls.
+
+```ts
+// app/routes/profile.ts
+import { Effect } from "effect";
+import { makeLoader, Respond } from "../route.server.ts";
+import type { Route } from "./+types/profile";
+
+export const loader = makeLoader((args: Route.LoaderArgs) =>
   Effect.gen(function* () {
-    const svc = yield* MyService;
-    return { profile: yield* svc.load(args.params.id) };
+    const profile = yield* getProfile(args.params.id); // can fail with FormError / BadInputError
+    if (!profile.public) {
+      yield* Respond.early({ restricted: true }); // recover with typed data
+    }
+    return { profile };
   }),
 );
 ```
 
-The runtime's services become the effect's allowed requirement channel: requiring a service the
-runtime provides type-checks, while requiring one it _doesn't_ is a compile error. With no
-`runtime`, effects must require nothing.
+Take `makeLoader`, `makeAction`, `makeMiddleware` and `Respond` from the factory:
+
+```ts
+// app/route.server.ts
+export const { makeLoader, makeAction, makeMiddleware, Respond } =
+  makeEffectRouteFactory<DomainErrors>()((Respond) => ({
+    runtime: appRuntime,
+    errorHandlers: {/* ... */},
+  }));
+```
 
-`errorHandlers` is optional too — configure a factory with just a runtime, or with nothing:
+`makeLoader` and `makeAction` are the same wrapper. The wrapper computes the resolved type from the
+effect and your handlers:
 
 ```ts
-makeEffectRouteFactory()(() => ({ runtime }));
-makeEffectRouteFactory()(() => ({}));
+type LoaderData = Route.ComponentProps["loaderData"];
+// { profile: Profile } | DataWithResponseInit<{ restricted: boolean }>
+//   ( BadInputError throws, so it never appears here )
 ```
 
-### Per-request services from middleware
+Without the adapter, an unhandled error is a compile error at the `makeLoader` or `makeAction` call.
+The message lists the unhandled errors. An effect can also require a service that neither the
+`runtime` nor the `requestContext` provides. That fails the same way, and the message lists the
+missing service.
 
-The runtime provides app-wide services. For **request-scoped** services — the current user, a
-request id, a per-request transaction — use [middleware](https://reactrouter.com/how-to/middleware).
-Middleware sets a fresh effect `Context` on a React Router context key each request; the factory's
-`requestContext` reads it and provides those services to the loader/action:
+### Middleware
+
+`makeMiddleware` wraps a [middleware](https://reactrouter.com/how-to/middleware) function the same
+way, with the same `errorHandlers`. Pin it to the route's generated `Route.MiddlewareFunction`.
+Middleware has no separate args-only type, so the full function type is the type argument. If you
+omit the type argument, it defaults to React Router's own `MiddlewareFunction`:
+
+```ts
+import { Effect } from "effect";
+import { makeMiddleware, Respond } from "../route.server.ts";
+import type { Route } from "./+types/profile";
+
+export const middleware: Route.MiddlewareFunction[] = [
+  makeMiddleware<Route.MiddlewareFunction>(({ request }, next) =>
+    Effect.gen(function* () {
+      const user = yield* getUser(request); // can fail with FormError / BadInputError
+      if (!user) yield* Respond.redirect("/login"); // throw → redirect, same as a loader
+      return yield* next(); // run the rest of the chain
+    }),
+  ),
+];
+```
+
+The effect gets `next` as `() => Effect.Effect<Result, FailureResponse>`. It is React Router's own
+`next: () => Promise<Result>`, wrapped. Call it with `yield*` to run the downstream loaders and
+middleware. A downstream throw, such as a nested loader's redirect, becomes a typed failure instead
+of a rejected promise. It flows through the same recover and throw handling as a loader or action.
+
+### Per-request services
+
+Without the adapter, no router middleware runs before React Router. Set the context key in a plain
+React Router middleware. The factory's `requestContext` reads it, and provides those services to the loader or
+action. With the adapter, do not set the key this way, as
+[Per-request services](#per-request-services) tells. This is the pattern without the adapter:
 
 ```ts
 // app/request-context.server.ts
@@ -227,17 +780,13 @@ import { Context } from "effect";
 import { createContext } from "react-router";
 import type { RequestContextKey } from "react-router-effect";
 
-class RequestContext extends Context.Service<
-  RequestContext,
-  {
-    readonly userId: string;
-  }
->()("app/RequestContext") {}
+class RequestContext extends Context.Service<RequestContext, { readonly userId: string }>()(
+  "app/RequestContext",
+) {}
 
-// `requestContext` is a plain React Router context key — `createContext` is RR's own.
 export const requestContext: RequestContextKey<RequestContext> = createContext();
 
-// app/routes/profile.ts — middleware sets a fresh value per request:
+// app/routes/profile.ts: a middleware sets a fresh value for each request.
 export const middleware: Route.MiddlewareFunction[] = [
   ({ context, request }, next) => {
     context.set(requestContext, Context.make(RequestContext, { userId: readUser(request) }));
@@ -245,13 +794,13 @@ export const middleware: Route.MiddlewareFunction[] = [
   },
 ];
 
-// app/route.server.ts — wire the same key into the factory:
+// app/route.server.ts: wire the same key into the factory.
 export const { makeLoader } = makeEffectRouteFactory<DomainErrors>()(() => ({
   runtime: appRuntime,
   requestContext,
 }));
 
-// the loader requires RequestContext directly — no provide, fresh each request:
+// The loader requires RequestContext directly, with a fresh value for each request.
 export const loader = makeLoader(() =>
   Effect.gen(function* () {
     const { userId } = yield* RequestContext;
@@ -260,26 +809,30 @@ export const loader = makeLoader(() =>
 );
 ```
 
-Effects may now require both the runtime's services and the request context's; requiring anything
-else is a compile error. `RequestContextKey<ReqServices>` is a type alias for
-`RouterContext<Context.Context<ReqServices>>` — sugar for annotating the key, nothing more.
-
 ## API
 
-- **`makeEffectRouteFactory<DomainErrors>()((Respond) => ({ errorHandlers?, runtime?, requestContext?, respond? }))`**
-  → `{ makeLoader, makeAction, makeMiddleware, Respond }` (`makeLoader`/`makeAction` are the same
-  wrapper; `makeMiddleware` wraps a `Route.MiddlewareFunction`, defaulting to react-router's own
-  `MiddlewareFunction`). The config is a _builder_ that receives the base `Respond`; all its fields
-  are optional. The returned `Respond` is the base helpers merged with your `respond` extensions
-  (base helpers win). A non-domain error left in a handler's error channel — or a required service
-  that neither the `runtime` nor the `requestContext` provides — is a compile error.
-- **`RequestContextKey<ReqServices>`** — type of the React Router context key for a per-request
-  effect context (`RouterContext<Context.Context<ReqServices>>`).
-- **`Respond`** (returned from the factory) — `early` (recover), `throw`, `redirect`, plus any
-  `respond` helpers you add.
-- **`ReturnableDataError`**, **`ThrowableDataError`**, **`ThrowableRedirectError`** — the library
-  route errors, and **`isRouteError`** to narrow them.
-- **`ErrorHandler<Err>`** — the handler signature type.
+- `makeEffectRouteFactory<DomainErrors>()((Respond) => ({ errorHandlers?, runtime?, requestContext?, respond?, actionMeta? }))`
+  returns `{ makeLoader, makeAction, makeMiddleware, Respond, handlers }`. The config is a builder
+  that receives the base `Respond`. All its fields are optional. The returned `Respond` is the base
+  helpers merged with your `respond` extensions, and the base helpers win. `makeLoader` and
+  `makeAction` are the same wrapper. `makeMiddleware` wraps a `Route.MiddlewareFunction`, and
+  defaults to React Router's own `MiddlewareFunction`.
+- `handlers` (`loader`, `action`, `middleware`, `requestContext`) is the runner that the server
+  adapter applies to every route module.
+- `Respond` has `early` (recover), `throw` and `redirect`, and the `respond` helpers that you add.
+- `ReturnableDataError`, `ThrowableDataError` and `ThrowableRedirectError` are the library route
+  errors. `isRouteError` narrows them.
+- `ErrorHandler<Err>` is the handler signature type.
+- `RequestContextKey<ReqServices>` is the type of the React Router context key for a per-request
+  effect context.
+- `EffectRouteArgs<Args>`, `EffectMiddlewareArgs<Middleware>`, `RouteData<F>` and `Register` are the
+  types of plain Effect routes.
+- `react-router-effect/server` (unstable) exports `ReactRouter`, with `ReactRouter.layer`, `ReactRouter.routes`
+  and the `ReactRouter.Options` type, and `ReactRouterAssets`, with `ReactRouterAssets.layer` and
+  `ReactRouterAssets.ClientBuildError`. It also exports the types `RouteEffectCheck` and
+  `RouteEffectFailures`.
+- `react-router-effect/vite` (unstable) exports `ReactRouterVite.layer` and the `ReactRouterVite.ViteDevServer`
+  type, for development on Node. It needs `@effect/platform-node`.
 
 ## Development