storyblok-to-zod

Generates clean, optimized Zod schemas from your Storyblok components by processing the output of Storyblok's CLI components pull and types generate commands. Unused schemas are automatically excluded for a smaller, easier-to-maintain result.

Useful for defining Zod schemas in Astro's Content Collections.

Automatically converting Storyblok's CLI output to Zod schemas with tools like ts-to-zod can be problematic. This tool helps this process by generating compatible Zod schemas directly from your Storyblok components.

Prerequisites

Before using this tool, you'll need to:

1. Pull your Storyblok components:

   storyblok pull-components --space=YOUR_SPACE_ID

2. Generate TypeScript types:

   storyblok generate-types --space=YOUR_SPACE_ID

This will create the necessary .storyblok/ folder structure that this tool processes.

Usage

Without installation

# With npm
npx storyblok-to-zod --space STORYBLOK_SPACE_ID

# With pnpm
pnpm dlx storyblok-to-zod --space STORYBLOK_SPACE_ID

# With yarn
yarn dlx storyblok-to-zod --space STORYBLOK_SPACE_ID

With installation

# With npm
npm install storyblok-to-zod --save-dev

# With pnpm
pnpm add storyblok-to-zod --dev

# With yarn
yarn add storyblok-to-zod --dev

Running:

# With pnpm
pnpm storyblok-to-zod --space STORYBLOK_SPACE_ID

# With yarn
yarn storyblok-to-zod --space STORYBLOK_SPACE_ID

Example Output

Given a Storyblok component named hero-section, this tool will generate:

// Generated by storyblok-to-zod
import { z } from 'astro/zod';

export const heroSectionSchema = z.object({
  title: z.string(),
  subtitle: z.string().optional(),
  image: storyblokAssetSchema.optional(),
});

Options

| Option | Short | Description | Default | | --------- | ----- | ------------------------------------------------------ | ---------------------------- | | --space | -s | (Required) The ID of your Storyblok space | - | | --output | -o | Output to file | - | | --folder | -f | Path to the folder containing the Storyblok components | '.storyblok' | | --verbose | -v | Verbose mode | false | | --debug | -d | Show debug information | false | | --help | -h | Show command help | false | | --no-extends-array | | Will not automatically convert StoryblokMultiasset | - |

Features

• ✅ Converts Storyblok component schemas to Zod schemas
• ✅ Handles component dependencies and circular references
• ✅ Processes TypeScript interfaces from Storyblok's type definitions
• ✅ Supports all major Storyblok field types
• ✅ Compatible with Astro's Content Collections
• ✅ Comprehensive error handling and validation

Notes

• --no-extends-array:
  ts-to-zod appears to be unable to convert the definition of StoryblokMultiasset because it extends Array<StoryblokAsset>. This tool will bypass ts-to-zod and automatically convert StoryblokMultiasset. You may disable this behaviour by specifying --no-extends-array.

• ts-to-zod version:
  Using ts-to-zod version ^3.15.0 because Astro hasn't updated to Zod v4 yet.

Feedback

Feedback and contributions are welcome! If you run into a problem, don't hesitate to open a GitHub issue.

Changelog

v0.1.0

• Cleaner Zod schema output:

  • Deduplicated imports moved to the top
  • Better formatting and organization
  • Enhanced readability

• Schema dependency analyzer:

  • Analyzes component schemas to determine which native schemas are actually used
  • Excludes unused schemas from output for cleaner results
  • Handles indirect dependencies between native schemas
  • Provides detailed usage statistics

v0.0.12

• Fix: Tool now works correctly when output is piped to other commands

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT - see LICENSE.txt for details.

TODO

• [ ] Add Storyblok datasources as well.