Storyblok CMS

This package provides a Storyblok CMS integration for Gesso CMS.

Installation

• pnpm install

Configuration

• Create a .env file in the root of the project based on example.env
• The STORYBLOK_OAUTH_TOKEN is a personal access token from Account Settings → Personal access tokens in the Storyblok app. It is required for any CLI command that pulls or pushes component schemas.
• The Gesso space is in the EU region, so every CLI command needs --region eu. The CLI defaults to EU.

Usage

• pnpm test to run the tests
• pnpm lint to lint the code

Storyblok Component Exports (exports/)

This package contains exports of the components defined in the Gesso Storyblok space. They are a starting point for new Storyblok projects — importing them gives a project the same set of components and content types that Gesso's Component Factory expects, similar to Paragraphs in Drupal.

The Storyblok CLI v4+ writes per-component files under a nested layout:

exports/
├── components/
│   └── <space-id>/
│       ├── <component>.json       # one file per component schema
│       ├── groups.json            # component groups metadata
│       ├── card.presets.json      # card presets
│       └── tags.json              # internal tags metadata (NOT the `tags` component schema — see caveat below)
└── logs/
    └── <space-id>/                # CLI run logs

Authentication

Authenticate the CLI once and credentials are saved to ~/.storyblok/credentials.json:

pnpx storyblok login --region us

Pick "Login with Token" and paste your personal access token.

Pulling components from a Storyblok space

Pull every component schema from the space into per-component files:

pnpx storyblok --path "packages/plugins/storyblok/exports" --region us components pull -s <space_id> --sf

Flag	Why
--path	Global option — must come before the subcommand. The CLI auto-nests under <path>/components/<space-id>/.
--region us	Required — Gesso spaces are in the US region.
components pull	The subcommand.
-s <space_id>	The Storyblok space to pull from.
--sf	"Separate files" — one JSON per component. Without this, all components end up in one bundled file.

Pushing components to a Storyblok space

Push from this package into a target space:

pnpx storyblok --path "packages/plugins/storyblok/exports" --region us components push -s <space_id> --sf

To push only a subset, use the --filter glob:

pnpx storyblok --path "packages/plugins/storyblok/exports" --region us components push -s <space_id> --sf --filter "section"
pnpx storyblok --path "packages/plugins/storyblok/exports" --region us components push -s <space_id> --sf --filter "card*"

Push behavior

• Push is non-destructive on schema fields: fields that exist in the target space but not in the local file are kept, not deleted. (Verified empirically; not documented.)
• No dry-run mode exists for components push (it's available for assets and stories only). Push to a sandbox space first to verify before pushing to production.
• Component-name clashes are not handled: if a component or group with the same name already exists with significant differences, manual cleanup may be needed in the Storyblok UI.

Spaces reference

Space	ID	Purpose
Gesso (production)	1020994	Canonical Gesso space — pull authoritative state from here, push only verified changes.
Gesso Sandbox	1021599	Sandbox space — safe to push experimental changes for testing.