The DatoCMS Blog

Introducing the GraphQL Real-Time Updates API

Posted on November 13th, 2020 by Stefano Verna

Preview content changes are still one of those "not quite covered" elements in Jamstack and static sites. Today, we are thrilled to release a new Real-Time Updates API to address this problem.

Instead of the API consumer only getting the new data upon their next query, with this new API new data is instantly pushed to them. This can be used to preview draft content on the real website as it gets authored by editors, without needing a page refresh.

Looks like magic when you try it:

Updates happen directly inside the browser, so there is no need for a dedicated preview server. Just a couple of lines of code on your frontend website are sufficient to completely change the way you work and interact with your content.

How does it work?

The new API relies on Server-Sent Events, which is a protocol supported natively from all modern browsers, and easily polyfillable on older ones.

If you know how to use DatoCMS GraphQL Content Delivery API, then you already know how to use the new real-time API. Replace the graphql.datocms.com domain to graphql-listen.datocms.com, and you'll receive an SSE channel that will send an update event every time there's a new change:

Our documentation covers everything with much greater detail, of course, but that's the gist of it.

I want to see it with my own eyes!

I bet you do. For the occasion, we've prepared a brand new Starter Project, mimicking a live-blog covering an Apple-like event, deployable on Vercel in less than 2 minutes:

It uses the awesome Next.js, and you also just test it live or read the source code from Github:

And yes, this demo proves that you can also offer real-time updates to your website's final visitors and not only to content editors, if that's what you need. Try it now!

Next.js Event Coverage Liveblog
Next.js Event Coverage Liveblog
Try the full-fledged DatoCMS demo project in minutes.
Deploy the demo project

Integrate it with Next.js

If you're a Next.js user, we've also prepared a specific guide and a step-by-step tutorial to help you integrate real-time updates into your project, so make sure to check those out.

Spoiler alert: you need to add just three lines of code to your page components, and you're done. It's so easy that you'll feel like you're cheating:

import { useQuerySubscription } from "react-datocms";
import { request } from '../lib/datocms';
const graphqlRequest = {
query: "{ allBlogPosts(first: $limit) { title } }",
variables: { limit: 10 },
};
export async function getStaticProps() {
return {
props: {
subscription: {
...graphqlRequest,
initialData: await request(graphqlRequest),
token: process.env.NEXT_PUBLIC_DATOCMS_API_TOKEN,
},
},
};
}
export default function Home({ subscription }) {
// Live updates everyone!!
const { data, error, status } = useQuerySubscription(subscription);
return (<div>{JSON.stringify(data, null, 2)}</div>);
}

How much does it cost?

First and foremost, every DatoCMS project can use the new Real-time Updates API, which we think is great.

Even though it is not billed per se, it uses the Content Delivery API to work, contributing to the number of API calls to it. Realistically speaking, if you use the API with your editors to show them a preview of their work, it will have minimal impact on the overall API call counts.

For more details, take a look at the Limits and Pricing section of the documentation.

That's all, folks!

This feature already has great out-of-the-box value for teams of all sizes, but we are sure it opens up exciting and creative scenarios. We can't wait to see how you use it for your projects!

Here are all the references in the documentation for further details:

As always, if you have specific questions not covered by the documentation or want to talk about your project, let's have a chat in our Community.