Here's Why and How to Use It

We've all been there. You're building a web app, everything works fine in one tab — but the moment a user opens a second tab, things start breaking. Cart items disappear. Login state gets out of sync. Background tasks run twice.

I ran into this problem one too many times, so I built tabcoord to solve it properly.

What is tabcoord?

tabcoord is a small library (under 5KB, zero dependencies) that keeps your browser tabs in sync. It gives you shared state, leader election, locks, and an event bus — all working across tabs automatically.

npm install tabcoord tabcoord-react

tabcoord-react uses tabcoord as a peer dependency, so you need both installed.

Built on Top of the Native BroadcastChannel API

tabcoord uses the browser's built-in BroadcastChannel API under the hood — so it's not replacing it, it's building on top of it.

BroadcastChannel is great at one thing: sending raw messages between tabs. But that's where it stops. Everything on top of that — syncing state, persisting it, bootstrapping a new tab that opens late, handling older browsers, working safely in SSR — you'd have to wire up yourself.

tabcoord takes care of all of that:

• State management — not just messages, but a real shared store with React bindings
• New tab bootstrap — when a tab opens late, it automatically gets the current state from existing tabs
• Persistence — state survives page refreshes via localStorage, without you touching it
• Leader election and locks — coordination primitives built on the same channel
• localStorage fallback — for older browsers or Safari private mode where BroadcastChannel isn't available
• SSR safety — no crashes in Next.js or Remix because the server never touches BroadcastChannel

So if you already know BroadcastChannel, tabcoord will feel familiar — it's just everything you'd have had to build on top of it, already done.

Shared State Across Tabs

The core feature is createSharedStore. You define a store once, and every tab that uses it stays in sync automatically.

// store.ts
import { createSharedStore } from 'tabcoord';

export const cart = createSharedStore({
  name: 'cart',
  initial: { items: [] as string[] },
});

Then use it in your React components with useSharedStore from tabcoord-react:

import { useSharedStore } from 'tabcoord-react';
import { cart } from './store';

function CartButton() {
  const items = useSharedStore(cart, s => s.items);

  return (
    <button onClick={() => cart.set(s => ({
      ...s,
      items: [...s.items, 'new-item'],
    }))}>
      Cart ({items.length})
    </button>
  );
}

Open your app in two tabs. Add something to the cart in one tab. The other tab updates immediately — no refresh, no extra setup.

State is also persisted to localStorage automatically, so it survives page refreshes too.

Only One Tab Does the Heavy Work

If you have background polling or periodic API calls, you don't want every tab running them at the same time. That's wasteful and can cause real problems.

leaderElection picks one tab to be in charge. If that tab closes, another one automatically takes over.

import { leaderElection } from 'tabcoord';

const election = leaderElection('background-sync');

election.onElected(() => {
  const interval = setInterval(() => {
    fetch('/api/updates');
  }, 30_000);

  election.onDemoted(() => clearInterval(interval));
});

One tab polls. The rest stay quiet. When the leader closes, a new one steps up.

Preventing Race Conditions with Locks

Sometimes two tabs might try to do the same thing at the same time — like submitting a form or running an import. lockManager makes them take turns.

import { lockManager } from 'tabcoord';

const lock = lockManager('data-import');

await lock.acquire(async () => {
  await runImport(); // Only one tab runs this at a time
});

The first tab to get the lock runs. Every other tab waits. When it's done, the next one goes.

Sending Events Across Tabs

Not everything needs shared state. Sometimes you just want to tell other tabs that something happened — like a logout or a notification.

import { eventBus } from 'tabcoord';

const bus = eventBus('app-events');

// In one tab, listen:
bus.on('user:logout', () => {
  redirectToLogin();
});

// In another tab, fire:
bus.emit('user:logout', { reason: 'session-expired' });

The event goes to every tab instantly. It supports wildcards (user:*) and a replay buffer so new tabs can catch up on recent events they missed.

Works with Next.js and Remix

Server-side rendering is where most tab-sync libraries break. They crash because browser APIs like BroadcastChannel don't exist on the server.

tabcoord handles this cleanly. On the server, stores return your initial values and behave like regular local state. When the page loads in the browser, they connect to the real cross-tab sync automatically. No crashes, no special wrappers needed.

How Does It Compare?

tabcoord vs Native BroadcastChannel

Use tabcoord when you need state management, persistence, leader election, or locks.
Use native BroadcastChannel when you just need simple one-off message passing.

tabcoord vs broadcast-channel (2k stars, 3M+ weekly downloads)

A popular BroadcastChannel polyfill with basic leader election.

Use tabcoord when you need the full coordination layer.
Use broadcast-channel when you need a polyfill for old browsers or Node.js IPC.

tabcoord vs WebSocket

Use tabcoord when it's one person's tabs on one machine.
Use WebSocket when you need real-time multi-user collaboration.

How Small Is It?

Under 6 KB total. Nothing else gets pulled in.

Quick Summary

• ✅ Shared state across tabs, synced in real time
• ✅ Persists across page refreshes automatically
• ✅ Leader election — one tab handles background work
• ✅ Lock manager — no duplicate actions across tabs
• ✅ Event bus with wildcard support and replay
• ✅ SSR safe — works with Next.js and Remix
• ✅ Falls back gracefully on older browsers
• ✅ TypeScript first, zero dependencies

If you've ever hacked together localStorage event listeners to sync tabs and thought there has to be a better way — this is what I built for exactly that.

tabcoord on npm · tabcoord-react on npm