This package handles communication between the Studio platform and the iframe webpage.
npm install @contentstack/studio-messengerA communication package that handles messaging between the Studio platform and iframe webpages using postMessage API.
Table of Contents
- Studio Messenger
- Overview
- Features
- Installation
- Usage
- Basic Setup
- Available Event Managers
- Sending Messages
- Listening for Messages
- API Reference
- Constants
- Channel IDs
- Query Parameters
- Event Types
- Studio Events (POST_MESSAGE_EVENTS)
- Visual Builder Events (VISUAL_BUILDER_POST_MESSAGE_EVENTS)
- Built-in Canvas Events (COMPOSABLE_STUDIO_BUILT_IN_CANVAS_POST_MESSAGE_EVENTS)
- Event Data Types
- Development
- Building
- Development Mode
- Linting
- Architecture
- Channel Flow
This package provides a robust messaging system for communication between different parts of the Studio ecosystem:
- Studio - The main editing interface
- Visual Builder - The visual editing interface
- Built-in Canvas - Embedded canvas components
- Popup Windows - Modal dialogs and popups
- Bidirectional Communication - Send and receive messages between iframes and parent windows
- Multiple Channels - Separate communication channels for different contexts
- Type Safety - Full TypeScript support with typed event data
- Event Management - Built on @contentstack/advanced-post-message for reliable messaging
- Debug Support - Optional debug mode for development
``bash`
npm install @contentstack/studio-messenger
The package automatically initializes event managers when loaded in a browser environment:
`typescript`
import {
composableStudioEventManager,
visualBuilderEventManager,
composableStudioPopupEventManager,
composableStudioBuiltInCanvasEventManager
} from '@contentstack/studio-messenger';
- composableStudioEventManager - Main Studio communicationvisualBuilderEventManager
- - Visual Builder communicationcomposableStudioPopupEventManager
- - Popup window communicationcomposableStudioBuiltInCanvasEventManager
- - Built-in canvas communication
`typescript
import { composableStudioEventManager, POST_MESSAGE_EVENTS } from '@contentstack/studio-messenger';
// Send a highlight node event
composableStudioEventManager?.emit(POST_MESSAGE_EVENTS.HIGHLIGHT_NODE, {
nodeId: 'my-node-id',
highlight: true
});
// Send a transform operation
composableStudioEventManager?.emit(POST_MESSAGE_EVENTS.TRANSFORM_OPERATION, {
operation: 'insert-node',
data: { / operation data / }
});
`
`typescript
import { visualBuilderEventManager, VISUAL_BUILDER_POST_MESSAGE_EVENTS } from '@contentstack/studio-messenger';
// Listen for composition saved events
visualBuilderEventManager?.on(VISUAL_BUILDER_POST_MESSAGE_EVENTS.COMPOSITION_SAVED, (data) => {
console.log('Composition saved:', data);
// Handle the saved composition
});
`
#### Channel IDs
- COMPOSABLE_STUDIO_CHANNEL_ID - Main Studio channelVISUAL_BUILDER_CHANNEL_ID
- - Visual Builder channelCOMPOSABLE_STUDIO_POPUP_CHANNEL_ID
- - Popup channelCOMPOSABLE_STUDIO_BUILT_IN_CANVAS_CHANNEL_ID
- - Built-in canvas channel
#### Query Parameters
- COMPOSABLE_STUDIO_QUERY_PARAM - Available query parameters for configuration
#### Studio Events (POST_MESSAGE_EVENTS)HIGHLIGHT_NODE
- - Highlight/unhighlight nodesSET_ACTIVE_NODE
- - Set the currently active nodeTRANSFORM_OPERATION
- - Apply transformations to nodesREGISTER_COMPONENTS
- - Register new componentsGET_NODE_STYLE
- - Retrieve node stylesUPDATE_DATA_SOURCE
- - Update data sourcesAPPLY_OPERATION
- - Apply operationsGET_ACTIVE_BREAKPOINT
- - Get current breakpointREGISTER_BREAKPOINTS
- - Register breakpoint definitionsSET_CURSOR_TYPE
- - Set cursor typeHIGHLIGHT_SLOT_NODE
- - Highlight slot nodesUPDATE_BINDING_ERRORS
- - Update binding validation errorsHIDDEN_COMPONENT_NOTIFICATION
- - Notify about hidden components
#### Visual Builder Events (VISUAL_BUILDER_POST_MESSAGE_EVENTS)REFETCH_SPEC
- - Request spec refetchCOMPOSITION_SAVED
- - Composition save notificationOPEN_IN_COMPOSABLE_STUDIO_EVENT_MESSAGE
- - Open in Studio
#### Built-in Canvas Events (COMPOSABLE_STUDIO_BUILT_IN_CANVAS_POST_MESSAGE_EVENTS)REQUEST_FOR_COMPOSITION_CONFIG
- - Request composition configuration
`typescript
interface OpenComposableStudioFromVBEventData {
compositionEntryUid: string;
windowFeatures?: string;
fetchCompositionData: FetchCompositionData | null;
}
interface CompositionSavedEventData {
entryUid: string;
contentTypeUid: string;
locale: string;
}
interface HiddenElementNotificationEventData {
action: "open" | "close";
uid: "__all__" | string;
}
`
`bash`
npm run build
`bash`
npm run dev
`bash`
npm run lint
npm run lint:fix
The package uses a singleton pattern to manage event managers across the application. Each manager is stored in window.__csMessengerListeners__ to ensure consistent communication channels.
```
Studio ↔ Visual Builder
↕
Built-in Canvas
↕
Popup Windows