@palamedes/react-router-rsc 1.16.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sebastian Software GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,128 @@
+# @palamedes/react-router-rsc
+
+Experimental request-scoped i18n for React Router RSC Framework Mode Server
+Functions.
+
+React Router marks RSC as experimental and allows breaking changes in patch and
+minor releases. This package is opt-in and intentionally pins its supported
+upstream contract to React Router `8.3.0` and `@vitejs/plugin-rsc` `0.5.34`.
+Review React Router's RSC release notes and rerun the production fixture before
+upgrading either package.
+
+## Installation
+
+```sh
+pnpm add @palamedes/core @palamedes/runtime @palamedes/react-router-rsc
+pnpm add -D @palamedes/cli @palamedes/vite-plugin @react-router/dev@8.3.0 \
+  @vitejs/plugin-rsc@0.5.34 vite react-router@8.3.0
+```
+
+`@palamedes/react-router-rsc` is ESM-only, matching React Router's RSC and Vite
+runtime. Use `import`; CommonJS `require()` is deliberately unsupported.
+
+This adapter supports only RSC Framework Mode. It does not change ordinary
+React Router Framework Mode applications or route actions. RSC Data Mode owns
+its RSC/SSR entry wiring, so it is not supported by this adapter.
+
+## Configure the RSC entry once
+
+Use the React Router RSC Vite plugin and Vite's experimental RSC plugin. React
+Router requires its RSC plugin before `rsc()`:
+
+```ts
+// vite.config.ts
+import { unstable_reactRouterRSC as reactRouterRSC } from "@react-router/dev/vite"
+import { palamedes } from "@palamedes/vite-plugin"
+import rsc from "@vitejs/plugin-rsc"
+import { defineConfig } from "vite"
+
+export default defineConfig({
+  plugins: [palamedes(), reactRouterRSC(), rsc()],
+})
+```
+
+Create `app/entry.rsc.tsx`. The resolver receives React Router's original
+Fetch `Request`, including `headers` and `cookies`; it owns locale negotiation,
+catalog loading, and activation of a **fresh** i18n instance.
+
+```tsx
+import defaultEntry from "@react-router/dev/config/default-rsc-entries/entry.rsc"
+import { createReactRouterRscI18nRequestScope } from "@palamedes/react-router-rsc"
+import type { RouterContextProvider } from "react-router"
+
+import { createRequestI18n } from "./i18n"
+
+const palamedesI18n = createReactRouterRscI18nRequestScope(createRequestI18n)
+
+export default {
+  fetch(request: Request, requestContext?: RouterContextProvider) {
+    return palamedesI18n.run(request, () => defaultEntry.fetch(request, requestContext))
+  },
+}
+
+if (import.meta.hot) {
+  import.meta.hot.accept()
+}
+```
+
+`createRequestI18n()` should load only the active locale before returning:
+
+```ts
+import { createI18n } from "@palamedes/core"
+import { messages as de } from "./locales/de.po"
+import { messages as en } from "./locales/en.po"
+
+export function createRequestI18n(request: Request) {
+  const locale = request.headers.get("cookie")?.includes("locale=de") ? "de" : "en"
+  const i18n = createI18n()
+  i18n.load(locale, locale === "de" ? de : en)
+  i18n.activate(locale)
+  return i18n
+}
+```
+
+The entry wrapper starts before React Router calls
+`unstable_matchRSCServerRequest`. It therefore covers Server Function argument
+and default-parameter evaluation, dispatch, awaited work, RSC rendering,
+automatic post-action revalidation, the SSR pass, and streams created during
+that work. Initialization failures reject before React Router dispatches a
+Server Function, with an error beginning `Palamedes React Router RSC i18n
+initialization failed`.
+
+## Current limits
+
+- The adapter relies on Node's `AsyncLocalStorage` through
+  `@palamedes/runtime/server`. Do not use it in Edge or Worker runtimes unless
+  that runtime's Node-compatible async context propagation has been verified.
+- `scope.run()` restores its caller's store when the default entry settles, but
+  timers, promise continuations, stream callbacks, and other async resources
+  created inside that scope inherit its request locale even if they run later.
+  Work initiated separately without an inherited request context has no active
+  locale; pass explicit data or create an appropriate new scope for it.
+- React Router RSC runs separate RSC and SSR module graphs. The shared
+  Palamedes runtime state and `AsyncLocalStorage` scope preserve locale
+  isolation across both graphs, including concurrent requests.
+- Vite graph splitting currently maps client chunks to active-locale catalog
+  fragments. It does not expose an RSC Server Function module-to-fragment
+  manifest, so this adapter cannot safely lazy-load only evaluated server
+  fragments. Load the active locale's server catalog in the resolver. This is
+  intentionally a documented limitation, not a transform fallback.
+- Do not add the Next.js directive-aware Server Function transform. The RSC
+  entry is earlier than parameter evaluation, while body instrumentation would
+  be too late for eager macro defaults and would need the existing safety
+  diagnostic.
+
+## Validation
+
+`examples/react-router-rsc-cookie` is the production-built browser fixture. It
+calls a real top-level `"use server"` function from a Client Component, proves
+direct/synchronous/asynchronous/cross-module macros and a default parameter,
+then verifies concurrent English and German requests plus revalidation.
+
+```sh
+pnpm verify:react-router-rsc
+```
+
+## License
+
+MIT © 2026 Sebastian Software

package/dist/index.d.mts

@@ -0,0 +1,23 @@
+import { I18nInstance } from '@palamedes/runtime';
+import { ServerI18nScope } from '@palamedes/runtime/server';
+
+/** Resolves a fresh, activated i18n instance from React Router's original Fetch request. */
+type ReactRouterRscI18nResolver<T extends I18nInstance = I18nInstance> = (request: Request) => T | Promise<T>;
+/** Runs the complete React Router RSC entry request inside a request-local i18n scope. */
+type ReactRouterRscI18nRequestScope<T extends I18nInstance = I18nInstance> = {
+    run<Result>(request: Request, dispatch: () => Result | Promise<Result>): Promise<Result>;
+    scope: ServerI18nScope<T>;
+};
+/**
+ * Creates the runtime boundary used by a custom React Router `entry.rsc.tsx`.
+ *
+ * Wrap React Router's default RSC `fetch()` call, not an individual Server
+ * Function. The default entry starts `unstable_matchRSCServerRequest` after
+ * this callback begins, so argument binding, Server Function dispatch, RSC
+ * rendering, automatic revalidation, SSR, and streams created during that work
+ * all inherit the same `AsyncLocalStorage` context.
+ */
+declare function createReactRouterRscI18nRequestScope<T extends I18nInstance = I18nInstance>(resolveI18n: ReactRouterRscI18nResolver<T>): ReactRouterRscI18nRequestScope<T>;
+
+export { createReactRouterRscI18nRequestScope };
+export type { ReactRouterRscI18nRequestScope, ReactRouterRscI18nResolver };

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+import { I18nInstance } from '@palamedes/runtime';
+import { ServerI18nScope } from '@palamedes/runtime/server';
+
+/** Resolves a fresh, activated i18n instance from React Router's original Fetch request. */
+type ReactRouterRscI18nResolver<T extends I18nInstance = I18nInstance> = (request: Request) => T | Promise<T>;
+/** Runs the complete React Router RSC entry request inside a request-local i18n scope. */
+type ReactRouterRscI18nRequestScope<T extends I18nInstance = I18nInstance> = {
+    run<Result>(request: Request, dispatch: () => Result | Promise<Result>): Promise<Result>;
+    scope: ServerI18nScope<T>;
+};
+/**
+ * Creates the runtime boundary used by a custom React Router `entry.rsc.tsx`.
+ *
+ * Wrap React Router's default RSC `fetch()` call, not an individual Server
+ * Function. The default entry starts `unstable_matchRSCServerRequest` after
+ * this callback begins, so argument binding, Server Function dispatch, RSC
+ * rendering, automatic revalidation, SSR, and streams created during that work
+ * all inherit the same `AsyncLocalStorage` context.
+ */
+declare function createReactRouterRscI18nRequestScope<T extends I18nInstance = I18nInstance>(resolveI18n: ReactRouterRscI18nResolver<T>): ReactRouterRscI18nRequestScope<T>;
+
+export { createReactRouterRscI18nRequestScope };
+export type { ReactRouterRscI18nRequestScope, ReactRouterRscI18nResolver };

package/dist/index.mjs

@@ -0,0 +1,22 @@
+import { createServerI18nScope } from '@palamedes/runtime/server';
+
+function createReactRouterRscI18nRequestScope(resolveI18n) {
+  const scope = createServerI18nScope();
+  return {
+    async run(request, dispatch) {
+      let i18n;
+      try {
+        i18n = await resolveI18n(request);
+      } catch (error) {
+        throw new Error(
+          "Palamedes React Router RSC i18n initialization failed before RSC dispatch ran.",
+          { cause: error }
+        );
+      }
+      return await scope.run(i18n, async () => await dispatch());
+    },
+    scope
+  };
+}
+
+export { createReactRouterRscI18nRequestScope };

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@palamedes/react-router-rsc",
+  "version": "1.16.1",
+  "description": "Experimental React Router RSC request-scoped i18n for Palamedes",
+  "homepage": "https://github.com/sebastian-software/palamedes",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sebastian-software/palamedes.git",
+    "directory": "packages/react-router-rsc"
+  },
+  "bugs": "https://github.com/sebastian-software/palamedes/issues",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "README.md",
+    "dist/"
+  ],
+  "engines": {
+    "node": ">=22.22.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@palamedes/runtime": "^1.16.1"
+  },
+  "peerDependencies": {
+    "@react-router/dev": "8.3.0",
+    "@vitejs/plugin-rsc": "0.5.34",
+    "react-router": "8.3.0"
+  },
+  "peerDependenciesMeta": {
+    "@react-router/dev": {
+      "optional": true
+    },
+    "@vitejs/plugin-rsc": {
+      "optional": true
+    },
+    "react-router": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@react-router/dev": "8.3.0",
+    "@types/node": "^24.0.0",
+    "@vitejs/plugin-rsc": "0.5.34",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "react-router": "8.3.0",
+    "react-server-dom-webpack": "^19.2.8",
+    "typescript": "^7.0.2",
+    "unbuild": "^3.6.1",
+    "vite": "^8.2.1",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "unbuild",
+    "test": "pnpm build && pnpm --filter @palamedes/runtime build && vitest run --globals src/index.test.ts && node ./scripts/packed-consumer.test.mjs",
+    "stub": "unbuild --stub"
+  }
+}