Registry / http-networking / vite-plugin-comlink

vite-plugin-comlink

library5.3.0jsnpmunverified

Vite plugin that integrates Comlink to simplify Web Worker and SharedWorker usage. Current stable version is 5.3.0, released under MIT license. It removes the need for manual `expose` and `wrap` calls, automatically transforming workers referenced via `ComlinkWorker` and `ComlinkSharedWorker` constructors. Requires Vite >=2.9.6 and comlink as a peer dependency. Key differentiator: zero-config setup for Comlink with Vite, supports both module and classic workers, and provides TypeScript type inference for worker modules.

http-networking

npm install vite-plugin-comlink

github ↗package ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-COMLIN

vite-plugin-comlink

http-networkingjavascriptv5.3.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

comlink

✓ import { comlink } from 'vite-plugin-comlink'

✗ import comlink from 'vite-plugin-comlink'

Named export 'comlink' is the plugin function; default import is not available.

ComlinkWorker

✓ const worker = new ComlinkWorker(new URL('./worker.js', import.meta.url), {});

✗ const worker = new ComlinkWorker('./worker.js', {});

ComlinkWorker is a global constructor provided by the plugin; do not import it. It must be used with a URL object, not a string.

ComlinkSharedWorker

✓ const sharedWorker = new ComlinkSharedWorker(new URL('./worker.js', import.meta.url), {});

✗ const sharedWorker = new comlinkSharedWorker(new URL('./worker.js', import.meta.url), {});

Also global; case-sensitive. For shared workers, Vite >=2.9.6 is required.

Configures Vite with the plugin, creates a simple worker, and calls its function via Comlink.

// vite.config.js import { comlink } from 'vite-plugin-comlink'; export default { plugins: [comlink()], worker: { plugins: () => [comlink()], }, }; // worker.js export const add = (a: number, b: number) => a + b; // main.ts const instance = new ComlinkWorker<typeof import('./worker')>( new URL('./worker.js', import.meta.url), { /* Worker options */ } ); const result = await instance.add(2, 3); console.log(result); // 5

Debug

Known issues

breakingv5.0.0 introduced a full rewrite; some undocumented internal options were removed.

fix

Check for usage of internal plugin options; they may be removed. Update to latest v5.

affects: >=5.0.0 <5.0.1

gotchaThe plugin must be included in both `plugins` and `worker.plugins` for proper worker transformation.

fix

Add `comlink()` to both arrays in vite.config.js.

affects: >=0.0.0

breakingAfter upgrading to Vite 5, `worker.plugins` must be a function returning an array, not an array directly.

fix

Change `worker: { plugins: [comlink()] }` to `worker: { plugins: () => [comlink()] }`.

affects: >=5.0.0

gotchaComlinkWorker and ComlinkSharedWorker are not imported; they are global types/constructors provided by the plugin. TypeScript may complain if the client types are not referenced.

fix

Add `/// <reference types="vite-plugin-comlink/client" />` to your env.d.ts file.

affects: >=0.0.0

deprecatedUsing `type: 'module'` in worker options may cause issues in production; plugin bundles workers as classic scripts by default.

fix

Avoid setting `type: 'module'` unless you understand the implications.

affects: >=0.0.0

Errors

Common errors & fixes

Cannot find name 'ComlinkWorker'.

TypeScript doesn't recognize the global type; client types not loaded.

fix

Add `/// <reference types="vite-plugin-comlink/client" />` to your vite-env.d.ts file.

The argument 'path' must be a string or URL instance.

Using a string instead of a URL object for the first argument of ComlinkWorker.

fix

Use `new URL('./worker.js', import.meta.url)` instead of just `'./worker.js'`.

Cannot access 'add' before initialization.

The worker module has circular dependencies or was not exported correctly.

fix

Ensure the worker file uses named exports and does not import from the main thread.

Upgrade

Version history

5.3.0latest on npm

Audit

Dependencies

comlinkrequiredPeer dependency; provides the Comlink RPC library for worker communication.

viterequiredPeer dependency; required as the build tool. Must be >=2.9.6 for SharedWorker support.

Agent activity

24 hits · last 30 days

node

Amazon

Anthropic

OpenAI (training)

Resources

githubhttps://github.com/mathe42/vite-plugin-comlink ↗

packagehttps://www.npmjs.com/package/vite-plugin-comlink ↗