How jungvonmatt/storyblok-migrations works
Project type and purpose
• Type: Command-line application built with Node.js & TypeScript.
• Purpose: Extend Storyblok’s CLI by providing schema and content migrations with full TypeScript support, along with configuration management, code generation, and rollback capabilities.
File structure
• bin/cli.ts – Entry point of the CLI (Commander.js).
• src/commands – CLI subcommands (config, login, pull-components, generate-types, generate-migration, run).
• src/handlers – Business logic per command broken into sub-folders (component, componentGroup, datasource, story, transformEntries).
• src/utils – Shared utilities (API wrappers, config loader, migration runner, schema helpers, Storyblok API integration).
• src/templates – Prebuilt templates for new migrations.
• src/types – TypeScript interfaces and type definitions.
• migrations folder (implicit) – Generated migration scripts.
• Configuration files: .storyblokrc.json, .env, tsconfig.json.
• External integrations: Storyblok CLI, Storyblok REST API.
Extract architectural insights from README
• Layers: CLI layer → Command parsing → Handlers → Utils → External API/CLI → Filesystem.
• Key technologies: Commander.js (CLI), Inquirer.js (prompts), Cosmiconfig (config), Jiti (ESM loader), Storyblok CLI & API.
Main components and their interactions
a. User & Shell
– User invokes sb-migrate commands in terminal.
b. CLI Frontend (bin/cli.ts)
– Parses arguments via Commander.js, triggers appropriate command.
c. Commands Layer (src/commands)
– Defines command metadata and maps commands to handler functions.
d. Handlers Layer (src/handlers)
– Implements core use cases:
• config: prompts, loads/saves .storyblokrc.json
• login: delegates to Storyblok CLI
• pull-components: uses Storyblok CLI & API, writes component schemas JSON
• generate-types: reads schemas, emits TypeScript definitions
• generate-migration: copies template into migrations/… with timestamp
• run: loads migration file, calls migration runner (utils/migration), interacts with Storyblok API
e. Utility Layer (src/utils)
– API wrappers, config loader, migration engine, schema helpers, file I/O.
f. Templates (src/templates)
– Source code templates for each migration type.
g. File System
– Config file (.storyblokrc.json or .env), schema JSON, generated types, migrations folder, template source.
h. External Services
– Storyblok CLI (shell tool), Storyblok REST API (HTTP requests).
i. Testing & CI
– Vitest tests in src/__tests__, GitHub Actions workflows.
Architectural patterns & principles
• Layered architecture: separation between CLI parsing, command definition, business handlers, utility services.
• Template-based code generation for consistency.
• Type-safe boundaries: TypeScript interfaces in src/types and generated code.
• Modular design: handlers and utils are isolated per feature.
• External adapter pattern: clear boundary between internal logic and Storyblok CLI/API integrations.
– Top: “User & Shell”
– Next: “CLI Frontend (bin/cli.ts)”
– Middle: “Commands → Handlers → Utils”
– Bottom: “Filesystem” & “External Services”
2. Within the “Commands → Handlers → Utils” cluster:
3. At the bottom:
• read/write config, templates → Filesystem
• spawn Storyblok CLI → External Services
• HTTP calls → Storyblok API
4. Testing & CI can be shown as a side-module: tests trigger src/__tests__, run via Vitest in GitHub Actions.
Diagramming conventions
• CLI/Parser (orange)
• Commands/Handlers (blue)
• Utilities (green)
• Filesystem (gray)
• External Services (purple)