okikio / sharedworker

A small spec. compliant polyfill for SharedWorkers, it acts as a drop in replacement for normal Workers.

@okikio/sharedworker

NPM | Github | Docs | Licence

A small mostly spec. compliant polyfill/ponyfill for SharedWorkers, it acts as a drop in replacement for normal Workers, and supports a similar API surface that matches normal Workers.

• Ponyfills are seperate modules that are included to replicate the functionality of the original API, but are not required to be used.
• Polyfills update the original API on the global scope if it isn't supported in that specific environment or it's feature set is lacking compared to modern variations.

Check out the blog post, created for it's launch.

Installation

npm install @okikio/sharedworker

Others

yarn add @okikio/sharedworker

or

pnpm install @okikio/sharedworker

Usage

import { SharedWorkerPolyfill as SharedWorker } from "@okikio/sharedworker";
// or 
import SharedWorker from "@okikio/sharedworker";

You can also use it directly through a script tag:

<script src="https://unpkg.com/@okikio/sharedworker" type="module"></script>
<script type="module">
    // You can then use it like this
    const { SharedWorkerPolyfill: SharedWorker } = window.sharedworker; 
</script>

You can also use it via a CDN, e.g.

import SharedWorker from "https://cdn.skypack.dev/@okikio/sharedworker";
// or 
import SharedWorker from "https://cdn.jsdelivr.net/npm/@okikio/sharedworker";
// or any number of other CDN's

@okikio/sharedworker supports the same API surfaces as SharedWorker and Worker, except it adds some none spec. compliant properties and methods to the SharedWorkerPolyfill class, that enables devs to use SharedWorker's on browsers that don't support it.

In order to support browsers that don't natively support SharedWorker's, the actual worker file needs to be tweaked slightly,

/* 
 * All variables and values outside the `start(...)` function are shared between all pages, this behavior can cause unexpected bugs if you're not careful
 */
const start = (port) => {
    // All your normal Worker and SharedWorker stuff can be placed here and should just work, with no extra setup required 
    
    /** 
     * All variables and values inside the `start(...)` function are isolated to each page, and will be allocated seperately per page. 
     */
    port.onmessage = ({ data }) => {
        console.log("Cool")
    };
};

self.onconnect = e => {
    let [port] = e.ports;
    start(port);
};

// This is the fallback for WebWorkers, in case the browser doesn't support SharedWorkers natively
if (!("SharedWorkerGlobalScope" in self)) 
    start(self);

Note: make sure to read the comments in the above code carefully to avoid unexpected bugs.

Showcase

A couple sites that use @okikio/sharedworker:

• astro.build/play - GitHub
• bundlejs.com - GitHub
• Your site here...

API

The API of @okikio/sharedworker closely match the web SharedWorker API, except that all the major methods and properties of SharedWorker.prototype.port are available directly on SharedWorker.prototype including addEventListener and removeEventListener.

Note: the normal functionality of the methods and properties that are normally available on SharedWorker.prototype will still be kept intact, in @okikio/sharedworker.

In addition, the terminate() method was added to @okikio/sharedworker, this allows both the close() method (this is from SharedWorker.prototype.port) and the terminate() method to manually close workers.

Check out the API site for detailed API documentation.

Browser Support

Chrome	Edge	Firefox	Safari	IE
4+	12+	4+	4+	10+

Native support for SharedWorker is not supported at all on Safari and IE, as well as all mobile browsers (excluding Firefox For Android).

Note: some features of Workers appeared at later versions of the spec., so, I suggest looking into the feature support table for Workers and SharedWorkers.

Contributing

I encourage you to use pnpm to contribute to this repo, but you can also use yarn or npm if you prefer.

Install all necessary packages

npm install

Then run tests (WIP)

npm test

Build project

npm run build

Preview API Docs

npm run typedoc && npm run preview

Note: this project uses Conventional Commits standard for commits, so, please format your commits using the rules it sets out.

Licence

See the LICENSE file for license rights and limitations (MIT).

sharedworker's Issues

Please clarify what this polyfill does?

I found this while trying to find a way to implement SharedWorker in Android for Chrome (the only remaining holdout for this mechanism). My question relates to what you wrote in your article:

The major limitation with @okikio/sharedworker is that on browsers that don't natively support SharedWorker, you can't use @okikio/sharedworker as an across tab communication tool. But for everything else it's feature parity and spec. compliance should be great.

If this doesn't actually bring across-tab communication to browsers that don't support SharedWorker, what exactly does it do/what is the point of it? (Surely there's a point, but I'm just not seeing it. So, I hope you can explain it to me!).

[BUG] v1.0.5 is not published in npm registry

Describe the bug

v1.0.5 release is tagged: https://github.com/okikio/sharedworker/releases/tag/v1.0.5
however it is not available on npm registry: https://www.npmjs.com/package/@okikio/sharedworker?activeTab=versions

To Reproduce
Steps to reproduce the behavior:

npm i @okikio/[email protected]

Expected behavior

v1.0.5 should be available for download from npm registry

Screenshots

Desktop:

• OS: MacOS
• Browser: n/a
• Version: 1.0.5

Single instance on multiple tabs

Is your feature request related to a problem? Please describe.
From the source, it seems that this library wraps a normal Worker in case there is no SharedWorker.
However, a SharedWorker is only instantiated once per origin/url. Does this library handle this as well?

Describe the solution you'd like
One tab could host the actual worker and the other tabs could be tricked into delegating everything to a BroadcastChannel, which the Worker also listens on.

Describe alternatives you've considered
None