SharedWorker: Browser Support, API, Limitations

What is SharedWorker?

SharedWorker is a JavaScript interface defined in the WHATWG HTML Living Standard. It loads a single worker script in the background, and any same-origin page, iframe, or worker can connect to it through the SharedWorker constructor. Communication happens over a MessagePort exposed on the .port property.

Which browsers does SharedWorker support?

SharedWorker works in every desktop Chromium, Gecko, and WebKit browser, while every Chromium-based mobile browser, the legacy Android Browser, and Internet Explorer do not support it.

What are the key features of SharedWorker?

SharedWorker gives JavaScript a single shared background script per origin, with port-based communication, structured-clone payloads, and a runtime that outlives any individual tab.

• Single instance per origin: A SharedWorker constructed with the same script URL and name returns one process for the whole origin. Tab A and tab B both get a port into the same script.
• MessagePort communication: Each connecting page gets its own MessagePort on .port. The worker exposes the connect event, so it can route messages back to a specific tab.
• Structured cloning: Payloads can include strings, numbers, arrays, plain objects, Maps, Sets, ArrayBuffers, and Blobs. Functions, DOM nodes, and class prototypes do not survive the clone.
• Module worker support: Chromium, Firefox, and modern Safari accept new SharedWorker(url, { type: 'module' }), so the worker script can use static import instead of importScripts.
• Same-origin scope: The browser only allows connections from contexts that share the worker's origin. A worker on app.example.com cannot be reached from payments.example.com.
• Port-driven lifetime: A SharedWorker stays alive while any port is open. Calling port.close on every tab tells the browser it can tear down the worker process and reclaim memory.
• Inspectable in DevTools: Chrome surfaces shared workers at chrome://inspect/#workers and Firefox lists them in about:debugging, so a single console can attach to the shared script.

Feature-detect the constructor before you reach for it; the snippet below ships in production code on browsers that lack the API:

// Feature detect SharedWorker before constructing one.
if (typeof SharedWorker !== 'undefined') {
    const worker = new SharedWorker('/shared-counter.js', { name: 'counter' });

    worker.port.start();

    worker.port.postMessage({ type: 'increment' });

    worker.port.onmessage = (event) => {
        console.log('Counter is now:', event.data.count);
    };
} else {
    console.warn('SharedWorker not supported. Falling back to a dedicated Worker plus BroadcastChannel.');
}

What are the common use cases of SharedWorker?

Web apps reach for SharedWorker any time multiple tabs need to share one expensive resource or one source of truth without round-tripping through a server.

• Single WebSocket per origin: A SharedWorker holds one WebSocket connection that every open tab subscribes to. The server sees one client instead of one per tab, which keeps fan-out costs predictable.
• Shared SQLite or IndexedDB writer: Database libraries like wa-sqlite and absurd-sql route every tab through one SharedWorker so writes do not collide and the page cache stays warm across tabs.
• Cross-tab event bus: A SharedWorker can re-broadcast events to every connected port, which gives apps a tab-scoped pub/sub bus without depending on BroadcastChannel.
• Centralized analytics queue: Tabs hand off impression and event payloads to one SharedWorker, which batches and ships them in one request, reducing duplicate beacon traffic.
• Long-lived auth and refresh-token logic: One SharedWorker handles silent refresh, so a hundred open tabs share one token-rotation flow instead of racing the same /refresh endpoint.
• Cached JSON warehouse: A SharedWorker fetches and caches large JSON blobs once and serves them to every tab, which speeds up dashboards that re-mount frequently.

What are the known issues with SharedWorker?

SharedWorker has been in browsers for over a decade, but production code still has to plan around uneven mobile support, debugging gaps, and a handful of WHATWG-spec constraints.

• No support on Android Chrome or Samsung Internet: Mobile Chromium dropped SharedWorker and never re-added it. Apps that must cover mobile users need a Service Worker or BroadcastChannel fallback.
• No blob URLs: SharedWorker does not accept blob: URLs as the script source on most browsers, so bundlers that ship workers as inline blobs need a separate code path for SharedWorker.
• DevTools logging is split: Console logs from inside a SharedWorker do not appear in the page's DevTools panel. Chrome surfaces them under chrome://inspect/#workers and Firefox uses about:debugging, so new developers often think the worker is silent.
• Vite and same-origin policy: Vite's dev server rewrites worker URLs in a way that breaks SharedWorker. Production builds work, but dev mode needs a workaround that serves the worker script from a sibling route.
• MDN example only fans out to one client: The canonical MDN snippet handles the connect event but only stores the most recent port. Real apps have to keep an array of every connecting port and broadcast to all of them.
• Module worker support is recent: The { type: 'module' } option only works on Chromium since Chrome 80, Firefox 114, and Safari 16. Older browsers parse the option as a name string, which silently changes behavior.
• Worker death on idle: The browser is allowed to kill an idle SharedWorker after every page closes. State that needs to survive a tab close must persist to IndexedDB or the server before the last port disconnects.

In my experience, the most common production bug is assuming the SharedWorker survives a hard reload. The browser tears it down the moment the last connected port closes, so any in-memory cache, WebSocket subscription, or unflushed analytics batch is gone. Persist anything important to IndexedDB before the last tab disconnects.

Citations

All SharedWorker version numbers and platform notes in this guide come from these primary sources:

• WHATWG HTML Living Standard - Workers: html.spec.whatwg.org/multipage/workers.html
• MDN Web Docs - SharedWorker interface: developer.mozilla.org/en-US/docs/Web/API/SharedWorker
• MDN Web Docs - SharedWorker constructor: developer.mozilla.org/en-US/docs/Web/API/SharedWorker/SharedWorker
• MDN Web Docs - SharedWorkerGlobalScope: developer.mozilla.org/en-US/docs/Web/API/SharedWorkerGlobalScope
• MDN Web Docs - MessagePort: developer.mozilla.org/en-US/docs/Web/API/MessagePort
• MDN Browser Compat Data - SharedWorker.json: github.com/mdn/browser-compat-data/blob/main/api/SharedWorker.json
• Chrome for Developers - Extended lifetime shared workers origin trial: developer.chrome.com/blog/extended-lifetime-shared-workers-origin-trial
• WebKit blog - WebKit Features in Safari 16.4: webkit.org/blog/13966/webkit-features-in-safari-16-4
• Apple Developer - Safari 16 Release Notes: developer.apple.com/documentation/safari-release-notes/safari-16-release-notes