schema push

Loads the schema exported from <entry-file>, fetches the current remote state of a Storyblok space, prints a diff, and applies the changes through the Management API. Each successful run saves a changeset file under the configured base path so the push can be reverted later with schema rollback.

The entry file must export a schema object of the shape { blocks, folders?, datasources?, fieldPlugins? }, identical to the shape consumed by defineSchema() and the Schema<typeof schema> type in @storyblok/schema:

import { defineSchema } from "@storyblok/schema";
import type { Schema as InferSchema } from "@storyblok/schema";
import { pageBlock, heroBlock } from "./blocks";
import { layoutFolder } from "./folders";
import { colorsDatasource } from "./datasources";

export const schema = defineSchema({
  blocks: { pageBlock, heroBlock },
  folders: { layoutFolder },
  datasources: { colorsDatasource },
});

export type Schema = InferSchema<typeof schema>;

Prerequisites

• An entry file that exports a schema object authored with @storyblok/schema.

Breaking changes and migrations

When a push contains breaking changes (field removals, type changes, or renames), the command analyzes them and, unless --no-migrations is set, generates scaffold migration files. The command confirms detected renames interactively. The generated migrations are scaffolds: review them before running migrations run.

With --dry-run, the command prints the analysis but does not write migration files.

Changesets

Every non-dry-run push writes a changeset file capturing the diff and the pre-push remote state. The changeset is the input consumed by schema rollback.

Local component files

With --write-components (the default), schema push writes each component schema to disk after a successful push, even when nothing changed. This keeps a fresh checkout in sync without requiring an extra components pull step. Pair the flag with --delete to also remove the local files of stale components — those removed from the local schema and deleted from the space by --delete.

Datasources and entries

schema push owns datasource definitions: it creates, updates, and (with --delete) removes datasources in the space. Use datasources push to sync entries after the datasource definition exists.

Usage

storyblok schema push <entry-file> [flags]

Arguments

Argument	Type	Description
Entry file	string	Required. Path to the TypeScript file that exports the schema object.

Flags

Flag	Type	Description
--space, -s	integer	Required. The ID of the Storyblok space to push the schema to.
--path, -p	string	Optional. Base path for changeset and migration files.
--dry-run	boolean	Optional. Show diffs without applying changes.
--delete	boolean	Optional. Delete remote entities that are not present in the local schema. Stories using deleted components will end up with out-of-schema content.
--migrations	boolean	Optional. Generate scaffold migration files for breaking changes. Enabled by default. Pass --no-migrations to skip.
--write-components	boolean	Optional. Write component schemas as local JSON files after push, and remove the files of components deleted via --delete. Enabled by default. Pass --no-write-components to skip.

Examples

The following examples assume that a space has been defined in a configuration file.

# Push the local schema to a space
storyblok schema push src/schema/schema.ts
# Preview the diff without applying changes
storyblok schema push src/schema/schema.ts --dry-run
# Push and delete remote entities not present locally
storyblok schema push src/schema/schema.ts --delete