Live Content API: Don't get stuck in a storm waiting for Dua Lipa

The title is inspired by real experiences.

Most content will need to change at some point. Some content doesn't need to change all that often. But for time-sensitive information like inventory status, breaking news, or audience interactions, having content that's truly live is absolutely critical. At Sanity, we have just released a new Live Content API that together with our upgrades to our CDN infrastructure, will make it possible to push content updates in real-time in a way that scales.

Why is scaling important? Imagine you're building a site for a big music festival (that unlike certain festivals will actually happen), with thousands of fans eagerly awaiting updates. The festival need a way to keep them all informed in real-time, whether they're at the main stage or the camping grounds. You want to be sure that whatever you're posting on social media, is reflected in your web applications and apps too.

Or maybe you are making a storefront for a popular clothing brand who’s doing Black Friday sales with limited inventory that's selling out fast. Chances are that your customers are spread out throughout the world as well. And they are impatient customers with high expecations that you don’t want to disappoint by leading them into a check-out flow, just to let them know that the items aren’t available.

Or perhaps you're building a sports site providing live scores and updates during the big game. Fans want to know what's happening as it happens, whether they're in the stadium or watching from home. They want to share in the same moment at the same time. They might be on their laptop or their phone. You want to accomodate live content updates anywhere your content is delivered.

That's what our new Live Content API is for. It gives you a way to integrate live content into your application in a way that scales and performs well. With just a few lines of code, you can start pushing live updates to your audience, without the hassle of managing websocket connections or rebuilding your site every time something changes. The Live Content API does the heavy lifting, so you can focus on creating amazing experiences.

We have made the Live Content API available for everyone in an experimental version. It will be available on all plans, with tiers for concurrent connections (to be announced).

And it’s a unique solution that’s unmatched in the CMS market (as far as we know): It does not require authentication, it works globally for your changes in your dataset, it’s not limited to specific queries (like GROQ listeners/GraphQL subscriptions) and you can use it in tandem with the Content CDN.

In other words, it enables Live by Default.

Let’s take a closer look at how it works and a demo of how it can be used with React Server Components in Next.js.

How the Live Content API works

The Live Content API is designed to make it easy to integrate live content into your application while still leveraging the Sanity Content Lake CDN for content delivery. Of course, we'll release tooling and abstractions to make the developer experience great, but here’s roughly how it works:

1. When fetching content, syncTags will be passed along with the response.
2. These tags identify the specific pieces of content that were returned.
3. You can then use these to subscribe to a stream of live updates that returns an Observable that emits events whenever content in your dataset changes (yes, that's quite a sentence).
4. When you receive an event, you can check if any of the event tags match the sync tags from the content you want to keep up to date.
5. A match can trigger a refetch of the content from the CDN (that has revalidated) using a paramt to ensure it’s the revalidated fresh content.

By following this pattern, you can efficiently keep your application's content in sync with the latest changes in your Sanity dataset, without having to constantly poll for changes or rebuild your entire site.

Example: Live blog with Next.js and React Server Components

Goal: Update a website with new published content for everyone without requiring manual reloading. Like this example of a live blog that covers the React Conf 2024 Keynote:

Let's take a look at how we can build a live blog using Next.js and React Server Components with the Live Content API. The demo repository is over here if you want to run it for yourself.

Set up the experimental sanityFetch

In a canary of the next-sanity toolkit (pnpm i next-sanity@canary), we have included a new function called defineSanityFetch that takes a client configuration and sets the searchParamKey where we store the state for when the last event was recieved.

// ./sanity/lib/fetch.ts
import { apiVersion } from './../env';
import { defineSanityFetch } from "next-sanity/live-subscription";

import {client} from './client'

export const sanityFetch = defineSanityFetch({
  client,
  searchParamKey: 'lastLiveEventId'
})

Fetch content with the live subscription component

Now you can use sanityFetch with GROQ to fetch content and the LiveSubscription component that you put anywhere in your component to add Live Content support:

// ./components/Feed.tsx
import { sanityFetch } from "@/sanity/lib/fetch"
import { LastLiveEventIdProps } from "./LiveBlog"
import { groq, PortableText } from "next-sanity"
import { FeedQueryResult } from "@/sanity.types"

const feedQuery = groq`*[_type == "post"]|order(_createdAt desc)`

// `lastLiveEventId` is passed down from the route component's `searchParams` prop
export async function Feed({ lastLiveEventId }: LastLiveEventIdProps) {
  const [posts, LiveSubscription]: [FeedQueryResult, any] = await sanityFetch({
    query: feedQuery,
    lastLiveEventId,
  })

  return (
    <div>
      {posts.map((post) => {
        const time = new Date(post._createdAt).toLocaleTimeString()
        return (
          <div key={post._id}>
            <div>
              <div>{time}</div>
            </div>
            <div>
              <h3>{post.title}</h3>
              <div>
                {post.body && <PortableText value={post.body} />}
              </div>
            </div>
          </div>
        )
      })}
      <LiveSubscription />
    </div>
  )
}

That’s it!

That's it! With just a few lines of code, you can start integrating live content into your application. The Live Content API handles all the heavy lifting of managing connections and delivering updates efficiently.

Of course, there's a lot more you can do with the Live Content API. Check out the documentation for more details on how it works and how to implement it.

Make your content “Live by Default”

We believe the Live Content API lowers the bar for developers to build dynamic, engaging applications. It opens up a whole new world of possibilities for real-time experiences.

But don't just take our word for it. Try it out for yourself and see the difference it makes. And let us know what you build and how it works for you!

And if you have any questions or feedback, don't hesitate to reach out. We're here to help you succeed with live content.

So what are you waiting for? Go forth and make your content live by default!