No more refresh button
If you have an existing Sanity project, you may prefer to read the Live Content API Docs for details on how to set it up in your application.
What's covered in this guide
You'll create a new free Sanity project using the Next.js template, publish new documents with Sanity Studio and explore how the Live Content API works.
Create a new project
From the command line, create a new free Sanity project using the Next.js template.
If you don't already have an account with Sanity, you'll be prompted to create one.
npm create sanity@latest -- --template sanity-io/sanity-template-nextjs-clean --coupon=real-guide
Now inside this directory, start the development server.
npm run devYou should now have two apps running:
- http://localhost:3000 – Your Next.js app
- http://localhost:3333 – Your Sanity Studio
These apps are separately configured in the following directories:
├─ /nextjs-app └─ /studio
The Sanity Studio is configured with code, edits you make to the configuration will render immediately in the development environment.
Content in Sanity Studio is written to a schemaless, cloud-hosted Dataset in what we call the Content Lake.
The Next.js app fetches content using Sanity Client with the GROQ query language.
Enter the Studio
Open http://localhost:3333 and log in to your Sanity Studio. The first tab that will open is the Presentation tool.
The Presentation tool is used to view your Next.js front end (http://localhost:3000) within an Iframe so that you can interact with your content.
💡 To see how Presentation can be used for interactive live preview of draft content, see the guide in this series on Visual Editing.
Publish a new post
Click "+ Create" from the top menu and select "Post."
The post document type currently has a few required fields. You will need to give this new document a
- Title
- Slug
- Cover Image
- and alternative text for the image
Once the Publish button is enabled, publish the post.
Open the post in Presentation
At the top of the document, you will see a box saying "Used on 2 pages" which you can open to show the locations of the current document in the front end.
Click the first location and you'll see the front end open side-by-side with the document editor. Make a change to the document and press Publish. You'll see the document update again, without a reload!
It's really real-time!
Open your Next.js application in a separate private browser window, and keep it open while you publish another change to the blog post. You should see the on-page content update briefly, without having to press reload, rebuild the site or purge the cache.
How this works
Sanity Client
Open nextjs-app/sanity/lib/client.ts
The most common way to interact with Sanity projects in JavaScript applications is with Sanity Client. One has been configured in the Next.js app for you.
Within the default configuration are settings for the Project ID and Dataset which you created at the beginning of this guide.
The other settings here in Sanity Client relate to Visual Editing.
You could use Sanity Client to fetch for content, but it would only be done once, at page load time. To go live we pass this client instance to another helper...
Sanity Live
Open nextjs-app/sanity/lib/live.ts
(The screenshot above has been simplified from the version in the template, to remove the token which is used for Visual Editing)
The defineLive helper from next-sanity allows you to turn a static fetch at load-time into a live-updating data source. Your Next.js app listens to published changes in your Dataset and refreshes content without the need to reload. It also handles caching.
Root layout component
Open nextjs-app/app/layout.tsx
The <SanityLive /> component comes from the defineLive helper and sets up the Event Source listener for content changes for the result of any fetches performed with sanityFetch.
The combination of <SanityLive /> and sanityFetch is all you need to make a Next.js application "live by default."
Next steps
Some ideas of what you might do next.
- Commit this repository to your Git provider and deploy to Vercel to share these live previews with content creators
- Add or edit Sanity Studio schema types. The template comes with a few already created, try adding a new field to
post.tsin the/studiodirectory and see how the Studio updates imediately. - Explore GROQ,
queries.tsin the/nextjs-appdirectory contains all the queries that the Next.js app currently makes. You can test queries in the Studio using the Vision tool. - Take the Day One with Sanity Studio Course to get a from-the-ground-up understanding of how to create new Sanity projects.
