A monorepo containing packages for cross-origin communication between Window contexts, built on the postMessage API.
This repository provides TypeScript libraries for establishing and maintaining bidirectional communication between parent and child Window contexts (such as iframes and popups). It's designed to handle one-to-many connections with automatic connection management, heartbeat monitoring, and type-safe message passing.
The core library for one-to-many cross-origin communication between Window contexts.
Key Features:
- 🔄 Automatic connection establishment and recovery
- 💓 Heartbeat monitoring for connection health
- 🎯 Type-safe message passing with TypeScript
- 📡 Request/response pattern support
- 🔌 One-to-many channel management
- 🛡️ Origin validation for security
Installation:
npm install @sanity/comlinkQuick Example:
// Parent window
import {createController} from '@sanity/comlink'
const controller = createController({targetOrigin: 'https://child-origin.com'})
const channel = controller.createChannel({name: 'parent', connectTo: 'child'})
channel.post('greeting', {message: 'Hello!'})
// Child window
import {createNode} from '@sanity/comlink'
const node = createNode({name: 'child', connectTo: 'parent'})
node.on('greeting', (data) => console.log(data.message))This package is used internally by:
sanity/presentation@sanity/visual-editing@sanity/core-loadernext-sanity/live@sanity/svelte-loader@sanity/react-loader
This is a monorepo managed with pnpm workspaces and Turborepo.
- Node.js >= 18 (Node.js 22 required for playground app)
- pnpm 10.18.2
# Install pnpm if you don't have it
npm install -g [email protected]
# Install dependencies
pnpm install
# Build all packages
pnpm build
# Run tests
pnpm test
# Run linter
pnpm lint
# Format code
pnpm format
# Type check
pnpm type-check# Watch mode for development (also runs the playground app)
pnpm devThe playground app is also deployed to Vercel and available at https://comlink-playground.sanity.dev/
.
├── apps/
│ └── playground/ # Example application for testing
├── packages/
│ ├── comlink/ # Core communication library
│ └── presentation-comlink/ # Sanity-specific utilities
└── .changeset/ # Changeset configuration for releases
This repository uses Changesets for version management and publishing.
To release a new version:
- Create a changeset describing your changes:
pnpm changeset add
- Open a PR with your changes and the changeset
- Once merged, a "Version Packages" PR will be automatically created
- Merge the "Version Packages" PR to publish the new version
Controllers manage one or more Channels that communicate with Nodes in child windows. Each Channel can connect to multiple Nodes across different Window contexts.
┌───────────────────────────────┐
│ Parent Window │
│ │
│ ┌──────────┐ │
│ │Controller│ │
│ └────┬─────┘ │
│ │ │
│ ┌────▼──────┐ ┌──────────┐ │
│ │ Channel 1 │ │Channel 2 │ │
│ └─────┬─────┘ └────┬─────┘ │
└────────┼─────────────┼────────┘
│ │
┌────▼────┐ ┌────▼───┐
│ iframe │ │ popup │
│ Node │ │ Node │
└─────────┘ └────────┘
Connections progress through the following states:
idle→handshaking→connected→disconnected
Contributions are welcome! Please read the code and follow existing patterns when contributing.
- All code must pass TypeScript type checking
- Follow existing code style (enforced by Prettier)
- Ensure linter passes (oxlint with type-aware checks)
- Add tests for new functionality
MIT License © 2016-2025 Sanity.io
See LICENSE for more details.
- @sanity/visual-editing - Visual editing tools for Sanity
- sanity - The Sanity Studio and toolkit