Generating TypeScript Types for Storyblok Components

This guide, part of Storyblok Visual Editor Integration, sets up generated TypeScript types for every Storyblok block, so the frontend’s components and the space’s schema stay in agreement. It covers pulling component schemas with the Storyblok CLI, generating types, typing block components and the component registry, checking for drift in CI, and handling fields that editors may leave empty.

Storyblok’s schema lives in the space, not in the codebase: developers and sometimes content designers add fields and blocks in the Storyblok app. Without generated types, the frontend’s interfaces for those blocks are written by hand and drift from the space as soon as someone renames a field or changes an option list. The mismatch shows up as empty sections on pages, not as errors. Generating types from the schema turns each such change into a type error in the component that renders the block.

The Problem

An online education company had forty blocks with hand-written interfaces. A content designer changed the cta block’s link field from a plain text URL to a multilink, so editors could pick stories. The frontend still read blok.link as a string and rendered [object Object] in the href of every call-to-action on the site. The change passed review in Storyblok, where nobody was looking at code, and the frontend had no way of knowing until users reported broken buttons.

How Type Generation Works

Pull schemas. The Storyblok CLI, authenticated with a personal access token, pulls the space’s component definitions into JSON files. Recent CLI versions provide a components pull command; older versions used pull-components.

Generate types. The CLI’s type generator reads the pulled schemas and writes a TypeScript file with one type per block, including the field types, option values, nested block fields and Storyblok’s common properties such as _uid and component. Recent versions provide types generate; older ones used generate-typescript-typedefs.

Use them everywhere. Block components take their generated type as props, the registry is typed so every block name maps to a component that accepts that block, and fetch helpers type the root content of each story.

Check in CI. CI pulls schemas from the staging space, regenerates types and fails if the committed file differs, then runs the type checker. A schema change without matching frontend work fails the pipeline.

Implementation

Add scripts that pull schemas and generate types, using a management token from the environment:

{
  "scripts": {
    "sb:pull": "storyblok components pull --space $STORYBLOK_SPACE_ID",
    "sb:types": "storyblok types generate --space $STORYBLOK_SPACE_ID",
    "sb:sync": "npm run sb:pull && npm run sb:types",
    "typecheck": "tsc --noEmit"
  }
}

Check the CLI’s help for the exact commands and output paths of your version, and move or re-export the generated file to a stable location such as src/storyblok/storyblok.types.ts, so imports do not depend on the CLI’s defaults.

Block components use the generated types as props:

// components/blocks/Cta.tsx
import { storyblokEditable } from "@storyblok/react/rsc";
import type { CtaStoryblok } from "@/storyblok/storyblok.types";
import { hrefFor } from "@/lib/links";

export default function Cta({ blok }: { blok: CtaStoryblok }) {
  const href = hrefFor(blok.link);        // multilink type: a string here is a compile error
  if (!href || !blok.label) return null;  // optional in the schema, so handle it
  return (
    <a {...storyblokEditable(blok)} href={href} className={`cta cta--${blok.variant ?? "primary"}`}>
      {blok.label}
    </a>
  );
}

A typed registry makes the mapping from block names to components exhaustive:

// components/blocks/registry.ts
import type { ComponentType } from "react";
import type * as T from "@/storyblok/storyblok.types";
import Cta from "./Cta";
import Hero from "./Hero";
import Teaser from "./Teaser";

// Every block type the space defines, keyed by its component name.
type Blocks = { cta: T.CtaStoryblok; hero: T.HeroStoryblok; teaser: T.TeaserStoryblok };

export const registry: { [K in keyof Blocks]: ComponentType<{ blok: Blocks[K] }> } = {
  cta: Cta,
  hero: Hero,
  teaser: Teaser,
};

To make the registry catch new blocks, add a small test that reads the pulled components JSON and asserts that every nestable block has an entry in the registry. The test fails when a block is added in Storyblok without a component, which is exactly when a developer should be involved.

// tests/registry.test.ts
import components from "@/storyblok/components.json";
import { registry } from "@/components/blocks/registry";

test("every nestable block has a component", () => {
  const nestable = (components as { name: string; is_nestable: boolean }[]).filter((c) => c.is_nestable).map((c) => c.name);
  const missing = nestable.filter((name) => !(name in registry));
  expect(missing).toEqual([]);
});

Running it in CI

Run sb:sync in CI against the staging space with a read-only management token, then git diff --exit-code on the generated files, then the type checker and tests. Run the same job on a schedule, not only on pull requests, because schema changes in Storyblok do not create pull requests: a nightly run that fails on drift tells the team that the space has moved ahead of the code.

Schema changes as a process

Types turn silent breakage into visible failures, but the smoother path is a process where schema changes and component changes land together. Make schema changes in a development space first, pull and generate types on a branch, update components, and apply the schema to staging and production when the frontend change is deployed. Storyblok’s CLI can push component definitions to another space, which keeps the schema itself under version control.

Configuration Reference

Gotchas & Edge Cases

• Everything optional. Fields that are not required in the schema are optional in the types; handle undefined rather than asserting, since editors can leave them empty.
• Required fields added later. Existing content does not gain values when a field becomes required; the type says required, the data may not. Validate at the data boundary for critical fields.
• Rich text and multilinks. Their generated types are structures, not strings; use the shared helpers for rendering and links.
• Custom field plugins. Plugin fields may be typed loosely; define their shapes in a small hand-written extension.
• Several spaces. When sites use different spaces with shared blocks, generate types per space and share only blocks whose schemas are identical.

Worked Example

The education company introduced generated types, a typed registry and the nightly drift check. On the first run, the type checker reported 58 errors, including the broken call-to-action and eleven other components reading fields that no longer existed or had changed type. After fixing them, schema changes started to arrive with frontend changes in the same week, because the nightly check made drift visible the morning after a change. In the following six months, no broken block reached production because of a schema mismatch.

Beyond Types: Validating Content

Types describe the schema; they cannot promise that every story’s content matches it. Old stories may lack fields added later, imported content may contain unexpected values, and custom field plugins may store data in shapes the generator cannot express. For pages where a broken block is costly, such as checkout or pricing, validate block data at the boundary with a runtime schema library and render a safe fallback when validation fails, logging the story and block _uid so editors can fix the content. Keep such runtime validation focused on the few blocks that matter; for most blocks, generated types plus defensive handling of optional fields are enough.

Rollout Checklist

• Pull component schemas from the staging space with the CLI.
• Generate types and commit them at a stable path.
• Type block components and the registry with generated types.
• Test that every nestable block has a component.
• Check for drift in CI on pull requests and nightly.
• Handle optional fields and validate critical blocks at runtime.

Frequently Asked Questions

Related

• Storyblok Visual Editor Integration
• Resolving Storyblok Relations and Links Efficiently
• Modeling Page-Builder Blocks with Discriminated Unions