Comctx: A Better Cross-Context Communication Library Than Comlink

John Wu — Fri, 25 Jul 2025 08:18:24 +0000

Comlink performs great for Web Worker communication, which is its main design goal. However, when you want to use it in other environments, you'll find the adaptation work extremely difficult.

I developed Comctx to solve this problem. It maintains Comlink's simple API while making environment adaptation easy through an adapter pattern.

What Problem Does It Solve

Comlink is primarily designed for Web Worker. While theoretically it can be adapted to other environments, the actual implementation is very difficult.

For example, in browser extensions, Content Script and Background Script can only communicate through the chrome.runtime API. If you want to use Comlink, you need to somehow wrap this API into MessagePort format, which is complex and error-prone. You have to rewrite Comlink's adapter code issue(438).

Similar problems exist in Electron and certain restricted environments. Every time you encounter a new environment, you need to do a complex set of adaptation work.

Comctx's approach is simple:

Don't restrict specific communication methods
Provide an adapter interface that lets you tell it how to send and receive messages
Handle all the RPC logic for you

This way, the same service code can be reused across various environments.

Where You Can Use It

1. Browser Extension Development

// Shared storage service
class StorageService {
  async get(key) {
    const result = await chrome.storage.local.get(key)
    return result[key]
  }

  async set(key, value) {
    await chrome.storage.local.set({ [key]: value })
  }

  async onChanged(callback) {
    chrome.storage.onChanged.addListener(callback)
  }
}

const [provideStorage, injectStorage] = defineProxy(() => new StorageService())

// Background Script (service provider)
class BackgroundAdapter {
  sendMessage = (message) => chrome.runtime.sendMessage(message)
  onMessage = (callback) => chrome.runtime.onMessage.addListener(callback)
}
provideStorage(new BackgroundAdapter())

// Content Script (service consumer)
const storage = injectStorage(new BackgroundAdapter())
await storage.set('userPrefs', { theme: 'dark' })
const prefs = await storage.get('userPrefs')

2. Web Worker Computation Tasks

// Image processing service
class ImageProcessor {
  async processImage(imageData, filters) {
    // Complex image processing algorithm
    return processedData
  }

  async onProgress(callback) {
    // Progress callback
  }
}

const [provideProcessor, injectProcessor] = defineProxy(() => new ImageProcessor())

// Worker side
class WorkerAdapter {
  sendMessage = (message) => postMessage(message)
  onMessage = (callback) => addEventListener('message', event => callback(event.data))
}
provideProcessor(new WorkerAdapter())

// Main thread
const processor = injectProcessor(new WorkerAdapter())
// Progress callback
processor.onProgress(progress => updateUI(progress))
// Processing result
const result = await processor.processImage(imageData, filters)

3. iframe Cross-Domain Communication

// Payment service (running in secure iframe)
class PaymentService {
  async processPayment(amount, cardInfo) {
    // Secure payment processing logic
    return paymentResult
  }

  async validateCard(cardNumber) {
    return isValid
  }
}

// Payment service inside iframe
class IframeAdapter {
  sendMessage = (message) => parent.postMessage(message, '*')
  onMessage = (callback) => addEventListener('message', event => callback(event.data))
}
provide(new IframeAdapter())

// Main page calling payment service
const payment = inject(new IframeAdapter())
const result = await payment.processPayment(100, cardInfo)

4. Electron Inter-Process Communication

// File operation service (providing file system access in main process)
class FileService {
  async readFile(path) {
    return fs.readFileSync(path, 'utf8')
  }

  async writeFile(path, content) {
    fs.writeFileSync(path, content)
  }

  async watchFile(path, callback) {
    fs.watchFile(path, callback)
  }
}

// Main process
class MainProcessAdapter {
  sendMessage = (message) => webContents.send('ipc-message', message)
  onMessage = (callback) => ipcMain.on('ipc-message', (_, data) => callback(data))
}
provide(new MainProcessAdapter())

// Renderer process
class RendererAdapter {
  sendMessage = (message) => ipcRenderer.send('ipc-message', message)
  onMessage = (callback) => ipcRenderer.on('ipc-message', (_, data) => callback(data))
}
const fileService = inject(new RendererAdapter())
const content = await fileService.readFile('/path/to/file')

5. Micro-Frontend Architecture

// Shared user authentication service
class AuthService {
  async login(credentials) { /* ... */ }
  async logout() { /* ... */ }
  async getCurrentUser() { /* ... */ }
  async onAuthStateChange(callback) { /* ... */ }
}

// Main app provides authentication service
class MicroFrontendAdapter {
  sendMessage = (message) => window.postMessage({ ...message, source: 'main-app' }, '*')
  onMessage = (callback) => {
    window.addEventListener('message', event => {
      if (event.data.source === 'micro-app') callback(event.data)
    })
  }
}

// All micro-frontend apps can use the same authentication service
const auth = inject(new MicroFrontendAdapter())
const user = await auth.getCurrentUser()

Through these examples, you can see that regardless of the underlying communication mechanism, your business code remains the same. This is the benefit of the adapter pattern.

Improvements Over Comlink

Besides solving environment limitation issues, Comctx has made optimizations in other areas:

Smaller Bundle Size
Thanks to the minimalist design of the core code, Comctx is only 1KB+, while Comlink is 4KB+

Automatic Transferable Objects Handling
When you transfer large objects like ArrayBuffer and ImageData, Comctx can automatically extract them for transfer. Comlink requires manual handling.

Better Connection Management
Comctx has built-in heartbeat detection that can automatically wait for remote services to be ready. This solves the common timing issues in Comlink — sometimes when you call a method, the other side isn't ready to receive messages.

Type Safety
TypeScript support is as good as Comlink, with all the type inference you expect.

Design Philosophy Differences

Comlink and Comctx have fundamentally different design approaches:

Comlink's Approach

// Directly wrap the entire worker
const api = Comlink.wrap(worker)
await api.someMethod()

This approach is straightforward, but the problem is it hardcodes the communication mechanism. The Worker object must support MessagePort, and it won't work in other environments.

Comctx's Approach

// First define the service
const [provide, inject] = defineProxy(() => new Service())

// Server side: publish service
provide(adapter)

// Client side: use service
const service = inject(adapter)

The key here is the adapter. It tells Comctx how to send and receive messages without restricting the specific method. This achieves separation between communication methods and business logic.

Additionally, Comctx has a heartbeat detection mechanism to ensure the connection is alive. This solves the common connection timing issues in Comlink.

Summary

The motivation behind developing Comctx is simple: make RPC communication environment-agnostic.

If you're just using Web Worker, Comlink is sufficient. But if your project involves browser extensions, iframes, Electron, or other custom communication scenarios, Comctx would be a better choice.

It not only solves environment adaptation problems but also improves bundle size, performance, and reliability. Most importantly, the API design maintains Comlink's simplicity with almost zero learning curve.

Related Resources

📚 GitHub Repository - Complete source code and examples
📦 NPM Package - Install and use immediately
📖 Online Documentation - Detailed usage guide

WebChat - Chat with anyone on any website.

John Wu — Tue, 15 Oct 2024 17:09:06 +0000

This is an anonymous chat browser extension that is decentralized and serverless, utilizing WebRTC for end-to-end encrypted communication. It prioritizes privacy, with all data stored locally.

The aim is to add chat room functionality to any website, you'll never feel alone again.

Github: https://github.com/molvqingtai/WebChat

Chrome Web Store: https://chromewebstore.google.com/detail/webchat/cpaedhbidlpnbdfegakhiamfpndhjpgf

Video:
https://www.youtube.com/watch?v=Rixj6zGZLUc

Applying Koa's onion model to front-end requests

John Wu — Thu, 24 Mar 2022 16:23:00 +0000

As anyone who has used koa knows, the onion model is a clever middleware pattern that uses nested functions, which elegantly encapsulates response and request processing in a single middleware

Koa middleware example:

app.use(async (ctx, next) => {
  await next();
})

When we process the request, we are splitting it for each request and the minimum focus should be on the request as a whole (Request & Response) rather than splitting the Request and Response of the request in two separate logics

It is better to visualize the causal relationship between request and response directly through the syntax level of the code, rather than through the function call order

For example, using Koa and Axios to implement the same request timing logic.

Koa

app.use(async (ctx, next) => {
  const start = Date.now()
  await next()
  const ms = Date.now() - start
  console.log(ms)
})

Axios

let start = 0

axios.interceptors.request.use(function(config){
  start = Date.now()
})

axios.interceptors.response.use(function(response){
  const ms = Date.now() - start
  console.log(ms)
})

In the axios code, we just implement the single logic of timing, but it is forcibly split into two Hooks, and it is not clear from the syntax level alone that they have any relationship, only that an external variable is created to couple them together

As you can see, the Onion Middleware looks cleaner and more logically cohesive than the regular Hooks.

The onion model has a natural advantage in handling Before / After logic, such as vue-router, redux also use this approach, since the onion model can be used for back-end requests, it can also be used for client-side requests

So, an HTTP client based on the onion model is created, and it looks like this.

Resreq

import Resreq from 'resreq'

const resreq = new Resreq({
  baseUrl: 'https://example.com'
})

// Intercepting responses and requests using middleware
resreq.use((next) => async (req) => {
  try {
    console.log(req) // Request can be changed here
    const res = await next(req)
    console.log(res) // Response can be changed here
    return res
  } catch (error) {
    console.log(error) // Catch errors here
    throw error
  }
})

const res = await resreq.get('/api', {
  params: { foo: 'bar' }
})

console.log(res)

GitHub: https://github.com/molvqingtai/resreq

DEV Community: John Wu