How to pass a callback function to a WebWorker using Comlink?

Wrap the callback with Comlink.proxy() to allow cross-thread invocation, as shown in the callback example. This is necessary because functions aren't structured cloneable or transferable by default.

Comlink vs manual postMessage: which is better for performance?

Comlink simplifies development but adds a thin RPC layer, so manual postMessage might be faster for high-frequency, low-latency messaging. For most apps, Comlink's ease of use outweighs the minor overhead.

Can Comlink handle large data transfers without copying?

Yes, use Comlink.transfer() with transferable objects like ArrayBuffer to move data efficiently. The README shows an example with Uint8Array to avoid structured cloning overhead.

How to set up Comlink with SharedWorkers?

Expose objects in the worker's onconnect callback and wrap the SharedWorker's port property, as detailed in the SharedWorker example. This requires extra steps compared to regular WebWorkers.

Is Comlink good for Node.js worker threads?

Yes, Comlink supports Node.js worker_threads, with an example in the docs folder. It provides the same RPC abstraction, making multi-threading in Node.js more accessible.

What happens if I don't release a Comlink proxy?

Proxies can cause memory leaks if not detached; call [Comlink.releaseProxy]() manually or rely on garbage collection with WeakRef support. The API section explains this to manage resources.

Open-Awesome

comlink

Apache-2.0TypeScriptv4.4.2

A tiny RPC library that simplifies WebWorker communication by hiding postMessage complexity with ES6 Proxies.

GitHub

12.8k stars437 forks0 contributors

What is comlink?

Comlink is a tiny JavaScript library that simplifies communication with WebWorkers by providing an RPC layer over the postMessage API. It allows developers to call functions and access objects in worker threads as if they were local, eliminating the complexity of manual message handling. This makes offloading work to background threads easier, helping keep the main UI thread responsive.

Target Audience

Frontend and Node.js developers who need to use WebWorkers or worker threads for CPU-intensive tasks, animations, or maintaining UI responsiveness, especially on low-end mobile devices.

Value Proposition

Developers choose Comlink because it dramatically reduces the boilerplate and cognitive overhead of WebWorker communication with a minimal 1.1kB footprint. Its proxy-based approach makes remote interactions feel native, unlike manually managing postMessage.

Overview

Comlink makes WebWorkers enjoyable.

Use Cases

Best For

Offloading CPU-heavy computations from the main UI thread to WebWorkers
Building responsive web apps that need to avoid jank on low-end mobile devices
Simplifying SharedWorker or iframe communication in complex applications
Creating Node.js applications that use worker_threads for parallelism
Implementing custom transfer handlers for non-cloneable objects like Event objects
Reducing WebWorker setup and message-passing boilerplate in JavaScript projects

Not Ideal For

Projects requiring direct, low-level control over postMessage serialization for performance tuning
Applications targeting older browsers without ES6 Proxy support and unwilling to add polyfills
Simple, one-off WebWorker tasks where the RPC abstraction adds unnecessary overhead
Real-time systems where the async proxy layer and serialization latency could impact responsiveness

Pros & Cons

Pros

Minimal Footprint

At only 1.1kB brotli'd, Comlink adds negligible overhead, as emphasized in the README's size section, making it ideal for performance-conscious web apps.

Intuitive RPC Abstraction

By using ES6 Proxies to turn message-based communication into simple remote procedure calls, Comlink eliminates postMessage boilerplate, letting developers focus on logic.

Broad Environment Support

Works with WebWorkers, SharedWorkers, Node.js worker_threads, and iframes, demonstrated in examples, providing versatility across different threading models.

TypeScript Ready

Includes built-in TypeScript types with Comlink.Remote<T>, enhancing developer experience, though the README notes it's best-effort and may require manual overrides.

Cons

Serialization Complexity

Non-cloneable objects like Events require custom transfer handlers, adding setup overhead and potential bugs, as admitted in the README with workaround examples.

Proxy Dependency

Relies on ES6 Proxies, so older browsers need a polyfill, increasing bundle size and compatibility concerns beyond the core library's tiny footprint.

Async Overhead Everywhere

All proxy interactions are inherently asynchronous, forcing await on even simple property accesses, which can complicate code and introduce subtle performance costs.

Frequently Asked Questions

Related Projects

partytown

Relocate resource intensive third-party scripts off of the main thread and into a web worker. 🎉

Stars13,803

Forks461

Last commit2 days ago

greenlet

🦎 Move an async function into its own thread.

Stars4,688

Forks97

Last commit5 years ago

workerize

🏗️ Run a module in a Web Worker.

Stars4,375

Forks86