Component Architecture

1.1. The RSC Mental Model

Think of Server Components as the backbone of your application that orchestrates data fetching, layouts, and non-interactive UI (rendering pure HTML with zero client JavaScript). Client Components act as interactive "islands" or leaves embedded inside the server tree.

The server streams HTML and React Flight JSON representations across an open HTTP stream. The browser consumes this stream without ever downloading the JavaScript source code of your Server Components.

2.1. Capabilities & Backend Access

• Direct Async Execution: Server Components can be async functions. You can await database queries, microservices, or files directly inside the component body.
• Zero Client Bundle Impact: Large dependencies imported into Server Components (e.g., Markdown parsers, SQL drivers, encryption packages) are never downloaded or executed by the browser.
• Secure Secret Access: Database credentials, private API keys, and environment variables stay strictly on the server without risk of client exposure.
• Automatic Streaming with <Suspense>: When slow asynchronous operations are wrapped in React <Suspense>, the layout shell and fallback UI can be delivered immediately without waiting for slow queries, while data streams progressively into the HTTP response.

// src/users/page.tsx (Server Component by default)
import { getContext } from "dinou";
import { db } from "@/lib/db"; // Never bundled to the client!

export default async function UsersPage() {
  // Direct backend query without an intermediary REST API
  const users = await db.user.findMany({ take: 10 });

  return (
    <main className="p-8 max-w-4xl mx-auto">
      <h1 className="text-2xl font-bold">Registered Users</h1>
      <ul className="mt-4 divide-y">
        {users.map((user) => (
          <li key={user.id} className="py-2 flex justify-between">
            <span>{user.name}</span>
            <span className="text-xs font-mono text-muted-foreground">{user.email}</span>
          </li>
        ))}
      </ul>
    </main>
  );
}

// src/users/page.tsx - Non-blocking streaming layout
import { Suspense } from "react";
import { db } from "@/lib/db";
import { UsersSkeleton } from "./skeleton";

export default function UsersPage() {
  return (
    <main className="p-8 max-w-4xl mx-auto">
      {/* 1. The outer shell is sent immediately (instant TTFB) */}
      <h1 className="text-2xl font-bold">Registered Users</h1>

      {/* 2. Displays fallback while the child query resolves */}
      <Suspense fallback={<UsersSkeleton />}>
        <UsersList />
      </Suspense>
    </main>
  );
}

// Child component handles the async query independently
async function UsersList() {
  const users = await db.user.findMany({ take: 10 });
  return (
    <ul className="mt-4 divide-y">
      {users.map((u) => (
        <li key={u.id} className="py-2 flex justify-between">
          <span>{u.name}</span>
          <span className="text-xs font-mono text-muted-foreground">{u.email}</span>
        </li>
      ))}
    </ul>
  );
}

2.2. Constraints & Limitations

Because Server Components do not execute in the browser, they cannot use browser-specific or client-interactive features:

• Cannot use state or lifecycle hooks (useState, useEffect, useReducer).
• Cannot add interactive client DOM event listeners (e.g. onClick, onChange, onSubmit).
• Cannot access browser-only globals (window, document, localStorage, navigator).
• Cannot consume (read) React Context with useContext() or use(Context). (While Server Components can render <Context> providers for client children, they cannot read context values themselves).

3.1. Interactivity & Browser APIs

Client Components have complete access to the client-side React ecosystem:

• Full state management with useState, useReducer, and React 19 useActionState.
• Side effects, timers, and DOM subscriptions via useEffect and useLayoutEffect.
• DOM event handling (clicks, hovers, drags, keystrokes, form submissions).
• Browser Web APIs (localStorage, Geolocation, IntersectionObserver, Audio).
• Consuming React Context providers created on the client.

3.2. Server Pre-Rendering Notice

A common point of confusion is assuming Client Components execute exclusively in the browser. Client Components are pre-rendered on the server to HTML during initial page load to ensure fast First Contentful Paint (FCP) and SEO indexing.

4.1. Establishing Module Boundaries

The directive is not a runtime function call—it is an instruction to the bundler (esbuild, Rollup, Webpack) that defines the network split point:

"use client"; // Must be at the very top of the file!

import { useState } from "react";

export function Counter({ initial = 0 }: { initial?: number }) {
  const [count, setCount] = useState(initial);

  return (
    <button
      onClick={() => setCount((c) => c + 1)}
      className="px-4 py-2 bg-blue-600 text-white rounded-lg font-medium"
    >
      Count: {count}
    </button>
  );
}

4.2. Import Cascading Behavior

Once a file declares "use client", all components, utility modules, and third-party libraries imported by that file are automatically treated as part of the client bundle. You do not need to add "use client" to child modules imported by a Client Component.

5.1. Supported Data Types

5.2. Passing Promises & React 19 use()

React 19 supports passing an unresolved Promise as a prop from a Server Component to a Client Component. The Client Component reads the promise synchronously using the use() hook, automatically triggering Suspense fallbacks until the promise settles:

// Server Component
import { Suspense } from "react";
import { UserProfile } from "./user-profile"; // "use client"

export default function Page() {
  // Start fetching without awaiting!
  const userPromise = fetchUserData();

  return (
    <Suspense fallback={<div>Loading profile skeleton...</div>}>
      <UserProfile userPromise={userPromise} />
    </Suspense>
  );
}

// Client Component (user-profile.tsx)
"use client";
import { use } from "react";

export function UserProfile({ userPromise }: { userPromise: Promise<{ name: string }> }) {
  // Unwraps the promise value seamlessly
  const user = use(userPromise);
  return <h2>Hello, {user.name}</h2>;
}