react-router-effect 2.1.0 → 2.2.0

package/README.md

@@ -1,7 +1,7 @@
 # react-router-effect
 
 Serve a [React Router](https://reactrouter.com) framework-mode app from [Effect](https://effect.website)'s
-Node HTTP server, and write its loaders, actions and middleware as Effects.
+HTTP router, on Node or on Cloudflare Workers. Write its loaders, actions and middleware as Effects.
 
 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
@@ -24,17 +24,21 @@ If your app does not serve React Router from an Effect HTTP server, read
 
 ## Install
 
+On Node:
+
 ```bash
-vp add react-router-effect effect @effect/platform-node
+vp add react-router-effect effect react-router @effect/platform-node
 ```
 
-`effect`, `@effect/platform-node` and `react-router` are peer dependencies. The library requires
-Effect 4.1 (`effect@^4.1.0`). Only `react-router-effect/vite` imports `@effect/platform-node`.
+`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).
 
 ## Get started
 
-[`examples/basic`](examples/basic) is an app with these files. It also has development with
-Vite, tests against the production build, and benchmarks.
+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.
 
 ### 1. Create the route factory
 
@@ -65,51 +69,59 @@ export const { Respond } = routeFactory;
 
 ### 2. Create the server app
 
-`ReactRouterHttp.make` returns an Effect that makes an Effect HTTP app. The app runs React Router
-with your route factory.
+`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 { ReactRouterHttp } from "react-router-effect/server";
+import { Layer } from "effect";
+import { ReactRouter, ReactRouterAssets } from "react-router-effect/server";
 
 import { routeFactory } from "../app/lib/route-factory.server";
 
-export const reactRouterApp = ReactRouterHttp.make({
-  build: () => import("virtual:react-router/server-build"),
-  factory: routeFactory,
-  clientAssets: true, // serves build/client in production
-});
+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
 
-The server makes the app once, when it starts, and serves it with its own Effect HTTP server and its
-own middleware. In production, making the app loads the build and reads the client build. If the
-server cannot read the client build, it fails to start, and the error names the resolved directory.
+`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.
 
-```ts
-// server/main.ts
+```js
+// server.js
 import { createServer } from "node:http";
 
-import { NodeHttpServer, NodeRuntime } from "@effect/platform-node";
-import { Effect, Layer } from "effect";
-import { HttpMiddleware, HttpServer } from "effect/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 { reactRouterApp } from "./app";
+import { App } from "./build/server/index.js";
 
-Layer.unwrap(
-  Effect.map(reactRouterApp, (app) => HttpServer.serve(app, HttpMiddleware.logger)),
-).pipe(
-  Layer.provide(NodeHttpServer.layer(() => createServer(), { port: 3000 })),
-  Layer.launch,
-  NodeRuntime.runMain,
+NodeRuntime.runMain(
+  Layer.launch(
+    HttpRouter.serve(App).pipe(
+      Layer.provide(NodeHttpServer.layer(() => createServer(), { port: 3000 })),
+    ),
+  ),
 );
 ```
 
 ### 4. Build the server
 
-Make `server/main.ts` the entry of the server build. The build then contains your server, and
-`react-router build` writes it to `build/server/index.js`.
+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
@@ -118,16 +130,17 @@ import { defineConfig } from "vite";
 
 export default defineConfig({
   plugins: [reactRouter()],
-  environments: { ssr: { build: { rollupOptions: { input: "./server/main.ts" } } } },
+  environments: { ssr: { build: { rollupOptions: { input: "./server/app.ts" } } } },
 });
 ```
 
 ```bash
 react-router build
-NODE_ENV=production node build/server/index.js
+NODE_ENV=production node server.js   # React's server build reads NODE_ENV
 ```
 
-For development, read [Development with Vite](#development-with-vite).
+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
 
@@ -164,6 +177,28 @@ middleware](#plain-effect-loaders-actions-and-middleware) explains why. A route
 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:
@@ -255,19 +290,37 @@ makeEffectRouteFactory()(() => ({}));
 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.
 
-The adapter option `requestContext` builds the services before React Router runs. Every middleware,
-loader and action sees them, and no middleware has to set them:
+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
-ReactRouterHttp.make({
-  build: () => import("virtual:react-router/server-build"),
-  factory: routeFactory,
-  requestContext: (request) =>
-    Context.make(RequestInfo, {
-      id: request.headers.get("x-request-id") ?? crypto.randomUUID(),
-      startedAt: Date.now(),
+// 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,
     }),
-});
+  ),
+);
 ```
 
 A [middleware](https://reactrouter.com/how-to/middleware) can also provide services. An effect
@@ -308,14 +361,24 @@ A route Effect can then require the runtime's services and the request's service
 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 Node HTTP server
-(`@effect/platform-node`). 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 adapter is an
-Effect HTTP app like any other. The app serves it with its own Effect HTTP server and keeps its own
-middleware: logging, compression, tracing, proxies and other routes.
+`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
@@ -325,66 +388,165 @@ sees the build, the adapter runs every loader, action and middleware through you
   Its failures go through the factory's error handlers.
 - Any other route function passes through. Promise loaders and `makeLoader` wrappers keep working.
 
-The options:
-
-- `build` is the server build, or a function that loads it.
-- `factory` is the route factory.
-- `requestContext: (request) => Context` builds the request's services before React Router runs.
-- `clientAssets: true` serves the client build, `build.assetsBuildDirectory` under
-  `build.publicPath`, before React Router. Files under `assets/` use a content hash in their name,
-  and the adapter caches them for a year as immutable. It caches other files for an hour. It serves
-  the files as `express.static` does. A directory serves its index file, such as a prerendered page.
-  A directory path without the trailing slash redirects to the path with it. It does not serve
-  dotfiles, and a request it does not serve goes to React Router. Like `express.static`, it looks up
-  each GET and HEAD request in the file system. It serves only a build that it loads once: in
-  production mode, or a build value. It never serves a development build, where Vite serves the
-  client. `assetsBuildDirectory` is relative to the working directory of the server. If the adapter
-  cannot read it, making the app fails with a `ClientBuildError` that names the resolved directory.
-  It needs the platform's file system, which `NodeHttpServer.layer` provides.
-- `mode` is React Router's server mode. The default is `process.env.NODE_ENV`. In production the
-  adapter loads the build once.
-
-The Web request comes from `HttpServerRequest.toWeb`, body included. Effect's stream sends the
-`100 Continue` when React Router reads the body of a request that sends `Expect: 100-continue`.
-
-The request URL is the one Effect derives from the request. An app behind a proxy applies the
-headers it trusts in its own middleware, with `request.modify` or `HttpMiddleware.xForwardedHeaders`.
-The request signal aborts only if the response ends early. That happens when the client leaves while
-React Router runs, or while the body streams. A completed response never aborts it.
+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`.
 
-React Router logs and answers the errors of route code. If the adapter's own steps fail, for example
-a `requestContext` that throws, the adapter logs the error with `Effect.logError` and answers 500.
-The log goes to the loggers of the app's Effect runtime.
+```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;
+    }),
+});
+```
 
-### Development with Vite
+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.
 
-In development Vite serves the client. `react-router-effect/vite` runs Vite's middleware in front of
-the app, on Effect's Node HTTP server:
+### Routes and middleware
 
-```ts
-import { ReactRouterVite } from "react-router-effect/vite";
+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.
 
-const vite = await createServer({ server: { middlewareMode: true } });
-HttpServer.serve(Effect.flatten(reactRouterApp).pipe(ReactRouterVite.devMiddleware(vite)));
+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,
+    }),
+  ),
+);
 ```
 
-In development, making the app does nothing but return it, so the server can make it for each
-request. Load the module that calls `ReactRouterHttp.make` through `vite.ssrLoadModule`. Then the route
-modules, the factory and the adapter share Vite's module graph. The example's `server.js` and
-`server/main.ts` do this.
+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. Effect HTTP middleware around the
-adapter can read and change them like any other cookie. A response that replaces React Router's has
-none of them.
+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`. If one response sets the
-same cookie name twice, for example to expire it on one path and set it on another, only the last
-one is sent.
+`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
 
@@ -401,10 +563,15 @@ return new Response(Readable.toWeb(file) as ReadableStream, {
 
 ### Tracing
 
-When the request has a server span, the adapter traces React Router. The span comes from
-`HttpMiddleware.tracer` with a tracer that exports spans, such as `OtelTracer`. 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`:
+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
@@ -423,6 +590,12 @@ instrumentation traces nest there too, such as a database driver that a promise
 Without a server span, or with Effect's native tracer, whose spans go nowhere, the adapter adds no
 spans and no cost.
 
+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.
+
 ## Route functions
 
 ### Plain Effect loaders, actions and middleware
@@ -510,8 +683,10 @@ Type '{}' is missing the following properties from type ...:
 
 ### Requirements and limits
 
-- Effect 4.1 or later, React Router 8.3 or later for the adapter, and `skipLibCheck`. The brand
-  augments `Effect`, and TypeScript cannot test the variance annotations of that augmentation.
+- 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.
 
@@ -594,9 +769,10 @@ of a rejected promise. It flows through the same recover and throw handling as a
 
 ### Per-request services
 
-Without the adapter there is no `requestContext` option. 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:
+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
@@ -651,10 +827,12 @@ export const loader = makeLoader(() =>
   effect context.
 - `EffectRouteArgs<Args>`, `EffectMiddlewareArgs<Middleware>`, `RouteData<F>` and `Register` are the
   types of plain Effect routes.
-- `react-router-effect/server` exports `ReactRouterHttp.make`, and the types `RouteEffectCheck` and
+- `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` exports `ReactRouterVite.devMiddleware`, for development. It needs
-  `@effect/platform-node`.
+- `react-router-effect/vite` (unstable) exports `ReactRouterVite.layer` and the `ReactRouterVite.ViteDevServer`
+  type, for development on Node. It needs `@effect/platform-node`.
 
 ## Development
 

package/dist/index.d.mts

@@ -1,2 +1,2 @@
-import { C as ReturnableDataError, D as WithActionMeta, E as isRouteError, O as actionMetaKey, S as AnyRouteError, T as ThrowableRedirectError, a as RegisteredMeta, b as RouteResult, c as Serialize, d as EffectNext, f as ErrorHandler, i as Register, l as ActionMetaArgs, n as EffectData, o as RegisteredRecover, p as FactoryTypes, r as EffectRouteArgs, s as RouteData, t as BrandData, u as EffectMiddlewareArgs, v as RequestContextKey, w as ThrowableDataError, x as makeEffectRouteFactory, y as RouteHandlers } from "./route-data-MgSnnR33.mjs";
+import { C as ReturnableDataError, D as WithActionMeta, E as isRouteError, O as actionMetaKey, S as AnyRouteError, T as ThrowableRedirectError, a as RegisteredMeta, b as RouteResult, c as Serialize, d as EffectNext, f as ErrorHandler, i as Register, l as ActionMetaArgs, n as EffectData, o as RegisteredRecover, p as FactoryTypes, r as EffectRouteArgs, s as RouteData, t as BrandData, u as EffectMiddlewareArgs, v as RequestContextKey, w as ThrowableDataError, x as makeEffectRouteFactory, y as RouteHandlers } from "./route-data-CWBxnNAA.mjs";
 export { type ActionMetaArgs, type AnyRouteError, type BrandData, type EffectData, type EffectMiddlewareArgs, type EffectNext, type EffectRouteArgs, type ErrorHandler, type FactoryTypes, type Register, type RegisteredMeta, type RegisteredRecover, type RequestContextKey, ReturnableDataError, type RouteData, type RouteHandlers, type RouteResult, type Serialize, ThrowableDataError, ThrowableRedirectError, type WithActionMeta, actionMetaKey, isRouteError, makeEffectRouteFactory };

package/dist/index.mjs

@@ -187,7 +187,8 @@ function makeEffectRouteFactory() {
 			...Respond
 		};
 		const userHandlers = config.errorHandlers ?? {};
-		const isUserError = (e) => typeof e === "object" && e !== null && "_tag" in e && e._tag in userHandlers;
+		/** The tags of the registered domain errors. */
+		const userTags = Object.keys(userHandlers);
 		/**
 		* Runs a handler's effect to completion: dispatches its whole error channel
 		* (registered domain errors, library route errors, respondables, or the 500
@@ -197,8 +198,8 @@ function makeEffectRouteFactory() {
 		*/
 		function runProgram(effect, context, signal) {
 			const program = effect.pipe(Effect.catchIf((_e) => true, (e) => {
-				if (isUserError(e)) {
-					const out = userHandlers[e._tag](e);
+				for (const tag of userTags) if (Predicate.isTagged(e, tag)) {
+					const out = userHandlers[tag](e);
 					return isRouteError(out) ? processRouteError(out) : out;
 				}
 				if (isRouteError(e)) return processRouteError(e);

package/dist/{route-data-MgSnnR33.d.mts → route-data-CWBxnNAA.d.mts}

@@ -209,6 +209,12 @@ type Diagnose<E, R, DomainError, Provided, AlsoHandled = never> = IsAny<E> exten
  * it in middleware and pass it to the factory's `requestContext` - the runner
  * reads it on every request and provides its services to the loader/action.
  *
+ * With the server adapter, do not set it to a new context. The adapter sets it
+ * to the request fiber's context before React Router runs, and a new context
+ * replaces those services, such as `HttpServerRequest` and the server span.
+ * Provide request services with a router middleware on `ReactRouter.routes`.
+ * The middleware below is for an app without the adapter.
+ *
  * It's just a `RouterContext`; create one with React Router's `createContext`:
  *
  * ```ts
@@ -222,7 +228,7 @@ type Diagnose<E, R, DomainError, Provided, AlsoHandled = never> = IsAny<E> exten
  *
  * export const requestContext: RequestContextKey<RequestContext> = createContext();
  *
- * // middleware:
+ * // middleware, in an app without the server adapter:
  * export const middleware: Route.MiddlewareFunction[] = [
  *   ({ context, request }, next) => {
  *     context.set(requestContext, Context.make(RequestContext, { userId: readUser(request) }));