Communicate with iframes like sending HTTP requests
npm install request-iframeCommunicate with iframes/windows like sending HTTP requests! A cross-origin browser communication library based on postMessage.
> π Languages: English | δΈζ
- Why request-iframe?
- Features
- Installation
- Quick Start
- Use Cases
- How It Works
- Communication Protocol
- Message Types
- Timeout Mechanism
- Protocol Version
- Detailed Features
- Interceptors
- Middleware
- Headers and Cookies
- File Transfer
- Streaming
- Connection Detection
- Response Acknowledgment
- Trace Mode
- Internationalization
- API Reference
- React Hooks
- useClient
- useServer
- useServerHandler
- useServerHandlerMap
- Complete Example
- Best Practices
- Error Handling
- FAQ
- Development
- License
In micro-frontend, iframe nesting, and popup window scenarios, cross-page communication is a common requirement. Traditional postMessage communication has the following pain points:
| Pain Point | Traditional Way | request-iframe |
|------------|----------------|----------------|
| Request-Response Association | Manual requestId management | Automatic management, Promise style |
| Timeout Handling | Manual timer implementation | Built-in multi-stage timeout mechanism |
| Error Handling | Various edge cases | Standardized error codes |
| Message Isolation | Easy to cross-talk | secretKey automatic isolation |
| API Style | Event listener style | HTTP-like request/Express style |
| TypeScript | Need custom types | Full type support |
| Test Coverage | None | 76%+ test coverage |
Core Advantages:
- β
Zero Learning Curve - If you're familiar with axios and Express, you can get started immediately
- β
Type Safe - Full TypeScript support for a great development experience
- β
Production Ready - High test coverage, thoroughly tested
- β
Feature Rich - Interceptors, middleware, streaming, file transfer all included
- π HTTP-like Style - Client sends requests, Server handles and responds, just like axios + express
- π Interceptor Support - Request/response interceptors for unified authentication, logging, etc.
- π Middleware Mechanism - Express-style middleware with path matching support
- β±οΈ Smart Timeout - Three-stage timeout (connection/sync/async), automatically detects long tasks
- π¦ TypeScript - Complete type definitions and IntelliSense
- π Message Isolation - secretKey mechanism prevents message cross-talk between multiple instances
- π File Transfer - File transfer via streams (clientβserver)
- π Streaming - Support for large file chunked transfer, supports async iterators
- π§Ύ Leveled Logging - Warn/Error logs enabled by default; can be configured via trace level
- π Internationalization - Error messages can be customized for i18n
- β
Protocol Versioning - Built-in version control for upgrade compatibility
``bash`
npm install request-iframeor
yarn add request-iframeor
pnpm add request-iframe
Requirements: Node.js >= 14
TypeScript: Built-in complete type definitions, no need to install @types/request-iframe
This repo also builds script-tag friendly UMD bundles (core + react hooks) that can be hosted on a CDN.
- Core bundle output: cdn/request-iframe.umd(.min).js β global RequestIframecdn/request-iframe-react.umd(.min).js
- React bundle output: β global RequestIframeReact (requires React global and RequestIframe global)
Example (using unpkg):
`html