Now available via: https://github.com/storyblok/monoblok/tree/main/packages/schema
Define Storyblok components as fully-typed TypeScript files, then generate Storyblok CLI-compatible JSON to push them to your space. Also supports the reverse: convert a pulled components.json back into typed .ts definitions.
- Type safety — every field type, option, and config property is typed
- Version control — component schemas live in your repo, reviewable in PRs
- No vendor lock-in — uses the official Storyblok CLI for all API communication
- Zero runtime dependencies — only TypeScript as a build dependency
npm install -D github:DominikAngerer/storyblok-bloks-as-code typescriptThis package uses ES modules. Make sure your package.json includes:
{
"type": "module"
}Create a bloks/ directory and define your components:
// bloks/hero.ts
import { defineComponent, text, richtext, asset, option, section } from "storyblok-bloks-as-code";
export const hero = defineComponent({
name: "hero",
display_name: "Hero",
is_nestable: true,
icon: "block-text-img-l",
color: "#00b3b0",
schema: {
section_content: section(["headline", "subline"], { display_name: "Content" }),
headline: text({
display_name: "Headline",
required: true,
translatable: true,
max_length: 100,
}),
subline: richtext({
display_name: "Subline",
translatable: true,
}),
background_image: asset({
display_name: "Background Image",
filetypes: ["images"],
}),
theme: option({
display_name: "Theme",
options: [
{ name: "Light", value: "light" },
{ name: "Dark", value: "dark" },
],
default_value: "dark",
}),
},
});Create a barrel export:
// bloks/index.ts
export { hero } from "./hero.js";Add a tsconfig.json to your project root:
{
"compilerOptions": {
"target": "ES2024",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"outDir": "dist",
"rootDir": ".",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true
},
"include": ["bloks"],
"exclude": ["node_modules", "dist"]
}Then compile:
npx tscnpx sb-bac generate --space <your-space-id>This writes Storyblok CLI-compatible files to .storyblok/components/<space-id>/:
.storyblok/components/<space-id>/
components.json
groups.json
presets.json
tags.json
storyblok components push --space <your-space-id>Pull your existing components and convert them to typed .ts files:
storyblok components pull --space <your-space-id>
npx sb-bac import .storyblok/components/<space-id>/components.json ./bloksThis generates one .ts file per component plus a barrel index.ts.
npx sb-bac generate --space <id> # Convert .ts definitions → Storyblok CLI JSON
npx sb-bac import <file> [output-dir] # Convert Storyblok JSON → typed .ts definitions
The space ID can also be set via the STORYBLOK_SPACE_ID environment variable.
All 18 Storyblok field types are supported:
| Helper | Storyblok type | Notes |
|---|---|---|
text() |
Text | |
textarea() |
Textarea | |
number() |
Number | Supports min_value, max_value, steps |
boolean() |
Boolean | |
datetime() |
Datetime | |
markdown() |
Markdown | |
richtext() |
Richtext | Supports customize_toolbar, toolbar |
option() |
Single option | Self-defined or datasource |
options() |
Multi option | Self-defined or datasource |
bloks() |
Blocks | Supports restrict_components, component_whitelist |
asset() |
Asset | Supports filetypes filter |
multiasset() |
Multi-asset | |
multilink() |
Link | Supports allow_target_blank, show_anchor |
table() |
Table | |
section() |
Section | section(keys, opts?) — groups fields visually |
tab() |
Tab | tab(keys, opts?) — organizes fields into tabs |
custom() |
Custom field | custom(fieldType, opts?) |
references() |
References | Datasource reference type |
Every helper accepts the full set of field properties (e.g. required, translatable, description, default_value, conditional_settings).
defineComponent({
name: "my_block", // required — the Storyblok component name
display_name: "My Block", // human-readable name
is_root: true, // content type (default: false → nestable)
is_nestable: true, // nestable block (default: true)
icon: "block-doc", // Storyblok icon name
color: "#1b243f", // hex color in the component list
preview_field: "title", // field shown as preview in the editor
component_group_name: "Content", // assign to a component group
schema: { ... },
});Field positions (pos) are auto-assigned based on declaration order — no need to set them manually.
npm run build # Compile TypeScript
npm run typecheck # Type-check without emitting
npm run generate # Shortcut for sb-bac generate
npm run import # Shortcut for sb-bac importISC