useBroadcast

A few weeks ago I noticed a strange state in a Next.js app router project I'm working on. If I opened two tabs in the same browser and logged into my app on one, the other would continue to show the sign in and sign up links in its main navbar. Similarly, if both had been logged in and then I signed out of one, the other's navbar would still display the user's handle and username until the page was reloaded.

I realized that I needed a way to communicate between different tabs in the browser, and after a little digging I found that window.BroadcastChannel was exactly what I was looking for. It's an API which allows scripts from the same origin but other browsing contexts (windows, workers) to send each other messages. It's not supported in IE (surprise, surprise) but has been supported by all major browsers for at least a few years.

Here's the first iteration of my hook:

import * as React from "react"

export function useBroadcast(
  key: string,
  handler?: (event: MessageEvent) => void
) {
  React.useEffect(() => {
    if (!handler) return
    const broadcastChannel = new BroadcastChannel(key)
    broadcastChannel.addEventListener("message", handler)
    return () => {
      broadcastChannel.removeEventListener("message", handler)
    }
  }, [handler, key])

  return (data: MessageEvent["data"]) => {
    new BroadcastChannel(key).postMessage(data)
  }
}
						

The key is used to create a new BroadcastChannel, and the handler (if one exists) is invoked whenever a message is sent on that channel. The hook's return value is a function which can be used to emit messages to the channel.

Here's an example of its usage (this component's parent is a server component which loads the current user and passes it as a prop):

"use client"
import * as React from "react"
import { useBroadcast } from "../hooks/useBroadcast"
import type { User } from "../utils/types"

export function UserSync(props: { user: User | null }) {
  const broadcast = useBroadcast("user", event => {
    if (event.data?.id !== props.user?.id) location.reload()
  })

  React.useEffect(() => {
    broadcast(props.user)
  }, [broadcast, props.user])

  return null
}
						

This is a fairly self-contained example of a legitimate use case. Every time the session changes, the new user (or null if they've logged out) will be broadcast. Any other tab whose user does not match the payload from the broadcast will simply reload, thereby refreshing the page to reflect the state based on the new auth cookie.

Our hook works, but there's definitely room for improvement. Passing a magic string as a key always has a strong code smell, and MessageEvent["data"] actually just means any. As we improve our type safety, let's imagine we're working for an eCommerce site and have been tasked with also ensuring that the cart stays synchronized between tabs. Our new implementation may look something like this:

import * as React from "react"
import type { Cart, User } from "../utils/types"

export function useBroadcast<
  K extends "cart" | "user",
  T extends K extends "cart" ? Cart : User | null
>(
  key: K,
  handler?: (event: MessageEvent<‍T>) => void
) {
  // same useEffect as above

  return (data: T) => {
    new BroadcastChannel(key).postMessage(data)
  }
}
						

Great! Now we know that "cart" and "user" are the only valid keys, and that the data we send and receive will always correspond to the key which was used to invoke the hook. Here's how we can use it to keep our cart components in sync:

// components/cart-app.tsx

"use client"
import * as React from "react"
import { useBroadcast } from "../hooks/use-broadcast"
import type { Cart } from "../utils/types"

export function CartApp(props: { cart: Cart }) {
  const [cart, setCart] = React.useState(props.cart)
  const broadcast = useBroadcast("cart", event => {
    setCart(event.data)
  })
  function handleCartUpdate(newCart: Cart) {
    setCart(newCart)
    broadcast(newCart)
  }
  // return JSX which displays cart items and allows updates
}



// components/navbar-cart-link.tsx

"use client"
import * as React from "react"
import { useBroadcast } from "../hooks/use-broadcast"

export function NavbarCartLink(props: { initialCount: number }) {
  const [itemCount, setItemCount] = React.useState(props.initialCount)
  useBroadcast("cart", event => {
    setItemCount(event.data.totalItemCount)
  })
  // return JSX with a link that shows cart item quantity
}



// components/clear-cart-button.tsx

"use client"
import { clearCart } from "../actions/clear-cart"
import { useBroadcast } from "../hooks/use-broadcast"

export function ClearCartButton() {
  const broadcast = useBroadcast("cart")
  async function handleClick() {
    const newCart = await clearCart()
    broadcast(newCart)
  }
  return <‍button onClick={handleClick}>Clear Cart<‍/button>
}
						

In this example, CartApp displays the current items in the cart and allows the user to remove them or update their quantities. As a result, it needs to both listen for broadcasts with updated values and be able to send new values back to the broadcast channel. The useBroadcast hook is responsible for handling both of these tasks.

NavbarCartLink is displayed at the top of the screen in the site's main navbar. As the name implies, it renders a link to the shopping cart page (where CartApp lives). Its CTA is a shopping cart icon with a number representing the total quantity of cart items, so this component needs to be able to receive cart broadcast events but never has a reason to send one.

Conversely, ClearCartButton uses a server action to clear the cart when clicked, after which it needs to broadcast the cleared cart so that the rest of the UI can be updated accordingly. However, this component has no need to subscribe to the broadcast channel since it doesn't need to know about the current state of the cart.

And there you have it, we've ensured that the cart and user will always be aligned in every instance of our app within the current browser. As you can see, we can also use this hook to communicate between client components even if they don't share any common ancestor or context provider.

My examples used React and Next.js but window.BroadcastChannel can be used in any JavaScript app, you'll just need to tweak my implementation a bit. Thanks for reading!