Storybook Sync

Sync Storybook events with external clients over WebSockets.

Installation

pnpm add --save-dev addon-storybook-sync

Register the addon in .storybook/main.ts:

import type { StorybookConfig } from '@storybook/your-framework';

const config: StorybookConfig = {
  // ...
  addons: [
    {
      name: 'addon-storybook-sync',
      options: {
        host: 'localhost',
        port: 7007,
      },
    },
  ],
};

export default config;

The addon starts a WebSocket server in development mode at ws://localhost:7007.

Options

Pass options with the addon entry in .storybook/main.ts to override the host or port:

const config: StorybookConfig = {
  // ...
  addons: [
    {
      name: 'addon-storybook-sync',
      options: {
        host: '0.0.0.0',
        port: 7008,
      },
    },
  ],
};

Both options are optional. The string shorthand addons: ['addon-storybook-sync'] uses the defaults.

Option	Type	Default
host	string	'localhost'
port	number	7007

Development

Run the example Storybook and the addon build watcher together:

pnpm start

Storybook runs at http://localhost:6006 and loads the locally built preset, whose WebSocket server runs at ws://localhost:7007.

With the example running, send a story selection through the sync server:

pnpm test:sync

The script selects example-button--primary and waits for Storybook to broadcast the translated navigation events. Pass another story ID and optionally docs to test a different selection:

pnpm test:sync example-header--logged-in docs

Set STORYBOOK_SYNC_URL to test a server other than ws://localhost:7007.

Releasing

Add a changeset for every user-facing change:

pnpm changeset

On main, the release workflow maintains a version pull request. Merging that pull request publishes the package to npm through trusted publishing and creates the corresponding GitHub release. Configure npm's trusted publisher for the dannyhw/addon-storybook-sync repository and the release.yml workflow; no npm token is stored in GitHub.