RFC: The Missing Advanced RSC Best Practices for @storyblok/react/rsc

[jplwood]

Note

I have been wrestling with RSC patterns for a few weeks while migrating our storyblok-driven app to Next.js App Router. I'm putting out this RFC to ensure it resonates and that there isn't some fundamental piece of information I am missing. Please let me know your thoughts! I also recognize this is written mostly through the lens through using @storyblok/react/rsc with Next.js App Router, but in theory this idea applies to anything using RSC rendering.

Summary

The @storyblok/react/rsc package works well for basic use cases, but the documentation is missing critical guidance for advanced RSC patterns. This makes it challenging to use true server components (async, server-only APIs) within Storyblok-powered applications.

Package: @storyblok/react
Current Documentation: Next.js App Router Guide

Glossary

• RSC: React Server Component (a component rendered to static html on the server, passes serialized props to client components, is ignored by react client rendering/hydration)
• Client Component: Uses 'use client' directive (can be nested inside RSCs)
• SSR: Server-Side Rendering (RSCs render on server, client components render on server during SSR pass)
• CSR: Client-Side Rendering (hydration in browser after SSR)
• storyblokInit: Configures component registry for Storyblok rendering
• StoryblokServerComponent: Renders dynamic Storyblok content using components from registry

What's Working Well

✅ StoryblokServerComponent works in both server and client contexts
✅ Basic integration with Next.js App Router
✅ Examples are clear for simple use cases
✅ RSCs can be used above the StoryblokStory rendering tree

What's Missing

1. Guidance on True Server Components

The current examples of "RSC"s (readme, example apps) only show isomorphic components (pure rendering, no server-only features):

// From documentation
function Feature({ blok }) {
  return (
    <div>
      <h2>{blok.headline}</h2>
      <p>{blok.text}</p>
    </div>
  );
}

What's missing: Examples showing async components with server-only APIs:

async function Feature({ blok }) {
  const data = await fetch(blok.apiUrl, {
    headers: { Authorization: process.env.SECRET_API_KEY }, // only allowed in RSC
  });
  return <div>{data}</div>;
}

The critical challenge: When StoryblokServerComponent is used inside a 'use client' boundary, it performs runtime lookup in the client bundle's component registry. This creates a cascading limitation:

• ❌ No async components can be nested (they're not in the client registry)
• ❌ No server-only APIs (fs, database, etc.) can be used in nested content
• ❌ No server-only environment variables in nested content
• ❌ You must carefully control which components are allowed to nest inside each client component

Why this is particularly problematic:

Even if you only use StoryblokServerComponent inside a 'use client' boundary once, you've now opted out of server-only RSCs for that entire subtree. With many components, tracking which components can nest where becomes unwieldy and error-prone.

This is technically correct React behavior (client components cannot import or render server-only code), but the implications for Storyblok component architecture are not documented.

The solution: NEVER use StoryblokServerComponent inside a 'use client' boundary. Instead, always use the composition pattern (RSC wrapper + client component) to keep StoryblokServerComponent in RSC context.

Suggested Documentation Additions

1. Composition Pattern for Client Components

Problematic pattern (limits nested content to client bundle only):

'use client';
import { StoryblokServerComponent } from '@storyblok/react/rsc';

function BlogContent({ blok }) {
  return (
    <div>
      {blok.body?.map((nestedBlok) => (
        <StoryblokServerComponent blok={nestedBlok} />
        {/* ❌ PROBLEM: This looks up components in the CLIENT bundle's registry
            ❌ Any server-only RSCs (async, server APIs) CANNOT be nested here
            ❌ You must carefully control which components can be nested */}
      ))}
    </div>
  );
}

Recommended pattern (allows all component types in nested content):

// BlogContentBlock.tsx (RSC wrapper - NO 'use client')
import { StoryblokServerComponent } from '@storyblok/react/rsc';
import { BlogContentClient } from './BlogContentClient';

function BlogContentBlock({ blok }) {
  return (
    <BlogContentClient>
      {blok.body?.map((nestedBlok) => (
        <StoryblokServerComponent blok={nestedBlok} />
        {/* ✅ CORRECT: This looks up components in the SERVER bundle's registry
            ✅ Server-only RSCs (async, server APIs) CAN be nested here
            ✅ No restrictions on nested component types */}
      ))}
    </BlogContentClient>
  );
}

// BlogContentClient.tsx
'use client';
export function BlogContentClient({ children }) {
  // Client-side logic here
  return <div>{children}</div>;
}

Why this matters:

• ✅ Nested content stays in RSC context - Can use async components, server APIs, etc.
• ✅ No component list restrictions - Any component can be nested, including server-only RSCs
• ✅ Simpler architecture - No need to track which components can nest where

Key principle: StoryblokServerComponent should ONLY be used in RSC context (files without 'use client'). If you need client-side interactivity, use composition patterns to keep StoryblokServerComponent in the RSC wrapper (see Next.js docs: Interleaving Server and Client Components).

2. Component Registration Strategy

Next.js App Router has three rendering phases, each using different bundles:

1. RSC Render (server bundle) - Creates RSC tree with "holes" for client components
2. SSR Pass (client bundle executing on server) - Renders client components to HTML
3. Client Hydration (client bundle in browser) - Makes the page interactive

Each bundle maintains its own component registry when storyblokInit is called. The key insight: both registries are used during server-side rendering, but at different phases.

Recommended approach:

// storyblokInitServer.ts (server bundle - for RSC render phase)
import { storyblokInit } from '@storyblok/react/rsc';
import Page from './Page'; // Direct import - can be async RSC
import Feature from './Feature'; // Direct import - React detects 'use client'
import Section from './Section'; // Direct import - isomorphic

storyblokInit({
  components: {
    page: Page, // Assume server-only RSC (async)
    feature: Feature, // Client component (has 'use client')
    section: Section, // Isomorphic
  },
});

// storyblokInitClient.ts (client bundle - for SSR + hydration phases)
'use client';
import { storyblokInit } from '@storyblok/react/rsc';

storyblokInit({
  components: {
    // ❌ Cannot include Page - it's async/server-only
    feature: () => import('./Feature'), // Dynamic import for code-splitting
    section: () => import('./Section'), // Dynamic import for code-splitting
  },
});

Why this matters:

• Direct imports in server bundle: React can detect 'use client' directives and create proper RSC boundaries during the RSC render phase
• Dynamic imports in client bundle: Enable code-splitting while still working during SSR (Next.js pre-bundles them)
• Server-only RSCs excluded from client bundle: Async components and those using server-only APIs cannot be in the client registry

Why client components MUST be in the server bundle's registry:

This is a common point of confusion: "If client components only render during SSR/CSR, why include them in storyblokInitServer?"

Answer: During the RSC render phase, when StoryblokServerComponent encounters a client component name (e.g., "button"), it needs to:

1. Look up the component in the server bundle's registry
2. Find the component definition (which has 'use client' directive)
3. Let React detect the 'use client' directive and create a "hole" (placeholder) for the client component
4. Pass props to that hole so they can be serialized and sent to the client

Without the client component in the server registry:

// Server bundle registry (WRONG - missing client components)
storyblokInit({
  components: {
    page: Page, // ✅ Found
    section: Section, // ✅ Found
    // ❌ Missing: button
  },
});

// During RSC render:
<StoryblokServerComponent blok={{ component: 'button', ... }} />
// ❌ ERROR: Component 'button' not found in registry
// ❌ StoryblokServerComponent cannot render it
// ❌ React never sees the 'use client' directive
// ❌ No "hole" is created

With the client component in the server registry:

// Server bundle registry (CORRECT - includes client components)
import Button from './Button'; // Direct import - has 'use client'

storyblokInit({
  components: {
    page: Page,
    section: Section,
    button: Button, // ✅ Included
  },
});

// During RSC render:
<StoryblokServerComponent blok={{ component: 'button', ... }} />
// ✅ Looks up 'button' in registry
// ✅ Finds Button component (which has 'use client')
// ✅ React detects 'use client' directive
// ✅ Creates a "hole" with serialized props
// ✅ Client bundle will render Button during SSR/hydration

Key insight: The server bundle doesn't render client components (that happens in SSR/hydration), but it needs to know about them to create the proper RSC boundaries.

3. Component Categorization

As alluded to above, there are three types of components: server-only RSCs, isomorphic, and client. It would be helpful to document the three types of components and how they should be registered:

Server-Only RSC:

• ✅ Can be async
• ✅ Can use server-only APIs (fs, database, etc.)
• ✅ Can access server-only environment variables
• ❌ Cannot be in client bundle
• ❌ Cannot be registered in client-side storyblokInit or be used by StoryblokServerComponent inside a 'use client' boundary

// Identified by: async keyword
async function Page({ blok }) {
  const data = await db.query(blok.id);
  const secret = process.env.API_SECRET; // Server-only
  return <div>{data}</div>;
}

Registration: Only in server bundle (storyblokInitServer)

Isomorphic:

• ✅ Pure rendering only
• ✅ Can be in either bundle, i.e.,
  • Can be rendered as an RSC, or
  • Can be rendered by SSR and hydrated by CSR, or
  • Can be rendered by CSR
• ✅ Can be registered in both server and client storyblokInit
• ❌ Cannot be async
• ❌ Cannot use hooks, event handlers, or server-only APIs

// Identified by: no 'use client', not async
function Section({ blok }) {
  return (
    <section>
      <h2>{blok.title}</h2>
      <p>{blok.text}</p>
    </section>
  );
}

Registration: Both server and client bundles (direct import in server, dynamic import in client)

Client:

• ✅ Uses hooks, event handlers, browser APIs
• ✅ Must have 'use client' directive
• ✅ Can be registered in both server and client storyblokInit
• ❌ Cannot be async
• ❌ Cannot use server-only APIs

// Identified by: 'use client' directive
'use client';
function Button({ blok }) {
  const [clicked, setClicked] = useState(false);
  return <button onClick={() => setClicked(true)}>{blok.label}</button>;
}

Registration: Both server and client bundles (direct import in server for RSC boundary detection, dynamic import in client for code-splitting)

Summary

The @storyblok/react/rsc package works great for basic use cases: RSCs can wrap <StoryblokStory /> and this package will render your story appropriately. However it falls over if you try to register RSCs with storyblok rendering, particularly nested RSCs. Adding documentation for these advanced patterns would help developers:

1. ✅ Use true, server-only RSCs - Examples showing async components with server-only APIs
2. ✅ Properly structure client components with nested content - RSC wrapper + client component composition pattern
3. ✅ Understand the three rendering phases - RSC render, SSR pass, client hydration
4. ✅ Set up component registries correctly - Which components go in which bundle and why
5. ✅ Categorize components - Server-only RSC, isomorphic, and client components with registration guidance

Key Takeaways:

• Both storyblokInit registries are used during server-side rendering (at different phases)
• Client components MUST be in server bundle's registry - Without them, StoryblokServerComponent cannot look up the component, React cannot detect 'use client' directives, and no RSC "holes" are created
• Direct imports in server bundle allow React to detect 'use client' boundaries
• Dynamic imports in client bundle enable code-splitting
• Server-only RSCs (async) cannot be in the client bundle at all

Related Resources:

• @storyblok/react Package
• Storyblok Next.js App Router Guide
• @storyblok/react README
• @storyblok/react Example Apps
• Next.js: Interleaving Server and Client Components
• Next.js Server/Client Composition Patterns
• Next.js App Router Rendering
• React Server Components RFC

[jplwood]

With the context above, I'd also like to float the idea of introducing a "Strict Mode" version for using StoryblokServerComponent (or some kind of global configuration on storyblokInit/StoryblokStory) that throws an error if StoryblokServerComponent is used within a client boundary to force better, safer client/RSC composition patterns.