React Server Components for Bun (DOM)

Common errors

• Error: This package is experimental and not intended for direct use.

  cause Attempting to import or use `react-server-dom-bun` directly in an application, rather than through a meta-framework.
  fix Integrate React Server Components via a supported meta-framework (e.g., Next.js, Remix) that handles this package internally.

• TypeError: (0, _react_server_dom_bun_server__WEBPACK_IMPORTED_MODULE_0__.renderToReadableStream) is not a function

  cause Incorrect import path for ESM or CJS, or attempting to use a function that is not exported or available in the specific runtime environment or subpath.
  fix Verify the correct import path (`/server` or `/client` subpath) and ensure your bundler/runtime correctly handles ESM imports from `react-server-dom-bun`.

• Invariant Violation: React Server Components require a Bun runtime.

  cause Attempting to run code using `react-server-dom-bun` in a non-Bun environment (e.g., Node.js, Deno).
  fix Ensure your server-side rendering environment is configured to use the Bun runtime for projects leveraging this package.

Warnings

• breaking This package is explicitly marked `0.0.0-experimental`. Its API is highly unstable, subject to frequent breaking changes, and not guaranteed to maintain backwards compatibility.
  Fix: Avoid direct reliance on this package for application-level code. Treat it as an internal implementation detail for meta-frameworks only.
• gotcha The package description explicitly states: 'It is not intended to be imported directly.' Application developers should not use this package, but rather consume its functionality indirectly through a meta-framework that integrates React Server Components.
  Fix: If you are not building a meta-framework, use a framework like Next.js, Remix, or others that provide React Server Components integration out-of-the-box.
• breaking Recent releases include critical security and stability patches, such as 'DoS mitigations to Server Actions' and 'cycle protections'. This indicates that previous experimental versions may have had vulnerabilities or instability, which are actively being addressed.
  Fix: Meta-frameworks should ensure they are using the absolute latest experimental versions of `react-server-dom-bun` to benefit from the most recent security and stability improvements.
• gotcha This package is specifically designed for the Bun runtime. Attempting to use it in Node.js or other JavaScript runtimes is unlikely to work correctly and may lead to runtime errors or unexpected behavior.
  Fix: Ensure your project is configured to run with Bun if you are developing or testing a meta-framework that utilizes `react-server-dom-bun`.

Install

• npm install react-server-dom-bun npm
• yarn add react-server-dom-bun yarn
• pnpm add react-server-dom-bun pnpm

Imports

• renderToReadableStream
  wrong:

  const { renderToReadableStream } = require('react-server-dom-bun/server');

  correct:

  import { renderToReadableStream } from 'react-server-dom-bun/server';

  Used by meta-frameworks to render React Server Components to a stream on the server. The package is not for direct application use.
• decodeReply
  wrong:

  import { decodeReply } from 'react-server-dom-bun';

  correct:

  import { decodeReply } from 'react-server-dom-bun/client';

  Intended for internal use by meta-frameworks to parse client-to-server communication for Server Actions. Note the `/client` subpath.
• createFromReadableStream
  wrong:

  import { createFromReadableStream } from 'react-server-dom-bun/server';

  correct:

  import { createFromReadableStream } from 'react-server-dom-bun/client';

  Used internally by meta-frameworks on the client-side to hydrate React Server Components from a readable stream. Requires the `/client` subpath.

Quickstart

Illustrates how a meta-framework might internally use `renderToReadableStream` to serve a React Server Component with Bun. Not intended for direct app use.

import { renderToReadableStream } from 'react-server-dom-bun/server';

// IMPORTANT: This package is NOT for direct application use.
// This quickstart demonstrates how a meta-framework *might* internally
// use react-server-dom-bun to render a React Server Component.

// Assume a simple Server Component for demonstration
function App() {
  return (
    <html>
      <head>
        <title>Bun RSC Demo</title>
      </head>
      <body>
        <h1>Hello from React Server Component on Bun!</h1>
        <p>Current time: {new Date().toLocaleTimeString()}</p>
      </body>
    </html>
  );
}

// A simplified Bun server implementation for illustration purposes.
// In a real meta-framework, this would be part of a much larger setup.
const server = Bun.serve({
  port: 3000,
  async fetch(req: Request) {
    const url = new URL(req.url);

    if (url.pathname === '/') {
      const stream = await renderToReadableStream(<App />);
      return new Response(stream, {
        headers: { 'Content-Type': 'text/html' }
      });
    }

    // Serve static assets (e.g., a client bundle if one existed)
    if (url.pathname.startsWith('/src')) {
      try {
        const filePath = `.${url.pathname}`;
        return new Response(Bun.file(filePath));
      } catch (error) {
        console.error(`Error serving static file: ${url.pathname}`, error);
        return new Response('Not Found', { status: 404 });
      }
    }

    return new Response('Not Found', { status: 404 });
  },
});

console.log(`Bun Server Components server running on http://localhost:${server.port}`);