PostMessage RPC

A professional postMessage-based RPC library that creates and maintains secure communication between window objects, like a web page and an iframe inside it.

A fork of Chamaileon's original plugin-interface, enhanced and maintained independently with TypeScript-first approach and modern tooling.

Key Features

• 🔒 Secure by Default - Message validation, origin checking, and iframe isolation prevent XSS attacks
• 📝 TypeScript First - Full type safety with comprehensive type definitions
• 🔄 Bidirectional - Parent ↔ Plugin two-way communication with async/await support
• ⚡ Easy to Use - Simple API: initialize parent, provide plugin, start communicating
• 🎣 Hooks System - Event-driven callbacks from plugin to parent
• 🎨 Multiple Modes - Fullscreen overlay or inline iframe plugins

Installation

npm install @micskeil/postmessage-rpc
Copy

Quick Start

Parent Side (Initialize Plugin)

import { initInlinePlugin } from '@micskeil/postmessage-rpc';

const plugin = await initInlinePlugin(
  {
    data: { userId: 123 },
    settings: { theme: 'dark' },
    hooks: {
      onSave: async (data) => {
        console.log('Saved:', data);
      }
    }
  },
  {
    src: 'https://your-plugin-url.com',
    container: document.getElementById('plugin-container'),
    timeout: 5000
  }
);

// Call plugin methods
const result = await plugin.methods.getData();

// Cleanup
plugin.destroy();
Copy

Plugin Side (Register with Parent)

import { providePlugin } from '@micskeil/postmessage-rpc';

const { data, settings, hooks } = await providePlugin({
  hooks: ['onSave', 'onClose'],
  methods: {
    getData: async () => {
      return { status: 'ok', data: myData };
    },
    setTheme: async (theme) => {
      applyTheme(theme);
      return { success: true };
    }
  },
  validator: ({ data, settings }) => {
    if (!data.userId) throw new Error('User ID is required');
  }
});

// Use data and settings from parent
console.log('Initialized with:', data, settings);

// Call parent hooks
await hooks.onSave({ content: 'Updated' });
Copy

Core Concepts

Inline Plugins

Embedded iframes within your page layout. Perfect for cards, widgets, or multiple instances.

import { initInlinePlugin } from '@micskeil/postmessage-rpc';
const plugin = await initInlinePlugin(config, options);
Copy

Fullscreen Plugins

Modal-style overlays that cover the entire viewport with show/hide animations and optional splash screens.

import { initFullscreenPlugin } from '@micskeil/postmessage-rpc';
const plugin = await initFullscreenPlugin(config, options);
plugin.show();   // Animate in
plugin.hide();   // Animate out
Copy

Use Cases

• Email editors with preview plugins
• Content management systems with widget plugins
• Dashboard applications with chart/analytics plugins
• Design tools with component library plugins
• Micro-frontend architecture
• Any scenario requiring sandboxed, communicating components

Documentation

• 📖 API Documentation - Auto-generated TypeScript API reference
• 🎮 Live Examples - Interactive sticky notes demo
• 💻 GitHub Repository - View source code and contribute

Examples

The repository includes an interactive sticky notes demo demonstrating:

• Multiple inline plugins on the same page
• Fullscreen editor plugin with animations
• localStorage persistence
• Parent-plugin bidirectional communication
• CRUD operations through the plugin interface

Run the examples:

npm install
npm run examples
Copy

Then open your browser to http://localhost:8765/examples/

Contributing

Contributions are welcome! Please see GitHub Issues to report bugs or request features.

Development Workflow

1. Fork and clone the repository
2. Create a feature branch: git checkout -b feat/my-feature
3. Make your changes and run tests: npm test
4. Lint and build: npm run lint-fix && npm run build
5. Submit a pull request

Development Commands

npm run dev           # Development server with hot reload
npm run build         # Build the library
npm run test          # Run tests with coverage
npm run test:watch    # Watch mode
npm run lint-fix      # Lint and auto-fix
Copy

CI/CD Pipeline

GitHub Actions automatically:

• Runs linting, type-checking, and tests on pull requests
• Publishes to npm on version tags
• Deploys API documentation to GitHub Pages
• Creates GitHub releases with changelogs

License

MIT - See LICENSE file for details.

---

Fork of Chamaileon's original plugin-interface | View on NPM