chore: React SDK POC #287

imranolas · 2025-09-04T13:30:27Z

A reimagining of the Storyblok React SDK to focus purely on rendering and component registration, removing data fetching concerns and letting users handle their own data strategy.

Changes

Removed data fetching hooks (useStoryblokApi, useStoryblokState)
SDK now handles only component registration and content rendering through registration with a Bloks/Blok api (inspired by React Router)
Type safe throughout and integrates well with the types generated by the CLI
Works with any React setup both client and server side

Next.js 15 Demo

Recreated the Nuxt Storyblok demo site as a React reference implementation
Next.js 15 with App Router, SSR, visual editing, and SWR

Why is this better?

Rendering and data fetching are now separate concerns avoid leaky behaviour between SSR and client
Users can choose their preferred data fetching strategy. This example uses SWR but easily supports others
A stateless API that eliminates module/global caching

Reviewers notes

This PR is a bit of a monster but it broadly falls into the following pieces:

React SDK. The changes here leave the API considerably smaller than previously. It's a much simpler API to use and maintain
The bulk of the change comes from replacing and relocating the next15 playground app https://github.com/storyblok/monoblok/tree/spike/react-next/apps/next15-demo
Along with the demo app I've also committed the generated types for the demo space which makes running and testing considerably easier.

resolves WDX-123

pkg-pr-new · 2025-09-04T13:34:28Z

Open in StackBlitz

@storyblok/astro

npm i https://pkg.pr.new/@storyblok/astro@287

storyblok

npm i https://pkg.pr.new/storyblok@287

@storyblok/eslint-config

npm i https://pkg.pr.new/@storyblok/eslint-config@287

@storyblok/js

npm i https://pkg.pr.new/@storyblok/js@287

storyblok-js-client

npm i https://pkg.pr.new/storyblok-js-client@287

@storyblok/management-api-client

npm i https://pkg.pr.new/@storyblok/management-api-client@287

@storyblok/nuxt

npm i https://pkg.pr.new/@storyblok/nuxt@287

@storyblok/react

npm i https://pkg.pr.new/@storyblok/react@287

@storyblok/region-helper

npm i https://pkg.pr.new/@storyblok/region-helper@287

@storyblok/richtext

npm i https://pkg.pr.new/@storyblok/richtext@287

@storyblok/svelte

npm i https://pkg.pr.new/@storyblok/svelte@287

@storyblok/vue

npm i https://pkg.pr.new/@storyblok/vue@287

commit: 10859c7

imranolas · 2025-09-04T13:41:56Z

apps/next15-demo/src/app/StoryblokComponent.tsx

+    <Bloks {...props} blok={blok} story={story} fallback={FallbackComponent}>
+      <Blok
+        component="featured-articles-section"
+        element={FeaturedArticlesSection}
+      />
+      <Blok component="grid-section" element={GridSection} />
+      <Blok component="hero-section" element={HeroSection} />
+      <Blok component="image-text-section" element={ImageTextSection} />
+      <Blok component="tabbed-content-section" element={TabbedContentSection} />
+      <Blok component="text-section" element={TextSection} />
+      <Blok component="banner" element={Banner} />
+      <Blok component="banner-reference" element={BannerReference} />
+      <Blok
+        component="latest-articles-section"
+        element={LatestArticlesSection}
+      />
+      <Blok component="faq-section" element={FaqSection} />
+      <Blok component="logo-section" element={LogoSection} />
+      <Blok
+        component="newsletter-form-section"
+        element={NewsletterFormSection}
+      />
+      <Blok component="personalized-section" element={PersonalizedSection} />
+      <Blok component="products-section" element={ProductsSection} />
+      <Blok component="testimonials-section" element={TestimonialsSection} />
+      <Blok component="article-overview-page" element={ArticleOverviewPage} />
+      <Blok component="article-page" element={ArticlePage} />
+      <Blok component="category" element={Category} />
+      <Blok component="contact-form-section" element={ContactFormSection} />
+      <Blok component="price-card" element={PriceCard} />
+      <Blok component="grid-card" element={GridCard} />
+      <Blok component="image-card" element={ImageCard} />
+      <Blok component="richtext-youtube" element={RichtextYoutube} />
+      <Blok component="tabbed-content-entry" element={TabbedContentEntry} />
+      <Blok component="headline-segment" element={HeadlineSegment} />
+      <Blok component="default-page" element={DefaultPage} />
+      <Blok component="nav-item" element={NavItem} />
+    </Bloks>


This the crux of the API. It's basically a gloried switch statement. This is user generated code and users can create as many or as few of these as they choose to target different rendering contexts.

imranolas · 2025-09-04T13:45:00Z

apps/next15-demo/src/app/[[...slug]]/page.tsx

+    slug = slug.join("/");
+  }
+
+  const { story, header } = await fetchPage(slug);


Async data fetching happens on the server and the result is populated in the SWR cache as fallback. This keeps the cache primed for the subsequent useSWR hook calls.

imranolas · 2025-09-04T13:45:44Z

apps/next15-demo/src/app/[[...slug]]/page.tsx

+        [`cdn/stories/${slug}`]: story,
+        "cdn/stories/site-config": header,


The cache keys simply need to match the request params for useSWR. Similar patterns exist in other data fetching libraries

imranolas · 2025-09-04T13:46:54Z

apps/next15-demo/src/lib/useStory.ts

+const fetcher = (key: string) => getStory(key).then(res => res.data.story);
+
+export const useStory = <T = unknown>(slug: string) => {
+  const { data, error, isLoading } = useSWR(`cdn/stories/${slug}`, fetcher);
+
+  return { story: data as ISbStoryData<T>, error, isLoading };
+}


The user creates their own purpose built hook around their chosen data fetching library.

imranolas · 2025-09-04T13:51:11Z

apps/next15-demo/src/app/Story.tsx

+  | StoryblokComponents.ArticlePage;
+
+export function Story({ slug }: { slug: string }) {
+  const { story, error, isLoading } = useStory<Component>(slug);


This is a user hook that wraps the their data fetching library (SWR in this case) using the js client. Since the SWR cache is already pre-populated in the Server Component, this will simply return the data needed to complete SSR.

On the client, the SWR cache is re-hydrated and bridge updates will mutate the cache and trigger live updates.

imranolas · 2025-09-04T13:53:20Z

apps/next15-demo/src/app/components/BridgeHandler.tsx

+    bridge.on("input", (event) => {
+      if (!event || !event.story) return;
+      mutate(`cdn/stories/${event.story.slug}`, event.story, {
+        revalidate: false,
+      });
+    });


The SWR cache is keyed by slug which is globally unique within the space. When a live update occurs we mutate the cache which triggers a re-render with the updated data. This occurs on the client only.

@imranolas do you think is this something that could be part of the SDK?

Also, have you tried reusing the useStoryblokBridge exported from @storyblok/js? I'd suggest it for reusability as it performs a few extra checks:

Is in editor

Is the same story, by checking id (needed when you set multiple listeners in the same page

Already implements the change and published events

Adding the code suggestion below

alexjoverm · 2025-09-09T07:04:16Z

apps/next15-demo/src/app/components/BridgeHandler.tsx

+    const bridge = new window.StoryblokBridge({
+      resolveRelations: resolveRelations,
+    });
+
+    bridge.on("input", (event) => {
+      if (!event || !event.story) return;
+      mutate(`cdn/stories/${event.story.slug}`, event.story, {
+        revalidate: false,
+      });
+    });


Suggested change

const bridge = new window.StoryblokBridge({

resolveRelations: resolveRelations,

});

bridge.on("input", (event) => {

if (!event || !event.story) return;

mutate(`cdn/stories/${event.story.slug}`, event.story, {

revalidate: false,

});

});

const cb = event => mutate(`cdn/stories/${event.story.slug}`, event.story, { revalidate: false });

useStoryblokBridge(story.id, cb, { resolveRelations });

(would need BridgeHandler to have the story from [[...slug]]/page.tsx to be passed as property)

imranolas added 4 commits August 26, 2025 16:01

chore: first pass at reimagined api

9ba819f

feat: react sdk poc

000aae7

chore: remove Next.js 15 demo app and related files

49dcd55

Merge remote-tracking branch 'origin/main' into spike/react-next

42d4658

imranolas had a problem deploying to test September 4, 2025 13:30 — with GitHub Actions Failure

fix: revert change

1ce0ab1

imranolas had a problem deploying to test September 4, 2025 13:32 — with GitHub Actions Failure

refactor(Bloks): simplify warning message formatting

10859c7

imranolas had a problem deploying to test September 4, 2025 13:39 — with GitHub Actions Failure

imranolas commented Sep 4, 2025

View reviewed changes

imranolas requested review from JDoza89 and edodusi September 4, 2025 14:44

alexjoverm reviewed Sep 9, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

chore: React SDK POC #287

chore: React SDK POC #287

Uh oh!

imranolas commented Sep 4, 2025 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Sep 4, 2025 •

edited

Loading

Uh oh!

imranolas Sep 4, 2025

Uh oh!

imranolas Sep 4, 2025

Uh oh!

imranolas Sep 4, 2025

Uh oh!

imranolas Sep 4, 2025

Uh oh!

imranolas Sep 4, 2025

Uh oh!

imranolas Sep 4, 2025

Uh oh!

alexjoverm Sep 9, 2025

Uh oh!

alexjoverm Sep 9, 2025 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		[`cdn/stories/${slug}`]: story,
		"cdn/stories/site-config": header,

chore: React SDK POC #287

Are you sure you want to change the base?

chore: React SDK POC #287

Uh oh!

Conversation

imranolas commented Sep 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Next.js 15 Demo

Why is this better?

Reviewers notes

Uh oh!

pkg-pr-new bot commented Sep 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

imranolas Sep 4, 2025

Choose a reason for hiding this comment

Uh oh!

imranolas Sep 4, 2025

Choose a reason for hiding this comment

Uh oh!

imranolas Sep 4, 2025

Choose a reason for hiding this comment

Uh oh!

imranolas Sep 4, 2025

Choose a reason for hiding this comment

Uh oh!

imranolas Sep 4, 2025

Choose a reason for hiding this comment

Uh oh!

imranolas Sep 4, 2025

Choose a reason for hiding this comment

Uh oh!

alexjoverm Sep 9, 2025

Choose a reason for hiding this comment

Uh oh!

alexjoverm Sep 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

imranolas commented Sep 4, 2025 •

edited

Loading

pkg-pr-new bot commented Sep 4, 2025 •

edited

Loading

alexjoverm Sep 9, 2025 •

edited

Loading