Introducing Perspectives: See your content from any angle (ssr)

Written by Jesus De Oliveira, Molly Friederich

Missing Image!

For years, we’ve all focused on getting the right content to the right people at the right time; the headless CMS category emerged in response to this challenge. Now, context is joining the complexity of devices, channels, and audiences. Contexts for your customers (where in the world are they? What are their preferences and patterns?) and for your teams (how do I preview the upcoming campaign or ensure content is rendering correctly for our UK readers?).

Querying the right content to build these increasingly mosaic views of content is hard. Hard enough that teams might settle for subpar experiences. For their audiences, this means less compelling, personalized experiences. For content teams, it means time-consuming hacks to preview a given view of content (or worse, crossing their fingers and hoping everything will “work out” when they click publish).

Announcing Perspectives

Today we’re introducing Perspectives, which dramatically simplifies building audience- or use-case-specific views. With Perspectives, you can add a single parameter to pull the right content variations for any given experience without making special accommodations in code. This enhances developers’ ability to create contextual variations of content (and improves the experience for both content teams and the audiences they serve).

With the launch of our first perspectives, we’re solving the most common use case developers and content teams grapple with, creating high-confidence, comprehensive previews across any device, channel, and context. These are available for all Sanity users and API versions for the GROQ query endpoint since v2021-03-25. To accommodate Perspectives, we've released new versions of the Vision plugin, JavaScript client, and Next.js toolkit. Customers who use GraphQL will find support for Perspectives using the GraphQL endpoint version v2023-08-01 and on. We've put Perspectives to use ourselves to improve Sanity's preview tooling by making live web previews more performant as well as expanding preview support to non-web surfaces like mobile apps.

In the future, we’ll deliver more perspectives to streamline the effort for Sanity users as they create contextual experiences. Just as the previewDrafts perspective simplifies building previews; we want to enable developers to specify a single parameter to power things like:

• Internationalization: Personalize content for audiences worldwide with high confidence you’re pulling the right language for each region.
• Content variants (A/B/N testing): Create alternative variations for documents and develop production tests and personalization.
• Point-in-time snapshots: Preview an upcoming content release, or look back to see previously published content.

For now, let’s take a closer look into what’s in the hands of teams using Sanity today.

Our first Perspectives: Lay eyes on any draft experience

While most solutions offer a rigid, page-based approach to previewing content, Sanity provides the most flexible preview solution for structured content. Since 2019, we’ve supported creating previews for any use case within Sanity Studio: from how your whole site looks to how it shows up in search result pages or even on a mockup of your content for printed materials.

Of course, there’s always room to improve innovation (what if Nabisco had stopped at single-stuffed Oreos?!). Over the past few years, we noticed many customers adding the same expressions across all their queries to build previews. Truth is, doing so while composing the many pieces of content that come together to build modern user experiences often became pretty complex.

Perspectives for previews simplify this complexity; it’s now a matter of specifying a single parameter in the query URL or client configuration. This makes it trivial to pull out all draft documents for a preview mode, and strictly published content for production—regardless of complex joins and different permission models.

There are three perspectives available as part of this release, available now for all Sanity customers on any project plan:

• previewDrafts: retrieves documents in their draft version (or published if no drafts exist). It will also add an originalId property to documents for additional control. As explored below, we designed previewDrafts to simplify the developer experience for building content previews.
• published: retrieves only the published version of documents. You can use this perspective as an extra layer of assurance to avoid draft content leaks for authenticated requests in production.
• raw: preserves the same functionality of queries as they worked pre-Perspectives (and is the default perspective if one is not specified). This means that Perspectives is a non-breaking feature.

The classic before-and-after photo

Let’s do a mini-case study on how the previewDrafts perspective untangles your queries for developing content previews. Let’s say you want to retrieve the draft content of both book documents and the referenced author documents with an authenticated request. Here’s what the query would look like before Perspectives:

*[_type == "book"]{
  title,
  "author": *[_id in [^.author._ref, "drafts." + ^.author._ref]|order(_updatedAt desc)[0]
}

In this query:

• we first filter for draft documents of the book type. We skip the logic of picking the draft/published of those for readability here.
• for author documents, we filter for both the published and draft versions. If there is a draft version, it is returned as first ([0]) in the list with the order(_updatedAt desc) function.

While it’s valuable you can express this complexity with GROQ, for common use cases, it’s better that you don’t need to.

If we first enable the previewDrafts perspective in our client, we can make this query way simpler when we use GROQ with Sanity:

import {createClient} from '@sanity/client'

const client = createClient({
  ...config,
  useCdn: false, // previewDrafts isn't cached on the CDN
  perspective: 'previewDrafts',
})

Now, with the previewDrafts perspective, you can retrieve the same draft content with the following query:

*[_type == "book"]{
  title,
  author->
}

Ahhhh, that’s nice. We replaced the whole sub-query logic in the example above with a simple join expression (->). This simplification makes the query all the more readable and easy to reason about (and reduces the risk of errors).

Get started with Perspectives

The first release of Perspectives which powers previews is now available for all Sanity users. GROQ users can utilize the query endpoint from version v2021-03-25 and on. GraphQL users can utilize the GraphQL endpoint from version v2023-08-01 and on. We’re eager for you to put it to use to save time and code. Here’s how developers can get started depending on your use case:

• Upgrade Vision, our GROQ playground plugin for Sanity Studio, to the latest version to filter results with a specified perspective
• Upgrade the JavaScript client to the latest version and specify a perspective in the client configuration. You can go to its documentation for more details.
• If you run requests against the query or GraphQL endpoints directly or from your own tooling, then Perspectives can be accessed by adding the parameter &perspective=previewDrafts (or published or raw) to the URL. More details are in our queries and GraphQL documentation.

We provided a tour of Perspectives and other new features at our Summer Release Demo on August 2. It's now available to watch on demand!