Installation

npm install @storyblok/live-preview
# or
yarn add @storyblok/live-preview

Usage

Live preview

Covers the most common live preview use cases with minimal setup.

import { onStoryblokEditorEvent } from "@storyblok/live-preview";

const stopListening = await onStoryblokEditorEvent((story) => {
  // update local state
});

// later — e.g. on component teardown
stopListening();

Every call on a page shares one bridge instance: relation options are unioned, and scalar options (customParent, resolveLinks, fallbackLang) use first-wins semantics among the subscribers currently active. preventClicks is the one exception: any active subscriber requesting true wins regardless of subscribe order. Outside the Visual Editor, the call is a no-op and resolves to a cleanup function that does nothing.

A subscribe or unsubscribe only rebuilds the shared bridge when the merged options actually change — an already-covered relation, or an empty {}, does not. Calls made synchronously in the same tick (or that arrive while the bridge module is still loading) share a single build; a call that lands after that window triggers a full teardown and rebuild of the shared bridge instead, briefly leaving the page with no attached bridge. Prefer batching known subscriptions upfront (e.g. with Promise.all) when possible.

Cleaning up a subscription immediately stops its own options from being merged in, and — if other subscriptions remain and the retraction changes the merge — rebuilds the live bridge to reflect it, so a departed subscriber's preventClicks/relation/scalar contribution stops applying right away rather than lingering until some unrelated future subscribe/unsubscribe.

Low-level Preview Bridge access

For advanced use cases where full control is needed, the Preview Bridge can be accessed directly.

import { loadStoryblokBridge } from "@storyblok/live-preview";

const bridge = await loadStoryblokBridge(bridgeOptions);

bridge.on(["input", "change", "published"], (event) => {
  // custom preview handling
});

Documentation

This package is intentionally minimal. More helpers and examples will be added over time as usage expands.

Community

For help, best practices, or discussions:

• Storyblok GitHub Discussions
• Join the Storyblok Discord

Support

For bugs or feature requests, please submit an issue.

License

MIT