How storyblok/monoblok works
Project Type and Purpose
• This is a Node.js-based monorepo (“Monoblok”) that centralizes all Storyblok open-source SDKs, framework integrations, utilities, and CLI tools.
• It uses PNPM workspaces for package management and NX for build orchestration, caching, and dependency visualization.
• The repo includes: core SDKs (@storyblok/js, @storyblok/js-client), framework adapters (@storyblok/react, vue, nuxt, svelte, astro), a richtext renderer, and the storyblok-cli.
Key Architectural Components
a. Root Workspace
• pnpm-workspace.yaml: defines which folders are part of the workspace.
• nx.json: configures NX tasks, caching, dependency graph.
• GitHub Actions (.github/workflows): CI/CD pipelines for build, test, publish.
• Husky & lint-staged: pre-commit/commit-msg hooks.
b. Package Modules (packages/*)
• Each package folder (js, js-client, react, vue, nuxt, svelte, astro, richtext, cli) is an isolated npm module.
• Source code (src/), tests (tests/ or __tests__), playground demos.
• Each has its own package.json, build/test scripts.
c. CLI Tool (packages/cli)
• Exposes command-line interface for Storyblok projects.
• Has its own build flow, internal commands, API calls to Storyblok services.
d. Development & Build Orchestrator
• NX: defines targets (build, test, lint, graph), computes affected packages, parallel execution, caching.
• monoblock-cli (tools/monoblok): admin helper for repo maintenance and migrations.
e. CI/CD
• GitHub Actions workflows triggered on push/PR: run pnpm install, pnpm nx affected:test/build, lint, then publish to npm.
• commitlint, release-it, publishing pipelines.
Relationships and Data Flow
• Developer Machine → pnpm install (root) → workspace packages are linked.
• Developer issues pnpm build/test via NX → NX resolves inter-package dependencies, runs tasks in correct order.
• monoblock-cli (tooling) ↔ repo for maintenance scripts.
• GitHub Actions → checks code, runs NX targets, on success publishes updated packages to npm registry.
• SDK packages → call out to external Storyblok Content Delivery API at runtime.
Architectural Patterns and Principles
• Monorepo with polytonic package grouping by functionality.
• Modular design: each SDK / integration is a standalone module.
• Shared development config (ESLint, TypeScript, Vitest, Cypress) at root and overridden per package.
• CI/CD as code: workflows defined in .github.
• Dependency graph visualization and incremental builds using NX.