SharedWorker for Cross-Tab Communication

Implementing SharedWorker for Cross-Tab Communication on a Website

SharedWorker — a Web Worker shared between all tabs, frames and windows of the same origin. A single worker instance serves N tabs through MessagePorts. When all tabs are closed — the worker is destroyed.

Applications: syncing state between tabs without a server, a single WebSocket connection for all tabs, shared cache, shared auth-state, distributed lock between tabs.

Support: Chrome, Firefox, Edge. Safari supports SharedWorker from version 16 (2022), but with limitations. For critical cross-tab communication, also consider BroadcastChannel (simpler, but without shared state) and localStorage events.

SharedWorker Architecture

The worker maintains a Set of connections and broadcasts messages to all connected tabs:

// shared-worker.ts
interface TabMessage {
  id: string
  type: string
  payload: unknown
}

const ports = new Set<MessagePort>()

self.addEventListener('connect', (event: MessageEvent) => {
  const port = event.ports[0]
  ports.add(port)

  port.addEventListener('message', (e: MessageEvent) => {
    const message = e.data as TabMessage
    handleMessage(message, port)
  })

  port.addEventListener('messageerror', (e) => {
    console.error('SharedWorker message error:', e)
  })

  port.start()

  // Notify worker that new tab connected
  port.postMessage({ type: 'CONNECTED', payload: { tabCount: ports.size } })

  port.addEventListener('close', () => {
    ports.delete(port)
    broadcast({ type: 'TAB_COUNT', payload: { count: ports.size } }, null)
  })
})

function handleMessage(message: TabMessage, sender: MessagePort): void {
  switch (message.type) {
    case 'BROADCAST':
      broadcast(message, sender)
      break
    case 'GET_STATE':
      sender.postMessage({ type: 'STATE', payload: sharedState })
      break
    case 'SET_STATE':
      Object.assign(sharedState, message.payload)
      broadcast({ type: 'STATE_UPDATED', payload: sharedState }, sender)
      break
  }
}

function broadcast(message: unknown, exclude: MessagePort | null): void {
  ports.forEach((port) => {
    if (port !== exclude) {
      port.postMessage(message)
    }
  })
}

// Shared state for all tabs
const sharedState: Record<string, unknown> = {}

Client Class

// SharedWorkerClient.ts
type MessageHandler = (type: string, payload: unknown) => void

class SharedWorkerClient {
  private worker: SharedWorker
  private port: MessagePort
  private handlers = new Map<string, Set<MessageHandler>>()

  constructor(scriptURL: string | URL) {
    this.worker = new SharedWorker(scriptURL, { type: 'module', name: 'app-shared' })
    this.port = this.worker.port

    this.port.onmessage = (event: MessageEvent) => {
      const { type, payload } = event.data
      this.emit(type, payload)
    }

    this.port.onmessageerror = (e) => {
      console.error('Port error:', e)
    }

    this.port.start()
  }

  on(type: string, handler: MessageHandler): () => void {
    if (!this.handlers.has(type)) {
      this.handlers.set(type, new Set())
    }
    this.handlers.get(type)!.add(handler)
    return () => this.handlers.get(type)?.delete(handler)
  }

  private emit(type: string, payload: unknown): void {
    this.handlers.get(type)?.forEach((h) => h(type, payload))
    this.handlers.get('*')?.forEach((h) => h(type, payload))
  }

  send(type: string, payload?: unknown): void {
    this.port.postMessage({ type, payload })
  }

  broadcast(type: string, payload?: unknown): void {
    this.port.postMessage({ type: 'BROADCAST', payload: { type, payload } })
  }

  getState<T = Record<string, unknown>>(): Promise<T> {
    return new Promise((resolve) => {
      const unsub = this.on('STATE', (_, payload) => {
        unsub()
        resolve(payload as T)
      })
      this.send('GET_STATE')
    })
  }

  setState(patch: Record<string, unknown>): void {
    this.send('SET_STATE', patch)
  }

  close(): void {
    this.port.close()
  }
}

WebSocket via SharedWorker

Instead of each tab creating a separate WebSocket connection, all tabs use one:

// shared-worker.ts — WebSocket part
let socket: WebSocket | null = null
let reconnectTimer: ReturnType<typeof setTimeout>

function connectSocket(url: string): void {
  if (socket?.readyState === WebSocket.OPEN) return

  socket = new WebSocket(url)

  socket.onopen = () => {
    broadcast({ type: 'WS_CONNECTED' }, null)
    clearTimeout(reconnectTimer)
  }

  socket.onmessage = (event) => {
    const data = JSON.parse(event.data)
    broadcast({ type: 'WS_MESSAGE', payload: data }, null)
  }

  socket.onerror = () => {
    broadcast({ type: 'WS_ERROR' }, null)
  }

  socket.onclose = () => {
    broadcast({ type: 'WS_DISCONNECTED' }, null)
    // Auto reconnect
    reconnectTimer = setTimeout(() => connectSocket(url), 3000)
  }
}

// In handleMessage:
case 'WS_CONNECT':
  connectSocket(message.payload as string)
  break
case 'WS_SEND':
  if (socket?.readyState === WebSocket.OPEN) {
    socket.send(JSON.stringify(message.payload))
  }
  break

Authentication Synchronization

Real scenario: user logged out in one tab — all others should redirect to /login:

// auth-sync.ts
const sharedWorker = new SharedWorkerClient(
  new URL('./shared-worker.ts', import.meta.url)
)

export function setupAuthSync(): () => void {
  const unsub = sharedWorker.on('AUTH_LOGOUT', () => {
    // Remove tokens and redirect
    localStorage.removeItem('token')
    window.location.href = '/login'
  })

  const unsubLogin = sharedWorker.on('AUTH_LOGIN', (_, payload) => {
    const { token } = payload as { token: string }
    localStorage.setItem('token', token)
    // Update UI without full reload
    window.dispatchEvent(new CustomEvent('auth:login', { detail: { token } }))
  })

  return () => {
    unsub()
    unsubLogin()
  }
}

export function broadcastLogout(): void {
  localStorage.removeItem('token')
  sharedWorker.broadcast('AUTH_LOGOUT')
}

export function broadcastLogin(token: string): void {
  sharedWorker.broadcast('AUTH_LOGIN', { token })
}

BroadcastChannel as Alternative

For simple cross-tab communication without shared state SharedWorker may be overkill:

const channel = new BroadcastChannel('app-events')

// Send to all tabs (except current)
channel.postMessage({ type: 'CART_UPDATED', payload: cartItems })

// Receive
channel.onmessage = (event) => {
  const { type, payload } = event.data
  if (type === 'CART_UPDATED') updateCartUI(payload)
}

channel.close()

BroadcastChannel is simpler, works everywhere (including Safari 15.4+), but has no shared state and doesn't allow creating a single WebSocket connection.

Debugging

SharedWorker is visible in Chrome DevTools:

• about:inspect → Shared workers
• Or via chrome://inspect/#workers

Worker doesn't restart on page reload — need to explicitly close the tab or via DevTools.

What's Included

SharedWorker implementation with broadcast and shared state support, typed client class, handling tab connection/disconnection, optionally — WebSocket bridge or authentication sync, BroadcastChannel fallback for incompatible browsers.

Timeline: 2–3 days depending on scenarios (auth sync, WebSocket bridge, shared cache).