storyblok-schema-to-ts

Generate TypeScript types from Storyblok component schemas.

Prerequisites

• Node.js >= 18

Authentication

The tool uses the Storyblok Management API to fetch component schemas and datasources. It resolves a token in this order:

1. --token flag — pass your personal access token directly
2. CLI credentials — reads from ~/.storyblok/credentials.json (created by npx storyblok login)

If no token is found, the tool shows instructions for obtaining one.

Get a personal access token at: https://app.storyblok.com/#/me/account?tab=token

Installation

npm install storyblok-schema-to-ts

CLI Usage

# With explicit token
npx storyblok-schema-to-ts --spaceId=123456 --token=your_token

# Using CLI credentials (after: npx storyblok login)
npx storyblok-schema-to-ts --spaceId=123456

# Non-EU region
npx storyblok-schema-to-ts --spaceId=123456 --region=us

# Custom output file
npx storyblok-schema-to-ts --spaceId=123456 --output=./types/storyblok.ts

# With custom prefixes
npx storyblok-schema-to-ts --spaceId=123456 --prefix=SB --builtinPrefix=SBCore

CLI Options

| Option | Description | Default | |--------|-------------|---------| | --spaceId | Storyblok space ID (required) | - | | --token | Personal access token | - | | --region | Storyblok region: eu, us, cn, ca, ap | eu | | --output | Output file path | SBGenerated.ts | | --prefix | Prefix for generated types | - | | --postfix | Postfix for generated types | - | | --builtinPrefix | Prefix for builtin types | - | | --builtinPostfix | Postfix for builtin types | - | | --capitalize | Capitalize type names | true | | --no-prettier | Skip prettier formatting | false | | --keep-temp | Keep .storyblok temp directory | false |

Programmatic Usage

import { generateTypes } from 'storyblok-schema-to-ts';

await generateTypes({
  spaceId: '123456',
  outputFile: 'types.ts',
  capitalize: true
});

Example Output

export interface Blok {
  _uid: string;
  component: string;
  _editable?: string;
}

export type Story<Content = Blok> = {
  alternates: Alternate[];
  content: Content;
  full_slug: string;
  id: number;
  name: string;
  slug: string;
  uuid: string;
  // ...
}

export type Hero = Blok & {
  component: "Hero";
  title: string;
  description?: string;
  theme?: "light" | "dark";
  image?: Asset;
  content?: RichText;
  items?: (Card | Button)[];
}

With --prefix=SB --builtinPrefix=SBCore, the output would use SBHero, SBCoreBlok, etc.

Deleted Component Warnings

When a field references components that no longer exist in the schema (e.g. via component_whitelist or filter_content_type), the generated types include an inline comment:

export type Page = Blok & {
  component: "Page";
  body?: (Hero | Card)[] /* [!] unknown component(s): DeletedSection */;
  related?: unknown /* [!] unknown component(s): OldWidget */;
}

This helps identify stale references without breaking TypeScript compilation.

License

MIT