request-iframe

Communicate with iframes/windows like sending HTTP requests! A cross-origin browser communication library based on postMessage.

> 🌐 Languages: English | 中文

📑 Table of Contents

- 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

Why request-iframe?

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

Features

- 🚀 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

Installation

``bash
npm install request-iframe


or

yarn add request-iframe

or

pnpm add request-iframe
`

Requirements: Node.js >= 14

TypeScript: Built-in complete type definitions, no need to install @types/request-iframe

CDN (UMD bundles)

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 RequestIframe
- React bundle output: cdn/request-iframe-react.umd(.min).js → global RequestIframeReact (requires React global and RequestIframe global)

Example (using unpkg):

`html