Apollo State Sync

Synchronize Apollo Client state effortlessly across all browsing contexts, such as browser tabs, windows, and iframes.

Apollo State Sync keeps Apollo Client state consistent across browsing contexts without redundant network requests.

It syncs Apollo's in-memory cache and reactive variables across contexts, and can persist state between sessions so users can resume where they left off. It also avoids duplicate GraphQL subscription channels across contexts.

💡 Why use it?

Modern web apps often run across multiple browser tabs or windows within the same workflow. Without shared state synchronization, users can end up with inconsistent data:

• logged in status differs across tabs
• Data edited in one tab stays outdated in another until a manual refresh.
• in-memory caches are inconsistent across tabs
• GraphQL subscriptions are duplicated across tabs
• app state resets unexpectedly when a tab is reopened

Apollo State Sync solves this by keeping state in sync across browsing contexts and user sessions. Apollo Shared WS reuses a shared WebSocket connection to share active subscription channels.

✨ Features

• Syncs Apollo Client's state across all browsing contexts.
  • browser tabs
  • windows
  • iframes
  • other active app instances
• Keeps Apollo cache and reactive variables synchronized in real time
• Persists state across browser restarts and user sessions
• Reuses a single shared WebSocket connection for GraphQL subscriptions
• Minimizes duplicate network traffic by indexing GraphQL subscription channels by payload
• Helps build multi-window and multi-tab apps without custom state plumbing

❗ Apollo State Sync keeps Apollo state synchronized across tabs and windows. For shared GraphQL subscription channels and a single reused WebSocket connection across browsing contexts, install and configure Apollo Shared WS npm package.

💻 Example use-cases

• User logs in from one tab and is automatically logged in on all other tabs
• Shopping cart updates are shared instantly across every open tab
• Chat applications, dashboards, live-location apps, or scoreboards can be opened in multiple windows without extra network load
• Long-lived user workflows continue seamlessly after closing and reopening the browser

📦 Installation

npm install apollo-state-sync

Using pnpm

1) For non-monorepos.

pnpm add apollo-state-sync

2) Adds to specific workspace.

pnpm add apollo-state-sync --filter="./packages/my-workspace"

3) Adds to root workspace.

pnpm add apollo-state-sync -w

Using yarn

1) For non-monorepos

yarn add apollo-state-sync

2) Adds to specific workspace.

yarn workspace <workspace-name> add apollo-state-sync

3) Adds to root workspace.

yarn add -W apollo-state-sync

⚙️ How it works ( Architecture )

Apollo State Sync listens for state changes in Apollo Client and broadcasts them across browsing contexts using Broadcast Channels. It can also persist state in Local Storage so it remains available when the user reopens the app.

🤖 Migration Automation

If you want to migrate an existing Apollo Client TypeScript project to Apollo State Sync, you can run the following commands:

npm i --save-dev ts-morph
npx apollo-state-sync --help
npx apollo-state-sync

By default, WebSocket migration is not enabled. For details on WebSocket configuration and migration, see the Apollo Shared WebSocket documentation.

To know what the migration does, or to migrate manually, refer to this API_OVERVIEW guide.

🔌 API reference

For most use cases, refer to the API_OVERVIEW guide.
For advanced configurations, refer to this API Reference.

👥 Community & Support

• 💬 Have an idea? Suggest new features in GitHub Discussions.

• 🚀 Support me or my projects through donations.

• 💼 Need custom work or consultation? I am available for hire! Reach out via email.