0
# Storybook Channels
1

2
Storybook Channels is a communication library that provides an EventEmitter-like interface for sending and receiving events between different parts of the Storybook ecosystem, particularly between the Storybook Manager and Renderer. It supports multiple transport mechanisms including PostMessage for iframe communication and WebSocket for real-time development communication.
3

4
**Note**: This package is deprecated and serves as a shim that re-exports functionality from `storybook/internal/channels`. Users are encouraged to migrate to the internal API structure introduced in Storybook v8.
5

6
## Package Information
7

8
- **Package Name**: @storybook/channels
9
- **Package Type**: npm
10
- **Language**: TypeScript
11
- **Installation**: `npm install @storybook/channels`
12

13
## Core Imports
14

15
```typescript
16
import { Channel, PostMessageTransport, WebsocketTransport, createBrowserChannel, HEARTBEAT_INTERVAL, HEARTBEAT_MAX_LATENCY } from "@storybook/channels";
17
```
18

19
For CommonJS:
20

21
```javascript
22
const { Channel, PostMessageTransport, WebsocketTransport, createBrowserChannel, HEARTBEAT_INTERVAL, HEARTBEAT_MAX_LATENCY } = require("@storybook/channels");
23
```
24

25
## Basic Usage
26

27
```typescript
28
import { createBrowserChannel, Channel } from "@storybook/channels";
29

30
// Create a browser channel with default transports
31
const channel = createBrowserChannel({ page: 'manager' });
32

33
// Listen for events
34
channel.addListener('story-changed', (data) => {
35
  console.log('Story changed:', data);
36
});
37

38
// Emit events
39
channel.emit('story-selected', { storyId: 'example-story' });
40

41
// Manual channel creation with custom transport
42
const customChannel = new Channel({
43
  transport: new PostMessageTransport({ page: 'manager' })
44
});
45
```
46

47
## Architecture
48

49
Storybook Channels is built around several key components:
50

51
- **Channel Class**: Core EventEmitter-like interface for event management with support for multiple transports
52
- **Transport System**: Pluggable transport mechanisms (PostMessage, WebSocket) for different communication scenarios
53
- **Factory Functions**: Convenience functions like `createBrowserChannel` for common setups
54
- **Type Safety**: Full TypeScript support with comprehensive type definitions for events and handlers
55

56
## Capabilities
57

58
### Core Channel Functionality
59

60
Event management and communication coordination through a single Channel interface that works with multiple transport mechanisms.
61

62
```typescript { .api }
63
class Channel {
64
  constructor(input: ChannelArgs);
65
  readonly isAsync: boolean;
66
  hasTransport: boolean;
67
  
68
  addListener(eventName: string, listener: Listener): void;
69
  emit(eventName: string, ...args: any): void;
70
  removeListener(eventName: string, listener: Listener): void;
71
  once(eventName: string, listener: Listener): void;
72
  removeAllListeners(eventName?: string): void;
73
}
74

75
type ChannelArgs = ChannelArgsSingle | ChannelArgsMulti;
76

77
interface ChannelArgsSingle {
78
  transport?: ChannelTransport;
79
  async?: boolean;
80
}
81

82
interface ChannelArgsMulti {
83
  transports: ChannelTransport[];
84
  async?: boolean;
85
}
86
```
87

88
[Channel API](./channel.md)
89

90
### Transport Mechanisms
91

92
Communication transports for different environments including PostMessage for iframe communication and WebSocket for real-time development.
93

94
```typescript { .api }
95
class PostMessageTransport {
96
  constructor(config: Config);
97
  setHandler(handler: ChannelHandler): void;
98
  send(event: ChannelEvent, options?: any): Promise<any>;
99
}
100

101
class WebsocketTransport {
102
  constructor(args: WebsocketTransportArgs);
103
  setHandler(handler: ChannelHandler): void;
104
  send(event: any): void;
105
}
106

107
interface Config {
108
  page: 'manager' | 'preview';
109
}
110
```
111

112
[Transport Systems](./transports.md)
113

114
### Factory Functions and Utilities
115

116
Convenience functions for creating configured channels and utility functions for common operations.
117

118
```typescript { .api }
119
function createBrowserChannel(options: Options): Channel;
120

121
interface Options {
122
  page: 'manager' | 'preview';
123
  extraTransports?: ChannelTransport[];
124
}
125
```
126

127
[Factory Functions](./factory.md)
128

129
## Core Types
130

131
```typescript { .api }
132
interface ChannelEvent {
133
  type: string;
134
  from: string;
135
  args: any[];
136
}
137

138
interface ChannelTransport {
139
  send(event: ChannelEvent, options?: any): void;
140
  setHandler(handler: ChannelHandler): void;
141
}
142

143
type ChannelHandler = (event: ChannelEvent) => void;
144

145
interface Listener {
146
  (...args: any[]): void;
147
}
148

149
interface EventsKeyValue {
150
  [key: string]: Listener[];
151
}
152

153
interface BufferedEvent {
154
  event: ChannelEvent;
155
  resolve: (value?: any) => void;
156
  reject: (reason?: any) => void;
157
}
158

159
/** WebSocket heartbeat interval in milliseconds (15000ms = 15 seconds) */
160
const HEARTBEAT_INTERVAL: number; // 15000
161

162
/** Maximum WebSocket heartbeat latency in milliseconds (5000ms = 5 seconds) */
163
const HEARTBEAT_MAX_LATENCY: number; // 5000
164

165
/** PostMessage transport key identifier for message routing */
166
const KEY: string; // 'storybook-channel'
167
```