👋 Next.js Conf 2024: Come build, party, run, and connect with us! See all events

Presenting and previewing content

Previewing changes to your content in a secure and high-fidelity setting before publishing is essential to a smooth editorial process.

By presenting all in-flight changes together within the real experience, content creators, reviewers, and stakeholders can get a realistic view of what the experience will look like when these changes are published. High-fidelity content previews enable valuable and accurate feedback, validation, and approvals before rolling out updates.

Likewise, ensuring that your "production" or "public" experience or application only presents published content is critical to ensuring that what is presented to your consumers is complete, validated, and approved.

Sanity offers a range of tools and Perspectives for Content Lake to help you build first-class preview experiences.

Protip

This article focuses on preview environments outside the studio. To learn more about the various ways of previewing content changes within Sanity Studio, please visit this article.

A key feature of composable content is that you can shape data from a variety of independent but interconnected documents into whatever shape is required on the consuming end. For content authored in Sanity Studio, all unpublished changes are tracked in draft documents that co-exist with the published version of the same document. With content spread over multiple documents, each with its own publishing state, creating robust preview tooling can become cumbersome.

Perspectives is an out-of-the-box solution that does away with the heavy lifting of creating engaging preview experiences.

Defining "published"

For simplicity, this article assumes that the publish status on the consuming end matches that of the Content Lake. That is, a document that is published in your studio should be visible in the front-end, while unpublished changes in draft documents are what’s most relevant for previewing purposes.

Content Lake Perspectives

Perspectives let you run your queries against an alternate "view" of the documents in your dataset. Use the previewDrafts perspective to preview what your content would look like if all drafts and changes were published, or set the published perspective in your production environment to make sure no unfinished draft content is accidentally made public.

The perspective is set as a property of the Sanity client configuration or passed as a parameter to the HTTP API query endpoints, allowing you to reuse queries between preview and production environments.

Best practice

Web applications often use perspectives to retrieve initial server-side or static content.

  • In your production environment, queries use the published perspective.
  • In preview environments, queries use the previewDrafts perspective and are then hydrated with live updates via Loaders.
// Example JS/TS client configuration
import {createClient} from '@sanity/client'

const client = createClient({
  ...config,
  useCdn: false, // must be false for 'previewDrafts'
  perspective: 'previewDrafts', // 'raw' | 'published' | 'previewDrafts' 
})
// Example using HTTP API
/data/query/production?query=*[]&perspective=previewDrafts

raw

The default behavior of the client, which you can set explicitly by specifying the raw perspective, is to return both drafts and published content for authenticated requests. This perspective is assumed if no value is set for the perspective property.

previewDrafts

When using this perspective, your queries will return as if all draft documents in your dataset were published. This means:

  • References to draft documents will be resolved/dereferenced normally, exactly as when dereferencing published documents
  • Query results will not be cached in the CDN, ensuring you always get the latest most up-to-date version of in-flight changes
  • When using custom permission resources, draft documents will be presented only when the user’s permissions grant access to the draft document; otherwise, the published version is presented

published

When you use this perspective, your queries will operate as if there were no draft documents in your dataset, i.e. no draft document will ever be returned.

Preview tooling

The Perspectives feature alone can enable running independent preview and production environments, but for truly custom, interactive live-as-you-type preview, Sanity also offers powerful tooling for any front end framework and offers guides on the most popular ones.

Filtering drafts from published documents without Perspectives

If, for some reason, you want to filter documents based on their draft status without using perspectives, you can check the documents _id for the drafts. path segment. Note that this query only makes sense when using the default (raw) perspective, since previewDrafts and published will return no documents with drafts. in their path.

[!(_id in path('drafts.**'))] // _id matches anything that is not in the drafts-path

Protip

Pro-tip: By default, documents with a period in their ID are hidden from unauthenticated queries. Requests from authenticated users will result in drafts (and other documents with periods in their paths) being returned side by side with published documents.

Was this article helpful?