@pactwork/storybook-addon

Storybook addon for Pactwork - Control API scenarios, latency, and network states directly from stories

Features

• Toolbar Controls - Scenario picker, latency presets, and network state toggle directly in Storybook's top toolbar
• Scenario Selection - Switch between API response scenarios in stories via parameters
• Latency Control - Add artificial delay to simulate slow networks (None, 200ms, 1s, 3s presets)
• Network Simulation - Test online, offline, and timeout states
• Addon Panel - Observability panel showing current state, request logs, and available handlers
• TypeScript Support - Full type safety with autocomplete for parameters
• CSF Factories - Storybook 10 compatible with definePreviewAddon

Requirements

• Storybook 10.x (ESM-only)
• Node.js >=20.11.0
• Pactwork 1.1.0+
• MSW 2.0+

Installation

npm install -D @pactwork/storybook-addon

Setup

1. Add to Storybook configuration

// .storybook/main.ts
import type { StorybookConfig } from '@storybook/react-vite';

const config: StorybookConfig = {
  addons: [
    '@storybook/addon-essentials',
    '@pactwork/storybook-addon', // Add pactwork addon
  ],
  // ... other config
};

export default config;

2. Initialize in preview.ts

// .storybook/preview.ts
import { initPactwork } from '@pactwork/storybook-addon';
import { handlers, handlerMeta, scenarios } from '../mocks';
import { worker } from '../mocks/browser';

// Start MSW worker
await worker.start({ onUnhandledRequest: 'bypass' });

// Initialize pactwork addon
initPactwork(worker, {
  handlers,
  handlerMeta,
  scenarios,
  debug: true, // Optional: log transformations to console
});

export default {
  // ... your preview config
};

3. (Alternative) CSF Factories Setup

For Storybook 10's recommended CSF Factories pattern:

// .storybook/preview.ts
import pactworkAddon from '@pactwork/storybook-addon';
import { definePreview } from '@storybook/react';

export default definePreview({
  addons: [pactworkAddon()],
});

Usage

Story Parameters

Control API behavior per-story using parameters.pactwork:

// Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';

const meta: Meta<typeof Button> = {
  component: Button,
};

export default meta;
type Story = StoryObj<typeof Button>;

// Default story - uses normal API responses
export const Default: Story = {};

// Loading state - 2 second delay
export const Loading: Story = {
  parameters: {
    pactwork: {
      scenario: 'getUser.loading',
      latency: 2000,
    },
  },
};

// Error state
export const Error: Story = {
  parameters: {
    pactwork: {
      scenario: 'getUser.serverError',
    },
  },
};

// Not found state
export const NotFound: Story = {
  parameters: {
    pactwork: {
      scenario: 'getUser.notFound',
    },
  },
};

// Empty list
export const EmptyList: Story = {
  parameters: {
    pactwork: {
      scenario: 'listUsers.empty',
    },
  },
};

// Network timeout
export const NetworkTimeout: Story = {
  parameters: {
    pactwork: {
      networkError: 'timeout',
    },
  },
};

// Multiple scenarios
export const ComplexState: Story = {
  parameters: {
    pactwork: {
      scenarios: ['getUser.loading', 'listUsers.empty'],
      latency: 500,
    },
  },
};

Toolbar

When Storybook is running, you'll see a Pactwork icon in the top toolbar. Click it to open the controls dropdown:

• Scenario - Select from available scenarios or reset to default
• Latency - Quick presets: None, 200ms, 1s, 3s
• Network - Toggle between Online, Offline, and Timeout states
• Reset All - Clear all active transformations

The toolbar button shows a status summary when any transformation is active.

Addon Panel

The "Pactwork" tab in the addon panel provides observability:

• Current State - Shows active scenario, latency, and network state
• Request Log - Live log of intercepted API requests with method, path, status, and timing
• Handler List - View all available handlers and their scenario counts

API Reference

PactworkParameters

Property	Type	Description
scenario	string	Scenario to apply. Format: 'operationId.scenarioName'
scenarios	string[]	Multiple scenarios to apply simultaneously
latency	number | LatencyOptions	Delay in ms or { min, max } for random range
networkError	'timeout' | 'abort' | 'network-error'	Network error to simulate
operations	string[]	Specific operations to apply transformations to
disabled	boolean	Disable all pactwork transformations

initPactwork(worker, config)

Initialize the addon with your MSW worker and pactwork configuration.

initPactwork(worker, {
  handlers: HttpHandler[],      // MSW handlers from pactwork generate
  handlerMeta: HandlerMetaMap,  // Handler metadata for O(1) lookups
  scenarios: Record<string, ScenarioMap>, // Available scenarios by operationId
  defaultLatency?: number,      // Default latency for all handlers
  debug?: boolean,              // Log transformations to console
});

Exported Functions

Function	Description
initPactwork	Initialize addon with MSW worker and config
setWorker	Manually set MSW worker reference
setGlobalConfig	Manually set global configuration
getGlobalConfig	Get current global configuration
resetHandlers	Reset all handlers to original state
pactworkDecorator	The Storybook decorator instance

Channel Events

For advanced integrations, the addon uses these channel events:

Event	Direction	Description
pactwork/scenario-change	Toolbar → Preview	Scenario selection changed
pactwork/latency-change	Toolbar → Preview	Latency value changed
pactwork/network-change	Toolbar → Preview	Network state changed
pactwork/state-update	Preview → Panel	Current state updated
pactwork/handlers-ready	Preview → Toolbar/Panel	Handler info available
pactwork/reset	Toolbar → Preview	Reset all transformations

Storybook 10 Migration

This addon is built specifically for Storybook 10.x. Key changes from previous Storybook versions:

Change	Before (SB 8/9)	After (SB 10)
Module format	CJS + ESM dual	ESM-only
Entry points	exportEntries	previewEntries + managerEntries
Path resolution	require.resolve()	import.meta.resolve()
Addon export	Manual annotations	definePreviewAddon()
Node target	18.0	20.19+

Upgrading from MSW addon

If you're migrating from msw-storybook-addon:

// Before (msw-storybook-addon)
export const handlers = [
  http.get('/api/user', () => HttpResponse.json({ name: 'John' })),
];

// After (pactwork)
// 1. Generate handlers with pactwork CLI
npx pactwork generate --spec openapi.yaml --output ./mocks

// 2. Use generated handlers with scenarios
import { handlers, handlerMeta, scenarios } from './mocks';

// 3. Configure addon
initPactwork(worker, { handlers, handlerMeta, scenarios });

// 4. Use scenarios in stories
parameters: {
  pactwork: { scenario: 'getUser.notFound' }
}

Troubleshooting

Panel not showing handlers

Make sure initPactwork is called after worker.start() in preview.ts.

Scenarios not applying

Check that the scenario string matches the format operationId.scenarioName exactly.

TypeScript errors

Ensure you have the correct peer dependencies:

npm install -D storybook@^10.0.0 msw@^2.0.0 pactwork@^1.1.0

ESM errors

This package is ESM-only. Make sure your project supports ES modules:

// package.json
{
  "type": "module"
}

License

MIT