feat: add @lazarv/rsc package and migrate RSC serialization to bundler-agnostic API

Author: lazarv

.github/workflows/ci.yml

@@ -48,7 +48,7 @@ jobs:
 
   test-dev-base:
     needs: changed
-    if: contains(needs.changed.outputs.all_changed_files, 'packages/react-server') || contains(needs.changed.outputs.all_changed_files, 'test/') || contains(needs.changed.outputs.all_changed_files, '.github/workflows/ci.yml')
+    if: contains(needs.changed.outputs.all_changed_files, 'packages/react-server') || contains(needs.changed.outputs.all_changed_files, 'packages/rsc') || contains(needs.changed.outputs.all_changed_files, 'test/') || contains(needs.changed.outputs.all_changed_files, '.github/workflows/ci.yml')
     timeout-minutes: 30
     runs-on: ${{ matrix.os }}
     strategy:
@@ -81,7 +81,7 @@ jobs:
 
   test-build-start-base:
     needs: changed
-    if: contains(needs.changed.outputs.all_changed_files, 'packages/react-server') || contains(needs.changed.outputs.all_changed_files, 'test/') || contains(needs.changed.outputs.all_changed_files, '.github/workflows/ci.yml')
+    if: contains(needs.changed.outputs.all_changed_files, 'packages/react-server') || contains(needs.changed.outputs.all_changed_files, 'packages/rsc') || contains(needs.changed.outputs.all_changed_files, 'test/') || contains(needs.changed.outputs.all_changed_files, '.github/workflows/ci.yml')
     timeout-minutes: 30
     runs-on: ${{ matrix.os }}
     strategy:
@@ -114,7 +114,7 @@ jobs:
 
   test-build-start-base-edge:
     needs: changed
-    if: contains(needs.changed.outputs.all_changed_files, 'packages/react-server') || contains(needs.changed.outputs.all_changed_files, 'test/') || contains(needs.changed.outputs.all_changed_files, '.github/workflows/ci.yml')
+    if: contains(needs.changed.outputs.all_changed_files, 'packages/react-server') || contains(needs.changed.outputs.all_changed_files, 'packages/rsc') || contains(needs.changed.outputs.all_changed_files, 'test/') || contains(needs.changed.outputs.all_changed_files, '.github/workflows/ci.yml')
     timeout-minutes: 30
     runs-on: ${{ matrix.os }}
     strategy:
@@ -149,7 +149,7 @@ jobs:
 
   test-build-start-base-edge-entry:
     needs: changed
-    if: contains(needs.changed.outputs.all_changed_files, 'packages/react-server') || contains(needs.changed.outputs.all_changed_files, 'test/') || contains(needs.changed.outputs.all_changed_files, '.github/workflows/ci.yml')
+    if: contains(needs.changed.outputs.all_changed_files, 'packages/react-server') || contains(needs.changed.outputs.all_changed_files, 'packages/rsc') || contains(needs.changed.outputs.all_changed_files, 'test/') || contains(needs.changed.outputs.all_changed_files, '.github/workflows/ci.yml')
     timeout-minutes: 30
     runs-on: ${{ matrix.os }}
     strategy:
@@ -184,7 +184,7 @@ jobs:
 
   test-dev-apps:
     needs: changed
-    if: contains(needs.changed.outputs.all_changed_files, 'packages/react-server') || contains(needs.changed.outputs.all_changed_files, 'test/') || contains(needs.changed.outputs.all_changed_files, '.github/workflows/ci.yml')
+    if: contains(needs.changed.outputs.all_changed_files, 'packages/react-server') || contains(needs.changed.outputs.all_changed_files, 'packages/rsc') || contains(needs.changed.outputs.all_changed_files, 'test/') || contains(needs.changed.outputs.all_changed_files, '.github/workflows/ci.yml')
     timeout-minutes: 30
     runs-on: ${{ matrix.os }}
     strategy:
@@ -217,7 +217,7 @@ jobs:
 
   test-build-start-apps:
     needs: changed
-    if: contains(needs.changed.outputs.all_changed_files, 'packages/react-server') || contains(needs.changed.outputs.all_changed_files, 'test/') || contains(needs.changed.outputs.all_changed_files, '.github/workflows/ci.yml')
+    if: contains(needs.changed.outputs.all_changed_files, 'packages/react-server') || contains(needs.changed.outputs.all_changed_files, 'packages/rsc') || contains(needs.changed.outputs.all_changed_files, 'test/') || contains(needs.changed.outputs.all_changed_files, '.github/workflows/ci.yml')
     timeout-minutes: 30
     runs-on: ${{ matrix.os }}
     strategy:
@@ -250,7 +250,7 @@ jobs:
 
   test-build-start-apps-edge:
     needs: changed
-    if: contains(needs.changed.outputs.all_changed_files, 'packages/react-server') || contains(needs.changed.outputs.all_changed_files, 'test/') || contains(needs.changed.outputs.all_changed_files, '.github/workflows/ci.yml')
+    if: contains(needs.changed.outputs.all_changed_files, 'packages/react-server') || contains(needs.changed.outputs.all_changed_files, 'packages/rsc') || contains(needs.changed.outputs.all_changed_files, 'test/') || contains(needs.changed.outputs.all_changed_files, '.github/workflows/ci.yml')
     timeout-minutes: 30
     runs-on: ${{ matrix.os }}
     strategy:
@@ -285,7 +285,7 @@ jobs:
 
   test-build-start-apps-edge-entry:
     needs: changed
-    if: contains(needs.changed.outputs.all_changed_files, 'packages/react-server') || contains(needs.changed.outputs.all_changed_files, 'test/') || contains(needs.changed.outputs.all_changed_files, '.github/workflows/ci.yml')
+    if: contains(needs.changed.outputs.all_changed_files, 'packages/react-server') || contains(needs.changed.outputs.all_changed_files, 'packages/rsc') || contains(needs.changed.outputs.all_changed_files, 'test/') || contains(needs.changed.outputs.all_changed_files, '.github/workflows/ci.yml')
     timeout-minutes: 30
     runs-on: ${{ matrix.os }}
     strategy:
@@ -318,6 +318,43 @@ jobs:
         env:
           EDGE_ENTRY: "1"
 
+  test-rsc:
+    needs: changed
+    if: contains(needs.changed.outputs.all_changed_files, 'packages/rsc') || contains(needs.changed.outputs.all_changed_files, '.github/workflows/ci.yml')
+    timeout-minutes: 10
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+        node_version: [20, 22, 24]
+        include:
+          - os: macos-latest
+            node_version: 24
+          - os: windows-latest
+            node_version: 24
+      fail-fast: false
+
+    name: "Test rsc 🧪 node.js v${{ matrix.node_version }} on ${{ matrix.os }}"
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - uses: ./.github/workflows/actions/common-setup
+        with:
+          node_version: ${{ matrix.node_version }}
+
+      - name: Test @lazarv/rsc with coverage
+        working-directory: ./packages/rsc
+        run: pnpm test:coverage
+
+      - name: Upload coverage report
+        if: always() && matrix.os == 'ubuntu-latest' && matrix.node_version == 24
+        uses: actions/upload-artifact@v4
+        with:
+          name: rsc-coverage-report
+          path: packages/rsc/coverage/
+          retention-days: 30
+
   lint:
     timeout-minutes: 10
     runs-on: ubuntu-latest

.github/workflows/publish-commit.yml

@@ -96,4 +96,4 @@ jobs:
         run: pnpm install
 
       - name: Publish packages
-        run: pnpm dlx pkg-pr-new@0.0 publish --compact --pnpm ./packages/react-server ./packages/create-react-server
+        run: pnpm dlx pkg-pr-new@0.0 publish --compact --pnpm ./packages/rsc ./packages/react-server ./packages/create-react-server

.github/workflows/release-experimental.yml

@@ -66,9 +66,37 @@ jobs:
           VERSION="0.0.0-experimental-$(git rev-parse --short HEAD)-$(date +'%Y%m%d')-$(openssl rand -hex 4)"
           echo "VERSION=$VERSION" >> $GITHUB_ENV
 
+      - name: Prepare @lazarv/rsc
+        id: prepare-rsc
+        if: contains(needs.changed.outputs.all_changed_files, 'packages/rsc')
+        working-directory: ./packages/rsc
+        run: |
+          jq --arg new_version "${{ env.VERSION }}" '.version = $new_version' package.json > tmp.json && mv tmp.json package.json
+
+      - name: Publish @lazarv/rsc
+        id: publish-rsc
+        if: steps.prepare-rsc.outcome == 'success'
+        working-directory: ./packages/rsc
+        run: pnpm publish --provenance --access=public --tag=latest
+
+      - name: Update @lazarv/react-server dependency on @lazarv/rsc
+        if: steps.publish-rsc.outcome == 'success'
+        working-directory: ./packages/react-server
+        run: |
+          jq --arg new_version "${{ env.VERSION }}" '.dependencies["@lazarv/rsc"] = $new_version' package.json > tmp.json && mv tmp.json package.json
+
+      - name: Get latest @lazarv/rsc version for @lazarv/react-server
+        if: contains(needs.changed.outputs.all_changed_files, 'packages/react-server') && steps.publish-rsc.outcome != 'success'
+        working-directory: ./packages/react-server
+        run: |
+          RSC_VERSION=$(npm view @lazarv/rsc version 2>/dev/null || echo "")
+          if [ -n "$RSC_VERSION" ]; then
+            jq --arg new_version "$RSC_VERSION" '.dependencies["@lazarv/rsc"] = $new_version' package.json > tmp.json && mv tmp.json package.json
+          fi
+
       - name: Prepare @lazarv/react-server
         id: prepare-react-server
-        if: contains(needs.changed.outputs.all_changed_files, 'packages/react-server')
+        if: contains(needs.changed.outputs.all_changed_files, 'packages/react-server') || steps.publish-rsc.outcome == 'success'
         working-directory: ./packages/react-server
         run: |
           jq --arg new_version "${{ env.VERSION }}" '.version = $new_version' package.json > tmp.json && mv tmp.json package.json
@@ -80,7 +108,7 @@ jobs:
         run: pnpm publish --provenance --access=public --tag=latest
 
       - name: Create release
-        if: steps.publish-react-server.outcome == 'success'
+        if: steps.publish-react-server.outcome == 'success' || steps.publish-rsc.outcome == 'success'
         env:
           GH_TOKEN: ${{ github.token }}
         run: |

packages/react-server/cache/client.mjs

@@ -24,7 +24,7 @@ export async function useCache(
     cacheDrivers.set(provider.name, provider.driver);
     cacheInstances.set(
       provider.name,
-      new StorageCache(provider.driver, provider.options)
+      new StorageCache(provider.driver, provider.options, provider.serializer)
     );
   }
   const cache = cacheInstances.get(provider.name);

packages/react-server/cache/rsc.mjs

@@ -1,15 +1,30 @@
-import { createFromReadableStream } from "react-server-dom-webpack/client.edge";
-import { renderToReadableStream } from "react-server-dom-webpack/server.edge";
+import { createFromReadableStream } from "@lazarv/rsc/client";
+import { renderToReadableStream } from "@lazarv/rsc/server";
 
 import { concat, copyBytesFrom } from "../lib/sys.mjs";
 
-export function toBuffer(model, options = {}) {
-  return new Promise(async (resolve, reject) => {
+async function getModuleResolver() {
+  try {
     const { clientReferenceMap } =
       await import("@lazarv/react-server/dist/server/client-reference-map");
     const map = clientReferenceMap();
-    const stream = renderToReadableStream(model, map, {
+    return {
+      resolveClientReference(value) {
+        return map[value.$$id];
+      },
+    };
+  } catch {
+    // Browser environment — no client reference map available
+    return undefined;
+  }
+}
+
+export function toBuffer(model, options = {}) {
+  return new Promise(async (resolve, reject) => {
+    const moduleResolver = await getModuleResolver();
+    const stream = renderToReadableStream(model, {
       ...options,
+      ...(moduleResolver ? { moduleResolver } : {}),
       onError(error) {
         reject(error);
       },
@@ -25,82 +40,26 @@ export function toBuffer(model, options = {}) {
 }
 
 export async function toStream(model, options = {}) {
-  const { clientReferenceMap } =
-    await import("@lazarv/react-server/dist/server/client-reference-map");
-  const map = clientReferenceMap();
-  return renderToReadableStream(model, map, options);
-}
-
-function createManifest() {
-  return {
-    serverConsumerManifest: {
-      serverModuleMap: new Proxy(
-        {},
-        {
-          get(target, prop) {
-            if (!target[prop]) {
-              const [id, name] = prop.split("#");
-              target[prop] = {
-                id: `react-server-reference:${id}#${name}`,
-                name,
-                chunks: [],
-              };
-            }
-            return target[prop];
-          },
-        }
-      ),
-      moduleMap: new Proxy(
-        {},
-        {
-          get(target, id) {
-            if (!target[id]) {
-              target[id] = new Proxy(
-                {},
-                {
-                  get(target, name) {
-                    if (!target[name]) {
-                      target[name] = {
-                        id: `react-client-reference:${id}::${name}`,
-                        name,
-                        chunks: [],
-                        async: true,
-                      };
-                    }
-                    return target[name];
-                  },
-                }
-              );
-            }
-            return target[id];
-          },
-        }
-      ),
-    },
-  };
+  const moduleResolver = await getModuleResolver();
+  return renderToReadableStream(model, {
+    ...options,
+    ...(moduleResolver ? { moduleResolver } : {}),
+  });
 }
 
 export function fromBuffer(payload, options = {}) {
-  const Component = createFromReadableStream(
+  return createFromReadableStream(
     new ReadableStream({
       type: "bytes",
       start(controller) {
         controller.enqueue(new Uint8Array(payload));
         controller.close();
       },
     }),
-    {
-      ...createManifest(),
-      ...options,
-    }
+    options
   );
-
-  return Component;
 }
 
 export function fromStream(stream, options = {}) {
-  return createFromReadableStream(stream, {
-    ...createManifest(),
-    ...options,
-  });
+  return createFromReadableStream(stream, options);
 }

packages/react-server/cache/storage-cache.mjs

@@ -6,6 +6,50 @@ import { createStorage } from "unstorage";
 
 import { CACHE_MISS } from "../server/symbols.mjs";
 
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+
+function encodeBytes(bytes, encoding = "base64") {
+  if (typeof Buffer !== "undefined" && typeof Buffer.from === "function") {
+    return Buffer.from(bytes).toString(encoding);
+  }
+  if (encoding === "base64") {
+    let binary = "";
+    for (let i = 0; i < bytes.byteLength; i++) {
+      binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary);
+  }
+  if (encoding === "hex") {
+    return Array.from(bytes)
+      .map((b) => b.toString(16).padStart(2, "0"))
+      .join("");
+  }
+  return textDecoder.decode(bytes);
+}
+
+function decodeBytes(str, encoding = "base64") {
+  if (typeof Buffer !== "undefined" && typeof Buffer.from === "function") {
+    return new Uint8Array(Buffer.from(str, encoding));
+  }
+  if (encoding === "base64") {
+    const binary = atob(str);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+      bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+  }
+  if (encoding === "hex") {
+    const bytes = new Uint8Array(str.length / 2);
+    for (let i = 0; i < str.length; i += 2) {
+      bytes[i / 2] = parseInt(str.substring(i, i + 2), 16);
+    }
+    return bytes;
+  }
+  return textEncoder.encode(str);
+}
+
 export default class StorageCache {
   constructor(storageDriver, options, serializer) {
     this.index = new Map();
@@ -100,9 +144,10 @@ export default class StorageCache {
 
     const timestamp = Date.now();
     const [type, encoding] = this.type?.split(";")?.map((s) => s.trim()) ?? [];
+    const resolvedEncoding = encoding ?? this.encoding ?? "base64";
     const data =
       type === "rsc" && this.serializer
-        ? `data:text/x-component;${encoding ?? this.encoding ?? "base64"},${Buffer.from(await this.serializer.toBuffer(value)).toString(encoding ?? this.encoding ?? "base64")}`
+        ? `data:text/x-component;${resolvedEncoding},${encodeBytes(new Uint8Array(await this.serializer.toBuffer(value)), resolvedEncoding)}`
         : await value;
     const payload = {
       data,
@@ -210,14 +255,12 @@ export default class StorageCache {
 
   async deserializeValue(data) {
     const [type, encoding] = this.type?.split(";")?.map((s) => s.trim()) ?? [];
+    const resolvedEncoding = encoding ?? this.encoding ?? "base64";
     return type === "rsc" && this.serializer
       ? await this.serializer.fromBuffer(
-          Buffer.from(
-            data.replace(
-              `data:text/x-component;${encoding ?? this.encoding ?? "base64"},`,
-              ""
-            ),
-            encoding ?? this.encoding ?? "base64"
+          decodeBytes(
+            data.replace(`data:text/x-component;${resolvedEncoding},`, ""),
+            resolvedEncoding
           )
         )
       : data;