Storyblok: the CMS your marketing team can see
Storyblok starts from a different assumption than most headless CMS products: editors should not have to imagine the page. The preview is the site, the fields sit on top of it, and the content model — a tree of components — is designed so that clicking what you see is how you edit it.
In short
- Storyblok is a hosted CMS built around a visual editor and a tree of components (“bloks”).
- The preview is your real front‑end, so what editors approve is what ships.
- The component tree maps almost one‑to‑one onto an Astro component library.
- Official
@storyblok/astrocovers the client, blok rendering and the editing bridge. - You rent it. SaaS only, tiered plans, and a nested JSON shape that needs mapping.
What Storyblok actually is
Every piece of content is a story — a page or a global fragment — and its content is a recursive tree of bloks. Each blok has a component name and a set of fields, and nested bloks can be reordered or added by the editor within limits you define.
You define those components in the Storyblok space (or sync them from a schema file), then build the matching Astro components. The naming convention is the contract: a blok called hero renders through the component registered as hero.
---
// src/components/StoryblokComponent.astro (simplified)
import Hero from './Hero.astro'
import FeatureGrid from './FeatureGrid.astro'
const { blok } = Astro.props
const map = { hero: Hero, feature_grid: FeatureGrid }
const Component = map[blok.component]
---
{Component && <Component blok={blok} />}
The official integration ships its own StoryblokComponent that does this lookup, so in practice you register components once and let it render the tree.
A practical detail that shapes the project: Storyblok separates spaces, environments and releases. Staging content can live in a preview environment inside the same space, and a release groups a set of changes to publish together. That is closer to how a real editorial calendar works than a single “draft” toggle — but it also means your build pipeline needs to know which environment it is reading.
Who it fits
- Marketing teams that review pages visually and want to fix a typo in place.
- Agencies with a design system, because a blok library is a component library with an admin attached.
- Multi‑brand or multi‑locale sites using releases and workflows across spaces.
- Teams that would rather not run infrastructure, and are fine with a subscription.
Less suitable when: the content is mostly articles rather than composed pages, when the budget cannot carry a recurring platform cost, or when the client’s security policy forbids another vendor holding their content.
How it connects to Astro
---
import { useStoryblokApi, StoryblokComponent } from '@storyblok/astro'
const storyblokApi = useStoryblokApi()
const slug = Astro.params.slug ?? 'home'
const { data } = await storyblokApi.get(`cdn/stories/${slug}`, { version: 'published' })
const story = data.story
---
<StoryblokComponent blok={story.content} />
Three things to plan for:
- Versioning. The same endpoint serves
published,draftand a specific release. Preview routes request drafts; public builds request published content. Never let a token with draft access leak into a client bundle. - Caching. The delivery API is CDN‑backed and fast; adding an in‑memory cache in the build keeps a 3,000‑page site from hammering it.
- Images. Storyblok’s image service serves transformed variants by URL. In Astro, either allow the Storyblok host in your image config or keep using their service — pick one, do not mix.
Publishing should trigger a rebuild through a webhook to your hosting platform. For pages that change hourly, add an on‑demand route; for everything else, a build is cheaper and simpler.
Strengths
- The editing loop. Click the page, edit the field, publish. No abstract preview to interpret.
- Component parity. The blok language is the component language, which keeps design and content aligned.
- Real editorial tooling. Releases, workflows, scheduled publishing, field‑level translation, asset management.
- Low operational load. No database, no server, no patches.
Weaknesses
- Hosted only, tiered pricing. Model the plan against seats, spaces and traffic before you commit; check the vendor’s current pricing page rather than any figure in an article.
- Nested JSON needs mapping. Deeply nested bloks produce awkward types unless you generate them.
- Preview needs an environment. The visual editor is only honest if your preview renders drafts — that is a server‑side route you have to build.
- The component model is opinionated. Content that is really a database record (events, products, people) fits less naturally than composed pages.
When to choose Storyblok
Choose it when the approval happens visually: marketing signs off on pages, not on JSON, and every extra round of “can you send me a screenshot” costs real time. It is also strong when the site is a composition of reusable sections rather than a stream of articles.
If your content is mostly long‑form text with references, Sanity structures it better. If the priority is owning the stack and writing the schema in code, read the Payload guide.
Summary
Storyblok sells a shorter feedback loop, and for a marketing site that loop is most of the value. You pay for it with a subscription, a vendor dependency and one more mapping layer between the CMS tree and your components — a fair price when editors are the bottleneck.
See where it lands against the alternatives in the headless CMS comparison for Astro, or start from the headless CMS hub. We build Storyblok‑backed Astro front‑ends as part of web development.
Screenshots in this series are placeholders — we will replace them with our own, taken on real projects.
Yuri Osipov
Founder, SEO & analytics
Runs Take the Space. Specialises in technical SEO, measurable analytics setups and AI search visibility.