vite-plugin-comlink

5.3.0 verified Sat Apr 25 auth: no javascript

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.

Common errors

error Cannot find name 'ComlinkWorker'. ↓

cause 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.

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

cause 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'.

error Cannot access 'add' before initialization. ↓

cause 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.

Warnings

breaking v5.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.

gotcha The plugin must be included in both `plugins` and `worker.plugins` for proper worker transformation. ↓

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

breaking After 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()] }`.

gotcha ComlinkWorker 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.

deprecated Using `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.

Install

npm install vite-plugin-comlink

yarn add vite-plugin-comlink

pnpm add vite-plugin-comlink

Imports

comlink
wrong
```
import comlink from 'vite-plugin-comlink'
```
correct
```
import { comlink } from 'vite-plugin-comlink'
```
Named export 'comlink' is the plugin function; default import is not available.
ComlinkWorker
wrong
```
const worker = new ComlinkWorker('./worker.js', {});
```
correct
```
const worker = new ComlinkWorker(new URL('./worker.js', import.meta.url), {});
```
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

wrong

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

correct

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

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

Quickstart

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