Announcing React SDK v4 with full support for React Server Components

Developers Draft

Storyblok is the first headless CMS that works for developers & marketers alike.

The introduction of the App Router paradigm in Next.js brought significant changes to the way developers build and structure applications. While it opened the door to exciting features like React Server Components (RSC) and finer control over rendering, it also introduced complexity for packages that needed to seamlessly support both client-side and server-side environments.

With the release of @storyblok/react version 4.0.0, we are proud to offer full support for React Server Components in Next.js. This update simplifies implementation, enables live preview functionality in our Visual Editor, and ensures robust server rendering, all in a single, unified setup.

Start using it now with:

        
      npm i @storyblok/react@4

warn:

If you are using @storyblok/react v3 with App Router, there are some breaking changes. Check out this article to learn how to update your app.

What's new in @storyblok/react 4.0.0?

Here's a quick rundown of the major improvements in this release:

Unified RSC support
Previously, React Server Components in Next.js required two different implementations for compatibility. With version 4.0.0, we've streamlined this and consolidated everything into one consistent approach.
Live preview with Visual Editor
Developers using the App Router can now enjoy live preview capabilities directly in the Storyblok Visual Editor, enhancing the development and content editing experience.
Seamless Server Rendering
Leverage the full server rendering capabilities of Next.js for improved performance and scalability of your applications

How to use it

Step 1: Initialize the SDK

Start by creating a new file lib/storyblok.js to initialize the SDK. Make sure to export the getStoryblokApi() function.

lib/storyblok.js

        
      import Page from '@/components/Page';
import Teaser from '@/components/Teaser';
import { apiPlugin, storyblokInit } from '@storyblok/react/rsc';

export const getStoryblokApi = storyblokInit({
  accessToken: 'YOUR_ACCESS_TOKEN',
  use: [apiPlugin],
  components: {
    teaser: Teaser,
    page: Page,
  },
});

The getStoryblokApi() function returns a shared instance of the Storyblok client that works across server and client components.

Step 2: Wrap Your Application with StoryblokProvider

Next, create a StoryblokProvider component to enable live editing on the client side. Wrap your entire app with this provider in the app/layout.jsx file.

app/layout.jsx

        
      import StoryblokProvider from '@/components/StoryblokProvider';

export default function RootLayout({ children }) {
  return (
    <StoryblokProvider>
      <html lang="en">
        <body>{children}</body>
      </html>
    </StoryblokProvider>
  );
}

Now, create the StoryblokProvider component:

components/StoryblokProvider.jsx

        
      'use client';

import { getStoryblokApi } from '@/lib/storyblok';

export default function StoryblokProvider({ children }) {
  getStoryblokApi(); // Re-initialize on the client
  return children;
}

Note that the StoryblokProvider is a client component. This ensures that your client-side components can interact with Storyblok, including live editing in the Visual Editor.

Step 3: Fetch Content and Render Components

In server components, use the getStoryblokApi() function to fetch content from Storyblok. Here’s an example app/page.jsx file.

app/page.jsx

        
      import { getStoryblokApi } from '@/lib/storyblok';
import { StoryblokStory } from '@storyblok/react/rsc';

export default async function Home() {
  const { data } = await fetchData();

  return (
    <div>
      <StoryblokStory story={data.story} />
    </div>
  );
}

export async function fetchData() {
  const storyblokApi = getStoryblokApi();
  return storyblokApi.get('cdn/stories/home', { version: 'draft' });
}

Step 4: Use StoryblokServerComponent for server rendering

For rendering components dynamically, always use the StoryblokServerComponent from @storyblok/react/rsc.

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

export default function Page({ blok }) {
  return <StoryblokServerComponent blok={blok} />;
}

This ensures compatibility with server-side rendering, even if you declare the component as a client component.

What’s Next?

We’re preparing an updated official documentation to make adopting version 4 even smoother. In the meantime, all the essential steps are included in the README.

Your feedback and contributions are vital to improving @storyblok/react! If you have suggestions or issues, feel free to open an issue or contribute directly to the project.