vite-plugin-comlink

vite-plugin-comlink

This plugins requires vite >=2.8 for WebWorkers and vite >= 2.9.6 for shared worker to work properly.

Use WebWorkers with comlink.

This plugin removes the need to call expose, wrap from comlink and also you don't need to create the worker on your own.

Upgrade Vite 4 to Vite 5

Make sure that you change the worker plugin config to a function for example like this

// vite.config.js
export default {
  worker: {
    plugins: () => [comlink()],
  },
};

see https://github.com/vitejs/vite/pull/14685 for details.

Install

npm i --save-dev vite-plugin-comlink # yarn add -D vite-plugin-comlink
npm i --save comlink # yarn add comlink

Comlink install

As you don't want to wait for a new release for this plugin when a new version of comlink is released, this plugin has comlink as a peer dependency so you can install the version of comlink that you need.

Add it to vite.config.js

// vite.config.js
import { comlink } from "vite-plugin-comlink";

export default {
  plugins: [comlink()],
  worker: {
    plugins: () => [comlink()],
  },
};

Plugin order

Put this plugin as one of the first plugins. Only other plugins that create ComlinkWorker or ComlinkSharedWorker or transform files based on the existence of ComlinkWorker or ComlinkSharedWorker should come before this plugin!

Usage

// worker.js
export const add = (a: number, b: number) => a + b;

// main.ts

// Create Worker
const instance = new ComlinkWorker(new URL("./worker.js", import.meta.url), {
  /* normal Worker options*/
});
const result = await instance.add(2, 3);

result === 5;

// Create SharedWorker
const instance = new ComlinkSharedWorker(
  new URL("./worker.js", import.meta.url),
  {
    /* normal Worker options*/
  }
);
const result = await instance.add(2, 3);

result === 5;

With TypeScript

Add

/// <reference types="vite-plugin-comlink/client" />

to your vite-env.d.ts file to make sure typescript will use vite-plugin-comlink/client.

// worker.ts
export const add = (a: number, b: number) => a + b;

// main.ts

// Create Worker
const instance = new ComlinkWorker<typeof import("./worker")>(
  new URL("./worker", import.meta.url),
  {
    /* normal Worker options*/
  }
);
const result = await instance.add(2, 3);

result === 5;

// Create SharedWorker
const instance = new ComlinkSharedWorker<typeof import("./worker")>(
  new URL("./worker", import.meta.url),
  {
    /* normal Worker options*/
  }
);
const result = await instance.add(2, 3);

result === 5;

Get Worker Instance

You can get to the worker instance like this:

import { endpointSymbol } from "vite-plugin-comlink/symbol";

const api = new ComlinkWorker<typeof import("./worker")>(
  new URL("./worker", import.meta.url),
  {
    /* normal Worker options*/
  }
);
const worker = api[endpointSymbol];

Module Worker

Not all Browsers support module Workers (see https://caniuse.com/mdn-api_worker_worker_ecmascript_modules).

This results in some drawbacks for fastest and best support:

For fast development we use module Workers as bundling the complete worker on the fly is not performant.

In default settings we bundle the whole worker at build to a single file. Therefore all browsers that support Workers, work in production.

This is the same behavior as vite and it is NOT CHANGEABLE!

If you want a worker to be a module worker in production, add type: 'module' to the worker constructor options.

What this means:

• In development you need a browser that supports module Worker (see https://caniuse.com/mdn-api_worker_worker_ecmascript_modules)
• In production all browsers are supported

Breaking changes

v2 to v3

• remove of customConfigs breaking FF support in development for some projects and removing the abbility for inline worker. This is a limitation of vite so if vite adds support of it this plugin will follow
• remove of typefile. For typescript support please write your own type file or switch to the new syntax.
• remove of ServiceWorker support. This was considered unstable an it was hacky so it got removed. If vite adds support for building ServiceWorker this will be added!
• you have to add comlink to worker.plugins array.

v3 to v4

• the import syntax will be removed you have to switch to the new syntax!
• Removal of Warnings of leagacy (v2) options
• ESM support
• Better Source Maps

v4 to v5

• some undocumented internal options got removed.
• full rewrite of the core transformer to fix a lot of bugs
• should be breaking free but as this is a big rewrite there might be breaking changes

Resources

https://github.com/GoogleChromeLabs/comlink
https://github.com/surma/rollup-plugin-comlink