0
# Storybook Channel PostMessage
1

2
Storybook Channel PostMessage is a deprecated PostMessage channel implementation for Storybook that facilitates communication when the Storybook renderer operates within an iframe or child window. This package serves as a compatibility layer that redirects to the newer `@storybook/channels` implementation, providing seamless cross-window event transmission between Storybook manager and preview environments.
3

4
## Package Information
5

6
- **Package Name**: @storybook/channel-postmessage
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @storybook/channel-postmessage`
10
- **Status**: Deprecated - scheduled for removal in v8.0
11

12
## Core Imports
13

14
```typescript
15
import { createChannel } from "@storybook/channel-postmessage";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const { createChannel } = require("@storybook/channel-postmessage");
22
```
23

24
**Migration Notice**: This package emits deprecation warnings. Import from `@storybook/channels` instead:
25

26
```typescript
27
import { createPostMessageChannel } from "@storybook/channels";
28
```
29

30
## Basic Usage
31

32
```typescript
33
import { createChannel } from "@storybook/channel-postmessage";
34

35
// Create a channel for manager context
36
const managerChannel = createChannel({ page: 'manager' });
37

38
// Create a channel for preview context  
39
const previewChannel = createChannel({ page: 'preview' });
40

41
// Listen for events
42
managerChannel.on('story-changed', (event) => {
43
  console.log('Story changed:', event);
44
});
45

46
// Emit events
47
managerChannel.emit('request-story', { storyId: 'example' });
48
```
49

50
## Capabilities
51

52
### Channel Creation
53

54
Creates a PostMessage-based channel for cross-window communication in Storybook environments.
55

56
```typescript { .api }
57
/**
58
 * Creates a channel instance with PostMessage transport
59
 * @deprecated Use createPostMessageChannel from @storybook/channels instead
60
 * @param config - Configuration specifying the page context
61
 * @returns Channel instance for event communication
62
 */
63
function createChannel(config: Config): Channel;
64

65
interface Config {
66
  /** Specifies whether this is running in manager or preview context */
67
  page: 'manager' | 'preview';
68
}
69
```
70

71
### PostMessage Transport
72

73
Low-level transport implementation for PostMessage-based communication.
74

75
```typescript { .api }
76
/**
77
 * Transport implementation for postMessage-based communication
78
 * Handles buffering, frame detection, and message routing
79
 */
80
class PostMessageTransport implements ChannelTransport {
81
  constructor(config: Config);
82
  
83
  /** Sets the event handler for incoming messages */
84
  setHandler(handler: ChannelHandler): void;
85
  
86
  /** Sends event to associated window, buffering if window not available */
87
  send(event: ChannelEvent, options?: any): Promise<any>;
88
}
89

90
/**
91
 * @deprecated Use PostMessageTransport instead
92
 */
93
class PostmsgTransport extends PostMessageTransport {}
94
```
95

96
### Channel Communication
97

98
Core channel class providing event-based communication with transport abstraction.
99

100
```typescript { .api }
101
/**
102
 * Core channel class for event communication
103
 * Provides EventEmitter-like interface with transport abstraction
104
 */
105
class Channel {
106
  constructor(input: ChannelArgs);
107
  
108
  /** Whether channel operates asynchronously */
109
  readonly isAsync: boolean;
110
  
111
  /** Whether channel has transport configured */
112
  get hasTransport(): boolean;
113
  
114
  /** Add event listener */
115
  addListener(eventName: string, listener: Listener): void;
116
  
117
  /** Emit event to all listeners and transports */
118
  emit(eventName: string, ...args: any): void;
119
  
120
  /** Get data from last event of given type */
121
  last(eventName: string): any;
122
  
123
  /** Get all registered event names */
124
  eventNames(): string[];
125
  
126
  /** Get number of listeners for event */
127
  listenerCount(eventName: string): number;
128
  
129
  /** Get listeners array for event */
130
  listeners(eventName: string): Listener[] | undefined;
131
  
132
  /** Add one-time event listener */
133
  once(eventName: string, listener: Listener): void;
134
  
135
  /** Remove all listeners for event or all events */
136
  removeAllListeners(eventName?: string): void;
137
  
138
  /** Remove specific listener */
139
  removeListener(eventName: string, listener: Listener): void;
140
  
141
  /** Alias for addListener */
142
  on(eventName: string, listener: Listener): void;
143
  
144
  /** Alias for removeListener */
145
  off(eventName: string, listener: Listener): void;
146
}
147
```
148

149
### Event Source Utilities
150

151
Utility function for determining the source of PostMessage events.
152

153
```typescript { .api }
154
/**
155
 * Determines the source URL of a message event from iframe elements
156
 * @param event - MessageEvent to analyze
157
 * @returns Source URL or null if unable to determine
158
 */
159
function getEventSourceUrl(event: MessageEvent): string | null;
160
```
161

162
## Types
163

164
```typescript { .api }
165
/** Transport interface for channel communication */
166
interface ChannelTransport {
167
  send(event: ChannelEvent, options?: any): void;
168
  setHandler(handler: ChannelHandler): void;
169
}
170

171
/** Channel event structure */
172
interface ChannelEvent {
173
  /** Event name/type */
174
  type: string;
175
  /** Event sender identifier */
176
  from: string;
177
  /** Event arguments */
178
  args: any[];
179
}
180

181
/** Event handler function type */
182
type ChannelHandler = (event: ChannelEvent) => void;
183

184
/** Event listener function type */
185
interface Listener {
186
  (...args: any[]): void;
187
}
188

189
/** Event buffering structure for disconnected state */
190
interface BufferedEvent {
191
  event: ChannelEvent;
192
  resolve: (value?: any) => void;
193
  reject: (reason?: any) => void;
194
}
195

196
/** Channel constructor arguments - single transport */
197
interface ChannelArgsSingle {
198
  transport?: ChannelTransport;
199
  async?: boolean;
200
}
201

202
/** Channel constructor arguments - multiple transports */  
203
interface ChannelArgsMulti {
204
  transports: ChannelTransport[];
205
  async?: boolean;
206
}
207

208
/** Union type for channel constructor arguments */
209
type ChannelArgs = ChannelArgsSingle | ChannelArgsMulti;
210

211
/** Map of event names to listener arrays */
212
interface EventsKeyValue {
213
  [key: string]: Listener[];
214
}
215
```
216

217
## Constants
218

219
```typescript { .api }
220
/** Message key identifier for Storybook channel messages */
221
const KEY: string = 'storybook-channel';
222
```
223

224
## Migration Guide
225

226
This package is deprecated. To migrate to the current API:
227

228
**Old (deprecated):**
229
```typescript
230
import { createChannel } from '@storybook/channel-postmessage';
231
const channel = createChannel({ page: 'manager' });
232
```
233

234
**New (recommended):**
235
```typescript
236
import { createPostMessageChannel } from '@storybook/channels';
237
const channel = createPostMessageChannel({ page: 'manager' });
238
```
239

240
The API is identical, only the import path changes.