Engineer Opportunity: My Storyblok Reference Architecture
Andrew Caperton, Senior .NET Engineer
I built a public reference implementation of Storyblok's pre-packaged demo space on Next.js and Mantine UI, and in January 2026 I wrote it up as a white paper. This article replaces that paper. The engineering held up; the vendor voice did not. What follows is the writeup I should have shipped the first time: the decisions, what each one cost, and what I would do differently now. The code is public at storyblok-nextjs-mantine-demo.
What the build is
Storyblok gives any developer a free, pre-packaged demo space [7] with content, images, pages, and component schemas already in place. The build implements that demo space as-is on the Next.js App Router and renders it entirely through Mantine components. I did not alter the demo content or the blok definitions. That constraint was deliberate. It keeps the build reproducible for anyone with a free account, and it pushed all the interesting work into the rendering layer instead of the content model.
The constraint has a real cost. The demo space is opinionated, its content structure and component names are fixed, and its design assumptions are not mine. This is not a generic UI kit, and I will not present it as one. What transfers to other projects is the architecture around the demo content: a registry-based component system, lazy component loading, CDN-backed image handling, incremental static regeneration with webhook-driven revalidation, and a theme driven from the CMS.
The three decisions
Storyblok, coming from Sitecore
Most of my career has been on enterprise platforms, eight years of it on Sitecore, where visual editing arrives with a license negotiation and an onboarding project. Storyblok puts a working Visual Editor [13] on a free tier [1] and serves content through a CDN-backed delivery API [12]. For a personal reference build, that settled it. I wanted to work through a visual-editing integration end to end without a platform contract in the way.
The trade-off is the one already named above. The free demo space [7] is a playground with fixed opinions, and outgrowing it means designing your own schemas and content architecture. Storyblok removes the cost barrier to learning this class of CMS. It does not make enterprise CMS selection a solved problem, and the original paper blurred that line.
Mantine over a utility-CSS stack
The default pairing for a Next.js starter is Tailwind plus headless primitives. I chose Mantine instead, for two reasons. First, coverage. More than 120 components [2] meant the demo space's pages could be assembled from tested, accessible components rather than hand-rolled markup. Second, theming. Mantine's provider and CSS variables [3] made it practical to drive the theme from CMS content, so editor-controlled design became a working feature rather than a promise.
The cost is buy-in. You adopt Mantine's component API and its theming model, and moving to a bespoke design system later means working through that provider, not around it. Tree-shaking keeps unused components out of the production bundle, which removed the bundle-size objection for me. The coupling objection stands, and I accepted it with open eyes.
Next.js App Router, plumbing included
The App Router's conventions [4] give predictable routing, server rendering, and first-class metadata for SEO. Published pages render through incremental static regeneration [6], and blok components load lazily behind React.lazy and Suspense [5], so a page only ships the components it actually uses.
The part the marketing version skipped is the plumbing. Draft mode, preview entry and exit, and cache behavior all have to be wired by hand. The build dedicates a proxy layer and a set of API routes to keeping the published path and the preview path from contaminating each other, and that wiring is worth more to a reader than any of the rendered pages.
The request path
The original paper leaned on an architecture diagram at this point. The flow reads fine as prose.
A request first hits proxy rewrite logic (src/proxy.ts) that routes it to the published path or the preview path. On the published path, the story comes from Storyblok's CDN content API [12], relations and links are normalized server-side [10][11], and the registry maps each blok to its Mantine-backed component. The result is served from the ISR cache [6]. When an editor publishes, a Storyblok webhook triggers on-demand revalidation, so exactly the affected pages update instead of waiting out a timer [6].
The preview path exists for Storyblok's Visual Editor [13], which loads the site in an iframe. Preview requests enter draft mode through an API route and render dynamically with caching disabled, and the Visual Editor bridge [12][13] connects clicks in the rendered page back to fields in the CMS.
The sharp edge
Relation and link resolution is where this stack costs time. Storyblok's referenced-content model [10] is useful, but its resolution behavior carries caveats the docs undersell, and the long-running GitHub issue on link resolution [11] documents the gap. The build's answer is to normalize relations and links in one server-side pass before rendering, so no individual component ever handles half-resolved data.
Images
Image handling stays on Storyblok's Image Service [8], which does resizing, format negotiation, and quality transforms at the CDN. FocusReactive's writeup on pairing the Image Service with Next.js [9] goes deeper on the same pattern.
Accessibility, restated
The original paper claimed the stack helps teams "meet WCAG 2.1 guidelines without extra overhead." That was overstated, and this rewrite is where I correct it. Mantine provides a strong floor. Its components ship semantic HTML, ARIA attributes, keyboard navigation, and focus management, so modals, menus, and form controls behave correctly with screen readers out of the box. Server-side rendering keeps content present before JavaScript arrives. None of that makes an application WCAG 2.1 compliant. It means the component layer stops fighting you while you do the actual accessibility work in your own markup, contrast choices, and content.
What I would change
The paper closed with a roadmap. Here it is again as priorities, not promises.
Authentication for preview content. The original outlook listed it as future work, which means the preview path shipped without it. Today it would be first on the list, ahead of everything below.
Centralized fragment rendering utilities. Also on the original list, and still right. Rendering helpers belong in one place.
Search indexing with Algolia. Worth keeping. The demo content is a reasonable corpus to build an indexing pipeline against.
Newer Next.js features. The paper promised component improvements tracking the latest Next.js releases. That is maintenance, and maintenance does not need a roadmap line.
A/B testing integration. I would cut this one. A reference build should demonstrate the seams of the platform integration, not every feature a platform could host.
Where this leaves it
This build is evidence of how I evaluate tooling, not a product, and I have stopped writing about it as one. If you are weighing this stack, read the proxy and preview wiring first, then the component registry, then the relation normalization. That is where the decisions live, and those are the parts I would carry into the next build whatever CMS or component library ends up on either side of them.
Revised August 2026. First published January 2026 as "The SNMUI White Paper," v1.3.
References
Links were last verified in January 2026, when the original paper was published.