#React Server Components (RSC)

React Server Components (RSC) is a new component type that allows components to be rendered in a server environment, bringing better performance and developer experience to modern web applications.

#Core Advantages

• Zero Client JavaScript: Server Components code is not bundled to the client, significantly reducing client bundle size
• Direct Access to Server Resources: Can directly access server resources such as databases, file systems, and internal APIs without additional API layers
• Better Performance: Data fetching is closer to the data source, reducing client-side data waterfalls and improving first-screen load speed
• Automatic Code Splitting: Code splitting based on actual rendered data, not just routes, enabling more granular code optimization
• Higher Cohesion: Logic closely related to data, permissions, caching, etc., can remain in Server Components, improving component cohesion and reducing state lifting and cross-level passing

#Quick Start

1. Ensure React and React DOM are upgraded to version 19 (recommended version 19.2.4 or above)

2. Install the react-server-dom-rspack@0.0.1-beta.0 dependency

npm install react-server-dom-rspack@0.0.1-beta.0

3. Set server.rsc to true:

import { defineConfig } from '@modern-js/app-tools';

export default defineConfig({
  server: {
    rsc: true,
  },
});

#Usage Guide

#Default Behavior

By default, when RSC is enabled, all components in Modern.js are Server Components by default. Server Components allow you to fetch data on the server and render UI. When you need interactivity (such as event handling, state management) or use browser APIs, you can use the "use client" directive to mark components as Client Components.

#Component Type Selection

#When to Use Client Component

When a component needs the following features, you need to use the "use client" directive to mark it as a Client Component:

• Interactivity: Using State and event handlers, such as onClick, onChange, onSubmit
• Lifecycle: Using lifecycle-related hooks, such as useEffect, useLayoutEffect
• Browser APIs: Using browser APIs (such as window, document, localStorage, navigator, etc.)
• Custom Hooks: Using custom hooks, especially those that depend on client-side features

#When to Use Server Component

The following scenarios should use Server Components (default behavior, no additional marking required):

1. Accessing Server Resources: Using APIs available only on the server (such as Node.js APIs, file systems, consul, RPC, etc.)
2. Data Fetching: Fetching data on the server to optimize performance and reduce client requests
3. Security: Accessing private environment variables or API keys, avoiding exposure to the client
4. Reducing Bundle Size: Using large dependency libraries that don't need to be included in the client bundle
5. Static Content: Rendering static or infrequently changing content

#Client Boundary

Once a file is marked with "use client", all other modules it imports (if they haven't been marked with "use client" yet) will also be considered client code and included in the client JavaScript bundle. This is the concept of Client Boundary.

'use client'; // <--- This is where the Client Boundary starts

import { useState } from 'react';
import Button from './Button'; // Button.tsx doesn't have "use client", but will be included in the client bundle
import Tooltip from './Tooltip'; // Tooltip.tsx also doesn't have "use client", and will be included

export default function InteractiveCard() {
  const [isActive, setIsActive] = useState(false);

  return (
    <div onClick={() => setIsActive(!isActive)}>
      <p>Click me!</p>
      <Button />
      <Tooltip text="This is a card" />
    </div>
  );
}

#How to Combine Both Component Types

Server Components and Client Components don't exist in isolation; they need to work together. Remember the following two rules:

#Server Component Can Import Client Component

This is the most common pattern. Your page body is a Server Component responsible for data fetching and layout, while interactive parts are embedded as Client Components.

// Server Component (default, no marking needed)
import CounterButton from './CounterButton'; // This is a Client Component

async function getPageData() {
  // Fetch data on the server
  const res = await fetch('https://api.example.com/data');
  return res.json();
}

export default async function Page() {
  const data = await getPageData();

  return (
    <div>
      <h1>{data.title}</h1> {/* Server-side rendered */}
      <p>This part is static.</p>
      {/* Client Component can be seamlessly embedded in Server Component */}
      <CounterButton />
    </div>
  );
}

'use client'; // Client Component

import { useState } from 'react';

export default function CounterButton() {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(c => c + 1)}>Count: {count}</button>;
}

#Client Component Cannot Directly Import Server Component

This may seem counterintuitive at first. The reason is that Server Component code doesn't exist on the client at all. When a Client Component renders in the browser, it cannot execute a function that only exists on the server.

However, there are two patterns to work around this limitation:

1. Pass Server Component via children Prop

You can pass Server Components as the children Prop to a Client Component. For example, an animated Tabs component where the tab switching logic is client-side, but the content of each tab might be static and fetched from the server.

'use client'; // Client Component

import React, { useState } from 'react';

interface TabsProps {
  tabLabels: string[];
  children: React.ReactNode;
}

export default function Tabs({ tabLabels, children }: TabsProps) {
  const [activeTab, setActiveTab] = useState(0);

  return (
    <div>
      <nav>
        {tabLabels.map((label, index) => (
          <button key={label} onClick={() => setActiveTab(index)}>
            {label}
          </button>
        ))}
      </nav>
      {/* React.Children.toArray ensures only the active child component is rendered */}
      <div>{React.Children.toArray(children)[activeTab]}</div>
    </div>
  );
}

// Server Component (default)
import Tabs from '../components/Tabs';
import Analytics from '../components/Analytics'; // Server Component
import UserSettings from '../components/UserSettings'; // Server Component

export default function DashboardPage() {
  const labels = ['Analytics', 'Settings'];

  return (
    <main>
      <h1>Dashboard</h1>
      {/*
        Here, Tabs is a Client Component (handling interactive logic),
        but Analytics and UserSettings are Server Components rendered on the server,
        passed to the Tabs component as children props.
        This maintains interactivity while maximizing the advantages of server-side rendering.
      */}
      <Tabs tabLabels={labels}>
        <Analytics />
        <UserSettings />
      </Tabs>
    </main>
  );
}

Through this pattern, you can keep components on the server to the maximum extent while maintaining interactivity, achieving optimal performance. This is one of the most powerful composition patterns in RSC.

2. Route Components Can Independently Choose Component Type

Each level of route components (such as layout.tsx, page.tsx) can independently choose to be a Client Component or Server Component:

-routes -
  layout.tsx - // Can be a Client Component
  page.tsx; // Can be a Server Component

For example, if layout.tsx is a Client Component (requiring client-side interactivity), you can still set page.tsx as a Server Component (for data fetching and rendering). This approach provides great flexibility and allows non-RSC projects to gradually migrate to RSC projects.

#Server Component and Data Loader

In RSC projects, you have two ways to fetch data: directly in Server Components, or using Data Loader. Both approaches have their advantages, and you can choose flexibly based on your scenario.

#Comparison of Two Data Fetching Approaches

Generally, we recommend fetching data in Server Components, because waterfall requests have less performance impact on the server, and this approach makes components more cohesive, with data fetching logic and UI rendering in the same place, making it easier to understand and maintain. However, if your page has multiple independent data sources and you want to completely avoid request waterfall issues, Data Loader's parallel execution feature will be more advantageous.

#Data Loader Execution Environment in RSC Projects

In RSC projects, the execution environment of Data Loaders is related to file naming:

• *.data.ts: Executes only on the server, and data can be consumed by both Client Components and Server Components
• *.data.client.ts: Executes only on the client

.
└── routes
    └── user
        ├── page.tsx           # Route component (can be Server or Client Component)
        ├── page.data.ts       # Executes on server, data can be consumed by any component
        └── page.data.client.ts # Executes on client

In Modern.js RSC projects, Server Components can receive data returned by Data Loaders through the loaderData prop:

// Server Component receives loaderData through props
export default function UserPage({ loaderData }: { loaderData: { name: string } }) {
  return <div>Welcome, {loaderData.name}</div>;
}

'use client';
// Client Component can also receive loaderData through props
export default function UserPage({ loaderData }: { loaderData: { name: string } }) {
  return <div>Welcome, {loaderData.name}</div>;
}

#Data Loader Returning Server Component

In Modern.js RSC projects, Data Loaders have a powerful feature: they can return Server Components. This is very helpful for gradual migration, allowing you to render server-generated content in Client Components.

// Server Component defined in data loader file
function UserProfile() {
  return <div>User Profile (Server Rendered)</div>;
}

export const loader = async () => {
  const userData = await fetchUserData();

  return {
    user: userData,
    // Return a Server Component as part of the data
    ProfileComponent: <UserProfile />,
  };
};

'use client';
import { Outlet } from '@modern-js/runtime/router';

export default function UserLayout({
  loaderData,
}: {
  loaderData: { user: any; ProfileComponent: React.ReactNode };
}) {
  const { user, ProfileComponent } = loaderData;

  return (
    <div>
      {/* Directly render Server Component in Client Component */}
      {ProfileComponent}
      <div>User: {user.name}</div>
      <Outlet />
    </div>
  );
}

#CSR Project Migration Guide

Modern.js's RSC capability supports both SSR and CSR projects. For existing CSR projects, if you want to gradually migrate to RSC, we recommend following these steps:

1. Enable RSC Configuration

import { defineConfig } from '@modern-js/app-tools';

export default defineConfig({
  server: {
    rsc: true,
  },
});

2. Mark All Route Components with 'use client'

This ensures that existing components maintain their behavior and continue to run as Client Components.

'use client';

export default function Page() {
  // Existing client-side logic remains unchanged
}

3. Rename All *.data.ts to *.data.client.ts

Since *.data.ts in RSC projects executes on the server by default, to maintain consistency with CSR project behavior (Data Loaders execute on the client), you need to rename the files.

# Before renaming
routes/user/page.data.ts

# After renaming
routes/user/page.data.client.ts

After completing these steps, you can gradually migrate components to Server Components and enjoy the performance benefits of RSC.

#Notes

#Projects Using Streaming SSR

If you're using both Streaming SSR and RSC, in React 19 you need to use use instead of the Await component:

function NonCriticalUI({ p }: { p: Promise<string> }) {
  let value = React.use(p);
  return <h3>Non critical value {value}</h3>;
}

<React.Suspense fallback={<div>Loading...</div>}>
  <NonCriticalUI p={nonCriticalData} />
</React.Suspense>;

#Best Practices

#Data Fetching

1. Whether it's an SSR or RSC project, it's recommended to use the cache function provided by Modern.js for data fetching logic executed on the server by default. This ensures that for each server-side render, no matter how many times the function is called, it will only execute once.

This is also the recommended usage by React.js, which provides the cache function. Modern.js's cache can be considered a superset of it.

import { cache } from '@modern-js/runtime/cache';

const getCriticalCached = cache(getCritical);

• Based on using the cache function, you no longer need to manage server-side state through props, context, etc. We recommend fetching data in the nearest Server Component where it's needed. With the cache function, even if the same function is called multiple times, this makes project state management, business logic, and performance optimization simpler.

// layout.tsx
export default async function Layout() {
  const criticalData = await getCriticalCached();
}

export default async function Page() {
  const criticalData = await getCriticalCached();
}

#Optimal Performance

To leverage the advantages of RSC or Streaming SSR, we need to make as many components as possible flow. A core principle is to make the area wrapped by Suspense as small as possible (this is also one of the reasons we recommend using the cache function).

For Server Components that directly consume data, we recommend wrapping them with Suspense at a higher level:

In this scenario, Server Components are often asynchronous. There's another case where Server Components are synchronous and data is consumed by Client Components, described below.

// profile/components/PostsList.tsx
export default async function PostsList() {
  const posts = await getUserPosts();

  return (
    <ul>
      {posts.map(post => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  );
}

// profile/page.tsx
import { Suspense } from 'react';
import UserInfo from './components/UserInfo';
import PostsList from './components/PostsList';
import PostsSkeleton from './components/PostsSkeleton';

export default function ProfilePage() {
  return (
    <div>
      <UserInfo />

      <hr />

      {/*
        We wrap the slow PostsList in Suspense.
        While PostsList is fetching data, users will see PostsSkeleton.
        Once PostsList data is ready, it will automatically replace the skeleton.
      */}
      <Suspense fallback={<PostsSkeleton />}>
        <PostsList posts={postsPromise} />
      </Suspense>
    </div>
  );
}

There's another scenario where data is consumed in Client Components. In this case, we should avoid using await in Server Components to avoid blocking rendering:

// profile/components/PostsList.tsx
'use client';
export default function PostsList({ postsPromise }) {
  const posts = use(postsPromise);

  return (
    <ul>
      {posts.map(post => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  );
}

// profile/page.tsx
import { Suspense } from 'react';
import UserInfo from './components/UserInfo';
import PostsList from './components/PostsList'; // Now a Client Component
import PostsSkeleton from './components/PostsSkeleton';
import { getUserPosts } from '../lib/data'; // Import data fetching function

// Note: This component is not async
export default function ProfilePage() {
  // 1. Call the data fetching function on the server, but don't await it
  // This immediately returns a Promise
  const postsPromise = getUserPosts();

  return (
    <div>
      <UserInfo />

      <hr />

      {/* 2. Suspense boundary is still required. It will catch
          the Promise thrown by the `use` hook inside PostsList */}
      <Suspense fallback={<PostsSkeleton />}>
        {/* 3. Pass the Promise object itself as a prop to the client component */}
        <PostsList postsPromise={postsPromise} />
      </Suspense>
    </div>
  );
}

#Helmet

When using React 19, you no longer need to use Helmet. We recommend directly using the components provided by React.

#Common Issues

#This entry point is not yet supported outside of experimental channels

The project's bundle has introduced a non-19 React version, commonly seen in monorepos. Please ensure all dependencies use React 19.

#Related Links

• React Server Components Official Documentation
• React Server Functions Documentation
• Data Cache
• Server-Side Rendering (SSR)
• Streaming SSR