Post index
-
{posts.map((post) => (
- {post?.title} ))}
← Return home
← Return home
Post index
-
{posts.map((post) => (
- {post?.title} ))}
← Return home
{post?.title}
← Return to index
{post?.title}
← Return to index
{post?.title}
← Return to index
{post?.title}
{post?.body ? (← Return to index
{author?.image ? (
) : null
}
```
1. **Create** a `Categories` component
```tsx:src/components/categories.tsx
import { POST_QUERYResult } from '@/sanity/types'
type CategoriesProps = {
categories: NonNullable{author.name}
) : null}{dayjs(publishedAt).format('D MMMM YYYY')}
) : null } ``` 1. **Create** a `Title` component for rendering a page title in a ``
```tsx:src/components/title.tsx
import { PropsWithChildren } from 'react'
export function Title(props: PropsWithChildren) {
return (
{props.children}
)
}
```
1. **Create** a `Post` component for rendering the above components on a single post page
```tsx:src/components/post.tsx
import { PortableText } from 'next-sanity'
import Image from 'next/image'
import { Author } from '@/components/author'
import { Categories } from '@/components/categories'
import { components } from '@/sanity/portableTextComponents'
import { POST_QUERYResult } from '@/sanity/types'
import { PublishedAt } from '@/components/published-at'
import { Title } from '@/components/title'
import { urlFor } from '@/sanity/lib/image'
export function Post(props: NonNullable) {
const { title, author, mainImage, body, publishedAt, categories } = props;
return (
{title}
{mainImage ? (
) : null}
{body ? (
);
}
```
1. **Create** a `PostCard` component for rendering the above components on the post index page
```tsx:src/components/post-card.tsx
import Link from 'next/link'
import Image from 'next/image'
import { Author } from '@/components/author'
import { Categories } from '@/components/categories'
import { POSTS_QUERYResult } from '@/sanity/types'
import { PublishedAt } from '@/components/published-at'
import { urlFor } from '@/sanity/lib/image'
export function PostCard(props: POSTS_QUERYResult[0]) {
const { title, author, mainImage, publishedAt, categories } = props
return (
{title}
)
}
```
1. **Create** a `Header` component for the top nav of the site
```tsx:src/components/header.tsx
import Link from 'next/link'
export function Header() {
return (
Layer Caker
-
Posts
-
Sanity Studio
)
}
```
## Update your routes
Now that you have many small components, it's time to import them into your routes to complete the design.
1. **Update** the root layout to display the site-wide navigation
```tsx:src/app/(frontend)/layout.tsx
import { Header } from '@/components/header'
import { SanityLive } from '@/sanity/lib/live'
export default function FrontendLayout({
children,
}: Readonly<{
children: React.ReactNode
}>) {
return (
)
}
```
1. **Update** the root page to use the `Title` component
```tsx:src/app/(frontend)/page.tsx
import Link from 'next/link'
import { Title } from '@/components/title'
export default async function Page() {
return (
Layer Caker Home Page
Posts index →
)
}
```
1. **Update** the post index page to use the `PostCard` component
```tsx:src/app/(frontend)/posts/page.tsx
import Link from 'next/link'
import { sanityFetch } from '@/sanity/lib/live'
import { POSTS_QUERY } from '@/sanity/lib/queries'
export default async function Page() {
const { data: posts } = await sanityFetch({ query: POSTS_QUERY })
return (
Post index
{posts.map((post) => (
-
{post?.title}
))}
← Return home
)
}
```
1. **Update** the individual post route to use the `Post` component
```tsx:src/app/(frontend)/posts/[slug]/page.tsx
import { notFound } from 'next/navigation'
import { sanityFetch } from '@/sanity/lib/live'
import { POST_QUERY } from '@/sanity/lib/queries'
import { Post } from '@/components/post'
export default async function Page({
params,
}: {
params: Promise<{ slug: string }>
}) {
const { data: post } = await sanityFetch({
query: POST_QUERY,
params: await params,
})
if (!post) {
notFound()
}
return (
)
}
```
## All done!
Click around the site now. You should have a richer site-wide header, post index, and individual post pages.
You're also in a much better position for the remaining lessons in this track. Let's test what you've learned in the final lesson.## [Fundamentals quiz](/learn/course/content-driven-web-application-foundations/fundamentals-quiz)
A quick test of everything you've learned through this course.
With the skills learned in this course, you can now build and deploy content-editable applications that serve three user groups that are impacted by the work we do:
* **Developers** can now collaboratively code, deploy, and repeat.
* **Authors** can now collaboratively write, publish, and repeat.
* **End users** can now consume content and act on it.
Here are a few quiz questions designed to reinforce what you've learned.
**Question:** What is the purpose of using Sanity and Next.js?
1. To create a content-editable application for end users and authors
2. To ensure we're on the cutting edge
3. To generate TypeScript types
4. To make a website
**Question:** Which command creates a new Sanity project inside a Next.js application
1. npm install sanity
2. next init
3. sanity init
4. yarn add sanity
**Question:** What enables route-level fetching in async components?
1. React Query
2. React Server Components
3. Sanity Client
4. Promises
**Question:** What is the purpose of using Git in a development workflow?
1. Deploying the application to Vercel
2. Collaboration with developer team members
3. Creating preview builds from branches
4. All of the above
**Question:** Why use the Next.js Image component?
1. To silence eslint warnings
2. Improved performance and optimization
3. You can't display images without it
4. GIF support
**Question:** What format does the Portable Text editor write?
1. Markdown
2. HTML
3. Portable Text
4. Textile
**Question:** What is the purpose of the PortableText React component?
1. To convert Portable Text to MDX
2. To author Portable Text
3. To serialize Portable Text into components
4. To query Portable Text
**Question:** How are TypeScript types generated from schema and queries?
1. Sanity Studio
2. Sanity TypeGen
3. Sanity Manage
4. GROQ
## What's next?
With the fundamentals finished, it's time to make the rendering and editing experience even more robust by completing the following courses in this track.# [SEO optimized content with Next.js](/learn/course/seo-optimization)
SEO doesn't have to be complicated. It's a matter of taking content you've already responsibly structured with Sanity and rendering it in the format and places that search engines expect. Complete this course to improve how robots and humans interact with your content with Sanity and Next.js
## [An introduction to SEO and structured content](/learn/course/seo-optimization/an-introduction-to-seo-and-structured-content)
A few core principles, applied consistently, can form a solid foundation that benefits both search engines and editorial workflows.
## About this course
This course will guide you on the best practices of building SEO-optimized content in Next.js with Sanity.
Rather than getting bogged down in complex SEO configurations, the focus is on creating simple but effective schema types and queries that give content editors flexibility while maintaining SEO best practices.
This approach emphasizes pragmatic solutions that address essential SEO needs without adding unnecessary complexity.
It focuses on structuring content for both search engines and editorial teams, offering smart defaults along with optional granular controls. The aim is to simplify SEO-friendly content creation while adhering to Next.js best practices.
## About the author
I'm Jono, the founder of [Roboto Studio](https://robotostudio.com/?utm-source=sanity-learn).
We specialize in building the best editorial experiences on the web with Sanity and Next.js
I'm excited to share our opinionated but battle-tested approach to SEO with you. This isn't just theory - these are the same patterns we use successfully with our clients every day.
Also a special thanks to Sne and Hrithik for their help structuring this course.
## Simplifying SEO with structured content
SEO is often presented as a complex endeavor, but it is more straightforward than commonly assumed. A few core principles, applied consistently, can form a solid foundation that benefits both search engines and editorial workflows.
A well-structured content model handles most of the heavy lifting, removing the need for overly complex schemas or endless metadata fields. This approach facilitates agnostic SEO practices. This means you can incrementally adopt SEO best practices without having to always enter content from scratch.
Next.js includes opinionated API's that streamline SEO optimization. Aligning Sanity schema types and queries with these conventions creates an effective framework for building SEO-ready websites.
In the following lessons we will take a closer look at how we can leverage structured content and Next.js to help search engines understand and rank your content.## [SEO schema types and metadata](/learn/course/seo-optimization/seo-schema-types-and-metadata)
Prepare useful, optional and reusable schema types specifically for SEO content and render them into page metadata the Next.js way.
For the benefit of content authors, fields relevant to SEO should not always be required. Instead, they should be used to override some existing content, when provided.
## Create an SEO schema type
No matter what document type you're applying SEO content to, the same data will be required. For example a title, description, image and more. So to easily re-use these fields you'll register a custom schema type to the Studio
1. **Create** a new schema type for SEO fields
```typescript:src/sanity/schemaTypes/seoType.ts
import { defineField, defineType } from "sanity";
export const seoType = defineType({
name: "seo",
title: "SEO",
type: "object",
fields: [
defineField({
name: "title",
description: "If provided, this will override the title field",
type: "string",
}),
],
});
```
1. **Update** your registered schema types to include `seoType`
```typescript:src/sanity/schemaTypes/index.ts
// ...all your other imports
import { seoType } from "./seoType";
export const schema: { types: SchemaTypeDefinition[] } = {
types: [
// ...all your other types
seoType,
],
};
```
1. **Update** your `page` and `post` document types to include the SEO fields
```typescript:src/sanity/schemaTypes/pageType.ts
export const pageType = defineType({
// ...all other configuration
fields: [
// ...all other fields
defineField({
name: "seo",
type: "seo",
}),
],
});
```
1. Throughout the rest of this course you'll be expected to keep both the `page` and `post` document schema types, GROQ queries and Next.js routes updated—but code examples may only be shown for the `page` type.
You should now see the SEO object field at the bottom of `page` and `post` document types in the Studio.
## Queries with fallbacks
In the description field of the SEO title, we've informed the author that the title is not required, but that it will override the title field if provided.
The title field is likely to be sufficient for SEO the majority of the time, but if for some reason it needs to be different, the author now has an avenue to override it.
For the front-end to respect this, there are a few ways to do it. You _could_ choose which field to render with logic like this:
```tsx:Example only
{seo?.title ?? title}
```
But then we'd need to duplicate that logic _everywhere_ we optionally render the correct value. It's also annoying because the `seo` attribute may or may not exist.
Because we have GROQ, we can move all this logic into our query instead.
1. **Update** the `PAGE_QUERY` to include an `seo` attribute with values and fallbacks
```typescript:src/sanity/lib/queries.ts
export const PAGE_QUERY =
defineQuery(`*[_type == "page" && slug.current == $slug][0]{
...,
"seo": {
"title": coalesce(seo.title, title, ""),
},
content[]{
...,
_type == "faqs" => {
...,
faqs[]->
}
}
}`);
```
Don't forget to update your POST_QUERY to include the same projection.
1. `coalesce()` is a GROQ [GROQ Functions Reference](https://www.sanity.io/learn/specifications/groq-functions) that returns the first value that is not null
Now `seo.title` will never be `null`, and contain either the optionally provided SEO title, or the page title, or an empty string.
1. **Run** the following command to update your Types now that you've made schema and query changes
```sh
npm run typegen
```
1. This command was setup in the [Generate TypeScript Types](https://www.sanity.io/learn/course/content-driven-web-application-foundations/generate-typescript-types) lesson of the [Content-driven web application foundations](https://www.sanity.io/learn/course/content-driven-web-application-foundations) course.
Just to prove this works, update the dynamic route that renders your pages to include a `` tag. It is a [feature of React 19](https://react.dev/blog/2024/12/05/react-19#support-for-metadata-tags) to move meta tags into the `<head>` tag. (But it's not how Next.js 15 recommends, you'll do that later).
1. **Update** the dynamic page route to include the `<title>` tag
```tsx:src/app/(frontend)/[slug]/page.tsx
import { PageBuilder } from "@/components/PageBuilder";
import { sanityFetch } from "@/sanity/lib/live";
import { PAGE_QUERY } from "@/sanity/lib/queries";
export default async function Page({
params,
}: {
params: Promise<{ slug: string }>;
}) {
const { data: page } = await sanityFetch({
query: PAGE_QUERY,
params: await params,
});
return (
<>
<title>{page.seo.title}
{page?.content ? (
` tag inside the `<head>`.
## Metadata, the Next.js way
The problem with relying on the previous method is deduplication. React will render multiple `<title>` tags when it finds them, and your Next.js application may eventually use nested layouts where this is a possibility.
Instead, Next.js has an API to export a uniquely named function from a route to take the same dynamic data that is rendered into the page to generate those meta tags as required.
In the example below we have extracted the `sanityFetch` to its own function, because now it will be re-used multiple times. (Which Next.js should cache and only run once). Inside the `generateMetadata` function, the same `seo.title` value is used to generate a `<title>` tag in the final markup.
1. **Update** your `page` route to generate metadata and the rendered on-page content in separate functions.
```tsx:src/app/(frontend)/[slug]/page.tsx
import type { Metadata } from "next";
import { PageBuilder } from "@/components/PageBuilder";
import { sanityFetch } from "@/sanity/lib/live";
import { PAGE_QUERY } from "@/sanity/lib/queries";
type RouteProps = {
params: Promise<{ slug: string }>;
};
const getPage = async (params: RouteProps["params"]) =>
sanityFetch({
query: PAGE_QUERY,
params: await params,
});
export async function generateMetadata({
params,
}: RouteProps): Promise<Metadata> {
const { data: page } = await getPage(params);
return {
title: page.seo.title,
};
}
export default async function Page({ params }: RouteProps) {
const { data: page } = await getPage(params);
return page?.content ? (
<PageBuilder
documentId={page._id}
documentType={page._type}
content={page.content}
/>
) : null;
}
```
Following the same pattern, you can add SEO overrides for other important metadata tags. Such as a `<meta name="description" />` tag. This is what Google uses to display a description of your page in the search results.
Again, you can also add an override for the `seoImage` field, which will be used to populate the `<meta property="og:image" />` tag.
The most important takeaway from this, is that you always want to have an override, and a fallback. It keeps consistency in your content, and standardizes the way you query your SEO fields.
Don't forget to update your individual post route to use the same conventions.
1. Take a look at the Next.js [metadata documentation](https://nextjs.org/docs/app/building-your-application/optimizing/metadata) for more information.
## Just getting started
At this point, you can see how the pattern works, and how this is easy to extend to other SEO fields.
In the next lesson, you will enhance your SEO functionality by adding more fields, including those for Open Graph data, and one to control search engine indexing## [Extending the SEO schema types](/learn/course/seo-optimization/adding-seo-fields-to-your-project)
Now you're setup for success, extend the fields made available to your authors.
In the first lesson, you learned how to add some basic SEO fields to your schema. Now you're going to kick it up a notch with Open Graph fields and more granular controls over displaying documents in lists.
## Add more SEO fields
1. **Update** your `seoType` schema type to include `description`, `image` and a `noIndex` field
```typescript
import { defineField, defineType } from "sanity";
export const seoType = defineType({
name: "seo",
title: "SEO",
type: "object",
fields: [
defineField({
name: "title",
description: "If provided, this will override the title field",
type: "string",
}),
defineField({
name: "description",
type: "text",
}),
defineField({
name: "image",
type: "image",
options: {hotspot: true}
}),
defineField({
name: "noIndex",
type: "boolean",
}),
],
});
```
You may wish to have separate title and description fields for Open Graph properties. But in this course you'll re-use these values.
1. **Update** `PAGE_QUERY` and `POST_QUERY` to include these new attributes, along with default values
```typescript:src/sanity/lib/queries.ts
export const PAGE_QUERY =
defineQuery(`*[_type == "page" && slug.current == $slug][0]{
...,
"seo": {
"title": coalesce(seo.title, title, ""),
"description": coalesce(seo.description, ""),
"image": seo.image,
"noIndex": seo.noIndex == true
},
content[]{
...,
_type == "faqs" => {
...,
faqs[]->
}
}
}`);
```
1. **Run** the following to regenerate Types now that you've made schema and query changes
```sh
npm run typegen
```
## Render more metadata
With these fields now present in your schema types and queries, you can now render even more metadata in your route.
Note in the code below how the Open Graph image reuses the `urlFor` helper function to generate an image the correct width and height–and will also respect crop and hotspot data.
The value for `noindex` we only include in the metadata if it is set to true.
```typescript:src/app/(frontend)/[slug]/page.tsx
// ...the rest of your route
export async function generateMetadata({
params,
}: RouteProps): Promise<Metadata> {
const { data: page } = await getPage(params);
if (!page) {
return {}
}
const metadata: Metadata = {
title: page.seo.title,
description: page.seo.description,
};
if (page.seo.image) {
metadata.openGraph = {
images: {
url: urlFor(page.seo.image).width(1200).height(630).url(),
width: 1200,
height: 630,
},
};
}
if (page.seo.noIndex) {
metadata.robots = "noindex";
}
return metadata;
}
```
Don't forget to update your individual post route as well.
### A note on `noIndex`
Having a page set to `noIndex` typically means that you want the published document to exist as a route in your application—but you don't want it included in search results. Either on search engine results or within your website.
Nothing needs to change now with your page type documents, but if you were to include these fields in your post type documents, you'd likely want to update any query that looks up and renders many posts to exclude results where `noIndex` is true. For example:
```groq:Example only
*[_type == "post" && seo.noIndex != true]
```
You'll see an example of this later in the lesson [Build a dynamic sitemap](https://www.sanity.io/learn/course/seo-optimization/building-a-dynamic-sitemap).
Now your Sanity Studio and application are capable of authoring, querying and rendering complex metadata for the most common SEO needs. You can continue to extend these fields for any other metadata requirements.
In the following lesson you'll take on another major SEO concern: redirects.## [Implementing redirects](/learn/course/seo-optimization/implementing-redirects)
Redirects are a critical component of SEO and site maintenance. While they may appear straightforward at first, improper implementation can lead to complex redirect chains and degraded site performance.
Let's go through best practices for implementing redirects with Next.js and Sanity.
## Learning objectives
You will create a redirect system that:
* Is configured with documents in Sanity Studio
* Can be managed by your content team
* Won't create a maintenance headache later
## Creating the schema
Let's start with your redirect schema type first. You want to make this as editor friendly as possible. The goal is to build a non-technical solution that can be managed by your content team, and output to your Next.js configuration.
1. See the Next.js [documentation about creating redirects](https://nextjs.org/docs/app/building-your-application/routing/redirecting#redirects-in-nextconfigjs)
Below is a simplified document schema, which you'll make much smarter with validation rules later in the lesson.
1. **Create** a new document schema type for redirects
```typescript:src/sanity/schemaTypes/redirectType.ts
import { defineField, defineType } from "sanity";
import { LinkIcon } from "@sanity/icons";
export const redirectType = defineType({
name: "redirect",
title: "Redirect",
type: "document",
icon: LinkIcon,
fields: [
defineField({
name: "source",
type: "string",
}),
defineField({
name: "destination",
type: "string",
}),
defineField({
name: "permanent",
type: "boolean",
initialValue: true,
}),
defineField({
name: "isEnabled",
description: "Toggle this redirect on or off",
type: "boolean",
initialValue: true,
}),
],
});
```
Don't forget to register it to your Studio schema types
```typescript:src/sanity/schemaTypes/index.ts
// ...all other imports
import { redirectType } from "./redirectType";
export const schema: { types: SchemaTypeDefinition[] } = {
types: [
// ...all other schema types
redirectType,
],
};
```
1. **Update** your structure builder configuration to add the redirect document type:
```typescript:src/sanity/structure.ts
// add this line
S.documentTypeListItem('redirect').title('Redirects')
```
## Fetching the redirects
The redirect documents created in Sanity Studio will need to be queried into our Next.js config file.
1. **Update** `queries.ts` to include a GROQ query for redirect documents
```typescript:src/sanity/lib/queries.ts
// ...all other queries
export const REDIRECTS_QUERY = defineQuery(`
*[_type == "redirect" && isEnabled == true] {
source,
destination,
permanent
}
`);
```
1. **Create** a new utility to fetch all redirect documents
```typescript:src/sanity/lib/fetchRedirects.ts
import { client } from "./client";
import { REDIRECTS_QUERY } from "./queries";
export async function fetchRedirects() {
return client.fetch(REDIRECTS_QUERY);
}
```
Since you've added schema types and a new query to the application, don't forget to generate Types.
```sh:Terminal
pnpm run typegen
```
### Things to note
* Vercel has a limit of 1,024 redirects in Next.js config.
* For large numbers of redirects (1000+), use a custom middleware solution instead. See Vercel's documentation on [managing redirects at scale](https://nextjs.org/docs/app/building-your-application/routing/redirecting#managing-redirects-at-scale-advanced) for more details.
## Add redirects in your Next.js config
Now we can use Next.js's built-in redirects configuration in `next.config.ts`. This allows us to define redirects that will be applied at build time. Note that redirects defined in `next.config.ts` run **before** any middleware, should you use it in the future.
1. **Update** your `next.config.ts` file to include redirects
```typescript:next.config.ts
// ...other imports
import { fetchRedirects } from "@/sanity/lib/fetchRedirects";
const nextConfig: NextConfig = {
// ...other config
async redirects() {
return await fetchRedirects();
},
};
export default nextConfig;
```
## Validation rules
Validation is critical as invalid redirects can break future builds. Without validation, authors could publish a redirect that prevents your application from deploying—or create a deployment with circular redirects.
* Source paths must start with `/`
* Never create circular redirects like `A` -> `B` -> `A`
Here's the validation logic, yes it's a bit complex but it's worth it to avoid hours of debugging, when your build breaks because of a missing slash.
1. **Update** the `source` field in the `redirectType` schema
```typescript:src/sanity/schemaTypes/redirectType.ts
import { defineField, defineType, SanityDocumentLike } from "sanity";
import { LinkIcon } from "@sanity/icons";
function isValidInternalPath(value: string | undefined) {
if (!value) {
return "Value is required";
} else if (!value.startsWith("/")) {
return "Internal paths must start with /";
} else if (/[^a-zA-Z0-9\-_/:]/.test(value)) {
return "Source path contains invalid characters";
} else if (/:[^/]+:/.test(value)) {
return "Parameters can only contain one : directly after /";
} else if (
value.split("/").some((part) => part.includes(":") && !part.startsWith(":"))
) {
return "The : character can only appear directly after /";
}
return true;
}
function isValidUrl(value: string | undefined) {
try {
new URL(value || "");
return true;
} catch {
return "Invalid URL";
}
}
export const redirectType = defineType({
name: "redirect",
title: "Redirect",
type: "document",
icon: LinkIcon,
validation: (Rule) =>
Rule.custom((doc: SanityDocumentLike | undefined) => {
if (doc && doc.source === doc.destination) {
return ["source", "destination"].map((field) => ({
message: "Source and destination cannot be the same",
path: [field],
}));
}
return true;
}),
fields: [
defineField({
name: "source",
type: "string",
validation: (Rule) => Rule.required().custom(isValidInternalPath),
}),
defineField({
name: "destination",
type: "string",
validation: (Rule) =>
Rule.required().custom((value: string | undefined) => {
const urlValidation = isValidUrl(value);
const pathValidation = isValidInternalPath(value);
if (urlValidation === true || pathValidation === true) {
return true;
}
return typeof urlValidation === "boolean"
? urlValidation
: pathValidation;
}),
}),
defineField({
name: "permanent",
description: "Should the redirect be permanent (301) or temporary (302)",
type: "boolean",
initialValue: true,
}),
defineField({
name: "isEnabled",
description: "Toggle this redirect on or off",
type: "boolean",
initialValue: true,
}),
],
});
```
The additional validation logic now thoroughly checks:
* If the `source` is a valid internal path
* If the `destination` is a valid URL, or valid internal path
* If the `source` and `destination` values are different
## Pro tips from experience
* Keep an eye on redirect chains, they can cause "too many redirects" errors
* Clean up old redirects periodically
* Consider logging redirects if you need to track usage
* Adjust the cache duration based on how often you update redirects
* You may need to redeploy your site as new redirects are added or existing redirects are modified
Next up, you'll learn how to generate Open Graph images using Tailwind CSS and Vercel edge functions.## [Creating dynamic Open Graph images](/learn/course/seo-optimization/creating-dynamic-open-graph-images-with-vercel-og)
Generate dynamic Open Graph images that pull your data directly from Sanity, saving you hours of design work and ensuring your social previews are always up to date with your content.
Open Graph images (or social cards) are the preview images that appear when your content is shared on social media platforms. It is proven that having these images included with your social shares increases click through rates.
Dependent on which platform you're sharing to, you may want to create a range of different aspect ratios. For this tutorial, you'll create the most common size, `1200x630` pixels.
As always, you'll set this up in such a way that if you do upload a bespoke image to the `seo.image` field, it will override the automatically generated one.
## Learning objectives
By the end of this lesson, you'll be able to:
* Generate dynamic Open Graph images using Next.js Edge Runtime
* Extract and use dominant colors from featured images
* Create professional, branded social previews
### Setting up the edge route
Let's create a new API route using Next.js Edge Runtime. This route will:
* Accept a parameter to dynamically fetch data
* Return an image response using Next.js `ImageResponse`
Make sure before you proceed any further, you have read the [limitations](https://vercel.com/docs/functions/og-image-generation#limitations) of Open Graph image generation on Vercel.
1. **Create** a new route in your Next.js application
```tsx:src/app/api/og/route.tsx
import { ImageResponse } from "next/og";
export const runtime = "edge";
const dimensions = {
width: 1200,
height: 630,
};
export async function GET(request: Request) {
const { searchParams } = new URL(request.url);
const title = searchParams.get("title");
return new ImageResponse(
(
<div tw="flex w-full h-full bg-blue-500 text-white p-10">
<h1 tw="text-6xl font-bold">{title || "Missing title parameter"}</h1>
</div>
),
dimensions
);
}
```
Visit [http://localhost:3000/api/og?title=hello](http://localhost:3000/api/og?title=hello) and you should see an image rendered of a blue rectangle with the word "hello" in the top right.
This creates a route that generates an image which will render whatever was passed into the title parameter.
We're using Tailwind CSS utility classes in a `tw` prop for styling. If you use `className` you will get an error. This is all part of how the `ImageResponse` function works.
This works, but isn't much to look at. And at present any user could enter _any_ value for the `title` parameter and have it render a custom image. Not safe! If we're going to render content, it's better to do so from a single source of truth. Your Content Lake.
### Creating the Sanity query
We'll need to fetch specific data for our OG images:
* Page title
* Featured image URL
* Color palette information
[There's lots of neat metadata you can pull from Sanity images](https://www.sanity.io/docs/image-metadata), such as the dominant colors within an image. We'll use these as part of the design.
1. **Update** queries with a GROQ query for the data needed to generate an image
```typescript:src/sanity/lib/queries.ts
// ...all other queries
export const OG_IMAGE_QUERY = defineQuery(`
*[_id == $id][0]{
title,
"image": mainImage.asset->{
url,
metadata {
palette
}
}
}
`);
```
1. **Update** the route that generates the OG image to fetch data based on the search parameter `id`
```tsx:src/app/api/og/route.tsx
import { client } from "@/sanity/lib/client";
import { urlFor } from "@/sanity/lib/image";
import { OG_IMAGE_QUERY } from "@/sanity/lib/queries";
import { notFound } from "next/navigation";
import { ImageResponse } from "next/og";
export const runtime = "edge";
async function loadGoogleFont(font: string, text: string) {
const url = `https://fonts.googleapis.com/css2?family=${font}&text=${encodeURIComponent(text)}`;
const css = await (await fetch(url)).text();
const resource = css.match(
/src: url\((.+)\) format\('(opentype|truetype)'\)/
);
if (resource) {
const response = await fetch(resource[1]);
if (response.status == 200) {
return await response.arrayBuffer();
}
}
throw new Error("failed to load font data");
}
export async function GET(request: Request) {
const { searchParams } = new URL(request.url);
const id = searchParams.get("id");
if (!id) {
notFound();
}
const data = await client.fetch(OG_IMAGE_QUERY, { id });
if (!data) {
notFound();
}
const vibrantBackground =
data?.image?.asset?.metadata?.palette?.vibrant?.background ?? "#3B82F6";
const darkVibrantBackground =
data?.image?.asset?.metadata?.palette?.darkVibrant?.background ?? "#3B82F6";
const text = data.title || "";
return new ImageResponse(
(
<div
tw="flex w-full h-full relative"
style={{
background: `linear-gradient(135deg, ${vibrantBackground} 0%, ${darkVibrantBackground} 100%)`,
}}
>
{/* Content container */}
<div tw="flex flex-row w-full h-full relative">
{/* Text content */}
<div tw="flex-1 flex items-center px-10">
<h1 tw="text-7xl tracking-tight leading-none text-white leading-tight">
{text}
</h1>
</div>
{/* Image container */}
{data.image && (
<div tw="flex w-[500px] h-[630px] overflow-hidden">
{/* eslint-disable-next-line @next/next/no-img-element */}
<img
src={urlFor(data.image).width(500).height(630).url()}
alt=""
tw="w-full h-full object-cover"
/>
</div>
)}
</div>
</div>
),
{
width: 1200,
height: 630,
fonts: [
{
name: "Inter",
data: await loadGoogleFont("Inter", text),
weight: 400,
style: "normal",
},
],
}
);
}
```
This query fetches the page title, image, and its color palette information—all based on the value of an ID passed to the route. It uses this data to create a dynamic background color based on the image.
The route now also uses the font Inter, [fetched from Google Fonts](https://fonts.google.com/specimen/Inter).
You can test this route by visiting `/api/og?id=your-document-id` in your browser, replacing `your-document-id` with an actual Sanity document ID.
The image template includes:
* A dynamic background color based on the featured image
* The page title
* The featured image, respecting its crop and hotspot settings
What we have now is a basic—but working—prototype for the future. You could extend this design or even explore creating different layouts depending on the value of the document's `_type`.
### Implementing metadata
Now that you have your Open Graph image generation set up, it will need to be added to each route's metadata so that it renders when that URL is shared.
1. **Update** the `generateMetadata` function in your `page` and `post` routes to use the dynamically generated Open Graph image, if an image is not specified in the document
```typescript:src/app/(frontend)/[slug]/page.tsx
// ...all your imports
export async function generateMetadata({
params,
}: RouteProps): Promise<Metadata> {
const { data: page } = await getPage(params);
if (!page) {
return {};
}
const metadata: Metadata = {
metadataBase: new URL('https://acme.com'),
title: page.seo.title,
description: page.seo.description,
};
metadata.openGraph = {
images: {
url: page.seo.image
? urlFor(page.seo.image).width(1200).height(630).url()
: `/api/og?id=${page._id}`,
width: 1200,
height: 630,
},
};
if (page.seo.noIndex) {
metadata.robots = "noindex";
}
return metadata;
}
```
Be sure to copy this logic over to your individual post route as well.
This setup generates metadata dynamically for each page, uses the page's Sanity ID to generate the correct Open Graph image, and maintains consistent dimensions across platforms.
## Testing your implementation
There are a few ways to test your implementation.
If you have a service like [ngrok](https://ngrok.com/) setup locally you can pipe your local development environment to an external URL, and then run that URL through an Open Graph previewing service.
1. [opengraph.ing](https://opengraph.ing/) is a simple service for validating your social previews in multiple applications and services
Once you're ready to deploy, you can check the implementation from your preview environment. Once deployed you can use the Vercel toolbar to preview your site and see the Open Graph image.
Other alternatives include using platform-specific debugging tools:
* [Facebook Sharing Debugger](https://developers.facebook.com/tools/debug/)
* [Twitter Card Validator](https://cards-dev.twitter.com/validator)
* [LinkedIn Post Inspector](https://www.linkedin.com/post-inspector/)
These tools allow you to test your Open Graph image on the platform you are sharing to, and see the preview image. There is an added benefit of these tools, that some of them force the cache to be invalidated, which means you can see the latest version of your Open Graph image across that social platform.
The next lesson will cover remixing content for social platforms using the Sanity AI Assistant.## [Generate social posts from your content](/learn/course/seo-optimization/ai-generate-social-posts-from-your-content)
Speed up ideation of social media posts. And as a result, boost your SEO from sharing your content to a wider audience across different social platforms.
1. This lesson uses features only available in paid plans. If you started a new project for this course, you can test these features during the free trial period. You can also start a new free project at any time.
Summarizing existing content and making it more useful in different forms is one of the best features of AI tooling. Sanity AI Assist makes it possible for authors to automatically generate new content, using existing fields along with prompts that they can save and share.
In this lesson you'll use Sanity AI Assist to generate text to post on social networks while sharing a link to the content.
1. Read more about [Sanity AI Assist](https://www.sanity.io/docs/install-and-configure-sanity-ai-assist) in the documentation
## Create new schema types
First you'll need new fields to write content to. Just like you made a new custom object schema type for SEO fields, create another for social networks.
In the example below we've chosen only LinkedIn and X (formerly known as Twitter) for now, feel free to include any of the countless others.
1. **Create** a new `social` object schema type
```typescript:src/sanity/schemaTypes/socialType.ts
import { defineField, defineType } from "sanity";
export const socialType = defineType({
name: "social",
title: "Social",
type: "object",
fields: [
defineField({
name: "linkedIn",
title: "LinkedIn",
type: "text",
rows: 3,
}),
defineField({
name: "x",
description: "Formerly known as Twitter",
type: "text",
rows: 2,
}),
],
});
```
Don't forget to register this type to your Sanity Studio schema types
```typescript:src/sanity/schemaTypes/index.ts
// ...all other imports
import { socialType } from "./socialType";
export const schema: { types: SchemaTypeDefinition[] } = {
types: [
// ...all other types
socialType,
],
};
```
1. **Update** your `page` and `post` schema types to include the `social` field.
```typescript:src/sanity/schemaTypes/pageType.ts
export const pageType = defineType({
// ...all other settings
fields: [
// ...all other fields
defineField({
name: "social",
type: "social",
}),
],
});
```
## Install Sanity AI Assist
To automatically generate content for these fields, you'll now install and configure the Sanity AI assistant.
1. **Run** the following in your terminal
```sh:Terminal
npm install @sanity/assist
```
1. **Update** your Sanity Studio config file to include the `assist` plugin
```typescript:sanity.config.ts
// ...all other imports
import { assist } from "@sanity/assist";
export default defineConfig({
// ...all other config
plugins: [
// ...all other plugins
assist(),
],
});
```
With this installed you can create a prompt to help Sanity AI Assist generate content from your existing fields.
Sanity AI Assist works at both field level and document level, however, for this example, you will be using the document level. Look at the top right of the Studio with any document open and you should see a sparkly new icon.
The first time you click this button you may be asked to Enable AI Assist
1. Click **Enable AI Assist**
You can see there are currently no instructions.
1. Click **Add item** to create your first instruction.
What we want AI Assist to do is to summarize the main body of the document
You're going to create a new prompt, use the example below for guidance.
Where you see the boxes like `[Title]`, replace these with references to the fields in your document.
Make sure the **Allowed fields** is set to only write to the **Social** field object.
1. **Create** your new Instruction and run it
```text
Take the content from [title] and [body] to generate text that will encourage people to click the link and find out more when this content is shared on social networks.
```
1. Writing prompts for AI is a bit of an art form! Take a look at the [instructions cheat sheet](https://www.sanity.io/docs/ai-assist-cheat-sheet) in the documentation for inspiration.
### Posting to social networks
In this lesson you're only using Sanity to **generate** text for posting to social networks. So for now your authors would need to copy and paste them from Sanity. There are a variety of third-party tools available to automate this process.
Please use the feedback form below to let us know if you have preferred ways to automate posting to social networks.
### Adapt to your tone of voice
By default, AI-generated copy can be generic. Consider adding some **AI context** documents (now visible in your Studio structure) to inform your preferred writing style and tone of voice. You can then add this context to your instruction, so that copy generated in future will be consistently informed.
In the following lesson, you'll create a dynamic sitemap that automatically updates when content changes. Helping search engines discover and index your content more effectively.## [Build a dynamic sitemap](/learn/course/seo-optimization/building-a-dynamic-sitemap)
A sitemap helps search engines understand and index your website more effectively. Generate a dynamic sitemap to guide search crawlers through your content, showing them what pages exist and how often they change.
A well-structured sitemap gives search engines clear guidance about your content hierarchy and update frequency.
## Why this approach?
Search engines like Google use sitemaps as a primary method to discover and understand your content. While they can crawl your site naturally through links, a sitemap:
1. Ensures all your content is discoverable, even pages that might be deep in your site structure
2. Helps search engines understand when content was last updated
3. Allows you to indicate content priority
4. Speeds up the indexing process for new content
This is especially important for dynamic content managed through Sanity, where pages might be added or updated frequently.
## Learning objectives
By the end of this lesson, you will:
* Create a dynamic sitemap from Sanity content
* Implement graceful validation error handling
### Understanding sitemaps
Before diving into the code, let's understand what makes a good sitemap from a technical perspective:
* **XML Format**: Search engines expect a specific XML format
* **Last Modified Dates**: Helps search engines know when content was updated
* **Change Frequency**: Indicates how often content changes
* **Priority**: Suggests the importance of pages
### Building the sitemap
Let's start with a GROQ query to fetch all `page` and `post` type documents.
1. **Update** `queries.ts` to include `SITEMAP_QUERY`
```typescript:src/sanity/lib/queries.ts
// ...all other queries
export const SITEMAP_QUERY = defineQuery(`
*[_type in ["page", "post"] && defined(slug.current)] {
"href": select(
_type == "page" => "/" + slug.current,
_type == "post" => "/posts/" + slug.current,
slug.current
),
_updatedAt
}
`)
```
This query:
* Gets all documents of type `page` and `post`
* Dynamically creates a complete path depending on the value of `_type`
* Returns that path as `href`, and the last updated date of the document
You've created a new query, so you'll need to create new types.
```sh:Terminal
pnpm run typegen
```
The Next.js app router has a special, reserved route for generating an XML sitemap response from an array of objects in JavaScript.
1. See the Next.js documentation for more details on the [sitemap route](https://nextjs.org/docs/app/api-reference/file-conventions/metadata/sitemap)
The route below fetches content from Sanity using the query above, and generates the shape of content response that Next.js requires.
1. **Create** a new route to generate the sitemap
```typescript:src/app/sitemap.ts
import { MetadataRoute } from "next";
import { client } from "@/sanity/lib/client";
import { SITEMAP_QUERY } from "@/sanity/lib/queries";
export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
try {
const paths = await client.fetch(SITEMAP_QUERY);
if (!paths) return [];
const baseUrl = process.env.VERCEL
? `https://${process.env.VERCEL_URL}`
: "http://localhost:3000";
return paths.map((path) => ({
url: new URL(path.href!, baseUrl).toString(),
lastModified: new Date(path._updatedAt),
changeFrequency: "weekly",
priority: 1,
}));
} catch (error) {
console.error("Failed to generate sitemap:", error);
return [];
}
}
```
### Testing your sitemap
After deploying your changes, you can test your sitemap by visiting [http://localhost:3000/sitemap.xml](http://localhost:3000/sitemap.xml) on your site.
You should see something like this:
```xml
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
<url>
<loc>http://localhost:3000/welcome-to-layer-caker</loc>
<lastmod>2025-01-10T14:13:34.000Z</lastmod>
<changefreq>weekly</changefreq>
<priority>1</priority>
</url>
<!-- // all other URLs... -->
</urlset>
```
Even if your sitemap looks correct, checking with a sitemap validator tool is recommended. Especially as your website grows. It's very easy to miss validation errors. A solid option is [XML Sitemaps](https://www.xml-sitemaps.com/validate-xml-sitemap.html) for a free and quick check.
### Best practices
To ensure your sitemap is doing what it's meant to, keep these points in mind:
* **Regular Updates**: Your sitemap should update when content changes
* **Size Limits**: Keep under 50,000 URLs **per sitemap file**
* **Valid URLs**: Ensure all URLs are properly formatted
At this stage, your sitemap will now automatically update whenever you publish new content in Sanity, helping search engines discover and index your content.
As you continue to enhance your sitemap implementation and expand out through other document types, you may want to consider adding different priorities for different page types to help search engines understand the relative importance of your content.
Next, you'll explore structured data and JSON-LD, a clever way of reusing your documents for set-and-forget SEO benefits.## [Generating JSON-LD dynamically](/learn/course/seo-optimization/generating-json-ld-dynamically)
JSON-LD is a powerful way to provide structured data to search engines—fortunately structured data is what Sanity does best.
JSON-LD data follows structured conventions for many different types of content. All you'll need to do is take content already authored in your documents, and render it into the DOM in the expected format. We already have FAQs as a document type, so it makes sense to start there.
When it comes to FAQs, proper JSON-LD implementation can help your content appear in rich snippets and potentially even surface you near the top of search results just by providing useful information.
## Learning objectives
By the end of this lesson, you will:
* Generate JSON-LD for FAQs programmatically
* Implement type-safe JSON-LD using Google's `schema-dts` package
* Improve your FAQ block from the page builder course
### Understanding JSON-LD generation
JSON-LD generation can be challenging to get right as it follows a strict structure. Fortunately, [Google provides a TypeScript package](https://github.com/google/schema-dts) called `schema-dts` that gives you type safety for your structured content.
Let's start by creating a function that transforms your FAQ data into a JSON-LD friendly structure. Back in [Create page builder schema types](https://www.sanity.io/learn/course/page-building/create-page-builder-schema-types) you created a document type schema for FAQs.
1. **Run** the following to install the `schema-dts` package
```sh:Terminal
pnpm add schema-dts
```
Currently in the GROQ query for pages the FAQ block is returning the full document for every reference.
Let's update this to only extract specific fields from the document, as well as the Portable Text in the `body` field as a string using the GROQ function `pt::text()`
1. **Update** your GROQ query for pages, to return the answer in plain text
```groq:src/sanity/lib/queries.ts
// replace this
faqs[]->
// with this
faqs[]->{
_id,
title,
body,
"text": pt::text(body)
}
```
You've updated your queries, so update your types
```sh:Terminal
pnpm run typegen
```
### Implementing FAQ JSON-LD in components
The JSON-LD markup can be rendered anywhere in the page—it doesn't need to be stored inside the `<head>`. So you can add it directly into components where you already have access to the correct data.
In this instance, you're rendering the FAQ content into an accordion in this block, so you can also have it process that same content into the JSON-LD format and add it to the component output.
1. **Update** your `FAQs` block to render JSON-LD content in a script tag
```tsx:src/components/blocks/faqs.tsx
// ...all your imports and types
import { FAQPage, WithContext } from "schema-dts";
const generateFaqData = (faqs: FAQsProps["faqs"]): WithContext<FAQPage> => ({
"@context": "https://schema.org",
"@type": "FAQPage",
mainEntity: faqs?.map((faq) => ({
"@type": "Question",
name: faq.title!,
acceptedAnswer: {
"@type": "Answer",
text: faq.text!,
},
})),
});
export function FAQs({ _key, title, faqs }: FAQsProps) {
const faqData = generateFaqData(faqs);
return (
<section className="container mx-auto flex flex-col gap-8 py-16">
<script
type="application/ld+json"
dangerouslySetInnerHTML={{ __html: JSON.stringify(faqData) }}
/>
{/* ...the rest of the component */}
</section>
);
}
```
Notice the most important part of this block, the `<script>` tag. This is where you're adding the JSON-LD to the page. This should get you thinking about how you can reuse this pattern across your site.
The FAQ schema covered here is just the tip of the JSON-LD iceberg. The beauty of structured data is that once implemented, it works silently in the background to enhance your search presence.
Some other examples you may want to implement:
* [Product information](https://schema.org/Product)
* [Event information](https://schema.org/Event)
* [Blog post information](https://schema.org/BlogPosting)
## Conclusion
The more you lean into structured data, the more benefits you'll experience.
If there's one thing to take away from this whole course, it's that SEO doesn't need to be a complex process. It's about taking your existing data and repurposing it to make it more digestible for your audience and, by extension, for search crawlers.
The future of the web won't be about configuring hundreds of different fields to get the perfect SEO score. Instead, it will focus on finding ways to accelerate content creation and automating the tasks you don't want to do.
It's time to revise everything you've learned in the final lesson!## [Sanity SEO quiz](/learn/course/seo-optimization/sanity-seo-quiz)
Let's test what you've learned in the prior lessons!
**Question:** What is the benefit of using dynamic metadata in Next.js?
1. It reduces the website's loading time
2. It improves the server's performance
3. It automatically creates backlinks
4. It allows for page-specific SEO optimization based on content
**Question:** When would you use a Sanity AI Assist context?
1. When you need to provide more information about your business within the prompt
2. When you need to add your specific writing style
3. When you need to reference important information that is regularly reused
4. All of the above
**Question:** What is the purpose of the coalesce query in GROQ?
1. To override the value if another value has been provided
2. To combine the two values together
3. To type check the value inside of a Sanity field
4. To assess which is the bigger of two fields
**Question:** Why might we specify an image, title and description, as well as an SEO title, SEO description, SEO image?
1. To create more work for the content editors
2. Because you cannot reuse fields in multiple locations
3. To be more granular when entering SEO information
4. To provide different content for different social media platforms
**Question:** What is the recommended way to structure SEO fields in your Sanity schema?
1. Create unique schema types for each document type's SEO fields
2. Add SEO fields directly to the document type without any structure
3. Create a reusable SEO object type that can be referenced across different document types
4. Store all SEO fields in a single global configuration document
**Question:** Why is there such a significant amount of validation within Next.js redirects?
1. To make the development process more complex
2. To slow down the build process
3. Because Next.js is overly cautious
4. Because providing incorrect redirect data can break your deployment pipeline
**Question:** What is the key advantage of implementing a dynamic sitemap in a Sanity + Next.js project?
1. It makes the website load faster
2. It automatically updates when content changes
3. It improves the website's visual design
4. It automatically generates meta descriptions
**Question:** When implementing schema markup with Next.js and Sanity, what is the recommended data format?
1. XML
2. JSON-LD
3. JavaScript
4. HTML microdata
**Question:** What is considered best practice when implementing SEO features in a Sanity + Next.js project?
1. Hardcoding all SEO values in the Next.js files
2. Creating reusable schemas and components that can be managed by content creators
3. Managing everything through external SEO tools
4. Letting search engines handle everything automatically
**Question:** What is the main purpose of implementing on-page schema in your website?
1. To make your website look better on social media
2. To increase your chance of search engines displaying rich results
3. To improve website loading speed
4. To create better URLs# [Build content apps with Sanity App SDK](/learn/course/build-content-apps-with-sanity-app-sdk)
Building fast, real-time content authoring applications has never been simpler. Create a feedback processing application with user assignment, AI analysis and more.
## [Building content apps](/learn/course/build-content-apps-with-sanity-app-sdk/building-content-apps)
A true content operating system provides more than one way to author content. Build powerful, fit-for-purpose applications faster than ever before.
The Sanity App SDK is a collection of utilities for building content applications backed by the Content Lake. It is headless by design, so you can use whatever front-end framework you like. In the React package, almost all of its functionality is provided by React Hooks.
It is the fastest way to rapidly build task-specific applications for authors and editor teams to perform content operations.
## Why build content apps?
Sanity Studio is a powerful and nearly infinitely customizable admin panel for creating and editing content. However, given its flexibility, it can become so complex that it becomes difficult for authors with a specific task in mind, especially one that needs to be done repetitively, to perform it efficiently.
So, while Sanity Studio may be the default experience for all of your content operations, the Sanity App SDK provides a way to build novel applications with a specific job in mind.
> When all you have is a hammer, everything looks like a nail
Sanity Studio is a hammer, but not all content operations are nails. Sanity App SDK is a scalpel. And this is a tortured metaphor.
For example, imagine a content author at a media publication who needs to process feedback. They could click through a Studio to find what they need, or you could build an application to do what they need faster and better.
And that's what you'll build in this course.
## Prerequisites
This course expects that you have a reasonable understanding of the Command Line, PNPM, React, TypeScript, and Sanity. You will not need to be an expert in any of these, but this course is written with the expectation that this is not your first time encountering these words.
If you would prefer to get a top-to-bottom look at how to work with _Sanity, the platform_, you may be better served by the Day One with Sanity course.
1. Take [Day one content operations](https://www.sanity.io/learn/course/day-one-with-sanity-studio)
## What you'll build
You'll be building a single-purpose application for processing feedback. You might imagine this feedback is received from a comments form or email account. Your content authors need a more efficient way to see which feedback:
* is pending approval to proceed in the workflow
* should be marked as spam and dismissed
* should be deleted
* and to mark the sentiment of any feedback as positive, neutral or negative.
Let's begin in the next lesson by first creating a new Sanity project and Studio.## [Create a new Project and Studio](/learn/course/build-content-apps-with-sanity-app-sdk/create-a-new-project-and-studio)
Get setup with a fresh hosted backend for your content, and the traditional administration panel for Sanity.
Content written to Sanity is stored within the Content Lake, not in Sanity Studio. The schema types you configure are made available in Sanity Studio, and it writes content of that shape to the Content Lake.
You can think of the Sanity Studio as a _"window into the Content Lake."_
## So I don't need a Studio to build an SDK App?
Nope!
You can write data of any shape (that conforms to JSON) to the Content Lake.
But having a Studio makes it easier to reason about our _complete_ universe of content if we have one configured. It's also where you'd configure TypeScript types. So you'll start this course by creating a new Sanity project and Sanity Studio—you just won't need to edit any content there.
## Create a new project
You can create a new free project and initialize a new Sanity Studio from one command using the Sanity CLI. If you do not yet have a Sanity account, you can create one during this process.
You may like to create a parent folder to contain the projects you work on in this course, as your Sanity Studio and App SDK app will live side-by-side.
Once you have a Studio and App setup, your folder structure should look like this:
```text
feedback-course
├── studio
└── app-feedback
```
1. **Run** the following command in your terminal to create a new Sanity project and Sanity Studio.
```sh:Terminal
pnpm dlx create-sanity@latest --template blog --create-project "Feedback Processor" --dataset production --typescript --output-path studio
```
1. **Run** the following from inside of the `/studio` directory
```sh:Terminal
pnpm run dev
```
Open [http://localhost:3333](http://localhost:3333) in your browser and log in. You should now see the Sanity Studio dashboard interface with Post, Category and Author schema types already configured.
## Add "Feedback" schema types
The schema types that appear in the Structure tool of Sanity Studio are defined in the project's configuration files. You'll need to create a new file to add "Feedback" type documents as an option in the Studio and a TypeScript type for your App.
1. **Create** a new file for Feedback type documents
```typescript:studio/schemaTypes/feedbackType.ts
import {defineField, defineType} from 'sanity'
export const feedbackType = defineType({
name: 'feedback',
title: 'Feedback',
type: 'document',
fields: [
defineField({
name: 'content',
type: 'text',
}),
defineField({
name: 'author',
type: 'string',
}),
defineField({
name: 'email',
type: 'string',
}),
defineField({
name: 'sentiment',
type: 'string',
options: {list: ['positive', 'neutral', 'negative'], layout: 'radio'},
}),
defineField({
name: 'status',
type: 'string',
options: {list: ['pending', 'approved', 'spam'], layout: 'radio'},
}),
defineField({
name: 'assignee',
type: 'string',
}),
defineField({
name: 'notes',
type: 'text',
}),
],
preview: {
select: {
title: 'content',
subtitle: 'author',
},
},
})
```
**Update** the schema types index file to include the feedback schema type.
```typescript:studio/schemaTypes/index.ts
import blockContent from './blockContent'
import category from './category'
import post from './post'
import author from './author'
import {feedbackType} from './feedbackType'
export const schemaTypes = [post, author, category, blockContent, feedbackType]
```
You should now see an option in your Structure tool to list and create Feedback type documents.
## Import seed data
It is easier to build front ends when you have content, and so some has been prepared for you already.
1. **Download** `feedback-seed.ndjson`
2. **Run** the following from the terminal, inside the `studio` folder to import 20 example Feedback type documents.
```sh:Terminal
pnpm dlx sanity dataset import feedback-seed.ndjson production
```
Open your Studio to confirm these documents are now visible, there's a mix of spam comments and none of them have been marked to indicate their "sentiment," that's the job of our new app!
Let's start building it next.## [Quickstart a new App SDK app ](/learn/course/build-content-apps-with-sanity-app-sdk/quickstart-a-new-app-sdk-app)
Start a new App SDK app in seconds from the command line using the Sanity UI template.
You've now got content to work with and a Sanity Studio, it's time to start building your app.
1. **Run** the following from the terminal in the root directory (above the `studio` directory)
```sh:Terminal
# in the parent directory
pnpm dlx sanity@latest init --template app-sanity-ui --typescript --output-path app-feedback
```
You may be prompted to select an Organization, select your personal organization, as that's where the project you created in the previous lesson was created.
You should now have these two adjacent folders.
```text
feedback-course
├── app-feedback
└── studio
```
## Why Sanity UI?
The command you just ran uses the Sanity UI app template. This includes the required context and packages for the same front end library used in other Sanity applications like Sanity Studio, Media Library and Dashboard.
You're free to use the front-end library of your choice in Sanity App SDK applications. For this course, however, you'll use Sanity UI so that the application you build shares visual harmony with the rest of the dashboard experience.
1. [Sanity UI](https://www.sanity.io/ui) has its own documentation site with implementation details
2. See the App SDK docs for examples on how to install other styling libraries
## Running two apps
By default, SDK Apps use the same port number (`3333`) as the Studio. To run the Studio and your applications simultaneously, you can update `sanity.cli.ts` of either one. Let's change the default port of the Studio.
1. **Update** the Sanity CLI config of the Sanity Studio
```typescript:studio/sanity.cli.ts
import {defineCliConfig} from 'sanity/cli'
export default defineCliConfig({
server: {
port: 3334,
},
// ...all other settings
})
```
Restart your Studio's development server, you'll get a new development URL.
Open the Studio in your browser and be asked to create a new CORS origin.
You can follow the instructions in the browser, or create a new origin using Sanity CLI with the following command run from inside your `studio` folder.
```sh:Terminal
# in /studio
pnpm dlx sanity@latest cors add http://localhost:3334 --allow
```
1. **Run** the following inside the `app-feedback` folder to start the app's development server.
```sh
# in /app-feedback
pnpm run dev
```
1. If you get an error about a mismatched Organization ID, you may have selected a different Organization to the one in which the project was created. Update `app-feedback/sanity.cli.ts` to use the correct Organization ID.
You'll see a URL in the terminal to open the App running from within the Sanity Dashboard.
Dashboard is the default "home screen" where authors can move between deployed Studios and other applications—such as the one you're building right now. The Dashboard also provides authentication to your app.
In a large enough organization, you may have many teams of authors working between or across multiple projects all served by deployed Sanity Studio instances or Apps of all shapes and sizes.
Content operations are not the job of a one-size-fits-nobody CMS!
## Targeting your project(s)
While this app will only target one project, an App SDK app can target multiple (worth knowing: Sanity Studio can't do this).
The entry point for your application is `App.tsx`, you can see this defined in `sanity.cli.ts`.
1. **Update** the main `App.tsx` file with the details found in your `studio/sanity.config.ts` file.
```typescript:app-feedback/src/App.tsx
const sanityConfigs: SanityConfig[] = [
{
projectId: 'REPLACE-WITH-YOUR-PROJECT-ID',
dataset: 'production',
},
]
```
There is an `ExampleComponent` already loaded as the main child of the application. Let's replace this with our first use of the App SDK's React hooks to query for a list of documents.## [useDocuments](/learn/course/build-content-apps-with-sanity-app-sdk/use-documents)
Performant querying for a live-updating list of documents has never been simpler.
Maybe the most basic thing we can do when creating an application is query and render a list of documents. In this lesson, you'll do it using the `useDocuments` hook.
Before we do, let's interrogate this decision.
## Why not use client.fetch?
[Sanity Client](https://github.com/sanity-io/client) is the primary way JavaScript applications are built to interact with Sanity's APIs. The App SDK is a wrapper of Sanity Client for building apps and solves much of the UI complexity that comes with working with a lower-level client.
For example, when you query documents with `client.fetch`, the list of documents will not update in real-time as documents change. You might also unknowingly fetch 10,000 documents. Edits made to these documents will not automatically create per-render optimistic updates in the UI.
All complexity and performance concerns are bundled up in the App SDK's React hooks, making it simpler and faster for us to build better content applications.
## Why not useQuery?
The App SDK provides the useQuery hook, which takes a GROQ query. We could use this hook for all our data fetching. However, many other hooks in the App SDK for React require "document handles" to be passed in as parameters.
These can be created ad hoc from values in a document. Still, it's simpler to retrieve document handles in a parent component and pass them down to child components, which perform fetches or actions using those handles.
### When you might want useQuery
There are some patterns where it makes more sense to use `useQuery` instead of `useDocuments`, such as when a parent component needs to know specific values of each document. For example, a component may need to know which day an event is on to render it into a calendar or the geolocation of an event to plot it on a map.
In these instances, you may be better off fetching with `useQuery` documents and their values in the parent component. Just be aware that this can lead to overfetching.
## What are document handles?
A document handle contains at least two and up to four useful pieces of information about a document to identify its type and origin. By keeping the data returned by fetches of documents smaller, we maintain focus on improved performance in our applications.
```json
{
"dataset": "production",
"documentId": "116d2c7a-d1de-4d00-9a88-8ac65ceaad10",
"documentType": "feedback",
"projectId": "xe385msc"
}
```
## tl;dr it's about more, smaller fetches
In Server-Side Rendered (SSR) web application frontends, you have likely formed a habit of fetching **everything** your web page needed in one huge GROQ query using `client.fetch`.
This isn't necessary in a Single Page Application (SPA).
The happy path for App SDK apps is to filter for specific documents using `useDocuments` and pass down the returned document handles to components which individually fetch, edit and take actions on documents.
Any concerns about caching, real-time and optimistic updates are all taken care of by the App SDK.
## Let's finally fetch something
1. **Create** a new component called `Feedback`, which will be the parent component of all our UI.
```tsx:app-feedback/src/Feedback.tsx
import { Suspense, useState } from "react"
import { DocumentHandle } from "@sanity/sdk-react"
import { Card, Flex, Grid, Spinner } from "@sanity/ui"
import { styled } from "styled-components"
import { FeedbackList } from "./FeedbackList"
const ScreenHeightCard = styled(Card)`
height: 100vh;
overflow: scroll;
`
export function Feedback() {
const [selectedFeedback, setSelectedFeedback] =
useState<DocumentHandle | null>(null)
return (
<Grid columns={5}>
<ScreenHeightCard columnStart={1} columnEnd={3}>
<Suspense fallback={<Loading />}>
<FeedbackList
setSelectedFeedback={setSelectedFeedback}
selectedFeedback={selectedFeedback}
/>
</Suspense>
</ScreenHeightCard>
<ScreenHeightCard borderLeft columnStart={3} columnEnd={6}>
{/* TODO: Add <FeedbackEdit /> form */}
</ScreenHeightCard>
</Grid>
)
}
function Loading() {
return (
<Flex justify="center" align="center" width="fill" height="fill">
<Spinner />
</Flex>
)
}
```
1. Don't forget your `Suspense` boundaries. The App SDK React Hooks use Suspense for data fetching. This means any component which uses one of these hooks could cause a re-render further up the component tree. Since this `Feedback` component will be rendering both the `FeedbackList` and `FeedbackEdit` form components, without being wrapped in `Suspense` an update in one component would force both to re-render.
1. **Read more** about [`Suspense` in the React documentation](https://react.dev/reference/react/Suspense)
1. **Create** another component to query for the feedback documents.
```tsx:app-feedback/src/FeedbackList.tsx
import { type DocumentHandle, useDocuments } from "@sanity/sdk-react"
import { Stack, Button } from "@sanity/ui"
type FeedbackListProps = {
selectedFeedback: DocumentHandle | null
setSelectedFeedback: (feedback: DocumentHandle | null) => void
}
export function FeedbackList({
selectedFeedback,
setSelectedFeedback,
}: FeedbackListProps) {
const { data, hasMore, loadMore } = useDocuments({
documentType: "feedback",
})
return (
<Stack space={2} padding={5}>
{data?.map((feedback) => (
<pre key={feedback.documentId}>{JSON.stringify(feedback, null, 2)}</pre>
))}
{hasMore && <Button onClick={loadMore} text="Load more" />}
</Stack>
)
}
```
Lastly, you'll need to load the Feedback component into the main App.
1. **Update** `App.tsx` to replace `ExampleComponent` with `Feedback`
```tsx:feedback-app/src/App.tsx
import {Feedback} from "./Feedback"
export default function App() {
// ...sanityConfigs, Loading
return (
<SanityUI>
<SanityApp config={sanityConfigs} fallback={<Loading />}>
<Feedback />
</SanityApp>
</SanityUI>
)
}
```
In your application you should now see a list of document handles rendered into the UI.
So you now have an application that can query documents, but not any useful information about them. Let's fix that in the next lesson.## [useDocumentProjection](/learn/course/build-content-apps-with-sanity-app-sdk/use-document-projection)
Pick just the content you need from individual documents, and only when a component is rendered in view.
We have a list of document handles, but we need more information about each document. Let's create a component that uses these handles to fetch more values from each document.
1. **Create** a new component to visualize the value of the `status` field in a document throughout our application.
```tsx:app-feedback/src/StatusBadge.tsx
import { Badge } from "@sanity/ui"
type StatusBadgeProps = {
status?: string
fontSize?: number
}
export function StatusBadge({
status = "PENDING",
fontSize = 2,
}: StatusBadgeProps) {
return (
<Badge
tone={
status === "approved"
? "positive"
: status === "spam"
? "caution"
: "default"
}
padding={2}
fontSize={fontSize}
>
{status.toUpperCase()}
</Badge>
)
}
```
1. **Create** a component to retrieve and display values from a document by its handle
```tsx:app-feedback/src/FeedbackPreview.tsx
import { useRef } from "react"
import { DocumentHandle, useDocumentProjection } from "@sanity/sdk-react"
import { Box, Stack, Text } from "@sanity/ui"
import { StatusBadge } from "./StatusBadge"
type FeedbackPreviewData = {
_createdAt: string
content: string | null
author: string | null
email: string | null
status: string
}
export function FeedbackPreview(props: DocumentHandle) {
const previewRef = useRef<HTMLDivElement>(null)
const { data, isPending } = useDocumentProjection<FeedbackPreviewData>({
...props,
ref: previewRef,
projection: `{
_createdAt,
content,
author,
email,
"status": coalesce(status, "PENDING")
}`,
})
const showPlaceholder = isPending && !data
return (
<Stack ref={previewRef} space={3}>
<Text size={2} weight="semibold" textOverflow="ellipsis">
{showPlaceholder ? "..." : data.author}
</Text>
<Text muted size={1} textOverflow="ellipsis">
{showPlaceholder
? "..."
: data.email + " " + data._createdAt.split("T")[0]}
</Text>
<Text size={2} textOverflow="ellipsis">
{showPlaceholder ? "..." : data.content}
</Text>
<Box>
<StatusBadge status={data.status} fontSize={1} />
</Box>
</Stack>
)
}
```
There's a few key things to look at in this component.
* `useDocumentProjection` receives the passed-in document handle as props, and then declares a GROQ "projection" which retrieves values from the document.
* The `ref` being passed into the hook is attached to the outermost Stack component. This will ensure that the content returned by this projection is only queried when the component is rendered and visible on the page. Another small but important performance win!
1. Throughout this course we're manually creating Types. This is because TypeGen support for App SDK currently uses experimental packages and may change in future. See the documentation for the most current implementation method.
1. See [App SDK and TypeGen](https://www.sanity.io/learn/app-sdk/sdk-typegen) in the documentation
## Update the feedback list
Now you have a component to fetch individual documents, let's update the feedback list component to use it.
1. **Update** the `FeedbackList` component to render the `FeedbackPreview` component
```tsx:app-feedback/src/FeedbackList.tsx
import { Suspense } from "react"
import { type DocumentHandle, useDocuments } from "@sanity/sdk-react"
import { Stack, Button, Spinner } from "@sanity/ui"
import { FeedbackPreview } from "./FeedbackPreview"
type FeedbackListProps = {
selectedFeedback: DocumentHandle | null
setSelectedFeedback: (feedback: DocumentHandle | null) => void
}
export function FeedbackList({
selectedFeedback,
setSelectedFeedback,
}: FeedbackListProps) {
const { data, hasMore, loadMore } = useDocuments({
documentType: "feedback",
})
return (
<Stack space={2} padding={5}>
{data?.map((feedback) => {
const isSelected = selectedFeedback?.documentId === feedback.documentId
return (
<Button
key={feedback.documentId}
onClick={() => setSelectedFeedback(feedback)}
mode={isSelected ? "ghost" : "bleed"}
tone={isSelected ? "primary" : undefined}
>
<Suspense fallback={<Spinner />}>
<FeedbackPreview {...feedback} />
</Suspense>
</Button>
)
})}
{hasMore && <Button onClick={loadMore} text="Load more" />}
</Stack>
)
}
```
You should now have the feedback items rendered as a list of buttons. Most importantly you'll see values from each document in each button. And if any other author makes changes to these documents, you'll see those values update live!
You can click to select them, they just won't do anything yet. In the next lesson you can start to building a form to edit each feedback document.## [useDocument](/learn/course/build-content-apps-with-sanity-app-sdk/use-document)
Fetch content with real-time and optimistic updates when edits are made—locally or remotely.
This hook is similar to `useDocumentProjection` in the previous lesson. However `useDocument` will sync with both local and remote changes to the document. Because of this it can be more memory intensive, this hook should be used sparingly.
That is why in this course you've used `useDocumentProjection` for the document list— which could eventually render 100's of documents—while only using `useDocument` for the one document rendered in the editing form.
1. **Create** a new component to query for the entire document from its handle.
```tsx:app-feedback/src/FeedbackEdit.tsx
import { DocumentHandle, useDocument } from "@sanity/sdk-react"
import { Card, Flex, Stack, Text, Container } from "@sanity/ui"
import { StatusBadge } from "./StatusBadge"
type FeedbackEditProps = {
selectedFeedback: DocumentHandle
}
export function FeedbackEdit({ selectedFeedback }: FeedbackEditProps) {
const { data } = useDocument({ ...selectedFeedback })
if (!data) {
return null
}
// Ensure type safety for all fields
const author = typeof data.author === "string" ? data.author : ""
const email = typeof data.email === "string" ? data.email : ""
const content = typeof data.content === "string" ? data.content : ""
const createdAt =
typeof data._createdAt === "string" ? data._createdAt.split("T")[0] : ""
const status = typeof data.status === "string" ? data.status : "pending"
const sentiment = typeof data.sentiment === "string" ? data.sentiment : ""
const notes = typeof data.notes === "string" ? data.notes : ""
const assignee = typeof data.assignee === "string" ? data.assignee : ""
return (
<Container width={1}>
<Card padding={[0, 0, 4, 5]}>
<Card padding={[0, 0, 4, 5]} radius={3} shadow={[0, 0, 2]}>
<Stack space={5}>
<Flex align="center" justify="space-between">
<Stack space={3}>
<Text size={3} weight="semibold">
{author}
</Text>
<Text size={1} muted>
{email} {createdAt}
</Text>
</Stack>
<StatusBadge status={status} fontSize={2} />
</Flex>
<Stack space={3}>
<Card padding={4} radius={2} tone="transparent">
<Text size={3}>{content}</Text>
</Card>
</Stack>
{/* In the next lessons... */}
{/* Sentiment, Notes, Assignee, Actions */}
</Stack>
</Card>
</Card>
</Container>
)
}
```
1. **Update** the parent Feedback component to render the editing form
```tsx:app-feedback/src/Feedback.tsx
import { Suspense, useState } from "react"
import { DocumentHandle } from "@sanity/sdk-react"
import { Card, Flex, Grid, Spinner } from "@sanity/ui"
import { styled } from "styled-components"
import { FeedbackList } from "./FeedbackList"
import { FeedbackEdit } from "./FeedbackEdit"
const ScreenHeightCard = styled(Card)`
height: 100vh;
overflow: scroll;
`
export function Feedback() {
const [selectedFeedback, setSelectedFeedback] =
useState<DocumentHandle | null>(null)
return (
<Grid columns={5}>
<ScreenHeightCard columnStart={1} columnEnd={3}>
<Suspense fallback={<Loading />}>
<FeedbackList
setSelectedFeedback={setSelectedFeedback}
selectedFeedback={selectedFeedback}
/>
</Suspense>
</ScreenHeightCard>
<ScreenHeightCard borderLeft columnStart={3} columnEnd={6}>
<Suspense fallback={<Loading />}>
{selectedFeedback ? (
<FeedbackEdit selectedFeedback={selectedFeedback} />
) : null}
</Suspense>
</ScreenHeightCard>
</Grid>
)
}
function Loading() {
return (
<Flex justify="center" align="center" width="fill" height="fill">
<Spinner />
</Flex>
)
}
```
You should now be able to click each document in the list, and open the editing form on the right. The values in this form have a real-time subscription to changes in the Content Lake, as well as an in-memory optimistic cache to render any edits as they happen.
It's time to start editing documents with the App SDK.## [useEditDocument](/learn/course/build-content-apps-with-sanity-app-sdk/use-edit-document)
Edit values in documents with all user interface and versioning complexity extracted away.
You've seen how simple it is to create performant, real-time lists of documents. Prepare to be amazed at how simple it is to edit them.
While the API in this lesson may look simple, what it's doing under the hood is anything but. Edits are optimistically written to an in-browser cache. When editing a published document, a new draft is immediately invoked, behavior which the Sanity Studio performs but has been difficult to replicate with Sanity Client alone.
The fetch from `useDocument` in the previous lesson provided us with real-time document values, now you can create form components which will update those values.
## Editing with a radio input
First let's create a control to update the value of the `sentiment` field with a selection of radio buttons.
1. **Create** a new component with a list of available values
```tsx:app-feedback/src/Sentiment.tsx
import { DocumentHandle, useEditDocument } from "@sanity/sdk-react"
import { Radio, Text, Inline, Stack } from "@sanity/ui"
type SentimentProps = {
value: string
handle: DocumentHandle
}
const SENTIMENTS = ["Positive", "Neutral", "Negative"]
export function Sentiment({ value, handle }: SentimentProps) {
const editSentiment = useEditDocument({ ...handle, path: "sentiment" })
return (
<Stack space={3}>
<Text weight="medium">Sentiment</Text>
<Inline space={3}>
{SENTIMENTS.map((sentiment) => (
<Inline key={sentiment} as="label" space={1} htmlFor={sentiment}>
<Radio
id={sentiment}
checked={value === sentiment.toLowerCase()}
onChange={(e) => editSentiment(e.currentTarget.value)}
name="sentiment"
value={sentiment.toLowerCase()}
/>
<Text>{sentiment}</Text>
</Inline>
))}
</Inline>
</Stack>
)
}
```
Notice how this component uses `useEditDocument` to only modify a specific path in the document. This means any value passed into the `editSentiment` function will be automatically written to that path in the document.
1. In many React applications you are encouraged to write and track changes to local state, perhaps with a `useState` hook. The real-time nature of Sanity Studio and the App SDK encourages you to always write directly to—and render responses from—the Content Lake. App SDK is doing work under the hood to make this optimistic and fast.
1. **Update** the `FeedbackEdit` component to render the `Sentiment` component
```tsx:app-feedback/src/FeedbackEdit.tsx
{/* In the next lessons... */}
<Sentiment value={sentiment} handle={selectedFeedback} />
```
You can now click the radio buttons on any selected document, and the edits will take place in real time.
Open the same document side-by-side in your app and Sanity Studio to see how the changes are reflected to both documents. As well as noting how drafts are automatically invoked when making edits to published documents.
## Editing with a text input
The `notes` field in our feedback schema is for authors to add some helpful details for other team members to read.
1. **Create** a new component to edit `notes`
```tsx:app-feedback/src/Notes.tsx
import { type DocumentHandle, useEditDocument } from "@sanity/sdk-react"
import { Stack, Text, TextArea } from "@sanity/ui"
type NotesProps = {
value: string
handle: DocumentHandle
}
export function Notes({ value, handle }: NotesProps) {
const editNotes = useEditDocument({ ...handle, path: "notes" })
return (
<Stack space={3}>
<Text weight="medium">Reviewer Notes</Text>
<TextArea
value={value}
onChange={(e) => editNotes(e.currentTarget.value)}
placeholder="Add your notes about this feedback..."
rows={3}
/>
</Stack>
)
}
```
This component is quite similar to the `Sentiment` component before, where `editDocument` is configured with a pre-set path, and the TextArea input writes changes to it.
1. **Update** `FeedbackEdit` to include the `Notes` component
```tsx:app-feedback/src/FeedbackEdit.tsx
<Notes value={notes} handle={selectedFeedback} />
```
Once again, try writing into the text field, and watch the same document in Sanity Studio update almost immediately after.
You're now able to make edits to documents, but they're all left in a draft state. So our authors can't commit their changes.
You'll setup document actions in the next lesson to finish the work.## [useApplyDocumentActions](/learn/course/build-content-apps-with-sanity-app-sdk/use-apply-document-actions)
Perform actions on documents to end—or begin—the content lifecycle
Document Actions are primarily used to modify the "version" of an entire document—to publish a draft document, to discard the current draft, or to delete the document.
In our app it may be useful to delete feedback that we don't want to keep (this is different from spam where we may want to keep it as a record of a sender for who all future submissions should be blocked).
## Delete document action
1. **Create** a new component to hold all our document actions.
```tsx:app-feedback/src/Actions.tsx
import {
deleteDocument,
type DocumentHandle,
useApplyDocumentActions,
} from "@sanity/sdk-react"
import { Button, Flex } from "@sanity/ui"
type ActionsProps = {
handle: DocumentHandle
}
export function Actions({ handle }: ActionsProps) {
const apply = useApplyDocumentActions()
const handleDelete = () => apply(deleteDocument(handle))
return (
<Flex gap={1} direction={["column", "column", "column", "row"]}>
<Button
mode="ghost"
tone="critical"
text="Delete"
onClick={handleDelete}
/>
</Flex>
)
}
```
1. **Update** the `FeedbackEdit` component to render it
```tsx:app-feedback/src/FeedbackEdit.tsx
<Flex
justify="flex-end"
direction={["column-reverse", "column-reverse", "row"]}
gap={2}
>
<Actions handle={selectedFeedback} />
</Flex>
```
You'll add some more buttons to this component in latter lessons, that's why we're wrapping it with a `Flex` component now.
You can now click the "delete" button to delete a document. This action is immediate and the document is removed from the Content Lake.
Remember, you can re-import the seed data if you want to re-populate the feedback list!
You may notice a _small_ bug into the UI—the currently selected document no longer exists and displays for a few moments before the list is updated. We'll improve this in a future lesson.
## Edit and publish in one function
The intention of these buttons is to perform a final action before moving onto the next piece of feedback. If we only edited the `status` field to set the value as "approved" or "spam," the resulting document would still be in a draft version.
What we need is a function that will both edit the field value of the document and publish it.
1. **Update** the Actions component to include buttons to mark as spam and approve
```tsx:app-feedback/src/Actions.tsx
import {
deleteDocument,
type DocumentHandle,
publishDocument,
useApplyDocumentActions,
useEditDocument,
} from "@sanity/sdk-react"
import { Button, Flex } from "@sanity/ui"
type ActionsProps = {
handle: DocumentHandle
}
export function Actions({ handle }: ActionsProps) {
const apply = useApplyDocumentActions()
const editStatus = useEditDocument({ ...handle, path: "status" })
const handleDelete = () => apply(deleteDocument(handle))
const handleMarkAsSpam = () => {
editStatus("spam")
apply(publishDocument(handle))
}
const handleApprove = () => {
editStatus("approved")
apply(publishDocument(handle))
}
return (
<Flex gap={1} direction={["column", "column", "row"]}>
<Button
mode="ghost"
tone="critical"
text="Delete"
onClick={handleDelete}
/>
<Button
mode="ghost"
tone="caution"
text="Mark as Spam"
onClick={handleMarkAsSpam}
/>
<Button
mode="ghost"
tone="positive"
text="Approve"
onClick={handleApprove}
/>
</Flex>
)
}
```
1. Invoking `editDocument` is how you can perform bulk editing operations across several documents at the same time.
You'll see these two new actions will invoke both `editDocument` to set the new `status` value and apply the `publishDocument` action.
If you click one of these buttons with the Studio open to the same document, you may only briefly see a draft document with the updated `status` value before it is immediately published.
Now that your app is performing significant actions on documents, some additional feedback in the UI will help users. Let's add notifications in the next lesson.## [useDocumentEvent](/learn/course/build-content-apps-with-sanity-app-sdk/use-document-event)
Listen to changes to content in your application and trigger events in the user interface.
User feedback is extremely important in our applications. Especially when users are taking actions as significant as publishing or deleting documents.
Sanity UI comes with hooks to pop up toast notifications. We'll configure that when events happen in this lesson.
Sanity UI exports a `ToastProvider` which should already be included inside the SanityUI component.
1. **Confirm** `SanityUI.tsx` includes the `ToastProvider`
```tsx:app-feedback/src/SanityUI.tsx
import {ThemeProvider, ToastProvider} from '@sanity/ui'
import {buildTheme} from '@sanity/ui/theme'
import {createGlobalStyle} from 'styled-components'
const theme = buildTheme()
const GlobalStyle = createGlobalStyle`
html, body {
margin: 0;
padding: 0;
}
`
export function SanityUI({children}: {children: React.ReactNode}) {
return (
<>
<GlobalStyle />
<ThemeProvider theme={theme}>
<ToastProvider>{children}</ToastProvider>
</ThemeProvider>
</>
)
}
```
Now you can create a new component to listen to document events as they happen, and when required, pop up toast notifications in the UI.
1. **Create** a new `FeedbackEvents` component to fire toast notifications as events happen
```tsx:app-feedback/src/FeedbackEvents.tsx
import { DocumentEvent, useDocumentEvent } from "@sanity/sdk-react"
import { useToast } from "@sanity/ui"
export function FeedbackEvents() {
const toast = useToast()
const onEvent = (documentEvent: DocumentEvent) => {
if (documentEvent.type === "published") {
toast.push({
title: "Feedback processed",
status: "success",
})
} else if (documentEvent.type === "deleted") {
toast.push({
title: "Feedback deleted",
status: "error",
})
}
}
useDocumentEvent({ onEvent })
return null
}
```
This component doesn't render any UI and so can be rendered anywhere inside the `SanityApp` provider.
1. **Update** `App.tsx` to include the `FeedbackEvents` component
```tsx:app-feedback/src/App.tsx
import { FeedbackEvents } from "./FeedbackEvents"
export function App() {
// ...sanityConfigs, Loading
return (
<SanityUI>
<SanityApp config={sanityConfigs} fallback={<Loading />}>
<Feedback />
<FeedbackEvents />
</SanityApp>
</SanityUI>
)
}
export default App
```
Now you can click **Approve**, **Mark as Spam** or **Delete** on any document and see a toast notification to show you've completed an action.
At this point, you could consider our app to be "feature complete." Authors are able to set the sentiment of a piece of feedback, add some notes and take a final action on the document.
But we can go deeper!## [useUsers](/learn/course/build-content-apps-with-sanity-app-sdk/use-users)
Render an interactive list of Sanity project users to assign to documents.
Storing user data against documents can be useful for instances such as user "assignment." You can add another document editing control to display all users in a project as a clickable list to set a user ID as a value in a document.
1. **Create** a new component `Assignee` to query for project users and render their avatars.
```tsx:app-feedback/src/Assignee.tsx
import { DocumentHandle, useEditDocument, useUsers } from "@sanity/sdk-react"
import { Inline, Avatar, Stack, Text, Button } from "@sanity/ui"
type AssigneeProps = {
value: string
handle: DocumentHandle
}
export function Assignee({ value, handle }: AssigneeProps) {
const { data: users } = useUsers()
const editAssignee = useEditDocument({ ...handle, path: "assignee" })
return (
<Stack space={3}>
<Text weight="medium">Assignee</Text>
<Inline space={1}>
{users?.map((user) => (
<Button
key={user.sanityUserId}
onClick={() => editAssignee(user.sanityUserId)}
padding={0}
mode="bleed"
>
<Avatar
status={value === user.sanityUserId ? "online" : "inactive"}
size={2}
src={user.profile?.imageUrl}
/>
</Button>
))}
</Inline>
</Stack>
)
}
```
1. **Update** the `FeedbackEdit` component to include it
```tsx:app-feedback/src/FeedbackEdit.tsx
<Assignee value={assignee} handle={selectedFeedback} />
```
There is another hook to quickly retrieve the details of the currently logged in user. We can use it to filter the documents returned in `useDocuments`. Let's put it to work in the next lesson.## [useUser](/learn/course/build-content-apps-with-sanity-app-sdk/use-user)
Filter the queried list of documents based on the current user and other selections.
Now that feedback documents can be marked as assigned to specific users, it would be useful to filter the feedback list of documents to just those the current user is responsible for.
The `useDocuments` hook you setup initially in `FeedbackList` only has a `documentType` option set:
```groq
documentType: 'feedback'
```
However, this hook can also take `filter` and `params` options which may be dynamically updated by the application. Let's add some UI elements which will dynamically filter the list of returned documents.
1. **Create** a new component to dynamically filter documents by `status`
```tsx:app-feedback/src/StatusSelector.tsx
import { Button, Grid } from "@sanity/ui"
type StatusSelectorProps = {
status: string
setStatus: (nextStatus: string) => void
}
const STATUSES = ["All", "Pending", "Spam", "Approved"]
export function StatusSelector({ status, setStatus }: StatusSelectorProps) {
return (
<Grid columns={[2, 2, 2, 4]} gap={1}>
{STATUSES.map((statusOption) => (
<Button
key={statusOption}
mode={statusOption.toLowerCase() === status ? "default" : "ghost"}
onClick={() => setStatus(statusOption.toLowerCase())}
text={statusOption}
/>
))}
</Grid>
)
}
```
1. **Create** another document to toggle an additional filter for the `assignee` field.
```tsx:app-feedback/src/OnlyMine.tsx
import { Switch, Inline, Text, Card } from "@sanity/ui"
import { useCurrentUser } from "@sanity/sdk-react"
import { Dispatch, SetStateAction } from "react"
type OnlyMineProps = {
userId: string | null
setUserId: Dispatch<SetStateAction<string | null>>
}
export function OnlyMine({ userId, setUserId }: OnlyMineProps) {
const currentUser = useCurrentUser()
return (
<Card border padding={2}>
<Inline space={2}>
<Text size={1} as="label" htmlFor="only-mine">
Only mine
</Text>
<Switch
id="only-mine"
disabled={!currentUser}
checked={userId === currentUser?.id}
onClick={() => {
if (currentUser) {
setUserId((currentId) =>
currentId === currentUser.id ? null : currentUser.id
)
}
}}
/>
</Inline>
</Card>
)
}
```
Now you'll need to import these into the `FeedbackList` and set a `filter` that will conditionally use the `params`.
1. **Update** the `FeedbackList` component
```tsx:app-feedback/src/FeedbackList.tsx
import { Suspense, useState } from "react"
import { type DocumentHandle, useDocuments } from "@sanity/sdk-react"
import { Stack, Button, Spinner } from "@sanity/ui"
import { FeedbackPreview } from "./FeedbackPreview"
import { StatusSelector } from "./StatusSelector"
import { OnlyMine } from "./OnlyMine"
type FeedbackListProps = {
selectedFeedback: DocumentHandle | null
setSelectedFeedback: (feedback: DocumentHandle | null) => void
}
export function FeedbackList({
selectedFeedback,
setSelectedFeedback,
}: FeedbackListProps) {
const [userId, setUserId] = useState<string | null>(null)
const [status, setStatus] = useState("all")
const { data, hasMore, loadMore } = useDocuments({
documentType: "feedback",
filter: `
select(defined($userId) => assignee == $userId, true)
&& select(
$status == "pending" => !defined(status) || status == "pending",
$status == "spam" => status == $status,
$status == "approved" => status == $status,
true
)
`,
params: { userId, status },
orderings: [{ field: "_createdAt", direction: "desc" }],
batchSize: 10,
})
return (
<Stack space={2} padding={5}>
<StatusSelector status={status} setStatus={setStatus} />
<OnlyMine userId={userId} setUserId={setUserId} />
{data?.map((feedback) => {
const isSelected = selectedFeedback?.documentId === feedback.documentId
return (
<Button
key={feedback.documentId}
onClick={() => setSelectedFeedback(feedback)}
mode={isSelected ? "ghost" : "bleed"}
tone={isSelected ? "primary" : undefined}
>
<Suspense fallback={<Spinner />}>
<FeedbackPreview {...feedback} />
</Suspense>
</Button>
)
})}
{hasMore && <Button onClick={loadMore} text="Load more" />}
</Stack>
)
}
```
You should now be able to click the buttons to filter based on user assignment or document status. Our app's really useful now!
## Conditional GROQ params
The GROQ filter we wrote is a bit gnarly! The `select()` function is used here to only filter by a param value if it is not `null`.
First it uses `defined()` to check if `$userId` is not `null`. If not, it will only find documents where the `assignee` field matches `$userId`. If it is `null`, the value of the assignee field is not used as part of the filter.
It also applies selective filtering looking at the value of the `status` field—first checking for documents without that value (or the value of "pending"), then only showing "spam" or "approved" documents if that's what the current filter matches. Lastly, it just returns everything regardless of the `status` field.
We can go _further_. Let's link your app and the Studio more closely together.## [useNavigateToStudioDocument](/learn/course/build-content-apps-with-sanity-app-sdk/use-navigate-to-studio-document)
Bridge the gap between your application and Sanity Studio with an automatic link.
It may benefit your application to include links from any document to the Studio, as your Studio is probably still the source of truth for all your content.
Fortunately, the App SDK provides a hook to automatically generate a link from a document to the correct Studio.
## Deploy the Studio
You will need to deploy your Studio first to make this work, as links from your app's development server won't open in your local running Studio.
1. **Run** the following command in the `/studio` folder to deploy your Studio and schema
```sh
# in the /studio folder
npx sanity@latest deploy
```
Follow the prompts, once deployed you should see your Studio as an option on the left hand side of the Dashboard.
Let's proceed!
## Composing suspenseful components
In the example below, the Suspense boundary is exported from the component file itself. This is a useful pattern to unify the `fallback` and child components to remove any layout shift.
Instead of a loading spinner, the fallback prop is a disabled version of the same button rendered by the child component when loading is complete.
You may like to consider implementing other suspenseful components in the same way, so that your logic of what renders before and after loading is colocated in a single file.
## Navigate to Studio
1. **Create** a new component for a button which will open documents in the Studio.
```tsx:app-feedback/src/OpenInStudio.tsx
import { Suspense } from "react"
import {
type DocumentHandle,
useNavigateToStudioDocument,
} from "@sanity/sdk-react"
import { Button } from "@sanity/ui"
const BUTTON_TEXT = "Open in Studio"
type OpenInStudioProps = {
handle: DocumentHandle
}
export function OpenInStudio({ handle }: OpenInStudioProps) {
return (
<Suspense fallback={<OpenInStudioFallback />}>
<OpenInStudioButton handle={handle} />
</Suspense>
)
}
function OpenInStudioFallback() {
return <Button text={BUTTON_TEXT} disabled />
}
function OpenInStudioButton({ handle }: OpenInStudioProps) {
const { navigateToStudioDocument } = useNavigateToStudioDocument(handle)
return <Button onClick={navigateToStudioDocument} text={BUTTON_TEXT} />
}
```
1. **Update** the `FeedbackEdit` component to add this new button alongside your actions
```tsx:app-feedback/src/FeedbackEdit.tsx
<Flex
justify="space-between"
direction={['column-reverse', 'column-reverse', 'row']}
gap={2}
>
<OpenInStudio handle={selectedFeedback} />
<Actions handle={selectedFeedback} />
</Flex>
```
You should now be able to go directly from any selected feedback document in your app, to that same document in your Sanity Studio.
Your app currently uses the most common hooks in the App SDK for React, but there's one more, do-anything hook we can put to work.## [useClient](/learn/course/build-content-apps-with-sanity-app-sdk/use-client)
"Break glass in case of emergency" access to the all-powerful Sanity Client.
If you've done Sanity development before App SDK, it's remarkable to think how complex of an application you've used without ever needing to access the Sanity Client directly.
Thankfully, however, if we have needs that the App SDK doesn't provide, we can always reach out and grab the Sanity Client to take control of our own destiny.
Currently, the sentiment editor is not very intelligent. It requires a human to read the feedback and spend mental cycles processing whether it is positive, neutral, or negative.
This is no longer a job for humans; this is a job for AI. Sanity Client contains AI Agent Actions which are just the tools we need.
## Deploying schema
In the previous lesson you deployed the Studio. This should have also deployed your Studio's schema types—which are required by Agent Actions.
You can list your deployed schemas from the command line:
```sh
# inside the /studio folder
npx sanity@latest schema list
```
You should see at least one schema deployment. If not, try deploying now.
```sh
# inside the /studio folder
npx sanity@latest schema
```
## Calling the agent action
You'll now update the `Sentiment` component almost entirely. Instead of the value being edited by a user selection, clicking a button will hand the work off to the Agent Action.
Note: In reality this might be better performed in a Sanity Function so it is automated, instead of waiting for user action.
1. **Update** the `Sentiment` component to call an Agent Action.
```tsx:app-feedback/src/Sentiment.tsx
import { DocumentHandle, useClient } from "@sanity/sdk-react"
import { Text, Inline, Stack, Button } from "@sanity/ui"
import { useToast } from "@sanity/ui"
type SentimentProps = {
feedback: string
value: string
handle: DocumentHandle
}
function titleCase(str: string) {
return str.replace(
/\w\S*/g,
(txt) => txt.charAt(0).toUpperCase() + txt.slice(1)
)
}
const SCHEMA_ID = "_.schemas.default"
export function Sentiment({ feedback, value, handle }: SentimentProps) {
const client = useClient({ apiVersion: "vX" })
const toast = useToast()
function assessSentiment() {
client.agent.action
.generate({
targetDocument: {
operation: "edit",
_id: handle.documentId,
},
instruction: `
You are a helpful assistant that analyzes customer feedback and determines the sentiment of the feedback.
The sentiment can be one of the following: "positive", "neutral", "negative",
Analyze the following feedback and determine the sentiment:
$feedback
`,
instructionParams: {
feedback: {
type: "constant",
value: feedback,
},
},
target: {
path: "sentiment",
},
schemaId: SCHEMA_ID,
})
.then((result) => {
toast.push({
title: "Sentiment assessed",
description: result.text,
status: "success",
})
})
.catch((error) => {
toast.push({
title: "Error assessing sentiment",
description: error.message,
status: "error",
})
})
}
return (
<Stack space={3}>
<Text weight="medium">Sentiment</Text>
<Inline space={3}>
<Button mode="ghost" onClick={assessSentiment} text="Assess" />
<Text>{value ? titleCase(value) : ""}</Text>
</Inline>
</Stack>
)
}
```
You'll also need to pass down the content of the feedback into this component, so it can be used as a parameter in the Agent Action.
1. **Update** the `FeedbackEdit` component to pass feedback down to `Sentiment` as a prop
```tsx:app-feedback/src/FeedbackEdit.tsx
<Sentiment
value={sentiment}
handle={selectedFeedback}
feedback={content}
/>
```
Now with any feedback document open you can click the "Assess" button and save yourself the decision making fatigue of determining user sentiment.
Your app is now feature complete! Let's deploy it to the world.## [Deployment and finishing touches](/learn/course/build-content-apps-with-sanity-app-sdk/deployment-and-finishing-touches)
You have a working app. It's time to share it with your authoring team and tidy up some rough edges.
## Deploy your app
You can deploy your custom application at any time. Just like your Sanity Studio, it can be deployed from the command line.
```sh
# in /app-feedback
pnpm dlx sanity deploy
```
The first time you deploy your application, you’ll be prompted for a title. Once deployed, your app receives a unique ID which should be added to your app's `sanity.cli.ts` file for smoother future deployments.
1. **Update** your `sanity.cli.ts` file once your app is deployed with its `ID`
```typescript:app-feedback/sanity.cli.ts
import { defineCliConfig } from "sanity/cli"
export default defineCliConfig({
// ...all other settings
deployment: {
appId: "YOUR_APP_ID",
},
})
```
You should now see your Feedback application in the left hand column of your Sanity dashboard.
## Avoid repetitive loading spinners
Using Suspense throughout the application has given us a way to render loading spinners while data is fetched. This is great at first, but you may notice some annoying behavior when clicking through multiple documents in the feedback list.
The spinner appears almost every time you change documents. Even though the responses for these documents are cached, this occasional disappearance and re-rendering of the editing form is visual noise that we could do without.
Fortunately, React gives us a function called `startTransition`, which we can use to prevent more than one loading spinner when we change the selected document.
1. **Update** the `Feedback` component to use `startTransition`
```tsx:app-feedback/src/Feedback.tsx
import { startTransition, Suspense, useState } from "react"
import { DocumentHandle } from "@sanity/sdk-react"
import { Card, Flex, Grid, Spinner } from "@sanity/ui"
import { styled } from "styled-components"
import { FeedbackList } from "./FeedbackList"
import { FeedbackEdit } from "./FeedbackEdit"
const ScreenHeightCard = styled(Card)`
height: 100vh;
overflow: scroll;
`
export function Feedback() {
const [selectedFeedback, setSelectedFeedback] =
useState<DocumentHandle | null>(null)
const updateSelectedFeedback = (handle: DocumentHandle | null) =>
startTransition(() => setSelectedFeedback(handle))
return (
<Grid columns={5}>
<ScreenHeightCard columnStart={1} columnEnd={3}>
<Suspense fallback={<Loading />}>
<FeedbackList
setSelectedFeedback={updateSelectedFeedback}
selectedFeedback={selectedFeedback}
/>
</Suspense>
</ScreenHeightCard>
<ScreenHeightCard borderLeft columnStart={3} columnEnd={6}>
<Suspense fallback={<Loading />}>
{selectedFeedback ? (
<FeedbackEdit selectedFeedback={selectedFeedback} />
) : null}
</Suspense>
</ScreenHeightCard>
</Grid>
)
}
function Loading() {
return (
<Flex justify="center" align="center" width="fill" height="fill">
<Spinner />
</Flex>
)
}
```
Now, when we click through documents in the list, the previously selected document should remain visible until the next document has finished loading.
It is possible to get a pending state from the `useTransition` hook. [Take a look in the React documentation](https://react.dev/reference/react/Suspense#indicating-that-a-transition-is-happening) for more details.
## Show optimistic updates in the document list
For performance reasons, we have used `useDocumentProjection` in the document list and `useDocument` in the editing form.
You may notice this creates a small discrepancy when changing the status of a document. It happens immediately in the editing form but takes a second to update in the document list.
Since we only need to see optimistic updates on the currently selected document—as that is the one being edited—we could create an optimistic preview component to use in the document list only for the currently selected document.
1. **Create** a new optimistic preview component for the document list
```tsx:app-feedback/src/FeedbackPreviewSelected.tsx
import { useRef } from "react"
import { DocumentHandle, useDocument } from "@sanity/sdk-react"
import { Box, Stack, Text } from "@sanity/ui"
import { StatusBadge } from "./StatusBadge"
type FeedbackPreviewData = {
_createdAt: string
content: string | null
author: string | null
email: string | null
status: string | null
}
export function FeedbackPreviewSelected(props: DocumentHandle) {
const previewRef = useRef<HTMLDivElement>(null)
const { data } = useDocument<FeedbackPreviewData>({ ...props })
const author = typeof data?.author === "string" ? data.author : "..."
const email = typeof data?.email === "string" ? data.email : "..."
const content = typeof data?.content === "string" ? data.content : "..."
const createdAt =
typeof data?._createdAt === "string" ? data._createdAt.split("T")[0] : "..."
const status = typeof data?.status === "string" ? data.status : "PENDING"
return (
<Stack ref={previewRef} space={3}>
<Text size={2} weight="semibold" textOverflow="ellipsis">
{author}
</Text>
<Text muted size={1} textOverflow="ellipsis">
{email} {createdAt}
</Text>
<Text size={2} textOverflow="ellipsis">
{content}
</Text>
<Box>
<StatusBadge status={status} fontSize={1} />
</Box>
</Stack>
)
}
```
1. **Update** the FeedbackList component to selectively render the correct component
```tsx:app-feedback/src/FeedbackList.tsx
{isSelected ? (
<FeedbackPreviewSelected {...feedback} />
) : (
<FeedbackPreview {...feedback} />
)}
```
If you change a Feedback item from "Approved" to "Spam" now it should be reflected immediately in the selected document preview.
Much better! Let's test what you've learned in the final lesson.## [SDK Quiz](/learn/course/build-content-apps-with-sanity-app-sdk/sdk-quiz)
Let's put everything you've learned to the test!
Now you've built a fully featured content application, let's see what you've learned about some of the hooks you've put to work.
**Question:** useDocuments is preferable to client.fetch because...
1. It fetches faster
2. Built-in batching and real-time updates
3. Hooks are the only way to fetch data in React
4. You can't be trusted with client.fetch
**Question:** useDocumentProjection is a hook for
1. Fetching multiple documents
2. Fetching document values
3. Fetching future values
4. Fetching user data
**Question:** useDocument should be used sparingly because
1. It costs extra
2. It resolves both local and remote states of the document
3. It's slower
4. It's not always correct
**Question:** useEditDocument creates better UI than client.patch because
1. It's faster
2. It handles versions
3. It handles webhooks
4. It's cheaper
**Question:** useApplyDocumentActions provides a way to perform actions, like
1. Trigger a webhook
2. Publish a document
3. Update your billing
4. Delete a user
**Question:** useDocumentEvent listens to
1. Mutations to documents
2. Webhooks firing
3. User log-ins
4. Your computer's microphone
**Question:** useNavigateToStudioDocument
1. Is an incredibly specific name for a hook
2. Is a mysterious name for a hook# [Controlling cached content in Next.js](/learn/course/controlling-cached-content-in-next-js)
Creating a high performance web application for fast loading depends on caching. Learn how to implement a caching strategy you can understand, debug and depend on.
## [Caching Fundamentals](/learn/course/controlling-cached-content-in-next-js/introduction)
Next.js has prioritized performance with its caching methods and expects you to configure them. Learn how to integrate the Next.js cache and Sanity CDN for high performance.
## Prefer live by default
You might not need this course.
The [Live Content API](https://www.sanity.io/learn/content-lake/live-content-api), and its simplified implementation with [`next-sanity`](https://www.sanity.io/learn/course/visual-editing-with-next-js/enhanced-visual-editing-with-react-loader), handles all aspects of fetching, rendering, caching and invalidating queries in a few lines of code.
1. This course remains online to explain finer details of working with Sanity and the Next.js cache. And the code examples in it may not follow from the previous [Content-driven web application foundations](https://www.sanity.io/learn/course/content-driven-web-application-foundations) course. Our **strong recommendation** is to use live fetches by default.
1. Skip to the [Integrated Visual Editing with Next.js](https://www.sanity.io/learn/course/visual-editing-with-next-js) course next.
## Welcome to caching
Caching is not unique to Next.js or Vercel; it's a common strategy across all programming and comes in many forms. For example, in-memory caching is one approach that stores data in the application's memory for quick access.
When discussing caching for web applications, it typically refers to network requests. When a user makes a request from a web server, the response may be cached in their browser, so subsequent requests for the same page do not need to perform yet another round-trip for the same response.
Similarly, when a web server computes and returns a response, it may be cached on the server so that subsequent requests from many other clients can be fulfilled from its cache – faster than recomputing the same request.
This is where things get tricky. How long should your web server cache that response? If it's too long, your users may be frustrated by being served stale content. If it's too short, too many users may have to wait for the web server to compute responses – and your web server may use too many resources doing so.
## Next.js specific caching
In typical web applications, caching is handled by modifying the headers sent with a request.
1. See the MDN documentation on [Cache-Control headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control)
However, Next.js has framework-specific configuration options to scope and simplify setup. This course will primarily focus on these. The following resources may be valuable additional reading:
1. [Next.js data fetching](https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating) documentation
2. [Next.js caching](https://nextjs.org/docs/app/building-your-application/caching) documentation
## Goals of this course
Once you have completed this course, you will:
* Understand why caching matters based on who is most impacted and how.
* Integrate requests for Sanity's CDN and API with the built-in Next.js cache, configured with sensible defaults.
* Observe the impact of – and debug changes to – cache configuration.
* Revalidate cached requests based on time, path, and tag.
* Setup [GROQ-powered webhooks](https://www.sanity.io/learn/compute-and-ai/webhooks) to perform cache revalidation automatically when documents change.
## Who is impacted by caching?
There's no one-size-fits-all strategy for caching, so a developer team is responsible for fine-tuning their application's caches. Let's consider how different user groups are impacted by the types of caching that can be implemented.
### Content authors
In content-driven web applications, content authors typically want to see the effect of their changes happen immediately. The most reliable way to do this would be to remove all caching from the front end so that every response is freshly created. You could also retrieve content from Sanity's API instead of the CDN to ensure the freshest content is used.
However, this strategy also creates the slowest loading and most expensive operating web applications. Not ideal.
1. Content authors that would prefer to see fresh content before – or immediately after – publishing are better served by configuring Visual Editing – rather than modifying cache settings in production. Take the [Integrated Visual Editing with Next.js](https://www.sanity.io/learn/course/visual-editing-with-next-js) course to find out how.
### Business stakeholders
Stakeholders in your business would like to keep the running costs of your web application low and conversions high, so you might think the most aggressive caching strategy would suit them. The fewer requests directed to an API instead of a CDN, the better. The less bandwidth a web server spends computing and fulfilling requests, the better.
1. See Cloudflare's documentation on how [website speed affects conversion rates](https://www.cloudflare.com/learning/performance/more/website-performance-conversion-rates)
However, overly aggressive caching is bound to frustrate your content authors and end-user groups.
### End users
The stakeholders mentioned above would also like to see improved conversions from end-users – who expect a mix of fast-loading pages and up-to-date, reliable content. For example, it's no good if a product page loads quickly but the stock level or price information is invalid.
1. Split requests for long-lived and dynamic parts of the same page. [Partial pre-rendering](https://nextjs.org/docs/app/api-reference/next-config-js/partial-prerendering) is one solution for the above problem.
As you can see, each group that is majorly impacted by your web application's cache brings a unique point of view. This makes knowing how caching works—and reacting to the changing realities of how your application is used—so important.
Now that you understand the problem space and who is impacted, it's best to equip yourself with the tools required to configure and debug your web application's caching configuration.## [Demystifying caching in development](/learn/course/controlling-cached-content-in-next-js/debugging-caching-in-development)
Set up Next.js so that as you make changes and navigate through the application, you can observe the impact of your cache configuration.
In recent years, the popularity of the "Jamstack" and Static Site Generators reduced the importance of caching when serving web applications. However, as the limitations of those approaches became more apparent, dynamic, server-rendered responses have once again become popular, spotlighting caching once again.
Next.js 14 not only provided aggressive caching for an application's `fetch` requests, but it also made it the default.
This led to faster response times at the expense of increased developer frustration. Every `fetch` request was instantly cached, whether in development or production. Further, this cache is stored in a separate data layer from your site code, so redeploys did not reset the site's state like you may have expected in the Jamstack years.
Next.js 15 has reversed this decision, and caching is opt-in once again. This was likely a difficult decision because there are pitfalls either way.
In this writer's opinion, this decision is not strictly _better_; it is just _different_.
It's more important to understand what has been cached and when than whether a request was cached by default.
In short, you will want to specify the caching configuration and be able to observe its results.
## Logging fetch requests
Fortunately, a Next.js configuration setting logs [the full URL of any fetch request](https://nextjs.org/docs/app/api-reference/next-config-js/logging), along with information about whether it was a cache `HIT` or `MISS` – and why.
1. A cache `HIT` occurs when the requested data is found in the cache, allowing it to be served quickly without fetching from the source.
2. A cache `MISS` is the opposite, requiring it to be fetched from the source, which is slower than serving from the cache.
Sanity Client uses `fetch` under the hood, so once you have enabled this debugging mode below, every query you perform with it will appear in the console.
1. **Update** your `next.config.ts` with the following configuration
```typescript:next.config.ts
import type { NextConfig } from "next";
const nextConfig: NextConfig = {
logging: {
fetches: {
fullUrl: true,
},
},
// ...all other settings
};
export default nextConfig;
```
Now refresh any page that fetches data from Sanity – like the posts index or an individual post page – and you should see something like the following in your console:
```text
GET /posts 200 in 39ms
│ GET https://q1a918nb.apicdn.sanity.io/v2024-07-24/data/query/production?query=*%5B_type+%3D%3D+%22post%22+%26%26+defined%28slug.current%29%5D%5B0...12%5D%7B%0A++_id%2C+title%2C+slug%0A%7D&returnQuery=false 200 in 5ms (cache hit)
```
From this, you can observe:
* The `client.fetch()` request was for `apicdn.sanity.io` which means the request was performed with Sanity Client's `useCdn` set to `true`.
* As a **cache hit**, the response was fulfilled by the Next.js cache, so this request for `/posts` may not have been sent to Sanity's CDN.
In the previous course – [Content-driven web application foundations](https://www.sanity.io/learn/course/content-driven-web-application-foundations) – these fetches were configured to update at most once every 60 seconds.
* If a cache hit has already been served within 60 seconds, the response will be fast.
* If that time has elapsed, the request will still be served stale, expired data – but in the background, the cache will be repopulated so that the next request receives fresh content.
1. This is similar to the [stale-while-revalidate](https://web.dev/articles/stale-while-revalidate) pattern of caching responses
## Purging the cache
Seeing what is cached is helpful, but it's even better to be able to completely reset the cache during development.
In the following lessons, you'll look at setting up surgical control for revalidating fetches based on time, path, and tag. This is the preferred option for your production web application. But sometimes, in development, you need a _hammer_.
1. **Create** a new API route in your application:
```typescript:src/app/api/revalidate/all/route.ts
import { revalidatePath } from 'next/cache'
export async function GET() {
if (process.env.NODE_ENV === 'development') {
revalidatePath('/', 'layout')
return Response.json({ message: 'Layout revalidated' })
}
return Response.json({
message: 'This route is configured to only revalidate the layout in development',
})
}
```
1. **Visit** [http://localhost:3000/api/revalidate/all](http://localhost:3000/api/revalidate/all) and you should see the same message above in your browser.
2. **Visit** [http://localhost:3000/posts](http://localhost:3000/posts) to check that it has worked.
You should see a different log in the terminal that finishes with `cache skip`:
```text
GET /posts 200 in 893ms
│ GET https://q1a918nb.apicdn.sanity.io/v2024-07-24/data/query/production?query=*%5B_type+%3D%3D+%22post%22+%26%26+defined%28slug.current%29%5D%5B0...12%5D%7B%0A++_id%2C+title%2C+slug%0A%7D&returnQuery=false 200 in 743ms (cache skip)
│ │ Cache skipped reason: (cache-control: no-cache (hard refresh))
```
Refresh the page again, and the request should once again be a `cache hit`.
Now you can purge the entire Next.js cache on demand, and observe the caching behavior of every `fetch` request made in the application.
The two uses of `client.fetch` in your application currently have the same configuration. This presents an opportunity to make our code more DRY (don't repeat yourself) and set some sensible defaults.
In the next lesson, let's do this and better understand how Sanity and Next.js caching work together.## [Combining Sanity CDN with the Next.js Cache](/learn/course/controlling-cached-content-in-next-js/combining-sanity-cdn-with-the-next-js-cache)
Implement Sanity Client in a way that compliments and leverages the Next.js cache with sensible defaults.
Even if Next.js had no affordances for caching – or you use a framework with no in-built caching options – the Sanity CDN provides a performant way to query content. This lesson briefly summarizes how querying the correct endpoint in your Next.js application is situation-dependent.
1. See the documentation on the [API CDN](https://www.sanity.io/learn/content-lake/api-cdn) for more details
## Querying Sanity's API or CDN
Your Sanity Client's `useCdn` setting determines whether your fetch request uses the CDN or the API. Depending on the context of your fetch, you may choose to query either one.
### Querying the Sanity API
Querying the API is slower but guaranteed to be fresh. Your project's plan will have a lower allocation of API requests, so you should factor that into your usage. For these reasons you should only query the API (`useCdn: false`) when responses are infrequent and fast responses are not required.
Examples include statically building pages ahead of time and performing incremental static revalidation or tag-based revalidation.
### Querying the Sanity CDN
Querying the CDN is faster but not guaranteed to be fresh. The Sanity CDN's cache is flushed every time a publish mutation is performed on a dataset, so there may be a brief delay between the latest content being published and it being available from the CDN. Your project's plan will have a far higher allocation of CDN requests. You should query the CDN (`useCdn: true`) when responses are frequent and fast responses are desired.
Examples include all situations other than those outlined in the previous situation where the API is preferred. This makes `useCdn: true` a sensible default.
### Overriding `useCdn` per-request
Whatever your Sanity Client configuration, it can be overridden at the time of request using the `withConfig` method. In this section, you'll configure `generateStaticParams` to build individual post pages at build time, instead of at request time.
1. Read more about [`generateStaticParams` on the Next.js documentation](https://nextjs.org/docs/app/api-reference/functions/generate-static-params)
1. **Add** an exported `generateStaticParams` function to the dynamic route
```typescript:src/app/(frontend)/posts/[slug]/page.tsx
// update your imports
import { POST_QUERY, POSTS_SLUGS_QUERY } from "@/sanity/lib/queries";
// add this export
export async function generateStaticParams() {
const slugs = await client
.withConfig({useCdn: false})
.fetch(POSTS_SLUGS_QUERY);
return slugs
}
```
When you next deploy your Next.js application, every individual post page will be created ahead of time, with guaranteed fresh data (fresh at the time it was deployed) fetched direct from the Sanity API.
## Sanity Client and Next.js cache configuration
If you completed the previous lesson, you are relying on Sanity Live to perform caching and live updates. It is possible to manually set cache configuration options when performing fetches with the Sanity Client.
### `sanityFetch` helper function
As detailed in the [next-sanity readme](https://github.com/sanity-io/next-sanity?tab=readme-ov-file#caching-and-revalidation), you may wish instead to create a helper function that wraps Sanity Client with caching configuration options.
This `next` key in the Sanity Client configuration takes the same configuration options found in the Next.js documentation for [controlling how fetches are cached](https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#caching-data).
1. **Update** your `client.ts` file to include an exported helper function, `sanityFetch`
```typescript:src/sanity/lib/client.ts
import {createClient, type QueryParams} from 'next-sanity'
// other imports, client export
// 👇 add this function
export async function sanityFetch<const QueryString extends string>({
query,
params = {},
revalidate = 60, // default revalidation time in seconds
tags = [],
}: {
query: QueryString
params?: QueryParams
revalidate?: number | false
tags?: string[]
}) {
return client.fetch(query, params, {
next: {
revalidate: tags.length ? false : revalidate, // for simple, time-based revalidation
tags, // for tag-based revalidation
},
})
}
```
The most important lines are highlighted above. By default this helper uses a 60 second revalidation—but will also accept tags for tag-based revalidation (covered in another lesson in this course).
1. **Update** your `/posts` route to use our own `sanityFetch`
```typescript:src/app/(frontend)/posts/page.tsx
// update your imports
import { sanityFetch } from "@/sanity/lib/client";
// update your fetch
const posts = await sanityFetch({query: POSTS_QUERY});
```
1. **Update** your individual post route to do the same
```typescript:src/app/(frontend)/posts/[slug]/page.tsx
// update your imports
import { client, sanityFetch } from '@/sanity/lib/client'
// update your fetch
const post = await sanityFetch({
query: POST_QUERY,
params,
})
```
1. This route still uses `client` directly in the `generateStaticParams` export. It's acceptable to use the Sanity Client when the cache settings of a request are not essential.
### What about `options.cache`?
Next.js will also accept options passed to the [Web Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)'s cache, but incorrectly configuring both `next` and `cache` options can lead to errors. It's simplest to let `cache` fall back to its default setting and only focus on `next` in the following lessons.
1. See Next.js [documentation on how it handles fetch](https://nextjs.org/docs/app/api-reference/functions/fetch#fetchurl-options).
### Onward!
With those changes made, you should see no change on your front end! However, you're in a much better place to implement time—and tag-based revalidation. Let's look a little more into time-based revalidation in the next lesson.## [Time-based cache revalidation](/learn/course/controlling-cached-content-in-next-js/time-based-cache-revalidation)
Time-based revalidation is simple to setup and predictable. It might be "enough" for your project.
1. See the Next.js documentation about [time-based revalidation](https://nextjs.org/docs/app/building-your-application/caching#time-based-revalidation)
For every `fetch` made so far, you've only been implementing time-based revalidation. This has been primarily for convenience. It's simple to set up and invalidates itself.
The default setting of 60 seconds is okay. The type of content your application displays and the volume of traffic you receive will determine whether to modify that setting.
Content that changes often, like product pages, may benefit from a lower revalidation time because accuracy is more important than raw speed. Other content, like your terms and conditions pages, likely changes so infrequently that their cache time could safely be set to hours.
The blog post index and individual pages fall into the latter category. Let's update the requests on both routes to cache the responses for an hour.
1. **Update** the fetch on your post-index route
```typescript:src/app/(frontend)/posts/page.tsx
const posts = await sanityFetch({
query: POSTS_QUERY,
revalidate: 3600,
})
```
1. **Update** the fetch on your post route
```typescript:src/app/(frontend)/posts/[slug]/page.tsx
const post = await sanityFetch({
query: POST_QUERY,
params,
revalidate: 3600,
})
```
Instead of hitting Sanity's CDN at least once a minute, requests will be served by the Next.js cache for up to an hour, a significant performance and bandwidth improvement.
Your business stakeholders and end-users are happy. Your content authors could be less so.
## The "typo" problem
Imagine you're a content author who has just published a new post – or fixed a typo on a post – and want to ensure the site is fixed immediately. Right now, they may need to wait up to an hour for the world to see those changes.
You do have a route to clear the entire cache, but this can potentially impact the performance of every request to every page for every user. The _hammer_ option isn't ideal for fixing a typo.
Fortunately, the passage of time isn't the only way to invalidate the cache. Next.js provides a way to invalidate a specific route on demand, and Sanity provides a way to run it automatically on content changes.
Let's revalidate by path in the next lesson.## [Path-based revalidation](/learn/course/controlling-cached-content-in-next-js/path-based-revalidation)
Surgically revalidate individual post pages by their path when updates are made to their document in Sanity Studio.
1. See the Next.js [documentation on `revalidatePath`](https://nextjs.org/docs/app/api-reference/functions/revalidatePath).
Next.js provides a function `revalidatePath`, which will purge the cache for fetches that took place on a specific URL.
Implementing this feature is a massive win for your business stakeholder groups and content authors.
* If post routes are revalidated individually, you can safely give them a much longer time-based revalidation setting – perhaps even infinite – significantly reducing Sanity request volume and server bandwidth.
* Content authors can press "publish" on a document, which automatically revalidates the cache for just that page, and see their updates published instantly.
Currently, each post document in Sanity is rendered on a unique route in Next.js. Because of this 1:1 relationship between document and route, revalidating a cached post is straightforward.
The goal is to purge the cache for a post whenever that post is edited – fixing the "typo problem" highlighted in the previous lesson. Ideally, this should happen automatically, and [GROQ-powered webhooks](https://www.sanity.io/learn/compute-and-ai/webhooks) make this possible.
## Why webhooks?
GROQ-powered webhooks allow you to automate side effects from the Content Lake based on any mutation to a document in a dataset.
While you could automate a function from the Studio to call one of Next.js' revalidate functions, triggering this from a webhook is much safer. It is guaranteed to be called from Sanity infrastructure – not in the browser because of a client interaction. It's also safer with automatic retries should the operation fail.
So, for a little extra setup, you get much more reliability.
1. See more about [GROQ-powered webhooks](https://www.sanity.io/learn/compute-and-ai/webhooks) in the documentation.
## Create an API route to revalidate paths
The code below is for a new API route in your web application designed to be requested by a GROQ-powered webhook. It will:
1. Only handle a `POST` request.
2. Confirm that the request came from a Sanity GROQ-powered webhook.
3. Retrieve the `body` from the request.
4. Retrieve the `path` attribute from the request body and revalidate it.
1. **Rename** your `.env` file to `.env.local`, as it will now contain secrets
2. **Update** your `.env.local` file with a new secret to secure the route. It can be any random string
```text:.env.local
SANITY_REVALIDATE_SECRET=<any-random-string>
```
You will also add this string to the GROQ-powered webhook you set up in this lesson.
1. **Create** a new route to execute `revalidatePath`
```typescript:src/app/api/revalidate/path/route.ts
import { revalidatePath } from 'next/cache'
import { type NextRequest, NextResponse } from 'next/server'
import { parseBody } from 'next-sanity/webhook'
type WebhookPayload = { path?: string }
export async function POST(req: NextRequest) {
try {
if (!process.env.SANITY_REVALIDATE_SECRET) {
return new Response(
'Missing environment variable SANITY_REVALIDATE_SECRET',
{ status: 500 },
)
}
const { isValidSignature, body } = await parseBody<WebhookPayload>(
req,
process.env.SANITY_REVALIDATE_SECRET,
)
if (!isValidSignature) {
const message = 'Invalid signature'
return new Response(JSON.stringify({ message, isValidSignature, body }), {
status: 401,
})
} else if (!body?.path) {
const message = 'Bad Request'
return new Response(JSON.stringify({ message, body }), { status: 400 })
}
revalidatePath(body.path)
const message = `Updated route: ${body.path}`
return NextResponse.json({ body, message })
} catch (err) {
console.error(err)
return new Response((err as Error).message, { status: 500 })
}
}
```
This route confirms the value of the `SANITY_REVALIDATE_SECRET` environment variable and handles any invalid requests to the route.
Because this API route is only configured to handle requests with a `POST` method, visiting it in your browser (which performs a `GET` request) will not work.
Let's configure the webhook to do that for us.
1. In this lesson, you'll only configure `revalidatePath` for a single static path. Still, it can also revalidate an entire dynamic path—like `/(frontend)/posts/[slug]`—see the Next.js [documentation on `revalidatePath`](https://nextjs.org/docs/app/api-reference/functions/revalidatePath) for more details.
## Create a webhook
A GROQ-powered webhook allows Content Lake to perform requests on your behalf whenever a mutation on a dataset is made. This is ideal for content operations like on-demand cache invalidation and will power a workflow where even a page set to be indefinitely cached can be purged and repopulated on demand.
### Remote access for your local environment
A tricky part of developing GROQ-powered webhooks is that even when making content changes in your Sanity Studio's local development environment, webhooks will fire remotely in the Content Lake – but the Content Lake cannot request API routes in your local development environment.
You'll need to share your local URL with the world. Several services can help you do this. Perhaps the simplest and best-known is Ngrok.
1. **Create** a new [free account at Ngrok](https://ngrok.com/) if you do not already have one.
2. Once logged in, complete any installation instructions for your machine
3. **Run** the following command below to share your local Next.js remotely
```text
ngrok http http://localhost:3000
```
Now, in the terminal, you should see many details about your account, version, etc. Along with a "Forwarding" URL which looks something like this:
```text
https://8067-92-26-32-42.ngrok-free.app
```
Open that URL in your browser to see your local Next.js app. You can click links – and even open `/studio` (though you will need to add a CORS origin to interact with it).
Now, you have a remote URL of your local development environment for a GROQ-powered webhook to request.
### Create a new webhook
Fortunately, we have prepared a webhook template to add to your Project. It has most of the settings preconfigured. You'll just need to update a few that are unique to you:
1. **Open** this [path revalidation webhook template](https://www.sanity.io/manage/webhooks/share?name=Path-based%20Revalidation%20Hook%20for%20Next.js&description=&url=https%3A%2F%2FYOUR-PRODUCTION-URL.TLD%2Fapi%2Frevalidate%2Fpath&on=create&on=update&on=delete&filter=_type%20in%20%5B%22post%22%5D&projection=%7B%0A%20%20%22path%22%3A%20select(%0A%20%20%20%20_type%20%3D%3D%20%22post%22%20%3D%3E%20%22%2Fposts%2F%22%20%2B%20slug.current%2C%0A%20%20%20%20slug.current%0A%20%20)%0A%7D&httpMethod=POST&apiVersion=v2021-03-25&includeDrafts=&headers=%7B%7D)
2. **Update** the URL to use your ngrok URL
3. **Click** "Apply Webhook" and select your project, apply to all datasets
4. **Click** "Edit Webhook" on the next screen, scroll to the bottom, and add the same "Secret" you added to your `.env` file
5. **Click** "Save"
You're now ready to publish changes in Sanity Studio to automatically revalidate a document's cached page in your web application.
1. The "Path" being revalidated is set within the "Projection" of the webhook using the [GROQ function](https://www.sanity.io/docs/groq-functions) `select()`. As your application grows, it could be extended to include other unique paths based on the document type or any other logic.
## Test it out
With all the machinery in place, you can test that what you've set up works.
1. **Visit** an individual post page in your application, and check the terminal first to ensure it was a cache `HIT`.
If it is a cache `MISS`, reload the page, and you should see it cached for the following request.
1. **Open** that post within your Sanity Studio at [http://localhost:3000/studio](http://localhost:3000/studio), change the `title` and publish it.
Almost instantly after publishing, in your terminal you should see a `POST` request which was automatically made from the GROQ-powered webhook:
```text
POST /api/revalidate/path 200 in 3540ms
```
1. **Reload** the same individual post page again. You should see a cache `MISS` in the terminal and your updated title on the page.
If you reload the page again, it should be cached for the next request.
### Handling stale data
Are you still seeing stale data? Currently, GROQ-powered webhooks fire when the mutation is made via the Sanity API, but _before_ the Sanity CDN is updated. Your request may have been made in the brief period in between, and the Next.js repopulated with stale data from the Sanity CDN.
If you encounter this situation, there are ways to mitigate it.
Within your API route to revalidate the path, the `parseBody` function from `next-sanity` takes a third argument to add a short delay before proceeding.
```typescript:src/app/api/revalidate/path/route.ts
const {isValidSignature, body} = await parseBody<WebhookPayload>(
req,
process.env.SANITY_REVALIDATE_SECRET,
true
)
```
Alternatively, if you ensure Next.js caches **every** fetch, you could change the Sanity Client configuration to never use the CDN by setting `useCdn: false`.
1. Beware of the potential pitfalls of constantly querying the Sanity API directly. You don't want your application to go viral with uncached requests to the Sanity API.
## We can go deeper
What you have set up now is pretty great! Individual post pages have long-lived cache times and are revalidated automatically on demand when changes are published.
There are two new problems to solve:
1. The post index page **isn't** being revalidated when a post changes, so an update to the title does not appear.
2. The post index and individual post pages show `author` and `category` document values. If those documents are updated, we need to revalidate any component that renders those.
Fortunately, Next.js also offers "tag-based revalidation" for "update once, revalidate everywhere" content operations, and you'll set it up in the next lesson.## [Tag-based revalidation](/learn/course/controlling-cached-content-in-next-js/tag-based-revalidation)
Assign tags to queries to revalidate the cache of many paths by targeting any individual tag.
1. See the Next.js [documentation about `revalidateTag`](https://nextjs.org/docs/app/api-reference/functions/revalidateTag)
So far, the focus has been on revalidating individual post pages when a post changes. But with the current content model, more than just post-type document fields are queried—and there's more than one route where those responses are rendered.
A `post`-type document could contain many `category` references and a single `author` reference. Ideally, a content author editing **any** of these document types should impact **every** route where that content is rendered.
This is made possible with `revalidateTag`.
1. Time-based and tag-based revalidation cannot be used together. This is why your `sanityFetch` function is configured to ignore the `revalidate` parameter if `tags` are provided.
In this lesson, you'll remove time-based revalidation from your existing queries instead of tag-based. You now know how to implement time and path-based revalidation in the future for instances where it is applicable.
## Tag your queries
When performing a fetch, `tags` can be an array of strings of any value. It's a standard convention to use the Sanity document types expected to be in the response.
For the posts index, add tags for the three document types that provide data for the response. If any documents of these types change, you'll want to revalidate any page that renders them.
1. **Update** your fetch in the post-index route
```typescript:src/app/(frontend)/posts/page.tsx
const posts = await sanityFetch({
query: POSTS_QUERY,
tags: ['post', 'author', 'category'],
})
```
You can be more granular for an individual post page. You don't need to revalidate **every** post page because **one** has post changed. Thankfully, the dynamic route provides us with a unique identifier for this post—its slug—so you can use it for this page's cache tags.
1. **Update** your fetch in the post route
```typescript:src/app/(frontend)/posts/[slug]/page.tsx
const post = await sanityFetch({
query: POST_QUERY,
params,
tags: [`post:${params.slug}`, 'author', 'category'],
})
```
### Create an API route to revalidate tags
Once again, you will need to create an API route to accept a request from a GROQ-powered webhook and perform the revalidation.
1. **Create** a new API route for `revalidateTag`
```typescript:src/app/api/revalidate/tag/route.ts
import { revalidateTag } from 'next/cache'
import { type NextRequest, NextResponse } from 'next/server'
import { parseBody } from 'next-sanity/webhook'
type WebhookPayload = {
tags: string[]
}
export async function POST(req: NextRequest) {
try {
if (!process.env.SANITY_REVALIDATE_SECRET) {
return new Response(
'Missing environment variable SANITY_REVALIDATE_SECRET',
{ status: 500 },
)
}
const { isValidSignature, body } = await parseBody<WebhookPayload>(
req,
process.env.SANITY_REVALIDATE_SECRET,
true,
)
if (!isValidSignature) {
const message = 'Invalid signature'
return new Response(JSON.stringify({ message, isValidSignature, body }), {
status: 401,
})
} else if (!Array.isArray(body?.tags) || !body.tags.length) {
const message = 'Bad Request'
return new Response(JSON.stringify({ message, body }), { status: 400 })
}
body.tags.forEach((tag) => {
revalidateTag(tag)
})
return NextResponse.json({ body })
} catch (err) {
console.error(err)
return new Response((err as Error).message, { status: 500 })
}
}
```
1. If you wish to delay the revalidation due to the Sanity CDN, include the third argument in `parseBody`, highlighted above.
## Create a webhook
1. Instructions for how to test webhooks during local development are in the previous lesson: [Path-based revalidation](https://www.sanity.io/learn/course/controlling-cached-content-in-next-js/path-based-revalidation)
Once again, we have prepared a webhook template for your Project. It has most of the settings preconfigured. You'll just need to update a few that are unique to you:
1. **Open** this [tag revalidation webhook template](https://www.sanity.io/manage/webhooks/share?name=Tag-based%20Revalidation%20Hook%20for%20Next.js%2015&description=&url=https%3A%2F%2FYOUR-PRODUCTION-URL.TLD%2Fapi%2Frevalidate%2Ftag&on=create&on=update&on=delete&filter=_type%20in%20%5B%22post%22%2C%20%22author%22%2C%20%22category%22%5D&projection=%7B%22tags%22%3A%20%5B_type%2C%20_type%20%2B%20%22%3A%22%20%2B%20slug.current%5D%7D&httpMethod=POST&apiVersion=v2021-03-25&includeDrafts=&headers=%7B%7D)
2. **Update** the URL to use your ngrok URL
3. **Click** "Apply Webhook" and select your project, apply to all datasets
4. **Click** "Edit Webhook" on the next screen, scroll to the bottom, and add the same "Secret" you added to your `.env` file
5. **Click** "Save"
You're now ready to automatically revalidate your posts index and individual post pages in your web application simply by changing a `post`, `author`, or `category` document in Sanity Studio.
1. According to the Next.js documentation, `revalidateTag` only invalidates the cache when the path is _next_ visited. This means calling `revalidateTag` with a dynamic route segment will not immediately trigger many revalidations at once.
## Test it out
1. If you still have the path-based revalidation webhook enabled, disable it in Manage.
With all the machinery in place, you can test that what you've set up works.
1. **Visit** the post index page at [http://localhost:3000/posts](http://localhost:3000/posts), and check the terminal first to ensure it was a cache `HIT`.
If it is a cache `MISS`, reload the page, and you should see it cached for the next request.
1. **Open** any `category` or `author`-type document within your Sanity Studio at [http://localhost:3000/studio](http://localhost:3000/studio), change any field and publish.
Almost instantly after publishing, in your terminal you should see a `POST` request which was automatically made from the GROQ-powered webhook:
```text
POST /api/revalidate/tag 200 in 3540ms
```
1. **Reload** the same individual post page again.
If you reload the page again, it should be cached for the next request. You should see a cache `MISS` in the terminal, your updated title on the post-index and the individual post page.
1. Are you still seeing stale data? The previous lesson includes instructions on how to mitigate the time between a webhook firing and the CDN being repopulated: [Path-based revalidation](https://www.sanity.io/learn/course/controlling-cached-content-in-next-js/path-based-revalidation)
With that, you're all cached up with somewhere to go. Let's review it in the final lesson.## [Quiz to win cache prizes](/learn/course/controlling-cached-content-in-next-js/conclusion)
Let's review what you've learned about caching and balancing the content you have with the people it serves.
With all these lessons completed, your application now only has one caching strategy: tag-based revalidation. It's a good one, but as your application grows, it may not be so one-sided.
Individual pages with slow-moving content and few connections may benefit from long revalidation times and path-based revalidation, as well as content such as terms and conditions, or help pages.
Connected content where many document types are joined together with references will continue to benefit from tag-based revalidation.
When to query the Sanity API or CDN is also situation dependent as well. You should be able to query the CDN most of the time. But in situations where requests are only made infrequently—or demand freshness—querying the API sparingly can still be useful.
To test what you've learned, let's take a brief quiz:
**Question:** Caching impacts business users because
1. Time is money
2. It directly ties to bandwidth and server costs
3. Cache performance is their favorite KPI
4. Caching strategies impact tax liability
**Question:** Caching impacts content authors because
1. It's their favorite thing to consider while authoring
2. They typically have strong opinions on Varnish
3. They'd like to see the impact of their published changes immediately
4. They expect manual control over caching configuration
**Question:** Caching impacts end users because:
1. They have strong opinions on database caching
2. They prioritize fast and accurate content
3. They appreciate cache-control headers deeply
4. They're famously patient
**Question:** Time-based revalidation is
1. Only available on paid plans
2. Impossible to set up
3. Simple and okay
4. Complex and not recommended
**Question:** Path-based revalidation is
1. Able to revalidate dynamic paths
2. Able to revalidate the entire layout
3. Able to revalidate static paths
4. All the above
**Question:** Tag-based revalidation is
1. Ideal for connected content
2. Ideal for single pages
3. Impossible
4. Required
**Question:** GROQ-powered webhooks fire
1. When the Sanity CDN is refreshed
2. When manually triggered
3. When a mutation is performed on a dataset
4. When a page refreshes# [Testing Sanity Studio](/learn/course/testing-sanity-studio)
Learn to balance test coverage with development velocity while protecting the critical operations that power your Content Operating System. Establish automated testing strategies, document business requirements in executable code, and enable confident iteration. From validation logic to React components, develop an intentional testing strategy that ensures reliability and enables you to ship Studio changes with confidence.
## [Why Testing Matters for Studio Development](/learn/course/testing-sanity-studio/why-testing-matters-for-studio-development)
Testing isn't just quality assurance—it's strategic infrastructure that protects your business logic and enables rapid iteration. Understand how tests document requirements in executable code, provide confidence before changes reach content editors, and free your team to move faster. Learn what makes Studio customizations worth testing and how to think about testing as an investment in long-term velocity.
This course takes an incremental approach to writing tests, starting with validation and access control logic, then progressing to more complex React components that interact with Studio's APIs. This building-block approach helps you establish a solid foundation of test coverage that grows with your Studio's complexity.
## What you'll build
By the end of this course, you'll have a complete test suite for a real Sanity Studio that manages events, artists, and venues. You'll test:
* **Validation and access control logic** - Permission checks and business rules
* **Validation logic** - Custom schema validation rules
* **React components** - Custom input components with Sanity hooks
* **Integration workflows** - CI/CD pipelines that run tests automatically
Upon completing this course, you'll be able to:
* Set up Vitest in a Sanity Studio project
* Write tests for validation and access control functions
* Test async validation functions with mocked clients
* Create reusable test fixtures for consistent mocking
* Test React components that use Sanity UI and Studio APIs
* Implement automated testing in GitHub Actions
* Make strategic decisions about what to test and when
## The strategic case for testing
Testing is an investment. It takes time to write tests, configure testing tools, and maintain test suites. But this upfront investment pays dividends:
**For solo developers:**
* Catch bugs before they reach production
* Refactor with confidence
* Document your intent for future you
**For teams:**
* Enable multiple developers to work simultaneously without breaking each other's code
* Onboard new team members faster with executable documentation
* Review pull requests more efficiently when tests verify behavior
**For AI-assisted development:**
* Tests provide clear specifications of expected behavior
* AI agents can understand your business logic through test descriptions
* Automated refactoring becomes safer when tests guard against regressions
When code becomes commodity through AI assistance, your specifications—documented in tests—become your competitive advantage.## [Setting Up Your Testing Environment](/learn/course/testing-sanity-studio/setting-up-your-testing-environment)
Configure Vitest as your testing framework and integrate it into your Studio development workflow. Set up test environments for both monorepo and single-app configurations, understand how testing fits into your build process, and write your first test. Learn the fundamentals of test structure, assertions, and organizing test files alongside the code they verify.
In this lesson, you'll set up a testing environment using Vitest and understand why testing is a strategic investment for your Sanity Studio.
## Why test your Studio?
With Sanity's code-first architecture, your Studio is configured through the code you write—custom inputs, validation functions, preview configuration, formatting helpers, and other business logic. Testing this code before it reaches Studio gives you confidence that your changes won't break the editing experience.
When you write tests for your Studio code, you're not checking that it runs—you're encoding your team's business requirements and design decisions. Tests become documentation of how your Studio should work, written in code that can verify itself.
Consider a concert venue booking system. If you write a validation rule that certain event types must have a venue, a test ensures this rule works correctly:
* When a concert event has no venue, validation fails with a helpful message
* When a livestream event has no venue, validation passes (it doesn't need one)
* When someone modifies the validation logic later, the test catches breaking changes
This is powerful when developing new features: write tests that describe the expected behavior first, then implement the code that makes them pass. Tests become executable specifications that document your business logic.
## Testing integrates into your workflow
Testing fits into your development workflow at multiple points:
* **During local development** - Watch mode provides instant feedback as you write code
* **In pull requests** - Automated CI runs validate changes before code review
* **Before deployment** - Tests ensure your changes won't disrupt content editors
By implementing a testing strategy, you can iterate on your Studio with confidence, knowing that your custom inputs, schema helpers, and validation functions are covered by tests.
## Setting up Vitest
[Vitest](https://vitest.dev) is a modern testing framework designed for TypeScript projects. It provides a fast, developer-friendly experience with instant feedback through watch mode.
### Monorepo configuration
This repository is a monorepo with multiple apps (`apps/studio`, `apps/tickets`, `apps/web`). Vitest's workspace feature lets you run tests across all apps from the root, or target individual apps.
First, install Vitest at the root level:
```sh
pnpm add -D vitest -w
```
The `-w` flag installs to the workspace root, making Vitest available to all packages.
Create a `vitest.config.ts` file at the repository root:
```typescript:vitest.config.ts
import {defineConfig}from 'vitest/config'
export default defineConfig({
test: {
// Automatically discover test configs in all apps
projects: ['apps/*'],
},
})
```
This tells Vitest to look for test configurations in each app directory. Each app can have its own specialized config.
1. Working with a standalone Studio app instead of in a monorepo? You can skip the workspace configuration and use `defineConfig()` directly in your Studio's `vitest.config.ts`.
### Studio app test configuration
Now create `apps/studio/vitest.config.ts`:
```typescript:apps/studio/vitest.config.ts
import {defineProject} from 'vitest/config'
export default defineProject({
test: {
name: 'studio',
include: ['**/*.test.ts'],
environment: 'node',
},
})
```
Notice we use `defineProject()` instead of `defineConfig()`. This provides better type checking for workspace projects. The `name: 'studio'` is required—Vitest needs unique names for each project.
Add test scripts in the root `package.json`:
```json:package.json
{
"scripts": {
"test": "vitest",
}
}
```
Now you can run tests from the root (all apps) or run individual app tests.
## Your first test
Let's write a simple test to verify your setup works. Create a test file at `apps/studio/example.test.ts`:
```typescript:apps/studio/example.test.ts
import {describe, it, expect} from 'vitest'
describe('Vitest setup', () => {
it('runs basic assertions', () => {
expect(2 + 2).toBe(4)
})
it('handles string comparisons', () => {
const greeting = 'Hello, Sanity'
expect(greeting).toContain('Sanity')
})
it('validates arrays', () => {
const events = ['concert', 'livestream', 'exhibition']
expect(events).toHaveLength(3)
expect(events).toContain('concert')
})
})
```
This test file demonstrates the basic structure:
* **`describe`** - Groups related tests together (think of it as a container)
* **`it`** - Defines an individual test case (read it as "it should...")
* **`expect`** - Makes assertions about values (this is where actual testing happens)
Run the tests. Since we're in a monorepo, you have multiple options:
```sh
# From the repository root - runs all tests in all apps
pnpm test
# From the root - run only Studio tests
pnpm test --project=studio
```
For now, the simplest approach is to run from the root with `pnpm test`.
1. Create the `apps/studio/example.test.ts` file with the code above and run `pnpm test` to verify your setup works.
You should see output indicating all three tests passed. Vitest enters watch mode, waiting for file changes to rerun tests automatically.
### The arrange-act-assert pattern
Each test follows a three-step pattern:
1. **Arrange** - Set up the data and conditions
2. **Act** - Execute the code being tested
3. **Assert** - Verify the result matches expectations
1. The arrange-act-assert pattern works great for [Test-Driven Development (TDD)](https://en.wikipedia.org/wiki/Test-driven_development). Write the test first (it fails), implement the code (it passes), then refactor with confidence.
Here's an example with the event domain:
```typescript
describe('Event type classification', () => {
it('identifies concerts as venue-required events', () => {
// Arrange
const eventType = 'concert'
const venueRequiredTypes = ['concert', 'exhibition']
// Act
const requiresVenue = venueRequiredTypes.includes(eventType)
// Assert
expect(requiresVenue).toBe(true)
})
})
```
This pattern keeps tests readable and maintainable. When a test fails, you can quickly identify which stage failed.
## What to test (and what not to test)
Not everything needs a test. Focus on code that contains business logic or could break in surprising ways:
**Write tests for:**
* Validation functions that enforce business rules
* Helper functions that transform or format data
* Custom input components with complex interactions
* Preview configurations that shape how content appears
**Don't test:**
* Simple field definitions with no logic
* Third-party library code (assume it's tested)
* Trivial getters and setters with no transformation
For this events Studio, high-value tests would cover:
* Validation: "Concert events must have a venue, livestream events don't"
* Date logic: "Doors open time calculates correctly from event date"
* URL validation: "Ticket URLs must be valid HTTPS URLs"
## Watch mode: your testing companion
Leave `pnpm test` running while you develop. Vitest watches your files and automatically reruns affected tests when you save changes.
Try modifying your test file—change an assertion to make it fail:
```typescript
expect(2 + 2).toBe(5)
```
Vitest immediately detects the change and shows you the failure. Change it back to `4` and the tests pass again. This instant feedback loop helps you catch errors early and iterate quickly.
1. With watch mode running, modify the test to make it fail, then fix it. Observe how Vitest automatically reruns tests on file changes.
## Next steps
You now have a working test environment and understand why testing is a strategic investment for Studio development. You've set up Vitest in a monorepo configuration with workspace projects, learned the basic structure of tests with `describe`, `it`, and `expect`, and discovered how watch mode provides instant feedback as you develop. You also know what types of code are worth testing—validation functions, helper utilities, and custom components with business logic—versus what to skip, like simple field definitions with no logic. In the next lesson, you'll test validation logic and access control rules from the events Studio, building confidence with real-world examples.
1. Think about one validation function or helper in your own Studio that would benefit from testing. You'll write tests for it as you progress through this course.
In the next lesson, you'll test validation logic and access control rules from the events Studio, building confidence with real-world examples.## [Testing Validation and Access Control](/learn/course/testing-sanity-studio/testing-validation-and-access-control)
Start with the simplest testing scenario: functions with no external dependencies or side effects. Test access control logic that determines who can edit fields, validation functions that enforce business rules, and utility functions that transform data. These isolated functions are straightforward to test and often contain critical business logic that protects content quality across your organization.
In this lesson, you'll test validation logic and access control rules from the events Studio—functions with no external dependencies that are straightforward to test.
## Why start with isolated functions?
A "pure" function is predictable and isolated:
* **Same inputs always produce same outputs** - No randomness or hidden state
* **No side effects** - Doesn't modify external state, make API calls, or change files
* **Easy to test** - Pass inputs, verify outputs, done
Functions with no external dependencies are the easiest place to start testing because they require no mocks, no setup, and no teardown. The function is completely self-contained.
## Testing validation and access control
The Studio includes access control logic that determines who can edit certain fields. The slug field has a rule: anyone can set the initial slug, but only administrators can change it once set:
```typescript:apps/studio/helpers.ts
import type {CurrentUser} from 'sanity'
/**
* Determines if the current user can edit a slug field
* Only administrators can edit existing slugs
*/
export function canEditSlug(user?: Omit<CurrentUser, 'role'> | null): boolean {
return user?.roles.some((role) => role.name === 'administrator') ?? false
}
```
1. Learn more about Sanity's role-based access control in [Users, roles and using roles](https://www.sanity.io/learn/course/introduction-to-users-and-roles)
This function is pure: given a user object, it returns whether they have admin privileges. No API calls, no state changes, no external dependencies.
To ensure this pure helper function matches our business logic, we should test the following scenarios:
1. **Admin user** - Has administrator role (should return `true`)
2. **Regular user** - Has non-admin role like editor (should return `false`)
3. **Multiple roles** - User with both editor and admin roles (should return `true`)
4. **Null user** - No user logged in (should return `false`)
5. **Empty roles** - User exists but has no roles assigned (should return `false`)
```typescript:apps/studio/helpers.test.ts
import {describe, it, expect} from 'vitest'
import type {CurrentUser} from 'sanity'
import {canEditSlug} from './helpers'
describe('canEditSlug', () => {
it('allows administrators to edit slugs', () => {
const adminUser: Omit<CurrentUser, 'role'> = {
id: 'admin-user',
name: 'Admin User',
email: 'admin@example.com',
roles: [{name: 'administrator', title: 'Administrator'}],
}
expect(canEditSlug(adminUser)).toBe(true)
})
it('prevents non-admin users from editing slugs', () => {
const regularUser: Omit<CurrentUser, 'role'> = {
id: 'regular-user',
name: 'Regular User',
email: 'user@example.com',
roles: [{name: 'editor', title: 'Editor'}],
}
expect(canEditSlug(regularUser)).toBe(false)
})
it('handles users with multiple roles', () => {
const multiRoleUser: Omit<CurrentUser, 'role'> = {
id: 'multirole-user',
name: 'Multi-role User',
email: 'multi@example.com',
roles: [
{name: 'editor', title: 'Editor'},
{name: 'administrator', title: 'Administrator'},
],
}
expect(canEditSlug(multiRoleUser)).toBe(true)
})
it('prevents access when user is `null`', () => {
expect(canEditSlug(null)).toBe(false)
})
it('prevents access when user has no roles', () => {
const userWithoutRoles: Omit<CurrentUser, 'role'> = {
id: 'no-roles',
name: 'No Roles',
email: 'noroles@example.com',
roles: [],
}
expect(canEditSlug(userWithoutRoles)).toBe(false)
})
})
```
Run the tests from the root with `pnpm test`. All tests should pass.
This approach ensures the permission check works correctly for all possible user states, protecting your content from unauthorized edits.
## Testing validation and access control
Another example might be the IANA tags that you might use to localize your content:
```typescript:apps/studio/validation.ts
import type {StringRule} from 'sanity'
/**
* IANA language tag pattern (BCP 47)
* @see https://en.wikipedia.org/wiki/IETF_language_tag
*
* Supports formats like:
* - en (2-letter language code)
* - en-US (language + region)
* - zh-Hant-TW (language + script + region)
* - en-US-x-private (with private use extensions)
*/
export const LANGUAGE_TAG_PATTERN =
/^[a-z]{2,3}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|\d{3}))?(?:-[a-zA-Z0-9]{5,8}|-[0-9][a-zA-Z0-9]{3})*$/
/**
* Validation function for IANA language tags (BCP 47 format)
*
* @example
* ```ts
* defineField({
* name: 'language',
* type: 'string',
* validation: validateLanguageTag
* })
* ```
*/
export const validateLanguageTag = (rule: StringRule): StringRule =>
rule.regex(LANGUAGE_TAG_PATTERN, {
name: 'IANA language tag',
})
```
1. This example uses [TSDoc](https://typedoc.org/)-style comments to annotate and provide at-a-glance, inline documentation when hovering over definitions.
Our test suite for this validation might look something like:
```typescript:apps/studio/validation.test.ts
import {describe, it, expect} from 'vitest'
import {LANGUAGE_TAG_PATTERN} from './validation'
describe('LANGUAGE_TAG_PATTERN', () => {
it('matches valid language tags (real-world examples)', () => {
// Simple language codes (most common)
expect(LANGUAGE_TAG_PATTERN.test('en')).toBe(true) // English
expect(LANGUAGE_TAG_PATTERN.test('fr')).toBe(true) // French
expect(LANGUAGE_TAG_PATTERN.test('ja')).toBe(true) // Japanese
expect(LANGUAGE_TAG_PATTERN.test('nan')).toBe(true) // Min Nan Chinese (3-letter ISO 639-3)
// Language + Region (localization)
expect(LANGUAGE_TAG_PATTERN.test('en-US')).toBe(true) // US English
expect(LANGUAGE_TAG_PATTERN.test('en-GB')).toBe(true) // British English
expect(LANGUAGE_TAG_PATTERN.test('fr-CA')).toBe(true) // Canadian French
expect(LANGUAGE_TAG_PATTERN.test('es-419')).toBe(true) // Latin American Spanish (UN M.49 numeric code)
})
it('rejects common mistakes', () => {
// Case errors (most common mistake)
expect(LANGUAGE_TAG_PATTERN.test('EN')).toBe(false) // Language must be lowercase
expect(LANGUAGE_TAG_PATTERN.test('en-us')).toBe(false) // Region must be uppercase (en-US)
expect(LANGUAGE_TAG_PATTERN.test('zh-hant')).toBe(false) // Script must be Title Case (zh-Hant)
expect(LANGUAGE_TAG_PATTERN.test('zh-HANT')).toBe(false) // Script cannot be all caps
// Wrong separator
expect(LANGUAGE_TAG_PATTERN.test('en_US')).toBe(false) // Must use hyphen, not underscore
expect(LANGUAGE_TAG_PATTERN.test('en.US')).toBe(false) // Must use hyphen, not period
// Using full names instead of codes
expect(LANGUAGE_TAG_PATTERN.test('english')).toBe(false) // Must use ISO code 'en', not full name
expect(LANGUAGE_TAG_PATTERN.test('English')).toBe(false)
// Wrong region code length
expect(LANGUAGE_TAG_PATTERN.test('en-USA')).toBe(false) // Region must be 2 letters, not 3
expect(LANGUAGE_TAG_PATTERN.test('en-U')).toBe(false) // Region cannot be 1 letter
// Confusing region with script
expect(LANGUAGE_TAG_PATTERN.test('zh-CN')).toBe(true) // Valid but ambiguous - prefer zh-Hans
expect(LANGUAGE_TAG_PATTERN.test('zh-TW')).toBe(true) // Valid but ambiguous - prefer zh-Hant
})
})
```
These functions exhibit a key trait: they're completely isolated. No API calls, no database queries, no React hooks. This makes them fast to test and easy to verify. Pure function tests require no special setup—no providers, no mocks, no configuration. This simplicity makes them an excellent starting point for your testing strategy.
More importantly though, these pure functions often form the foundation of critical business rules in your Sanity Studio. Validation functions ensure data integrity, formatting utilities maintain consistency, and helper functions encapsulate important domain logic. By thoroughly testing these functions, you're safeguarding the core rules that protect your content quality.
## Next steps
You've tested validation and access control logic—permission logic with edge cases like admin checks and null handling and IANA tag validation.
Next you'll test functions that need more context—validation rules that query Sanity's Content Lake to enforce business logic. You'll learn to mock Sanity client, create reusable fixtures, and build a testing harness for async validation logic.## [Testing Stateful Studio Logic](/learn/course/testing-sanity-studio/testing-stateful-studio-logic)
Test validation functions that query your Content Lake to verify business rules across documents. Learn to mock the Sanity client to create controlled test scenarios, build reusable test fixtures that simplify setup, and verify async validation logic that prevents invalid content states. Understand how to test functions that depend on external data without requiring a populated dataset.
In this lesson, you'll test validation functions that need context—rules that query your Content Lake to check conditions across multiple documents.
The validation logic you tested in the previous lesson worked in isolation: it took a user as input and returned a boolean to determine access control. But some business rules require checking other documents in your dataset.
Consider validation that depends on dataset state:
* _"Only one event can be featured at a time"_ (needs to check if others are featured)
* _"Artist cannot have overlapping performances"_ (needs to check other event dates)
These validations need to query Content Lake. To test them, you'll mock the Sanity client and validation context, creating reusable fixtures that keep your tests clean and focused on business logic.
## Testing stateful validation functions
Event companies need to promote one event above others—the "featured" event appears on the homepage, gets social media promotion, and drives ticket sales. Only one event can be featured at a time.
This business rule needs enforcement at the data layer. If two events are featured simultaneously, the homepage breaks and marketing campaigns become confused.
```typescript:apps/studio/validation.ts
import {
DEFAULT_STUDIO_CLIENT_OPTIONS,
getPublishedId,
type BooleanRule,
type ValidationBuilder,
type ValidationContext,
} from 'sanity'
/**
* Checks if setting this event as featured would result in a single featured event
* Business logic function that queries the dataset for other featured events
*/
export async function isSingleFeaturedEvent(
value: boolean | undefined,
context: ValidationContext,
): Promise<boolean> {
// If not setting to featured, no need to check
if (!value) return true
const {getClient, document} = context
if (!document) {
throw new Error('Document context required for validation')
}
const client = getClient(DEFAULT_STUDIO_CLIENT_OPTIONS)
const documentId = getPublishedId(document._id)
// Query for other featured events (excluding this document's versions)
const existingFeatured = await client.fetch<boolean>(
`defined(*[_type == "event" && featured == true && !sanity::versionOf($documentId)][0]._id)`,
{documentId},
{tag: 'validation.single-featured-event', perspective: 'raw'},
)
// Return true if no other featured event exists
return !existingFeatured
}
/**
* Validation builder for the featured field
* Ensures only one event can be featured at a time
*
* @example
* ```ts
* defineField({
* name: 'featured',
* type: 'boolean',
* validation: validateSingleFeaturedEvent
* })
* ```
*/
export const validateSingleFeaturedEvent: ValidationBuilder<BooleanRule, boolean> = (rule) =>
rule.custom(async (value, context) => {
if (await isSingleFeaturedEvent(value, context)) {
return true
}
return 'Only one event can be featured at a time'
})
```
There is a clean separation between the testable business logic function (`isSingleFeaturedEvent`), which returns a boolean indicating validity, and the validation builder that wraps it with the error message.
## Understanding mocking
When testing functions with external dependencies, you need a controlled environment where you can verify behavior without relying on external systems. **Mocking** creates this test "harness" by replacing real dependencies with controlled test doubles that you configure precisely for each test scenario.
A mock is a fake implementation that mimics the behavior of a real object. You control what the mock returns, letting you simulate different scenarios without needing the real dependency. Mocks also track how they're called—which methods were invoked, with what arguments, and how many times—letting you verify your code interacts with dependencies correctly.
For validation functions that query Sanity's Content Lake, you'll mock the Sanity client's `fetch()` method. Instead of running actual database queries, the mock returns predefined values you specify. This lets you test scenarios like "no featured events exist" or "another event is already featured" without populating a real dataset. The tests run in milliseconds instead of seconds, and always produce the same results regardless of what data exists in your actual Content Lake.
1. Mocks let you test business logic in isolation. You're verifying your code's behavior, not testing that Sanity's client works (we do that for you).
## Creating test fixtures
Testing our various stateful functions requires setup—mock clients, mock contexts, test data. Rather than recreate this setup in every test, you'll use **fixtures**: reusable building blocks that encapsulate common test setup patterns.
A fixture is a function that creates consistent test data or dependencies. Instead of writing the same mock setup repeatedly, you call a fixture function that handles the details. This keeps tests focused on what's unique (the scenario being tested) rather than boilerplate (how to create a mock client).
First let's create a client fixture will be reused across all validation tests, ensuring consistency and reducing repetitive code:
```typescript:apps/studio/__tests__/fixtures/client.ts
import {test as base, vi, type Mock} from 'vitest'
import type {SanityClient} from 'sanity'
type MockSanityClient = SanityClient & {
fetch: Mock
}
/**
* Helper function to create a mock Sanity client
* Use this when you need a client outside of the test fixture
*
* @example
* ```tsx
* const mockClient = createMockClient()
* mockClient.fetch.mockResolvedValue({...})
* vi.mocked(useClient).mockReturnValue(mockClient)
* ```
*/
export function createMockClient(): MockSanityClient {
return {
fetch: vi.fn(),
} as unknown as MockSanityClient
}
/**
* Mock Sanity client fixture
*
* Provides a mocked Sanity client for testing components that use useClient().
* The client has a mocked fetch() method that can be configured per-test.
*
* @example
* ```tsx
* import {test, expect} from '@/__tests__/fixtures/client'
*
* test('fetches data', async ({mockClient}) => {
* mockClient.fetch.mockResolvedValue({_id: '123', title: 'Test'})
*
* // Your test code here
* })
* ```
*/
export const test = base.extend<{
mockClient: MockSanityClient
}>({
// eslint-disable-next-line no-empty-pattern
async mockClient({}, use) {
// eslint-disable-next-line react-hooks/rules-of-hooks
await use(createMockClient())
},
})
```
1. The `mockClient` fixture will be reused across all validation tests in this course and beyond. Investing in good fixtures pays off quickly.
This fixture extends Vitest's base `test` function with a `mockClient` property. Each test automatically gets a fresh mock client, preventing tests from interfering with each other. The fixture pattern keeps test setup minimal while ensuring consistency.
Now let's test our stateful validation function using our `mockClient` fixture as well as some locally defined ones:
```typescript:apps/studio/validations.test.ts
import {describe, expect} from 'vitest'
import type {ValidationContext, ID} from 'sanity'
import {isSingleFeaturedEvent} from '../helpers'
import {it} from './__tests__/fixtures/client'
describe('isSingleFeaturedEvent', () => {
// Local helper - creates mock event document
const createMockEventDocument = (id: ID) => ({
_id: id,
_type: 'event',
_createdAt: '2025-01-01T00:00:00Z',
_updatedAt: '2025-01-01T00:00:00Z',
_rev: 'mock-rev',
})
// Local fixture - creates validation context for featured event tests
const createValidationContext = ({documentId, client}: {documentId: string; client: any}) =>
({
getClient: () => client,
document: createMockEventDocument(documentId),
path: ['featured'],
}) as unknown as ValidationContext
it('returns `true` when no other featured event exists', async ({mockClient}) => {
mockClient.fetch.mockResolvedValue(false) // No existing featured event
const context = createValidationContext({documentId: 'event-1', client: mockClient})
expect(await isSingleFeaturedEvent(true, context)).toBe(true)
})
it('returns `false` when another event is already featured', async ({ mockClient }) => {
mockClient.fetch.mockResolvedValue(true) // Another event is featured
const context = createValidationContext({documentId: 'event-2', client: mockClient})
expect(await isSingleFeaturedEvent(true, context)).toBe(false)
})
it('returns true when unsetting featured (no query needed)', async ({ mockClient }) => {
const context = createValidationContext({documentId: 'event-3', client: mockClient})
expect(await isSingleFeaturedEvent(false, context)).toBe(true)
// Should not query when value is false
expect(mockClient.fetch).not.toHaveBeenCalled()
})
it('queries with correct parameters and excludes document versions', async ({ mockClient }) => {
mockClient.fetch.mockResolvedValue(false)
const documentId = getDraftId('event-4')
const context = createValidationContext({documentId, client: mockClient})
await isSingleFeaturedEvent(true, context)
expect(mockClient.fetch).toHaveBeenCalledWith(
expect.any(String),
expect.objectContaining({documentId: getPublishedId(documentId)}), // Published ID, not draft
expect.objectContaining({tag: 'validation.single-featured-event', perspective: 'raw'}),
)
})
})
```
1. Validation functions that query your Content Lake are async by nature. All your test functions will need to be asynchronous and use `await` when calling these validators.
### Understanding the test strategy
The local helper functions (`createMockEventDocument`, `createContext`) keep test setup close to the tests that use them. While `createMockClient()` is imported from fixtures (reusable across all tests), the validation context helper is specific to featured event validation—it knows about the `event` type and `featured` path.
This pattern balances reusability with specificity:
* **Global fixtures** - Broadly useful (mock clients)
* **Local helpers** - Test-suite specific (event documents, featured field context)
These four tests verify the business logic returns correct booleans:
1. **No existing featured event** → Returns `true` (can set featured)
2. **Existing featured event** → Returns `false` (cannot set featured)
3. **Unsetting featured** → Returns `true` without querying (performance)
4. **Correct query** → Verifies GROQ uses published IDs and tags
By testing the business logic function, we verify the core decision-making. The validation builder just wraps this with an error message—that's simple enough to trust without testing.
## Why this validation matters
Validation functions that query your dataset might have more moving parts than pure functions—async operations, client queries, document ID handling—but they're equally critical to test. The complexity makes them more fragile and the business impact makes them more important:
**Without this test:**
* Refactor the query → accidentally allow multiple featured events
* Change the document ID logic → validation blocks the wrong documents
* Remove the early return → unnecessary queries slow down the editor
**With this test:**
* Query changes break tests immediately
* Document ID handling is verified
* Performance optimizations are protected
This is the kind of business logic that justifies test investment. A broken featured event selector means confused marketing, broken homepage, and lost ticket sales.
## Next steps
You've learned to test validation functions that query your Content Lake to enforce business rules. By creating a reusable mock client fixture and test-specific local helpers for validation contexts, you've built a testing harness that keeps tests focused on business logic rather than setup boilerplate. You now know how to test async validation with controlled mock return values, verify that queries use correct parameters, and protect performance optimizations with assertions that functions don't query unnecessarily. These patterns work for any validation rule that accesses document state or queries your Content Lake to check conditions across multiple documents.
In the next lesson, you'll test custom input components that render UI, use Sanity hooks, and handle user interactions. You'll learn to set up a browser-like test environment and simulate real user behavior.## [Testing Studio React Components](/learn/course/testing-sanity-studio/testing-studio-react-component)
Test custom input components that render UI, use Studio hooks, and handle user interactions. Configure a browser-like test environment with React Testing Library, create provider fixtures that supply Studio context, and verify component behavior through simulated user actions. Learn what aspects of components are worth testing and how to balance thorough coverage with maintainable tests.
The validation logic and access control functions you've tested so far run in Node.js with no UI. Custom input components are different—they render DOM elements, depend on Sanity UI's theming context, use Studio hooks like `useFormValue` and `useClient`, and respond to user interactions. Testing these components requires a browser-like environment, provider setup for Sanity UI, and tools to simulate user behavior like clicks and typing.
Testing components verifies not just that your code runs, but that content editors can successfully interact with your custom inputs. A permission check might pass its pure function test but fail when integrated into a component's `readOnly` callback. A date calculation might work in isolation but render incorrectly when formatted for display. Component tests catch these integration issues by exercising the full user interaction flow.
## Setting up the component testing environment
Install React Testing Library and `jsdom`:
```sh
pnpm add -D @testing-library/react @testing-library/user-event jsdom @testing-library/jest-dom
```
These packages provide:
* **`jsdom`** - A browser environment implementation for Node.js
* **@testing-library/react** - Utilities for rendering and querying React components
* **@testing-library/user-event** - Functions that simulate realistic user interactions
* **@testing-library/jest-dom** - Additional matchers for DOM testing
1. `jsdom` simulates a browser environment in Node.js. It's not a real browser, so some browser-specific features (like layout calculations) won't work. For most Studio components, `jsdom` is sufficient.
## Configuring multiple test environments
Your test suite now has different needs: pure functions run in Node, React components need a browser environment.
Update `apps/studio/vitest.config.ts` to define **test-type projects** (not to be confused with workspace projects):
```typescript:apps/studio/vitest.config.ts
import {defineProject} from 'vitest/config'
export default defineProject({
test: {
name: 'studio',
// Define test-type projects within the Studio workspace project
projects: [
{
test: {
name: 'unit',
environment: 'node',
include: ['**/*.test.ts'],
},
},
{
test: {
name: 'component',
environment: 'jsdom',
include: ['**/*.test.tsx'],
setupFiles: ['./__tests__/setup.ts'],
},
},
],
},
})
```
1. **Important:** Vitest requires unique project names across your entire workspace. If you add other workspace projects, you may need to adjust the naming convention.
And we'll need to create the setup file for the component test suite:
```typescript:apps/studio/__tests__/setup.ts
import {cleanup} from '@testing-library/react'
import {afterEach} from 'vitest'
import '@testing-library/jest-dom/vitest'
afterEach(() => {
cleanup()
})
```
1. Component tests are slower than unit tests because they render real DOM elements. This is why we separate them into different test projects with the `.test.tsx` extension.
This configuration creates **nested projects**:
1. **Workspace project** - `studio` (defined at root `vitest.config.ts` with `projects: ['apps/*']`)
2. **Test-type projects** - `unit` and `component` (defined within Studio's config)
The `component` project:
* Uses `jsdom` to provide DOM APIs that React needs
* Only runs files with `.test.tsx` extension (TypeScript with JSX)
* Runs a setup file before each test
## Creating provider fixtures
React components in Sanity Studio don't work in isolation—they expect certain contexts to exist. Sanity UI components read theme values from a `ThemeProvider` to render correctly (colors, spacing, typography). Without this provider, components throw errors or render incorrectly. Similarly, components that trigger toast notifications need a `ToastProvider`, and dialogs need a `LayerProvider` for z-index management.
In production, your Studio wraps everything with these providers automatically. In tests, you need to recreate this harness manually. Rather than wrap each component individually in every test, create a reusable fixture that provides all required contexts:
```tsx:apps/studio/__tests__/fixtures/providers.tsx
import {LayerProvider, ThemeProvider, ToastProvider} from '@sanity/ui'
import {defaultTheme} from 'sanity'
import {render, type RenderOptions} from '@testing-library/react'
import type {ReactElement} from 'react'
export function TestProviders({children}: {children: React.ReactNode}) {
return (
<ThemeProvider theme={defaultTheme}>
<ToastProvider>
<LayerProvider>{children}</LayerProvider>
</ToastProvider>
</ThemeProvider>
)
}
export function renderWithProviders(
ui: ReactElement,
options?: Omit<RenderOptions, 'wrapper'>
) {
return render(ui, {wrapper: TestProviders, ...options})
}
```
1. Start with these three providers for most Sanity UI components. Add more providers (like `FormBuilderProvider`) only when your components require them. Keep provider setup minimal.
The `TestProviders` component recreates the essential Studio provider hierarchy for these component tests:
* **`ThemeProvider`** - Provides theme values (colors, spacing, typography)
* **`ToastProvider`** - Enables toast notifications (some inputs use these)
* **`LayerProvider`** - Manages z-index stacking for dialogs and popovers
These are the providers the `DoorsOpenInput` component needs. Other custom components might require additional providers—like `FormBuilderProvider` for components that use form-level hooks, or custom context providers for specialized features. Add providers to `TestProviders` as your test suite requires them.
The `renderWithProviders()` helper wraps React Testing Library's `render()` function, automatically including these providers for every component test. This fixture becomes your test harness for Sanity UI components—call it instead of `render()` and components work as they would in production.
## Testing the `DoorsOpenInput` component
The `DoorsOpenInput` component shows when doors open based on the event date and a minutes-before value. It uses:
* `useFormValue` hook to read the event date
* `useClient` hook to access the Sanity client
* Custom logic to calculate and display the doors open time
## Testing the `DoorsOpenInput` component
The `DoorsOpenInput` component displays when doors open for an event, calculated from the event date and a minutes-before value:
```tsx:apps/studio/schemaTypes/components/DoorsOpenInput.tsx
import {getPublishedId, type NumberInputProps, useClient, useFormValue} from 'sanity'
import {Stack, Text} from '@sanity/ui'
import {useEffect} from 'react'
// ..
export function DoorsOpenInput(props: NumberInputProps) {
const date = useFormValue(['date']) as string | undefined
const client = useClient({apiVersion: '2025-05-08'})
const documentId = useFormValue(['_id']) as string | undefined
// Query for document versions (demonstration purposes)
useEffect(() => {
if (!documentId) return
// ... query logic
}, [client, documentId])
return (
<Stack space={3}>
{props.renderDefault(props)}
{typeof props.value === 'number' && date ? (
<Text size={1}>
Doors open{' '}
{subtractMinutesFromDate(date, props.value).toLocaleDateString(undefined, {
month: 'long',
day: 'numeric',
year: 'numeric',
hour: 'numeric',
minute: 'numeric',
})}
</Text>
) : null}
</Stack>
)
}
```
The component uses Sanity hooks (`useFormValue`, `useClient`) to access form data and the Sanity client. Testing it requires mocking these hooks to control what values the component receives:
```tsx:apps/studio/schemaTypes/components/DoorsOpenInput.test.tsx
import {describe, it, expect, vi, beforeEach} from 'vitest'
import {screen} from '@testing-library/react'
import {useFormValue, useClient} from 'sanity'
import {renderWithProviders} from '../../../__tests__/fixtures/providers'
import {DoorsOpenInput} from './DoorsOpenInput'
// Mock Sanity hooks
vi.mock('sanity', async () => {
const actual = await vi.importActual('sanity')
return {
...actual,
useFormValue: vi.fn(),
useClient: vi.fn(),
}
})
describe('DoorsOpenInput', () => {
const mockProps = {
value: 60,
onChange: vi.fn(),
renderDefault: vi.fn((props) => <input type="number" {...props} />),
} as any
beforeEach(() => {
vi.clearAllMocks()
})
it('shows doors open time when date and value exist', () => {
vi.mocked(useFormValue).mockImplementation((path) => {
if (path[0] === 'date') return '2025-06-15T20:00:00Z'
if (path[0] === '_id') return 'event-1'
return undefined
})
vi.mocked(useClient).mockReturnValue({} as any)
renderWithProviders(<DoorsOpenInput {...mockProps} />)
expect(screen.getByText(/Doors open/i)).toBeInTheDocument()
expect(screen.getByText(/June/i)).toBeInTheDocument()
})
it('hides doors open time when date is missing', () => {
vi.mocked(useFormValue).mockImplementation((path) => {
if (path[0] === 'date') return undefined
if (path[0] === '_id') return 'event-2'
return undefined
})
vi.mocked(useClient).mockReturnValue({} as any)
renderWithProviders(<DoorsOpenInput {...mockProps} />)
expect(screen.queryByText(/Doors open/i)).not.toBeInTheDocument()
})
it('hides doors open time when value is missing', () => {
vi.mocked(useFormValue).mockImplementation((path) => {
if (path[0] === 'date') return '2025-06-15T20:00:00Z'
if (path[0] === '_id') return 'event-3'
return undefined
})
vi.mocked(useClient).mockReturnValue({} as any)
const propsWithoutValue = {...mockProps, value: undefined}
renderWithProviders(<DoorsOpenInput {...propsWithoutValue} />)
expect(screen.queryByText(/Doors open/i)).not.toBeInTheDocument()
})
})
```
1. Module mocks apply to the entire test file. If you need different mock behavior per test, use `mockImplementation()` in each test's setup rather than at the file level.
This test mocks the entire `sanity` module to control what `useFormValue` and `useClient` return:
1. **`vi.mock('sanity')`** - Intercepts all imports from the `sanity` package
2. **`vi.importActual()`** - Preserves original exports (types, utilities)
3. **`useFormValue: vi.fn()`** - Replaces hook with mock function
4. **`mockImplementation()`** - Controls what the hook returns based on the path argument
5. **`beforeEach()`** - Clears mocks between tests for isolation
The `mockImplementation()` function lets you return different values based on which form field is being accessed. When the component calls `useFormValue(['date'])`, the mock checks if `path[0] === 'date'` and returns the appropriate value. This pattern works for any component that reads multiple form fields through `useFormValue`.
## What to test in components
Focus on behavior that matters to content editors and enforced data integrity:
**Test:**
* Components render with expected content
* User interactions trigger correct callbacks
* Interactive components mutate documents accurately
* Accessibility attributes are present
**Don't test:**
* Implementation details (state variable names, hooks used)
* Sanity internals (we ensure test coverage for our own code)
* CSS styles and exact positioning
* Third-party library behavior (they should be testing it)
Custom inputs that modify documents deserve thorough testing. A bug in a read-only component might confuse an editor temporarily, but a bug in a component that writes data to the published document rather than the current draft would be a headache. Test these rigorously to ensure they write the correct values to the intended fields in the intended document.
1. Add a test that verifies the component calls `onChange` when the user modifies the input value. Use `userEvent.type()` to simulate typing.
## Next steps
You've learned to test React components in Sanity Studio:
* Setting up `jsdom` for browser-like testing
* Creating provider fixtures for Studio context
* Rendering components with React Testing Library
* Simulating user interactions with `userEvent`
* Mocking Sanity hooks like `useFormValue` and `useClient`
* Using accessible queries to find elements
In the next lesson, you'll integrate tests into GitHub Actions, implement coverage reporting, and develop a testing strategy that scales with your Studio.## [Continuous Integration and Test Strategy](/learn/course/testing-sanity-studio/continuous-integration-and-test-strategy)
Move tests from local development into CI pipelines that verify changes before they reach production. Configure automated test runs on pull requests, report test results directly in GitHub, and develop a strategic framework for deciding what to test. Learn to prioritize test coverage based on business impact, complexity, and change frequency—balancing protection with development velocity.
## From local development to production
You've been running tests locally with `pnpm test` in watch mode. This provides instant feedback while developing. But tests become more valuable when integrated into your workflow at key points:
* **Pull requests** - Automated checks prevent broken code from being merged
* **Before deployment** - Tests catch issues before they reach content editors
* **Scheduled runs** - Detect drift from dependencies or external changes
Running tests as part of your continuous integration (CI) ensures every code change is validated automatically, regardless of who wrote it or what they tested locally.
1. [Architecture & DevOps](https://www.sanity.io/learn/course/architecture-and-devops) covers setting up schema validation, linting, and preview deployments for your pull requests.
## Reporting test output in pull requests
When tests fail in CI, Vitest reports the failure(s) in your pull request. In Github, for example, failing pull requests will show:
* ❌ Red X next to the commit
* Detailed logs showing which tests failed
* Line numbers and error messages
* Option to re-run failed tests
This prevents merging broken code and makes code review more efficient. Reviewers can focus on logic and design, trusting that tests verify correctness.
## What is important to test?
Not all code is equally important to test. Prioritize based on:
### High priority - Always test
**Validation functions** - Protect data integrity
**Data transformation** - Shape content for display
**Critical business logic** - Features that could break revenue/experience
### Medium priority - Test when complex
**Custom input components** - When they have non-trivial logic
**Schema structure helpers** - When they involve logic
### Low priority - Usually skip
**Simple schema definitions** - No logic to test
**Thin wrappers** - Just pass through to libraries
**UI-only components** - Styling with no behavior
1. Testing strategy is about making intentional trade-offs. Perfect coverage isn't the goal—protecting critical business logic while maintaining development velocity is.
## Test organization patterns
As your test suite grows, maintain structure:
`apps/studio/
├── schemaTypes/
│ ├── validation/
│ │ ├── eventValidation.ts
│ │ └── eventValidation.test.ts
│ ├── components/
│ │ ├── DoorsOpenInput.tsx
│ │ └── DoorsOpenInput.test.tsx
│ └── eventType.ts
└── __tests__/
├── fixtures/
│ ├── validation.ts
│ ├── client.ts
│ └── providers.tsx
└── setup.ts`
Key principles:
* **Co-locate tests** with the code they test
* **Share fixtures** in a central location (`__tests__/fixtures`)
* **Name tests** after the file being tested (`DoorsOpenInput.test.tsx`)
## Test maintenance best practices
Tests require maintenance like production code. Follow these practices:
### Keep tests simple
```typescript
// ❌ Complex test with multiple concerns
it('handles everything', async () => {
const result1 = await validateVenue(venue1, context1)
const result2 = await validateVenue(venue2, context2)
const result3 = await validateVenue(venue3, context3)
expect(result1).toBe(true)
expect(result2).toBe(false)
expect(result3).toBe(true)
})
// ✅ Focused tests, one concept each
it('allows venue for in-person events', async () => {
const result = await validateVenue(venue, inPersonContext)
expect(result).toBe(true)
})
it('rejects venue for virtual events', async () => {
const result = await validateVenue(venue, virtualContext)
expect(result).toBe('Only in-person events can have a venue')
})
```
### Use descriptive test names
```typescript
// ❌ Vague
it('works', () => {})
it('test1', () => {})
// ✅ Clear intent
it('allows venue for in-person events', () => {})
it('rejects venue for virtual events', () => {})
it('calculates doors open time 60 minutes before event', () => {})
```
### Extract test helpers
```typescript
// ❌ Repeated setup in every test
it('test 1', () => {
const context = {document: {_id: '1', _type: 'event', eventType: 'in-person'}}
// ... test
})
it('test 2', () => {
const context = {document: {_id: '2', _type: 'event', eventType: 'virtual'}}
// ... test
})
// ✅ Reusable fixture
function createEventContext(eventType: string) {
return createMockValidationContext({
_id: `event-${eventType}`,
_type: 'event',
eventType,
})
}
it('allows venue for in-person events', () => {
const context = createEventContext('in-person')
// ... test
})
```
## Start small, grow strategically
Building a test suite is an investment. Start small and expand strategically:
### Phase 1: Test critical validation
Begin with functions that protect data integrity:
* Required field validation
* Business rule enforcement
* Data consistency checks
**Goal**: Prevent content editors from creating invalid documents
### Phase 2: Test complex helpers
Add tests for helper functions with non-trivial logic:
* Date/time calculations
* Formatting utilities
* Data transformations
**Goal**: Catch bugs in commonly-used utilities
### Phase 3: Test custom components
Test custom inputs with complex behavior:
* Components with conditional rendering
* Components with user interactions
* Components that query the dataset
**Goal**: Ensure editor UI works correctly
### Phase 4: Integrate CI
Add GitHub Actions to run tests automatically:
* On every pull request
* Before merging to main
* Before deployments
**Goal**: Prevent untested code from reaching production
1. Review your current Studio code. Categorize your validation functions, helpers, and components into high/medium/low priority based on business impact and complexity.
## Maintaining test quality
As your suite grows, periodically review test quality:
### Red-green-refactor cycle
1. **Red** - Write a failing test
2. **Green** - Make it pass with minimal code
3. **Refactor** - Improve both test and production code
1. [Test-driven development (TDD)](https://en.wikipedia.org/wiki/Test-driven_development) naturally produces better-designed code. Writing tests first forces you to think about interfaces and edge cases before implementation.
This discipline prevents over-engineering and keeps tests focused.
### Delete obsolete tests
When you remove features or refactor code, delete tests that no longer serve a purpose. Dead code in tests is still maintenance burden.
## Key takeaways
**Strategic investment**
* Tests pay dividends through confident refactoring and faster debugging
* Start with high-value tests (validation, critical logic)
* Grow your suite incrementally as complexity increases
**Technical implementation**
* Pure functions are easiest to test
* Mock external dependencies (clients, contexts)
* Test user-facing behavior, not implementation details
**Workflow integration**
* Watch mode for instant local feedback
* CI runs for automated validation
* Coverage reports to find gaps
**Sustainable testing**
* Keep tests simple and focused
* Co-locate tests with code
* Delete obsolete tests
* Prioritize readability over cleverness## [Tests as Content Operating System Infrastructure](/learn/course/testing-sanity-studio/tests-as-content-operating-system-infrastructure)
Tests aren't overhead—they're strategic infrastructure that enables confident scaling of your Content Operating System. Comprehensive test coverage protects critical operations as your Studio grows, documents business requirements for future developers, and creates the safety net that allows your team to iterate rapidly. Learn to view testing as a foundational investment that compounds in value over time.
You've built a comprehensive testing strategy, progressing from validation logic and access control to stateful functions to React components. In Sanity's Content Operating System, your Studio isn't just an editing interface—it's programmable infrastructure that encodes business rules, workflow automation, and content governance. Tests are specifications for this infrastructure.
Just as the Content Operating System treats content as structured, reusable data rather than unstructured files, testing treats business requirements as executable specifications rather than documentation that drifts from reality. Your tests document how validation should work, what helpers should return, and how custom inputs should behave—in code that verifies itself. This aligns with Sanity's philosophy of strategic preparation: when code becomes commodity through AI assistance, your specifications become your competitive advantage.
Tests enable AI agents to understand your business logic, allowing them to safely refactor, extend, and maintain your Studio while respecting the rules that protect your content quality. Your test suite becomes a strategic asset that compounds in value as complexity grows, enabling you to move fast always through preparation rather than scrambling.
Start with high-value tests—validation functions that protect data integrity, helper utilities with business logic, custom components that mutate documents. Grow incrementally as complexity increases. Keep tests simple and focused, co-located with the code they verify. Mock external dependencies like Sanity clients and validation contexts. Separate business logic from validation builders for reusability. Use watch mode locally for instant feedback, run comprehensive suites in CI before merge, and leverage coverage reports to find gaps in critical paths.
Add tests for new features before they reach production. Test components that write data rigorously to prevent corruption. Build reusable fixtures for your domain. Review tests in code review. Delete obsolete tests as features change. Refactor tests when they become harder to maintain than production code.
Your Studio is now protected by executable specifications that grow with your business needs. Content editors work confidently, knowing custom logic protects their content. Developers refactor fearlessly, knowing tests catch regressions. Your tests are infrastructure for the Content Operating System, ensuring reliable content operations at scale.# [Build landing pages with Next.js](/learn/course/page-building)
Give your content authors the creative freedom they need to produce landing pages by assembling individual blocks while still benefitting from structured content.
## [An introduction to page builders](/learn/course/page-building/an-introduction-to-page-builders)
Setup your page builder the right way with Sanity and Next.js, understanding the process and best practices. With editing affordances your content creators will understand and appreciate.
By the end of this course, you'll have a robust page builder that allows you to generate pages with a set of reusable "blocks". Not only will you learn how to implement new blocks but you'll understand every step of the process, and ensure best practices for your editors.
But before we get into things, why don't we quickly discuss what a page builder _is_? Dependent on your experience, you may have a range of different expectations as to what a page builder actually is.
## What is a page builder?
Think of a page builder as a set of stackable LEGO blocks, where each block is a piece of content that can be used to build a page. This is an apt description, because it's rare that a page will go left and right, it'll almost always go from top to bottom.
1. The drag-and-drop functionality in Sanity's Visual Editing can be used to move items that are laid out horizontally, even if the same content is represented vertically in the Sanity Studio.
In simple terms, described as Sanity Schema Types, a page builder is an array of objects.
With this in mind, a page builder allows you to move blocks vertically on a page, and to add and remove blocks on a page. If you build a new component for it, it can then be used on any page and added to the selection of blocks within your page builder.
### Keep an open mind
While this course focuses primarily on page building for web pages, the same approach of being able to create an ordered list of different shapes of content may also be used in other front ends like applications.
1. **Consider this:** The Portable Text Editor is also "just" an array of objects. And yet its purpose can conjure a very different idea of what content is suitable to enter into it, and how it may be presented!
As much as possible, your page builder should be modeling **content**, not **presentation**. While rare, consider future opportunities where other applications may consume this same content and display it in a different way, or a different context, with different meaning.
## Why is it important?
With a page builder, you're allowing your content team to build pages without relying on developers. They can change the order of content, use repeatable components to create consistency and ultimately generate new pages in a fraction of the time.
What's very useful about the above, is the fact that when you build a new block, your whole team has access to that block to use throughout any of the pages that use the page builder.
## What problems does it solve?
* **Speed**: Content teams can build pages in a fraction of the time.
* **Consistency**: Repeatable components can be used to create consistency across pages.
* **Flexibility**: Content teams can change the order of content and add and remove blocks from a page.
## What problems does it create?
You have to think about how you will structure your page builder. Whether you use a single page builder throughout all of your pages, or whether you want to have specific page builders for different pages.
You shouldn't use it for something like a blog, where almost all blog posts follow the same formulaic structure of a big chunk of text with a few images.
Always remember, as soon as you add a page builder, you're handing over the reins for page layout to your content team, and a lack of rigidity can result in inconsistent user experiences.
Over time your authors may have many requests for unique blocks, and your page builder becomes difficult to maintain or understand. A strict adherence to consistency can reduce the likelihood of "runaway schema."
## About the author
My name is Jono, and I'm the founder of [Roboto Studio](https://robotostudio.com/?utm-source=sanity-learn). I have been building websites for many years, focusing on delivering the best editorial experiences with cutting-edge technologies. I wrote this course to simplify the process of creating a page builder with Sanity and Next.js.
The goal is to provide a straightforward course on crafting a solid page builder that allows your end users to have the best editorial experience. After years of building websites with Sanity and Next.js, I wrote this course based on what I wish I had learned when I first started building.
Throughout this course, you will learn the process of building blocks and the positive and negative implications of content modeling decisions. By the end of the course you will be able to design and manage page builder blocks easily and have an understanding of the best practices.
Now, let's go ahead and build the page builder blocks.## [Create page builder schema types](/learn/course/page-building/create-page-builder-schema-types)
Setup the initial "blocks" of content and set the foundation of your page builder schema types.
1. The schema types you'll add in this lesson follow on from those created in the [Content-driven web application foundations](https://www.sanity.io/learn/course/content-driven-web-application-foundations) course.
The choices you make at this stage will determine the efficiency of content creation. Keeping your schema simple and well-structured is the key to effortless authoring.
## Learning objectives
By the end of this lesson, you'll be able to:
* Structure a page builder
* Implement new blocks
* Understand when to use references vs objects
## Setting up a page builder
The page builder is typically an [array of](https://www.sanity.io/docs/array-type) [`object`](https://www.sanity.io/docs/array-type) or [`reference`](https://www.sanity.io/docs/array-type) types that can be reordered. It's the container for all your building blocks. With Sanity, there are no pre-built blocks, but it's fast and easy to create what you need.
* If you use **objects**, the content is simpler to query but trapped within the document.
* If you use **references**, the content can be reused between documents, and your queries must resolve them.
### Create the block schema types
Let's start by creating your first `pageBuilder` block. Note that this example uses an object type to create the block.
Since you are new to page builders, the following example will start with objects, and the reasons for this choice will [be explained later](https://www.sanity.io/learn/course/page-building/scaling-page-builders-and-pitfalls#s-2e72d1b5ac82).
The next step is to add a `splitImage` block, a simple layout with text on one side and an image on the other, either left or right. You've definitely seen this block on many websites.
[Here's a link for what this block could look like](https://v0.dev/chat/zwZtgP2aDSB?b=b_LmbyJ1dlp4v)
1. **Create** the `splitImage` block
```typescript:src/sanity/schemaTypes/blocks/splitImageType.ts
import { defineField, defineType } from "sanity";
export const splitImageType = defineType({
name: "splitImage",
type: "object",
fields: [
defineField({
name: "orientation",
type: "string",
options: {
list: [
{ value: "imageLeft", title: "Image Left" },
{ value: "imageRight", title: "Image Right" },
],
},
}),
defineField({
name: "title",
type: "string",
}),
defineField({
name: "image",
type: "image",
}),
],
preview: {
select: {
title: "title",
media: "image",
},
prepare({ title, media }) {
return {
title,
subtitle: "Text and Image",
media
};
},
},
});
```
Now, let's add a `hero` block. This is a simple block with a title text and image. Despite the schemas looking very similar, you would usually have a hero at the top of a page, so it's a good idea to have a dedicated block for it.
You may have noticed that the code snippets use a block field for the text. This is known as portable text, a powerful way to render rich text within Sanity. While it's more complex than a simple string, its flexibility makes it incredibly useful.
1. See [Presenting Portable Text](https://www.sanity.io/learn/developer-guides/presenting-block-text) in the documentation for more details
[Here's a link for what this block could look like](https://v0.dev/chat/MiPurXiE59K?b=b_gUmeXji6heI)
1. **Create** the `hero` block
```typescript:src/sanity/schemaTypes/blocks/heroType.ts
import { defineField, defineType } from "sanity";
export const heroType = defineType({
name: "hero",
type: "object",
fields: [
defineField({
name: "title",
type: "string",
}),
defineField({
name: "text",
type: "blockContent",
}),
defineField({
name: "image",
type: "image",
}),
],
});
```
1. Getting an error with `blockContent` missing? The schema types you'll add in this lesson follow on from those created in the [Content-driven web application foundations](https://www.sanity.io/learn/course/content-driven-web-application-foundations) course.
An "FAQ Block" is an ideal block for using references, allowing the same document to be reused in multiple places.
If you have a list of FAQs that you want to show on multiple pages, you can create a single FAQ document and reference it from each page rather than duplicating the FAQ content. This makes it easier to maintain since you only need to update the content in one place.
Let's create a FAQ document type and reference it in a block. First, let's create the FAQ document schema:
In this example, the name of the block is `faqBlock`
[Here's a link for what this block could look like](https://v0.dev/chat/zl4hrYbDzOg?b=b_lTKHW2wTTS4)
1. **Create** the `faq` document schema type
```typescript:src/sanity/schemaTypes/faqType.ts
import { defineField, defineType } from "sanity";
export const faqType = defineType({
name: "faq",
title: "FAQ",
type: "document",
fields: [
defineField({
name: "title",
type: "string",
}),
defineField({
name: "body",
type: "blockContent",
}),
],
});
```
1. **Create** the `faqAccordion` block, which will reference the FAQ document.
```typescript:src/sanity/schemaTypes/blocks/faqsType.ts
import { defineField, defineType } from "sanity";
export const faqsType = defineType({
name: "faqs",
title: "FAQs",
type: "object",
fields: [
defineField({
name: "title",
type: "string",
}),
defineField({
name: "faqs",
title: "FAQs",
type: "array",
of: [{ type: "reference", to: [{ type: "faq" }] }],
}),
],
});
```
Finally, one more block. This one is a features block, and this is going to get a little more complex with an array of features (as a block) inside a block.
[Here's a link for what this block could look like](https://v0.dev/chat/z0zxFeAPm1z?b=b_ZpymafJ4kCT)
1. **Create** the `features` block
```typescript:src/sanity/schemaTypes/blocks/featuresType.ts
import { defineField, defineType } from "sanity";
export const featuresType = defineType({
name: "features",
type: "object",
fields: [
defineField({
name: "title",
type: "string",
}),
defineField({
name: "features",
type: "array",
of: [
defineField({
name: "feature",
type: "object",
fields: [
defineField({
name: "title",
type: "string",
}),
defineField({
name: "text",
type: "string",
}),
],
}),
],
}),
],
});
```
### Create the page builder schema type
Okay great, you have got your blocks. Now let's put them together in your page builder component. The order of the blocks is how it will appear when a user adds a new block to the array.
1. **Create** the `pageBuilder` schema type
```typescript:src/sanity/schemaTypes/pageBuilderType.ts
import { defineType, defineArrayMember } from "sanity";
export const pageBuilderType = defineType({
name: "pageBuilder",
type: "array",
of: [
defineArrayMember({ type: "hero" }),
defineArrayMember({ type: "splitImage" }),
defineArrayMember({ type: "features" }),
defineArrayMember({ type: "faqs" }),
],
});
```
### Create the page document type
The schema types in your Sanity Studio for now are only useful for writing blog posts. The pages being built with this schema have a different intention to those, and so should be stored in a distinct schema type.
1. **Create** a `page` document schema type
```typescript:src/sanity/schemaTypes/pageType.ts
import { DocumentIcon } from "@sanity/icons";
import { defineField, defineType } from "sanity";
export const pageType = defineType({
name: "page",
title: "Page",
type: "document",
icon: DocumentIcon,
fields: [
defineField({
name: "title",
type: "string",
}),
defineField({
name: "slug",
type: "slug",
options: {
source: "title",
},
}),
defineField({
name: "content",
type: "pageBuilder",
}),
defineField({
name: "mainImage",
type: "image",
options: {
hotspot: true,
},
}),
],
preview: {
select: {
title: "title",
subtitle: "slug.current",
},
},
});
```
### Add your new types to the Studio schema
Finally, update the schema types index file to import all of these newly created schema types.
1. **Update** your registered schema types
```typescript:src/sanity/schemaTypes/index.ts
// ...all your existing imports
import { pageType } from "./pageType";
import { pageBuilderType } from "./pageBuilderType";
import { faqType } from "./faqType";
import { faqsType } from "./blocks/faqsType";
import { featuresType } from "./blocks/featuresType";
import { heroType } from "./blocks/heroType";
import { splitImageType } from "./blocks/splitImageType";
export const schema: { types: SchemaTypeDefinition[] } = {
types: [
// ...all your existing schema types
pageType,
pageBuilderType,
faqType,
faqsType,
featuresType,
heroType,
splitImageType,
],
};
```
### Update Studio Structure
The desk structure will now include `page` and `faq` type documents, but won't display them nicely with plurals.
1. **Update** the Studio's structure configuration
```typescript:src/sanity/structure.ts
import type { StructureResolver } from "sanity/structure";
// https://www.sanity.io/docs/structure-builder-cheat-sheet
export const structure: StructureResolver = (S) =>
S.list()
.title("Blog")
.items([
S.documentTypeListItem("post").title("Posts"),
S.documentTypeListItem("category").title("Categories"),
S.documentTypeListItem("author").title("Authors"),
S.divider(),
S.documentTypeListItem("page").title("Pages"),
S.documentTypeListItem("faq").title("FAQs"),
S.divider(),
...S.documentTypeListItems().filter(
(item) =>
item.getId() &&
!["post", "category", "author", "page", "faq"].includes(item.getId()!)
),
]);
```
## Check it's working
With all of these new schema types registered you should now be able to create Page type documents with the Page Builder field allowing you to add any one of four blocks.
Now that your page builder schema is set up, all the fundamental building blocks are in place. Next, you can add new blocks, reorder them, and update the array as needed.## [Improve authoring with previews and thumbnails](/learn/course/page-building/improved-ui-with-previews-and-thumbnails)
Updates to the configuration of your page builder schema types can dramatically improve the content creation experience.
Next, you will enhance the user interface (UI) with previews, thumbnails, and filters. These additions will help editors quickly find and use the blocks they need to create pages.
Previews are the snippets of information that appear in the list view of the page builder. They're the first thing your editors will see when they're adding a new block to the page builder.
Here's an example of what a _good_ preview looks like:
## What makes a good preview?
Previews should always have consistency. Consistency creates familiarity and familiarity improves user experience. The more consistency you have in your previews and page builders, the faster it will be for your editors to create pages.
`object` and `document` schema types in Sanity Studio have a preview property which allow the following to be customized:
* `title`: This is the title of the block, or the most important headline. Think what section a marketer would care about the most.
* `subtitle`: Set this to the block name.
* `media`: If the block has an image, use that, otherwise use an icon as a fallback.
Let's revisit our blocks from the last lesson and improve the readability.
Note, this lesson uses the [default icons from Sanity](https://icons.sanity.build/) to minimize dependencies. However, in a real-world project, [Lucide](https://lucide.dev/) may be preferred as it has a larger icon selection.
## Using prepare and preview
Pay attention to the `preview` and `prepare` functions. This is where you are defining how the block appears in the preview.
In the example below, there is a block with a title, subtitle and media.
The pink cat on the left-hand side is the `media`, this can either be an image, or an icon. However, you should never leave it blank.
1. **Update** the `splitImage` schema type to include an `icon` and `preview`
```typescript:src/sanity/schemaTypes/blocks/splitImageType.ts
import { defineField, defineType } from "sanity";
import { BlockContentIcon } from "@sanity/icons";
export const splitImageType = defineType({
name: "splitImage",
// ...all other settings
icon: BlockContentIcon,
preview: {
select: {
title: "title",
media: "image",
},
prepare({title, media}) {
return {
title: title,
subtitle: "Split Image",
media: media ?? BlockContentIcon,
};
},
},
});
```
Insert a "Split Image" block and give it some content. The preview should now look like this:
This example is a simple block with a title, subtitle and media. The `prepare` function is used to set the title and media for the preview.
1. **Update** the `hero` type block
```typescript:src/sanity/schemaTypes/blocks/heroType.ts
import { defineField, defineType } from "sanity";
import { TextIcon } from "@sanity/icons";
export const heroType = defineType({
name: "hero",
// ...other settings
icon: TextIcon,
preview: {
select: {
title: "title",
media: "image",
},
prepare({ title, media }) {
return {
title,
subtitle: "Hero",
media: media ?? TextIcon,
};
},
},
});
```
1. **Update** the faqs type block
```typescript:src/sanity/schemaTypes/blocks/faqsType.ts
import { defineField, defineType } from "sanity";
import { HelpCircleIcon } from "@sanity/icons";
export const faqsType = defineType({
name: "faqs",
// ...other settings
icon: HelpCircleIcon,
preview: {
select: {
title: "title",
},
prepare({ title }) {
return {
title,
subtitle: "FAQs",
};
},
},
});
```
1. **Update** the features type block
```typescript:src/sanity/schemaTypes/blocks/featuresType.ts
import { defineField, defineType } from "sanity";
import { StarIcon } from "@sanity/icons";
export const featuresType = defineType({
name: "features",
// ...other settings
icon: StarIcon,
preview: {
select: {
title: "title",
},
prepare({ title }) {
return {
title,
subtitle: "Features",
};
},
},
});
```
## Adding thumbnails
Customized icons are good, but a visual preview of what a block can look like is even better.
To implement these previews, you need to update your page builder schema. For this particular example, you'll add a `grid` view to the `options` property.
This creates a grid view of the block, and the preview image is taken from the `static` folder.
It should look something like this:
1. **Update** the page builder schema type
```typescript:src/sanity/schemaTypes/pageBuilderType.ts
export const pageBuilderType = defineType({
// ... previous configuration
options: {
insertMenu: {
views: [
{
name: "grid",
previewImageUrl: (schemaType) => `/block-previews/${schemaType}.png`,
},
],
},
},
});
```
### Create your own thumbnails
Next.js provides a public folder in the root of your application for serving static images. You could place your own images in this directory, ensuring they adhere to the following specifications:
* Dimensions: 600x400px (maintain consistent sizing)
* Format: PNG with transparent background
* Naming: Match schema type names (e.g., `hero.png`, `splitImage.png`)
There is a community file built for designing these, [it is available here](https://www.figma.com/community/file/1404904715260176924/arrayfield-template-for-sanity).
### Pre-designed thumbnails
For the blocks in this lesson, we have prepared some example thumbnails you can use. Download these example images and place them in your application at `/public/block-previews`
1. **Download**, the example thumbnails, and extract them into a `/public/block-previews` directory
Click the "Add item" button now and you should see the preview images.
It's time to finally start getting this content to show up in your Next.js application. First let's create a new dynamic route for rendering page documents.## [Render pages](/learn/course/page-building/rendering-pages)
Create a new dynamic route to render "page" documents and create links to them within Sanity Studio for an interactive live preview within Presentation.
You've created your perfect schema, improved your editorial experience by adding thumbnails and now it's time to get your page builder blocks wired up on the frontend.
## Learning objectives
Now that you've created "page" type documents in the Studio, you'll need the Next.js application to query them at a dynamic route.
By the end of this chapter, you'll be able to:
* Query for and render any page by its slug
## Query a page
You are going to create a query to fetch the page and its page builder content from the Content Lake.
Let's break down what's happening in this query.
The `->` operator in Sanity is used for dereferencing documents. When you have a reference to another document (like our FAQs), by default you only get the reference ID. Adding `->` tells Sanity to "follow" that reference and include the full content of the referenced document in your query results. This is particularly useful when you need the actual content immediately and want to avoid making multiple separate queries.
1. **Update** the file with all your queries to include one for an individual page:
```typescript:src/sanity/lib/queries.ts
// ...all other queries
export const PAGE_QUERY =
defineQuery(`*[_type == "page" && slug.current == $slug][0]{
...,
content[]{
...,
_type == "faqs" => {
...,
faqs[]->
}
}
}`);
```
This query also demonstrates a shorthand syntax of the GROQ function `select()`, by which you can handle individual blocks differently by checking their `_type`.
Since you've changed schema types and queries, it's time to regenerate Types as well.
```sh
npm run typegen
```
1. This command was setup in the [Generate TypeScript Types](https://www.sanity.io/learn/course/content-driven-web-application-foundations/generate-typescript-types) lesson of the [Content-driven web application foundations](https://www.sanity.io/learn/course/content-driven-web-application-foundations) course.
## Render a page
Before rendering individual blocks, the Next.js application needs a route to render any individual page.
1. **Create** a new route for rendering any page document by its unique slug.
```tsx:src/app/(frontend)/[slug]/page.tsx
import { sanityFetch } from "@/sanity/lib/live";
import { PAGE_QUERY } from "@/sanity/lib/queries";
export default async function Page({
params,
}: {
params: Promise<{ slug: string }>;
}) {
const { data: page } = await sanityFetch({
query: PAGE_QUERY,
params: await params,
});
return <div>{JSON.stringify(page)}</div>;
}
```
## Update the Presentation tool resolver
To create a link between your Sanity Studio documents and their locations in the front-end, update the resolve function created for your Presentation tool to generate dynamic links to your live preview.
1. **Update** the document locations resolver
```typescript:src/sanity/presentation/resolve.ts
import {
defineLocations,
PresentationPluginOptions,
} from "sanity/presentation";
export const resolve: PresentationPluginOptions["resolve"] = {
locations: {
// ...other locations
page: defineLocations({
select: {
title: "title",
slug: "slug.current",
},
resolve: (doc) => ({
locations: [
{
title: doc?.title || "Untitled",
href: `/${doc?.slug}`,
},
],
}),
}),
},
};
```
You should now be able to open any page in Presentation by clicking the "Used on one page" link at the top of the document editor.
Now you can create pages in Sanity Studio and preview them live in the Presentation tool. The next step is to render each block as a unique component.## [Render page builder blocks](/learn/course/page-building/rendering-page-builder-blocks)
Setup the unique components for each individual "block" to render on the page.
The example components in this lesson have been given deliberately simple designs. Feel free to redesign them with much more _flair_.
You'll notice also the props for each component has been typed from the `PAGE_QUERYResult` generated from Sanity TypeGen. The type itself looks _quite_ gnarly, but it will be constantly updated as you make future changes to your schema types and queries.
## Create block components
1. **Create** a component to render the Hero block
```tsx:src/components/blocks/hero.tsx
import { PortableText } from "next-sanity";
import Image from "next/image";
import { Title } from "@/components/title";
import { urlFor } from "@/sanity/lib/image";
import { PAGE_QUERYResult } from "@/sanity/types";
type HeroProps = Extract<
NonNullable<NonNullable<PAGE_QUERYResult>["content"]>[number],
{ _type: "hero" }
>;
export function Hero({ title, text, image }: HeroProps) {
return (
<section className="isolate w-full aspect-[2/1] py-16 relative overflow-hidden">
<div className="relative flex flex-col justify-center items-center gap-8 h-full z-20">
{title ? (
<h1 className="text-2xl md:text-4xl lg:text-6xl font-semibold text-white text-pretty max-w-3xl">
{title}
</h1>
) : null}
<div className="prose-lg lg:prose-xl prose-invert flex items-center">
{text ? <PortableText value={text} /> : null}
</div>
</div>
<div className="absolute inset-0 bg-pink-500 opacity-50 z-10" />
{image ? (
<Image
className="absolute inset-0 object-cover blur-sm"
src={urlFor(image).width(1600).height(800).url()}
width={1600}
height={800}
alt=""
/>
) : null}
</section>
);
}
```
1. **Create** a component to render the FAQs block
```tsx:src/components/blocks/faqs.tsx
import { PAGE_QUERYResult } from "@/sanity/types";
import { PortableText } from "next-sanity";
type FAQsProps = Extract<
NonNullable<NonNullable<PAGE_QUERYResult>["content"]>[number],
{ _type: "faqs" }
>;
export function FAQs({ _key, title, faqs }: FAQsProps) {
return (
<section className="container mx-auto flex flex-col gap-8 py-16">
{title ? (
<h2 className="text-xl mx-auto md:text-2xl lg:text-5xl font-semibold text-slate-800 text-pretty max-w-3xl">
{title}
</h2>
) : null}
{Array.isArray(faqs) ? (
<div className="max-w-2xl mx-auto border-b border-pink-200">
{faqs.map((faq) => (
<details
key={faq._id}
className="group [&[open]]:bg-pink-50 transition-colors duration-100 px-4 border-t border-pink-200"
name={_key}
>
<summary className="text-xl font-semibold text-slate-800 list-none cursor-pointer py-4 flex items-center justify-between">
{faq.title}
<span className="transform origin-center rotate-90 group-open:-rotate-90 transition-transform duration-200">
←
</span>
</summary>
<div className="pb-4">
{faq.body ? <PortableText value={faq.body} /> : null}
</div>
</details>
))}
</div>
) : null}
</section>
);
}
```
1. **Create** a component to render the Features block
```tsx:src/components/blocks/features.tsx
import { PAGE_QUERYResult } from "@/sanity/types";
type FeaturesProps = Extract<
NonNullable<NonNullable<PAGE_QUERYResult>["content"]>[number],
{ _type: "features" }
>;
export function Features({ features, title }: FeaturesProps) {
return (
<section className="container mx-auto flex flex-col gap-8 py-16">
{title ? (
<h2 className="text-xl mx-auto md:text-2xl lg:text-5xl font-semibold text-slate-800 text-pretty max-w-3xl">
{title}
</h2>
) : null}
{Array.isArray(features) ? (
<div className="grid grid-cols-3 gap-8">
{features.map((feature) => (
<div key={feature._key} className="flex flex-col gap-4">
<h3 className="text-xl font-semibold text-slate-800">
{feature.title}
</h3>
<p className="text-lg text-slate-600">{feature.text}</p>
</div>
))}
</div>
) : null}
</section>
);
}
```
1. **Create** a component to render the Split Image block
```tsx:src/components/blocks/split-image.tsx
import Image from "next/image";
import { urlFor } from "@/sanity/lib/image";
import { PAGE_QUERYResult } from "@/sanity/types";
import { stegaClean } from "next-sanity";
type SplitImageProps = Extract<
NonNullable<NonNullable<PAGE_QUERYResult>["content"]>[number],
{ _type: "splitImage" }
>;
export function SplitImage({ title, image, orientation }: SplitImageProps) {
return (
<section
className="container mx-auto flex gap-8 py-16 data-[orientation='imageRight']:flex-row-reverse"
data-orientation={stegaClean(orientation) || "imageLeft"}
>
{image ? (
<Image
className="rounded-xl w-2/3 h-auto"
src={urlFor(image).width(800).height(600).url()}
width={800}
height={600}
alt=""
/>
) : null}
<div className="w-1/3 flex items-center">
{title ? (
<h2 className="text-3xl mx-auto md:text-5xl lg:text-8xl font-light text-pink-500 text-pretty max-w-3xl">
{title}
</h2>
) : null}
</div>
</section>
);
}
```
## Render the page builder content
Now we have components for each block, we need to render them in order.
Each array item has a distinct `_type` attribute, which you can switch over to render the correct component.
Each item also contains a unique (to the array) `_key` value, which can be passed to React as a `key` prop—required by React for performant and consistent rendering of an array.
We have also passed the remaining props to the block component using the spread operator.
1. **Create** the `PageBuilder` component to render all the content of the page
```tsx:src/components/page-builder.tsx
import { Hero } from "@/components/blocks/hero";
import { Features } from "@/components/blocks/features";
import { SplitImage } from "@/components/blocks/split-image";
import { FAQs } from "@/components/blocks/faqs";
import { PAGE_QUERYResult } from "@/sanity/types";
type PageBuilderProps = {
content: NonNullable<PAGE_QUERYResult>["content"];
};
export function PageBuilder({ content }: PageBuilderProps) {
if (!Array.isArray(content)) {
return null;
}
return (
<main>
{content.map((block) => {
switch (block._type) {
case "hero":
return <Hero key={block._key} {...block} />;
case "features":
return <Features key={block._key} {...block} />;
case "splitImage":
return <SplitImage key={block._key} {...block} />;
case "faqs":
return <FAQs key={block._key} {...block} />;
default:
// This is a fallback for when we don't have a block type
return <div key={block._key}>Block not found: {block._type}</div>;
}
})}
</main>
);
}
```
1. **Update** the dynamic page route to use the `PageBuilder` component
```tsx:src/app/(frontend)/[slug]/page.tsx
import { PageBuilder } from "@/components/page-builder";
import { sanityFetch } from "@/sanity/lib/live";
import { PAGE_QUERY } from "@/sanity/lib/queries";
export default async function Page({
params,
}: {
params: Promise<{ slug: string }>;
}) {
const { data: page } = await sanityFetch({
query: PAGE_QUERY,
params: await params,
});
return page?.content ? <PageBuilder content={page.content} /> : null;
}
```
You should now be able to create page documents, use all of the blocks from the Page Builder array we have created, and preview changes as you author them.
For now you have click-to-edit functionality in Presentation. Before going any further, let's use everything we've built so far to create the application's home page.## [Creating a "home" page](/learn/course/page-building/creating-a-home-page)
Create a "singleton" document to store distinct content that is globally relevant to the application.
A quick side mission before going further. A website's "home" page is typically used to show the same sort of content that our page builder can generate. So it makes sense to reuse this content structure on the home page like we would any other page.
For any editable piece of content that has global relevance to an application—like site name, navigation, footer text, etc—most often you will use a "singleton" document. That is, a document type of which there should only ever be one in a dataset and it likely has a distinct `_id` value.
## Site settings schema type
We'll keep the site settings simple for now. A new document type with just a single field—a reference to a page, which will be used as the home page on the site.
1. **Create** the `siteSettings` schema type
```typescript:src/sanity/schemaTypes/siteSettingsType.ts
import { defineField, defineType } from "sanity";
import { ControlsIcon } from "@sanity/icons";
export const siteSettingsType = defineType({
name: "siteSettings",
title: "Site Settings",
type: "document",
icon: ControlsIcon,
fields: [
defineField({
name: "homePage",
type: "reference",
to: [{ type: "page" }],
}),
],
preview: {
prepare() {
return {
title: "Site Settings",
};
},
},
});
```
1. **Register** `siteSettings` to your Studio schema types
```typescript:src/sanity/schemaTypes/index.ts
// ...all other imports
import { siteSettingsType } from "./siteSettingsType";
export const schema: { types: SchemaTypeDefinition[] } = {
types: [
// ...all other types
siteSettingsType,
],
};
```
Singleton documents can be invoked with a distinct `_id` value by configuring it in your structure builder configuration.
**Update** the structure builder configuration to include a singleton siteSettings document.
```typescript:src/sanity/structure.ts
export const structure: StructureResolver = (S) =>
S.list()
.title("Blog")
.items([
// ...all other items
S.listItem()
.id("siteSettings")
.schemaType("siteSettings")
.title("Site Settings")
.child(
S.editor()
.id("siteSettings")
.schemaType("siteSettings")
.documentId("siteSettings")
),
...S.documentTypeListItems().filter(
(item) =>
item.getId() &&
![
// ...all other ignored types
"siteSettings",
].includes(item.getId()!)
),
]);
```
1. See more examples of what you can do in the [Structure Builder cheat sheet](https://www.sanity.io/learn/studio/structure-builder-cheat-sheet)
You should now see the Site Settings document on the left hand side of your Structure tool. Instead of opening a list of documents, it opens a single one.
1. **Select** a "Home Page" reference, and **publish** the Site Settings
### There can only be one
To prevent the creation of any more site settings documents, the type can be removed from the "Create" menu at the top left of your Studio.
1. **Update** your Studio config to remove this document type from the list
```typescript:sanity.config.ts
export default defineConfig({
// ...all other settings
document: {
newDocumentOptions: (prev) => prev.filter((item) => item.templateId !== "siteSettings"),
},
});
```
## Query the home page
The current "page" document type query relies on a page slug, so you'll need a different query for this site settings document first, and then query that page.
1. **Update** your `queries.ts` file to include this home page query
```typescript:src/sanity/lib/queries.ts
// ...all other queries
export const HOME_PAGE_QUERY = defineQuery(`*[_id == "siteSettings"][0]{
homePage->{
...,
content[]{
...,
_type == "faqs" => {
...,
faqs[]->
}
}
}
}`);
```
1. **Run** the following command to update your schema extraction and generated types
```sh:Terminal
pnpm run typegen
```
1. This command was setup in the [Generate TypeScript Types](https://www.sanity.io/learn/course/content-driven-web-application-foundations/generate-typescript-types) lesson of the [Content-driven web application foundations](https://www.sanity.io/learn/course/content-driven-web-application-foundations) course.
Then update your home page route file similar to the dynamic route for individual pages, but for just this distinct home page.
1. **Update** the home page route
```typescript:src/app/(frontend)/page.tsx
import { PageBuilder } from "@/components/page-builder";
import { sanityFetch } from "@/sanity/lib/live";
import { HOME_PAGE_QUERY } from "@/sanity/lib/queries";
export default async function Page() {
const { data: page } = await sanityFetch({
query: HOME_PAGE_QUERY,
});
return page?.homePage?.content ? (
<PageBuilder content={page?.homePage.content} />
) : null;
}
```
The front page of your application at [http://localhost:3000](http://localhost:3000) should now show the page selected in your Site Settings document.
Excellent! You might now imagine how you would build other global content like your heading, footer and navigation menus into this same Site Settings document.
Let's keep enhancing the editing experience in the next lesson.## [Drag and drop in Visual Editing](/learn/course/page-building/drag-and-drop-in-visual-editing)
Allow authors to re-order blocks on page, without editing the document.
The same functionality you setup in [Add drag-and-drop elements](https://www.sanity.io/learn/course/visual-editing-with-next-js/add-drag-and-drop-elements) can be used here for your Page Builder array. This way authors can reorder array items on the page without needing to use the document editor.
1. You can setup drag-and-drop for _any_ array type field. Consider adding it to the Features and FAQs blocks as well.
## Adding drag handles
Drag-and-drop support in Presentation requires the outer DOM element of an array—and every DOM element for an item within the array—to contain additional `data-sanity` attributes. These attributes are created with a `createDataAttribute` function exported from `next-sanity` and require the ID and Type of the source document.
Additionally, for fast on-page changes, a `useOptimistic` hook is provided by `next-sanity`. Using this hook will require changing to a client component.
The `PageBuilder` component you created in a previous lesson is where we can create and set these attributes, for the `content` array and its individual blocks.
1. **Update** your `PageBuilder` component to add attributes for drag-and-drop
```tsx:src/components/page-builder.tsx
"use client";
import { Hero } from "@/components/blocks/hero";
import { Features } from "@/components/blocks/features";
import { SplitImage } from "@/components/blocks/split-image";
import { FAQs } from "@/components/blocks/faqs";
import { PAGE_QUERYResult } from "@/sanity/types";
import { client } from "@/sanity/lib/client";
import { createDataAttribute } from "next-sanity";
import { useOptimistic } from "next-sanity/hooks";
type PageBuilderProps = {
content: NonNullable<PAGE_QUERYResult>["content"];
documentId: string;
documentType: string;
};
const { projectId, dataset, stega } = client.config();
export const createDataAttributeConfig = {
projectId,
dataset,
baseUrl: typeof stega.studioUrl === "string" ? stega.studioUrl : "",
};
export function PageBuilder({
content,
documentId,
documentType,
}: PageBuilderProps) {
const blocks = useOptimistic<
NonNullable<PAGE_QUERYResult>["content"] | undefined,
NonNullable<PAGE_QUERYResult>
>(content, (state, action) => {
if (action.id === documentId) {
return action?.document?.content?.map(
(block) => state?.find((s) => s._key === block?._key) || block
);
}
return state;
});
if (!Array.isArray(blocks)) {
return null;
}
return (
<main
data-sanity={createDataAttribute({
...createDataAttributeConfig,
id: documentId,
type: documentType,
path: "content",
}).toString()}
>
{blocks.map((block) => {
const DragHandle = ({ children }: { children: React.ReactNode }) => (
<div
data-sanity={createDataAttribute({
...createDataAttributeConfig,
id: documentId,
type: documentType,
path: `content[_key=="${block._key}"]`,
}).toString()}
>
{children}
</div>
);
switch (block._type) {
case "hero":
return (
<DragHandle key={block._key}>
<Hero {...block} />
</DragHandle>
);
case "features":
return (
<DragHandle key={block._key}>
<Features {...block} />
</DragHandle>
);
case "splitImage":
return (
<DragHandle key={block._key}>
<SplitImage {...block} />
</DragHandle>
);
case "faqs":
return (
<DragHandle key={block._key}>
<FAQs {...block} />
</DragHandle>
);
default:
// This is a fallback for when we don't have a block type
return <div key={block._key}>Block not found: {block._type}</div>;
}
})}
</main>
);
}
```
The `PageBuilder` component now requires the source document ID and document type.
1. **Update** your routes that load this component to include these props.
```tsx:src/app/(frontend)/[slug]/page.tsx
import { PageBuilder } from "@/components/PageBuilder";
import { sanityFetch } from "@/sanity/lib/live";
import { PAGE_QUERY } from "@/sanity/lib/queries";
export default async function Page({
params,
}: {
params: Promise<{ slug: string }>;
}) {
const { data: page } = await sanityFetch({
query: PAGE_QUERY,
params: await params,
});
return page?.content ? (
<PageBuilder
documentId={page._id}
documentType={page._type}
content={page.content}
/>
) : null;
}
```
Don't forget the home page route as well
```tsx:src/app/(frontend)/page.tsx
import { PageBuilder } from "@/components/PageBuilder";
import { sanityFetch } from "@/sanity/lib/live";
import { HOME_PAGE_QUERY } from "@/sanity/lib/queries";
export default async function Page() {
const { data: page } = await sanityFetch({
query: HOME_PAGE_QUERY,
});
return page?.homePage?.content ? (
<PageBuilder
documentId={page?.homePage._id}
documentType={page?.homePage._type}
content={page?.homePage.content}
/>
) : null;
}
```
### Test it out
Within Presentation you should now see the "drag handle" icon (two columns of three dots) when hovering over the outer edge of each block.
Click and hold, to drag-and-drop. Additionally, hold shift while dragging to zoom the page out and see the entire array at once.
You've created your page builder, wired it up to work on the frontend, and used the visual editor to rearrange block order.
You have built the gold standard of editorial experience for your end users. Great job!
## Time to review
What remains is to learn about some of the pitfalls and challenges of using the visual editor at scale, which will be covered in the final lesson.## [Scaling page builders and pitfalls](/learn/course/page-building/scaling-page-builders-and-pitfalls)
How to keep your page builder tidy as your project grows over time.
Your page builder works just fine at this stage. But what happens when you have 20 more components, 100 more pages, and 10 more users? This lesson covers those questions and the pitfalls ahead.
## The pitfalls
### Don't include too many variations
If a block has too many variations, you're going to run into a lot of edge cases. It's also difficult to manage because you will have to pick a thumbnail as the `main` image for the block. If your variation is different from the `main` image it becomes confusing for the content team to differentiate between the variations.
Here's a good rule of thumb: if you have more than two variations of a block, you should consider splitting them into individual blocks.
### Is it a page builder or a document?
Think carefully about modeling your content as a page builder or a document type. If you want your content to be more rigid and you want to be able to reuse the same block in multiple places, then you should use a document type.
Alternatively, if you want your content to be reordered, have different layouts, or have different components, then you should use a page builder.
### Paradox of choice for marketers
To help your marketing team create pages efficiently, limit the number of block options available. Too many choices can confuse and overwhelm, leading to mistakes and delays in content creation.
For example, if a "features" block is unnecessary for a "case study," remove it from the options for that document type. This streamlines the process and makes it easier for new team members to navigate.
### Use references sparingly
This is the number one mistake I see in the wild.
Avoid making your entire page builder an array of references; it's more difficult to scale. The reason is that often, you won't need to use the same referenced block in multiple places.
One of the few exceptions is a repeated call to action where the text is identical or you might have two different versions that appear on many different pages. This is a good use case for references. If there is not a clear need to re-use content across many pages—use an object.
### Remember to prune
As you scale your website and your page builder, you will naturally have blocks that you no longer use. You should prune them regularly to eliminate technical debt.
If you do need to start removing blocks, consider the course [Handling schema changes confidently](https://www.sanity.io/learn/course/handling-schema-changes-confidently).
## Go deeper
What you've built in this course is a basic implementation using default settings. The dynamic nature of building Sanity Schema with TypeScript lends itself to opinionated abstractions. Take a look at these resources for some inspiration:
1. [Vyuh Framework's "Structure Plugin"](https://docs.vyuh.tech/guides/sanity/structure-plugin/)
## Start building!
You've made it to the end of the course. You're now fully equipped to start building your own page builders with confidence. We hope this structured approach to page building will make content management simpler and more efficient for your team.
We'd love to see the page builders that you create, [tag us on X](https://x.com/sanity_io) or [join our community](https://slack.sanity.io/) to share any projects you create# [A/B Testing](/learn/course/a-b-testing)
Understand the what, why, and how of A/B testing within Sanity Studio. Enable data-driven decision-making to lead to an improved product
## [Introduction to A/B Testing](/learn/course/a-b-testing/introduction-to-a-b-testing)
Why would we want to A/B test, and how do we plan for an A/B test
In this course you will learn:
* What is A/B Testing
* How to A/B Test
* How to setup Field level experiments using `@sanity/personalization-plugin`
* Adding an experiment to a field
* Connecting an external service to get running experiments
* Getting data for a running experiment
* Running an experiment on a page.
## About the author
Hi, I'm Jon, a Senior Solutions Architect at Sanity.
I work with our customers to enable them to get the full value out of the Sanity platform. As part of my role I have been developing the `@sanity/personalization-plugin` and working with our customers on how to implement it.
Prior to joining Sanity, I was a customer and worked on implementing Sanity into new and existing projects. I made sure we were making data driven decisions by implementing A/B testing of new features, and helped content editors to test their changes.
## What is A/B Testing
We often want to make changes to our content, and often this is because we think this change will help our website, app, or other platform perform better. Now this could just be a hunch, but we need to check that we are actually improving the platform.
A/B testing is a method that has been used to test out hypothesis for over 100 years (although it might not have had that name) from things like medicine to farming, to advertising. An A/B test is a basic kind of randomized controlled experiment, where you compare two versions of something to figure out which performs better. There are many ways to measure performance of a version, from increased conversion rate, decreased bounce rate, scroll depth, retention rate, average order value, customer satisfaction. What you choose will depend on what you are testing, but you are essentially seeing if users who have viewed the variant have improved against your chosen metric compared with those that have viewed the control. A/B testing should help us to better understand our customers, make more effective choices and increase conversions.
A/B tests can be as simple as the choice of wording on a button (“buy now” vs “add to cart”), or it could be two completely separate versions of a page (this is split testing which often gets lumped in with A/B testing). A/B tests don't just need to have two versions of content. A/B/N testing has N number of versions of content that would all be included in the same experiment.
It is now common practice for companies to run A/B testing on their digital platforms, with companies like Amazon, Facebook, and Google each conducting more than 10,000 experiments per year.
## How to A/B Test
We need to start with a clear goal of what we want to measure, and a hypothesis of how we think we can make a change to this goal.
In order to work out if our test is a success we need to be collecting data that we want to track, this could be conversion rates, user engagement, or bounce rate, among others.
Once we have that we can create the versions of content we want to test (usually a control and a variant).
We assign a user to a group and show each group a version of the content or a page, and then use statistical analysis of the data we have collected to determine which version performs better.
Normally we would assign the user at random but we need to be aware of other factors that may influence the results of your test. For example you may be testing the wording of a button but that button may only appear of the desktop version of your website. In this case you might only split users by device first and then assign their group.
Now we know a bit about A/B Testing, lets configure fields for experimentation using the `@sanity/personalization-plugin` .## [Field Level Experimentation](/learn/course/a-b-testing/field-level-experimentation)
Sanity has created a plugin that allows A/B/N testing experiments to individual fields. You can set the experiments and their variations as config or use an async function to return the information.
## Prerequisites
You should be able to follow this course if you have completed the Day One with Sanity Studio course. It will also build on the same studio, schema, and front end.
1. Go to the [Day one content operations](https://www.sanity.io/learn/course/day-one-with-sanity-studio) course
### Import example content to your dataset
To save you from having to fill out and publish a bunch of content to make this course interesting, we have prepared a dataset that you can import and work on.
Download `production.tar.gz` below and import it into your Sanity project by running the following command in your studio folder:
1. **Download**, the dataset export
2. **Run** the following command in the terminal to Import the dataset into your project's `production` dataset
```sh
npx sanity@latest dataset import ~/path/to/production.tar.gz production
```
A successful import will give you a bunch of artists, venues, and events in the past and future between 2010–2030.
## Configure Field Level Experiments
You could create your own schema types to support A/B Testing from external sources, but Sanity has created a plugin that gives an opinionated way of handling A/B testing inside of the Sanity Studio.
We are going to add a new field to run an experiment on the name of an event. Our hypothesis is that more information in the name of an event will encourage our users to read more about it.
First you need to install and add the plugin `@sanity/personalization-plugin` to your Sanity Studio configuration
1. **Run** the following command in the terminal to install the [Personalization Plugin](https://github.com/sanity-io/sanity-plugin-personalization)
```sh
npm install @sanity/personalization-plugin
```
When configuring the plugin you will need to specify which fields types to run experiments on, and the details of the experiments and their variants that we are running.
1. **Update** `sanity.config.ts` to configures the plugins field types and experiments
```typescript:sanity.config.ts
// ...all other imports
import {fieldLevelExperiments} from '@sanity/personalization-plugin'
export default defineConfig({
// ... all other config settings
plugins: [
// ...all other plugins
fieldLevelExperiments({
// field types that you want to be able to emperiment on
fields: ['string'],
// hardcoded experiments and variants
experiments: [
{
id: 'event-name',
label: 'Event Name',
variants: [
{
id: 'control',
label: 'Control',
},
{
id: 'variant',
label: 'Variant',
},
],
},
],
})
],
})
```
Adding a field will create a new type that we can use in our schema types. This type will be prefixed with `experiment`. In this example the new type to use in the schema will be `experimentString`. With this we can add the a new Name experimentation field to the schema of our event.
1. **Update** `eventType.ts` to add a `newName` field to schema of event
```typescript:schemaTypes/eventType.ts
export const eventType = defineType({
name: 'event',
title: 'Event',
icon: CalendarIcon,
type: 'document',
groups: [
{name: 'details', title: 'Details'},
{name: 'editorial', title: 'Editorial'},
],
fields: [
defineField({
name: 'name',
type: 'string',
group: ['editorial', 'details'],
}),
defineField({
name: 'newName',
type: 'experimentString',
group: ['editorial', 'details'],
}),
// ... and the rest
```
You're adding a new field using the new `experimentString` type to ensure you don't accidentally clear the existing value.
This will render the new experimentation field with a default value input.
Let's add content for our new field in the Studio:
* Add a default value to be used when the experiment is not running or if the user is not included in the experiment.
* Select add experiment on the field.
* Select which experiment you want to add the content for.
* Add content for the control
1. **Add** content for the A/B test
## Complex Field Types
When specifying the field types in the plugin config you can use Sanity Studio primitives, your own custom defined types, types from other plugins, or you can defined a type in the plugin config. You can add validation/options in the plugin config or on the schema definition.
```typescript:sanity.config.ts
// ...all other imports
import {defineArrayMember, defineConfig, defineField} from 'sanity'
import {fieldLevelExperiments} from '@sanity/personalization-plugin'
export default defineConfig({
// ...all other config
plugins: [
// ... all other plugins
fieldLevelExperiments({
fields: [
// primitives
'string',
'image',
'slug',
// custom defined types
'path',
// internationalized Array plugin types
'internationalizedArrayString',
// types defined in plugin config
defineField({
name: 'featuredAuthor',
type: 'reference',
to: [{type: 'author'}],
hidden: ({document}) => !document?.title,
validation: (Rule) => Rule.required()
}),
defineField({
name: 'customArray',
title: 'Custom Array',
type: 'array',
of: [defineArrayMember({type: 'object', fields: [{name: 'string', type: 'string'}]})],
}),
],
// experiements removed for brevity
}),
],
})
```
```typescript:schemaTypes/articleType.ts
import {defineField, defineType} from 'sanity'
export const path = defineType({
name: 'path',
type: 'string',
validation: (Rule) =>
Rule.required().custom((value: string | undefined, context) => {
if (!value) return true
if (!value.startsWith('/')) return 'Must start with "/"'
return true
}),
})
export const article = defineType({
name: 'article',
title: 'Article',
type: 'document',
fields: [
defineField({
name: 'title',
title: 'Title',
type: 'experimentString',
}),
defineField({
name: 'path',
title: 'Path',
type: 'experimentPath',
}),
defineField({
name: 'image',
title: 'Image',
type: 'experimentImage',
}),
defineField({
name: 'image',
title: 'Image',
type: 'experimentImage',
validation: (Rule) =>
Rule.custom((value: any) => {
if (!value.default) return 'Must have a default image'
if (value.active && (!value.variants || value.variants?.length === 0)) {
return 'Must have at least one variant'
}
return true
}),
}),
defineField({
name: 'featuredArtist',
title: 'Featured Artist',
type: 'experimentFeaturedArtist',
}),
defineField({
name: 'array',
type: 'experimentCustomArray',
}),
],
preview: {
select: {
title: 'title',
media: 'image',
},
prepare({title, media}) {
return {
title: title.default ? title.default : undefined,
subtitle: title.variants
? title.variants.map((variant: any) => variant.value).join(' | ')
: undefined,
media: media?.default ?? undefined,
}
},
},
})
```
## Getting experiments
You might consider using an external service to help with your A/B testing as they help with traffic allocation of your experiment on the frontend, connect with analytics platforms to give you information about your experiments, and they often have other features such as feature flagging and personalization.
When choosing a service you need to consider if the service meets your needs, what other tools might you need, and what the cost of the service will be.
You can connect `@sanity/personalization-plugin` to an external service by using an async function for getting your experiments and variants. This function will be passed a Sanity Client so you can use information stored in the Content Lake if needed, as in the example below.
```typescript:sanity.config.ts
import { getExperiments } from './utils/experiments'
export default defineConfig({
// ... all other config
plugins: [
// ... all other plugins
fieldLevelExperiments({
// .. field types
experiments: (client: SanityClient) => getExperiments(client),
}
],
})
```
```typescript:utils/experiments.ts
import {SanityClient} from 'sanity'
import {ExperimentType} from '@sanity/personalization-plugin'
export const getExperiments = async (client: SanityClient) => {
// secret is stored in the content lake using @sanity/studio-secrets
const query = `*[_id == 'secrets.namespace'][0].secrets.key`
const secret = await client.fetch(query)
if (!secret) {
return []
}
// call to external api to fetch experiments
const response = await fetch('https://example.api/experiments', {
headers: {
Authorization: `Bearer ${secret}`,
},
})
const {experiments: externalExperiments} = await response.json()
// map and transform to get experiments and their variations
const experiments: ExperimentType[] = externalExperiments?.map(
(experiment: externalExperiment) => {
const experimentId = experiment.id
const experimentLabel = experiment.name
const variants = experiment.variations?.map((variant) => {
return {
id: variant.variationId,
label: variant.name,
}
})
return {
id: experimentId,
label: experimentLabel,
variants,
}
},
)
return experiments
}
```
In the following lesson you will get the data for the experiment and add it to your Next.js application.## [Implementing an A/B test](/learn/course/a-b-testing/implementing-an-a-b-test)
How to query for data and how to setup an A/B test on a front end
Depending on how content is rendered will influence how you fetch data to be used on the page.
If your page is statically generated, changing its content is not achievable at build time. In this instance, you might want to apply a routing-based approach with middleware.
For server-side rendering, pass the values for which variant to use as parameters to your query. This might require middleware to set the user group and store it in a cookie.
For client-side rendering you can add the parameters to the fetch—or you can fetch all variants and then filter the results client-side.
To ensure a consistent experience for a user it is a good idea to set a cookie to store the value of the user group they have been assigned.
## Server-side filtering, in the query
For filtering on the query it may look something like this:
```groq
*[
_type == "event" &&
slug.current == $slug
][0]{
...,
"name": coalesce(
newName.variants[
experimentId == $experiment
&& variantId == $variant
][0].value,
newName.default,
name
),
"date": coalesce(date, now()),
"doorsOpen": coalesce(doorsOpen, 0),
headline->,
venue->
}
```
This query uses the `coalesce` function to get the correct variant based on the experiment and the variant. If those are not present or do not match you'll get the default value, and then fallback to the existing `name` field incase the data has not been migrated across.
You will need to pass along values for the `$experiment` and `$variant` query params. These should come from an external service or a cookie set on the user.
## Client-side filtering, in JavaScript
If you're unable to perform filtering server-side in the query, you may instead query for all variants, and then write a function like this which will look through all of the returned variants and return only one.
```typescript
const getExperimentContent = (field, experimentId, variantId) => {
return (
field.variants.find(
(variant) =>
variant.experimentId === experimentId &&
variant.variantId === variantId
)?.value || field.default
);
};
```
You also need to consider occasions where A/B tests are not running, and some users might be excluded from an experiment, so we need to ensure that we get a fallback value if this is the case.
## Implementing A/B Tests
1. The following details how to implement A/B tests in Next.js, but the same principles and implementation patterns could be repeated in any framework.
Let's try implementing the A/B test created in the Studio in the Next.js application. For this you'll use the hardcoded experiment that was initially added.
In order to get a working A/B test you'll need some way of assigning an ID and group to a user—using middleware—and retrieving the variant that user should see.
1. Learn more about [Next.js middleware](https://nextjs.org/docs/app/building-your-application/routing/middleware) in their documentation.
You'll also need a way to track if a user has viewed an experiment. This tracking would typically be done on an external A/B testing service like Google analytics, Segment, or others that could be linked up to a A/B testing service.
To be able to analyze the experiment we will need to know if a user has been included in an experiment and which variant they saw. What we can do is get the `userID` and `userGroup` and use this in a client component to send an event when the user has viewed the page with an experiment.
1. **Create** functions for getting variants, userId and setting user group
```typescript:src/lib/experiments.ts
import { v4 } from "uuid";
import { cookies } from "next/headers";
import type { NextRequest, NextResponse } from "next/server";
type Experiment = Record<
string,
{ label: string; variants: { id: string; label: string }[] }
>;
const EXPERIMENTS: Experiment = {
"event-name": {
label: "Event Name",
variants: [
{
id: "control",
label: "Control",
},
{
id: "variant",
label: "Variant",
},
],
},
};
const getTestCookie = async () => {
const cookieStore = await cookies();
return cookieStore.get("ab-test")?.value;
};
export const getUserGroup = async () => {
const testCookie = await getTestCookie();
return testCookie ? JSON.parse(testCookie)?.userGroup : "control";
};
// mocking a fetch to an external service for getting an experiment variant
export const getExperimentValue = async (experimentName: string) => {
const userGroup = await getUserGroup();
return {
variant: EXPERIMENTS[experimentName].variants.find(
(variant) => variant.id === userGroup
),
};
};
export const setCookiesValue = (
request: NextRequest,
response: NextResponse
) => {
if (!request.cookies.has("ab-test")) {
// randomly assign a user to a group
const userGroup = Math.random() > 0.5 ? "control" : "variant";
// create a user ID
const userId = v4();
// Setting cookies on the response using the `ResponseCookies` API
response.cookies.set("ab-test", JSON.stringify({ userGroup, userId }));
}
return response;
};
// If use is part of any experiments, get the tracking call data
// This is passed into the <Tracking> client component
export const getDeferredTrackingData = async (): Promise<
| {
userGroup: string;
userId: string;
}
| undefined
> => {
const testCookie = await getTestCookie();
const data = testCookie ? JSON.parse(testCookie) : undefined;
return data;
};
```
1. **Create** middleware to incepted the page request and storing the user group and user id as a cookie
```typescript:src/middleware.ts
import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";
import { setCookiesValue } from "./lib/experiments";
export function middleware(request: NextRequest) {
let response = NextResponse.next();
response = setCookiesValue(request, response);
return response;
}
export const config = {
matcher: [
/*
* Match all request paths except for the ones starting with:
* - api (API routes)
* - _next/static (static files)
* - _next/image (image optimization files)
* - favicon.ico, sitemap.xml, robots.txt (metadata files)
*/
"/((?!api|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
],
};
```
A new component is required to send back events when a user has been assigned an ID and a group and has partaken in an experiment.
The example code below only logs these events to the console. You would need to replace this with the integration of your choice for measuring experiments.
1. **Create** client component for sending tracking data
```typescript:src/components/tracking.tsx
"use client";
import { useEffect } from "react";
// Helper component to track experiment views from server components
export function Tracking({
userGroup,
userId,
}: {
userGroup: string;
userId: string;
}) {
useEffect(() => {
// TODO: track with Google Analytics, Segment, etc.
console.log("Viewed Experiment, send tracking", {
userGroup: userGroup,
userId: userId,
});
}, [userId, userGroup]);
return null;
}
```
Update the route for a single event to query for the correct variant as well as include the `Tracking` component.
1. **Update** the single event page route
```tsx:src/app/events/[slug]/page.tsx
import { getExperimentValue, getDeferredTrackingData } from "@/lib/experiments";
import { Tracking } from "@/components/tracking.tsx";
import { client } from "@/sanity/client";
import { sanityFetch } from "@/sanity/live";
import imageUrlBuilder from "@sanity/image-url";
import { SanityImageSource } from "@sanity/image-url/lib/types/types";
import { defineQuery, PortableText } from "next-sanity";
import Image from "next/image";
import Link from "next/link";
import { notFound } from "next/navigation";
const EVENT_QUERY = defineQuery(`*[
_type == "event" &&
slug.current == $slug
][0]{
...,
"name": coalesce(newName.variants[experimentId == $experiment && variantId == $variant][0].value, newName.default, name),
"date": coalesce(date, now()),
"doorsOpen": coalesce(doorsOpen, 0),
headline->,
venue->
}`);
const { projectId, dataset } = client.config();
const urlFor = (source: SanityImageSource) =>
projectId && dataset
? imageUrlBuilder({ projectId, dataset }).image(source)
: null;
export default async function EventPage({
params,
}: {
params: Promise<{ slug: string }>;
}) {
const { slug } = await params;
const { variant } = await getExperimentValue("event-name");
const trackingData = await getDeferredTrackingData();
const queryParams = {
slug,
experiment: "event-name",
variant: variant?.id || "",
};
const { data: event } = await sanityFetch({
query: EVENT_QUERY,
params: queryParams,
});
if (!event) {
notFound();
}
const {
name,
date,
headline,
image,
details,
eventType,
doorsOpen,
venue,
tickets,
} = event;
const eventImageUrl = image
? urlFor(image)?.width(550).height(310).url()
: null;
const eventDate = new Date(date).toDateString();
const eventTime = new Date(date).toLocaleTimeString();
const doorsOpenTime = new Date(
new Date(date).getTime() - doorsOpen * 60000
).toLocaleTimeString();
return (
<main className="container mx-auto grid gap-12 p-12">
<div className="mb-4">
<Link href="/">← Back to events</Link>
</div>
<div className="grid items-top gap-12 sm:grid-cols-2">
<Image
src={eventImageUrl || "https://placehold.co/550x310/png"}
alt={name || "Event"}
className="mx-auto aspect-video overflow-hidden rounded-xl object-cover object-center sm:w-full"
height="310"
width="550"
/>
<div className="flex flex-col justify-center space-y-4">
<div className="space-y-4">
{eventType ? (
<div className="inline-block rounded-lg bg-gray-100 px-3 py-1 text-sm dark:bg-gray-800 capitalize">
{eventType.replace("-", " ")}
</div>
) : null}
{name ? (
<h1 className="text-4xl font-bold tracking-tighter mb-8">
{name}
</h1>
) : null}
{headline?.name ? (
<dl className="grid grid-cols-2 gap-1 text-sm font-medium sm:gap-2 lg:text-base">
<dd className="font-semibold">Artist</dd>
<dt>{headline?.name}</dt>
</dl>
) : null}
<dl className="grid grid-cols-2 gap-1 text-sm font-medium sm:gap-2 lg:text-base">
<dd className="font-semibold">Date</dd>
<div>
{eventDate && <dt>{eventDate}</dt>}
{eventTime && <dt>{eventTime}</dt>}
</div>
</dl>
{doorsOpenTime ? (
<dl className="grid grid-cols-2 gap-1 text-sm font-medium sm:gap-2 lg:text-base">
<dd className="font-semibold">Doors Open</dd>
<div className="grid gap-1">
<dt>Doors Open</dt>
<dt>{doorsOpenTime}</dt>
</div>
</dl>
) : null}
{venue?.name ? (
<dl className="grid grid-cols-2 gap-1 text-sm font-medium sm:gap-2 lg:text-base">
<div className="flex items-start">
<dd className="font-semibold">Venue</dd>
</div>
<div className="grid gap-1">
<dt>{venue.name}</dt>
</div>
</dl>
) : null}
</div>
{details && details.length > 0 && (
<div className="prose max-w-none">
<PortableText value={details} />
</div>
)}
{tickets && (
<a
className="flex items-center justify-center rounded-md bg-blue-500 p-4 text-white"
href={tickets}
>
Buy Tickets
</a>
)}
</div>
</div>
{trackingData && (
<Tracking
userGroup={trackingData.userGroup}
userId={trackingData.userId}
/>
)}
</main>
);
}
```
With this done you will now see that a cookie is set when you visit an event page, and that based on that cookie and the content in your Sanity Studio the name of the event will show 1 of 3 options (the default if no experiment matches, the control for an experiment, or the variant).
If you remove the cookie and refresh the page you will see a new cookie is added and there is a random chance it will be assigned a different group, thus potentially showing you a different name.
Let's test everything you've learned in the final lesson with a quiz.## [A/B Testing quiz](/learn/course/a-b-testing/a-b-testing-quiz)
You have made it this far 🎉, lets have a quiz to put your A/B testing knowledge to the ... test.
**Question:** What is A/B Testing?
1. A way to compare two versions of content to see which has the most page views
2. A way to compare two versions of content to see which performs better.
3. A way to convince your boss that your idea is better by showing them two versions of it and hoping they pick the one you want.
4. A way to pick at random what content you should use
**Question:** What are common names for the A/B test versions?
1. Control and Comparison
2. Control and Benchmark
3. Benchmark and Variant
4. Control and Variant
5. Comparison and Variant
**Question:** How do you assign a user to a group?
1. Assign them based on what you think they will prefer
2. First x see version 1, then next y see version 2
3. At random but aware of biases like screen size
4. By location
**Question:** When using the fieldLevelExperiments plugin from @sanity/personalization-plugin what would be the name of the type to use for an experiment on a text field?
1. experimentText
2. testText
3. customText
4. textExperiment
**Question:** When using a function to get experiments in the fieldLevelExperiments plugin, what is passed in?
1. current user
2. schema
3. sanity client
**Question:** How do you ensure a consistent user experience when doing A/B testing?
1. Only run one experiment at a time
2. Only show one variant at a time
3. Add a cookie to store which variant a user sees
4. Ask the user what version they want to see# [Integrated Visual Editing with Next.js](/learn/course/visual-editing-with-next-js)
The ultimate upgrade for content authors is to have absolute confidence in the impact of their work before they press publish – as well as the tools to rapidly find and update even the most minor pieces of content.
## [Understanding Visual Editing](/learn/course/visual-editing-with-next-js/understanding-visual-editing)
Visual Editing is powered by a combination of Sanity features, which is helpful to understand before implementation.
Content creators will find it highly beneficial to preview the impact of their work before pressing publish. An interactive live preview will give them greater confidence to do so.
Visual Editing is the catch-all term for the ability for content creators to make and see the impact of content changes in real-time, even when working on draft documents. It also describes navigating the website to find and edit content instead of browsing through document lists in the Sanity Studio Structure tool.
## Goals of this course
Once you have completed this course, you will:
* Know how to create, store, and access Sanity project tokens so your application can query for private documents such as draft documents.
* Enable Next.js "draft mode" for authenticated users to put your application into a dynamic state.
* Configure the Presentation plugin to browse and edit the application within Sanity Studio.
* In the Studio, configure document "locations" so content creators can move quickly between the Structure and Presentation tools.
* Switch data fetching to React Loader for enhanced Visual Editing with faster previews.
### Glossary
The following terms describe the functions that combine to create an interactive live preview: [**Visual Editing**](https://www.sanity.io/docs/introduction-to-visual-editing).
Visual Editing can be enabled on **any** hosting platform or [front end](https://www.sanity.io/glossary/front-end) framework.
* [**Perspectives**](https://www.sanity.io/docs/perspectives) modify queries to return either draft or published content. These are especially useful for server-side fetching to display draft content on the initial load when previewing drafts.
* [**Content Source Maps**](https://www.sanity.io/docs/content-source-maps) aren't something you'll need to interact with directly, but they are used by Stega encoding (below) when enabled. They are an extra response from the [Content Lake](https://www.sanity.io/docs/datastore) that notes the full path of every field of returned content.
* [**Stega encoding**](https://www.sanity.io/docs/stega) is when the Sanity Client takes Content Source Maps and combines every field of returned content with an invisible string of characters, which contains the full path from the content to the field within its source document.
* [**Overlays**](https://www.sanity.io/docs/visual-editing-overlays) are created by a dedicated package that looks through the DOM for these Stega encoded strings and creates clickable links to edit documents.
* [**Presentation**](https://www.sanity.io/docs/presentation) is a plugin included with Sanity Studio to simplify displaying a front end inside an iframe with an adjacent document editor. It can communicate directly with the front end instead of making round-trips to the Content Lake for faster live preview.
* [**Draft mode**](https://nextjs.org/docs/app/building-your-application/configuring/draft-mode) is a Next.js-specific way of enabling, checking, and disabling a global variable available during requests, primarily used to make your application query draft content.
* In other frameworks, you might replace this with an environment variable, cookie, or session.
Let's get started.## [Token handling and security](/learn/course/visual-editing-with-next-js/token-handling-and-security)
To access draft content your application will need to be authenticated with a token. Learn how to do this securely.
In a public dataset, documents are kept private in the Content Lake when they have a period (`.`) in the `_id` attribute. For example, draft document IDs begin with a `drafts.` prefix.
Authentication will also be required to use the `previewDrafts` "perspective," a method of performing a GROQ query that returns the latest draft version of a document instead of an already-published document.
1. Learn more about [Perspectives for Content Lake](https://www.sanity.io/learn/content-lake/perspectives) in the documentation
To view draft content, requests to the Content Lake require authentication.
On the client side, the same credentials that allow authors to log in to Sanity Studio will handle this. On the server side, an API token will be required.
1. Learn more about [Authentication](https://www.sanity.io/learn/content-lake/http-auth) in the documentation
## Creating an API token
Access tokens can be created from Manage or the API.
You can access Manage for your project either from the menu at the top left of your Studio:
Or you can automatically open your browser to the Manage page of your project from the command line:
```text
pnpm dlx sanity manage
```
1. In Manage, go to the "API" tab and create a token with "Viewer" permissions
1. **Update** your `.env.local` file to include the token
```text:.env.local
NEXT_PUBLIC_SANITY_PROJECT_ID="your-project-id"
NEXT_PUBLIC_SANITY_DATASET="your-dataset-name"
# 👇 add this line
SANITY_API_READ_TOKEN="your-new-token"
```
1. It is your responsibility to secure this token. Unencrypted access could allow a user to read any document from any dataset in your project. The way it is implemented in this course should never lead to it being included in your code bundle.
You may need to restart your development environment to make the token available. The file below will throw an error if the token is not found in your environment variables.
1. **Create** a new file to store, protect, and export this token
```typescript:src/sanity/lib/token.ts
export const token = process.env.SANITY_API_READ_TOKEN
if (!token) {
throw new Error('Missing SANITY_API_READ_TOKEN')
}
```
Now the token can be exported from a reliable location. In the next lesson you'll add it to the `defineLive` function.## [Receiving live edits to drafts](/learn/course/visual-editing-with-next-js/fetching-preview-content-in-draft-mode)
Add perspectives to your Sanity data fetches to query for draft content, when Draft Mode is enabled.
For interactive live preview to be truly immersive, the same fast, cached web application your end users interact with must be put into an API-first, fully dynamic state. Thankfully, Next.js provides "Draft Mode."
1. See the Next.js documentation for more details on [Draft Mode](https://nextjs.org/docs/app/building-your-application/configuring/draft-mode).
For Visual Editing to work, the entire application must act differently when Draft Mode is enabled. Queries must use a different perspective and entirely skip the cache. Additional UI will be rendered into the page for clickable overlays. Thankfully this complexity is handled inside `SanityLive` and another component you'll import called `VisualEditing`.
## Fetching in draft mode
First you'll need to update the content fetching functions to apply token authentication and settings required for Visual Editing.
### Update Sanity Client
The update below adds Stega encoding to the Sanity Client configuration. This will only be used when Draft Mode is enabled. The URL is used to create clickable links in the preview, which open to the correct document and field from which the content came.
1. **Update** the Sanity Client file to include Stega encoding
```typescript:src/sanity/lib/client.ts
export const client = createClient({
projectId,
dataset,
apiVersion,
useCdn: true,
stega: { studioUrl: '/studio' },
})
```
### Update live mode helpers
The token you created in the previous lesson will now need to be passed to the live mode helpers, so that live draft content will be sent to the browser.
These tokens will only be used when the site is in Draft Mode, which is only enabled by users in the Presentation tool in the Studio, or by anyone you share a preview link with.
The token is not stored in the production app code.
1. **Update** the live mode helpers to set a `browserToken` and `serverToken`
```typescript:src/sanity/lib/live.ts
import { client } from "@/sanity/lib/client";
import { token } from "@/sanity/lib/token"
import { defineLive } from "next-sanity/live";
export const { sanityFetch, SanityLive } = defineLive({
client,
browserToken: token,
serverToken: token,
});
```
## Powering Visual Editing in Draft Mode
Interactive live preview works by listening client-side to changes from your dataset and, when detected, prefetching data server-side. The machinery to do this can be configured manually if you like, but it gets a little complicated, so thankfully, it's been packaged up for us in `next-sanity`.
When Draft Mode is enabled, it's helpful to have a button to disable it.
1. **Create** a component to allow a user to disable Draft Mode
```tsx:src/components/disable-draft-mode.tsx
'use client'
import { useDraftModeEnvironment } from 'next-sanity/hooks'
export function DisableDraftMode() {
const environment = useDraftModeEnvironment()
// Only show the disable draft mode button when outside of Presentation Tool
if (environment !== 'live' && environment !== 'unknown') {
return null
}
return (
<a
href="/api/draft-mode/disable"
className="fixed bottom-4 right-4 bg-gray-50 px-4 py-2"
>
Disable Draft Mode
</a>
)
}
```
To power Visual Editing, all you need is one import.
1. **Update** your root layout to import the `VisualEditing` component from `next-sanity/visual-editing`
```tsx:src/app/(frontend)/layout.tsx
import { draftMode } from 'next/headers'
import { VisualEditing } from 'next-sanity/visual-editing'
import { DisableDraftMode } from '@/components/disable-draft-mode'
import { Header } from '@/components/header'
import { SanityLive } from '@/sanity/lib/live'
export default async function FrontendLayout({
children,
}: Readonly<{
children: React.ReactNode
}>) {
return (
<section className="bg-white min-h-screen">
<Header />
{children}
<SanityLive />
{(await draftMode()).isEnabled && (
<>
<DisableDraftMode />
<VisualEditing />
</>
)}
</section>
)
}
```
## Activating draft mode
The Presentation tool maintains an automatically rotating secret stored in the dataset. This is so your Next.js application can confirm that same secret before proceeding with any attempt to enable draft mode.
Thankfully, this entire handshake has been made into a simple helper function from `next-sanity`.
1. **Create** a new API route to enable draft mode
```typescript:src/app/api/draft-mode/enable/route.ts
/**
* This file is used to allow Presentation to set the app in Draft Mode, which will load Visual Editing
* and query draft content and preview the content as it will appear once everything is published
*/
import { defineEnableDraftMode } from 'next-sanity/draft-mode'
import { client } from '@/sanity/lib/client'
import { token } from '@/sanity/lib/token'
export const { GET } = defineEnableDraftMode({
client: client.withConfig({ token }),
})
```
### Disabling draft mode
Once your browser is authenticated to view the web application in draft mode, you will see it in all other tabs in that browser.
The earlier update to the root layout included a button to disable preview mode. This is useful when content authors have finished their changes and want to see the application with the same published content that end users will see.
1. **Create** a new API route to disable draft mode
```typescript:src/app/api/draft-mode/disable/route.ts
import { draftMode } from 'next/headers'
import { NextRequest, NextResponse } from 'next/server'
export async function GET(request: NextRequest) {
;(await draftMode()).disable()
return NextResponse.redirect(new URL('/', request.url))
}
```
Your app is ready to start receiving draft content updates—the next step is to actually make that happen. It's easiest to do this within the Presentation plugin; let's set that up in the next lesson.## [Configuring Presentation](/learn/course/visual-editing-with-next-js/configuring-presentation)
Install and configure the Presentation plugin to enable draft preview and a web preview from within Sanity Studio
Everything you have configured so far has been to prepare the site for when it is put into Draft Mode. To do this securely and automatically, you'll install and configure the [Presentation plugin](https://www.sanity.io/docs/configuring-the-presentation-tool). It will handle creating and requesting a URL to enable Draft Mode with a secret string in the URL that is checked in your API route.
It is also the most convenient way to browse and edit the website in Draft Mode, with an iframe displaying an interactive preview inside the Sanity Studio.
First you'll need to add the plugin to your Sanity Studio configuration.
1. **Update** your `sanity.config.ts` file to import the Presentation tool
```typescript:sanity.config.ts
// ...all other imports
import { presentationTool } from 'sanity/presentation'
export default defineConfig({
// ... all other config settings
plugins: [
// ...all other plugins
presentationTool({
previewUrl: {
previewMode: {
enable: '/api/draft-mode/enable',
},
},
}),
],
})
```
Notice how the plugin's configuration includes the "enable" API route you created in the previous lesson. Presentation will visit this route first, confirm an automatically generated secret from the dataset, and if successful, activate draft mode in the Next.js application.
You should now see the Presentation tool in the top toolbar of the Studio or by visiting [http://localhost:3000/studio/presentation](http://localhost:3000/studio/presentation) where you can navigate the site and click on any Sanity content to open the document – and focus the field – from which that content came.
Because of the `previewDrafts` perspective, the post index route now displays a list of draft **and** published post documents. The latest draft content should appear on already published post documents.
Make edits to any content, and you should see them reflected live on the page.
Success! You now have an interactive live preview conveniently located within your Sanity Studio. Content authors can browse the front end to find pieces of content they need to edit and instantly see the impact of their changes before pressing publish.
We can go deeper. In the next lesson, you'll make the experience of switching between the Structure and Presentation tools even better.## [Setup document locations](/learn/course/visual-editing-with-next-js/setup-document-locations)
Showing where in the application the document they're editing may be displayed can help content creators understand the impact of their changes.
The content of a document may be used in multiple places. For example, currently in your blog, a post’s title is shown both on the individual post route and on the post index page.
When viewing a document, to show where its content is used, you can list paths in your web application to generate one-click links to those pages and view them inside the Presentation tool.
1. **Create** a new file for the `resolve` option in the Presentation plugin options:
```typescript:src/sanity/presentation/resolve.ts
import { defineLocations, PresentationPluginOptions } from 'sanity/presentation'
export const resolve: PresentationPluginOptions['resolve'] = {
locations: {
// Add more locations for other post types
post: defineLocations({
select: {
title: 'title',
slug: 'slug.current',
},
resolve: (doc) => ({
locations: [
{
title: doc?.title || 'Untitled',
href: `/posts/${doc?.slug}`,
},
{ title: 'Posts index', href: `/posts` },
],
}),
}),
},
}
```
In the `locations` key above, `post` is the document schema type from which these locations will render. As you build out your web application and content model, you will extend this configuration to include more document types that render routes – or appear on them.
1. **Update** your `sanity.config.ts` file to import the locate function into the Presentation plugin.
```typescript:sanity.config.ts
// ...all other imports
import { resolve } from '@/sanity/presentation/resolve'
export default defineConfig({
// ... all other config settings
plugins: [
// ...all other plugins
presentationTool({
resolve,
previewUrl: {
draftMode: {
enable: '/api/draft-mode/enable',
},
},
}),
],
})
```
You should now see the locations at the top of all `post`-type documents:
Now, your content authors can seamlessly move between the front-end-focused Presentation tool – and the structure-focused Structure tool.
Believe it or not, we can go _even deeper_. One part of the Presentation tool is disabled: the toggle to switch between Drafts and Published perspectives. To enable that, we need to implement React Loader, which has the added benefit of even faster live previews.## [Add drag-and-drop elements](/learn/course/visual-editing-with-next-js/add-drag-and-drop-elements)
Go beyond "click-to-edit" with additional affordances for rearranging arrays in your front end
### Add "related posts" to your posts
1. **Update** the `post` schema type fields to include an array of "related posts" to render at the bottom of your `post` type documents.
```typescript:src/sanity/schemaTypes/postType.ts
export const postType = defineType({
// ...all other settings
fields: [
// ...all other fields
defineField({
name: "relatedPosts",
type: "array",
of: [{ type: "reference", to: { type: "post" } }],
}),
],
});
```
1. **Update** your single post query to return the array and resolve any references.
```typescript:src/sanity/lib/queries.ts
export const POST_QUERY =
defineQuery(`*[_type == "post" && slug.current == $slug][0]{
_id,
title,
body,
mainImage,
publishedAt,
"categories": coalesce(
categories[]->{
_id,
slug,
title
},
[]
),
author->{
name,
image
},
relatedPosts[]{
_key, // required for drag and drop
...@->{_id, title, slug} // get fields from the referenced post
}
}`);
```
1. **Update** your types now that the GROQ query has changed.
```sh
pnpm run typegen
```
1. **Create** a new component to render the related Posts
```tsx:src/components/related-posts.tsx
'use client'
import Link from 'next/link'
import { createDataAttribute } from 'next-sanity'
import { useOptimistic } from 'next-sanity/hooks'
import { POST_QUERYResult } from '@/sanity/types'
import { client } from '@/sanity/lib/client'
const { projectId, dataset, stega } = client.config()
export const createDataAttributeConfig = {
projectId,
dataset,
baseUrl: typeof stega.studioUrl === 'string' ? stega.studioUrl : '',
}
export function RelatedPosts({
relatedPosts,
documentId,
documentType,
}: {
relatedPosts: NonNullable<POST_QUERYResult>['relatedPosts']
documentId: string
documentType: string
}) {
const posts = useOptimistic<
NonNullable<POST_QUERYResult>['relatedPosts'] | undefined,
NonNullable<POST_QUERYResult>
>(relatedPosts, (state, action) => {
if (action.id === documentId && action?.document?.relatedPosts) {
// Optimistic document only has _ref values, not resolved references
return action.document.relatedPosts.map(
(post) => state?.find((p) => p._key === post._key) ?? post
)
}
return state
})
if (!posts) {
return null
}
return (
<aside className="border-t">
<h2>Related Posts</h2>
<div className="not-prose text-balance">
<ul
className="flex flex-col sm:flex-row gap-0.5"
data-sanity={createDataAttribute({
...createDataAttributeConfig,
id: documentId,
type: documentType,
path: 'relatedPosts',
}).toString()}
>
{posts.map((post) => (
<li
key={post._key}
className="p-4 bg-blue-50 sm:w-1/3 flex-shrink-0"
data-sanity={createDataAttribute({
...createDataAttributeConfig,
id: documentId,
type: documentType,
path: `relatedPosts[_key=="${post._key}"]`,
}).toString()}
>
<Link href={`/posts/${post?.slug?.current}`}>{post.title}</Link>
</li>
))}
</ul>
</div>
</aside>
)
}
```
You will notice `data-sanity` attributes being added to the wrapping and individual tags of the list. As well as a useOptimistic hook to apply these changes in the UI immediately, while the mutation in the content lake is still happening.
1. **Update** the `Post` component to include the `RelatedPosts` component.
```tsx:src/components/post.tsx
import Image from "next/image";
import { PortableText } from "next-sanity";
import { Author } from "@/components/author";
import { Categories } from "@/components/categories";
import { components } from "@/sanity/portableTextComponents";
import { POST_QUERYResult } from "@/sanity/types";
import { PublishedAt } from "@/components/published-at";
import { Title } from "@/components/title";
import { urlFor } from "@/sanity/lib/image";
import { RelatedPosts } from "@/components/related-posts";
export function Post(props: NonNullable<POST_QUERYResult>) {
const {
_id,
title,
author,
mainImage,
body,
publishedAt,
categories,
relatedPosts,
} = props;
return (
<article className="grid lg:grid-cols-12 gap-y-12">
<header className="lg:col-span-12 flex flex-col gap-4 items-start">
<div className="flex gap-4 items-center">
<Categories categories={categories} />
<PublishedAt publishedAt={publishedAt} />
</div>
<Title>{title}
) : null}
{body ? (
` component from [`sanity-plugin-utils`](https://github.com/SimeonGriggs/sanity-plugin-utils) makes for a nice user experience.
1. **Gotcha** – initial values are only applied at the time of document creation. If you’re adding them retrospectively, you’ll need to patch the user values to pre-existing documents. The [Handling schema changes confidently](https://www.sanity.io/learn/course/handling-schema-changes-confidently) course covers handling data migrations / modifications like this.
Following the addition of this field, we can make use of the `StructureResolverContext` to make adjustments in the Structure of our Studio.
1. **Update** your Structure to the code below to create your filtered list of articles
```typescript:src/structure/index.tsx
import {DocumentsIcon} from '@sanity/icons'
import type {ConfigContext} from 'sanity'
import type {
DocumentListBuilder,
StructureBuilder,
StructureResolver,
} from 'sanity/structure'
const API_VERSION = '2023-01-01'
function defineStructure(
factory: (S: StructureBuilder, context: ConfigContext) => StructureType,
) {
return factory
}
export const structure: StructureResolver = (S, context) =>
S.list()
.id('root')
.title('Content')
.items([
S.listItem()
.title('Articles')
.icon(DocumentsIcon)
.schemaType('article')
.child(createArticleList(S, context)),
// other structure items...
])
const createArticleList = defineStructure((S, context) => {
const user = context?.currentUser
const roles = user?.roles.map((r) => r.name)
const isLimited = roles?.includes('article-editor')
let userQuery = ``
if (isLimited) {
userQuery = `createdBy == $userId`
} else {
userQuery = ``
}
return S.documentTypeList('article')
.title(`Articles`)
.filter([`_type == "article"`, userQuery].filter(Boolean).join(` && `))
.params({userId: user?.id})
.apiVersion(API_VERSION)
})
```
What's going on here?
Firstly, a `defineStructure()` factory function helps Typescript to determine the types we expect for the various customizations being made.
In the Structure, the list item child for articles is passed a `createArticleList()` function - this grabs the user from the context and maps their roles into an array of strings. These roles can then be tested to see if the `article-editor` role is present.
In the case where this role is present, the article list should be limited. Therefore a filter is applied to the `documentTypeList` by joining `createdBy == $userId` to our query and passing the user ID as a parameter.
### User specific stores
Another requirement is to only show relevant store offers in the Structure. Essentially, the requirement is to show offers only when a user is a store manager, a regional manager or an administrator.
If I am none of these, I don’t want to see anything concerning stores or offers in the Structure in order to remove clutter and improve my experience:
If I am the manager of a single store – “Store 1” – then I’m only interested in offers for my particular store:
However, if I manage multiple stores, I want to be able to access offers for all of these stores:
Note that in the case of managing a single store, the item is at the _top-level_ of the Structure - whereas when I manage multiple, these are nested under an “Offers” list item.
1. **Update** your Structure to the code below to add offers to your structure
```typescript:src/structure/index.tsx
import {DocumentsIcon, HomeIcon, TagIcon} from '@sanity/icons'
import type {ConfigContext} from 'sanity'
import type {
DocumentListBuilder,
ListItemBuilder,
StructureBuilder,
StructureResolver,
} from 'sanity/structure'
import {stores} from '../lib/constants'
const API_VERSION = '2023-01-01'
function defineStructure(
factory: (S: StructureBuilder, context: ConfigContext) => StructureType,
) {
return factory
}
export const structure: StructureResolver = (S, context) =>
S.list()
.id('root')
.title('Content')
.items([
S.listItem()
.title('Articles')
.icon(DocumentsIcon)
.schemaType('article')
.child(createArticleList(S, context)),
...[createOffers(S, context) as ListItemBuilder].filter(Boolean),
])
const createArticleList = defineStructure((S, context) => {
const user = context?.currentUser
const roles = user?.roles.map((r) => r.name)
const isLimited = roles?.includes('article-editor')
let userQuery = ``
if (isLimited) {
userQuery = `createdBy == $userId`
} else {
userQuery = ``
}
return S.documentTypeList('article')
.title(`Articles`)
.filter([`_type == "article"`, userQuery].filter(Boolean).join(` && `))
.params({userId: user?.id})
.apiVersion(API_VERSION)
})
const createOffers = defineStructure((S, context) => {
const roles = context?.currentUser?.roles.map((r) => r.name)
const storesManaged = roles?.filter((r) => r.endsWith('-manager')).length
if ((storesManaged && storesManaged > 1) || roles?.includes('administrator')) {
return S.listItem()
.title('Offers')
.icon(TagIcon)
.child(
S.list()
.title('Offers')
.items(createStoreOffers(S, context) as ListItemBuilder[]),
)
} else if (storesManaged && storesManaged == 1) {
return createStoreOffers(S, context) as ListItemBuilder
}
})
const createStoreOffers = defineStructure((S, context) => {
const roles = context?.currentUser?.roles.map((r) => r.name)
const userStores =
stores
.map((store) => {
if (roles?.includes(`${store.id}-manager`) || roles?.includes('administrator')) {
return S.listItem()
.title(`${store.name} Offers`)
.icon(HomeIcon)
.child(
S.documentTypeList('offer')
.title(`${store.name} Offers`)
.filter(`_type == "offer" && store == $storeId`)
.params({storeId: store.id})
.apiVersion(API_VERSION)
)
}
})
.filter((item) => !!item) || []
return userStores?.length == 1 ? userStores[0] : userStores
})
```
This adds two new functions - `createOffers()` and `createStoreOffers()`. The `createOffers` function essentially checks whether the user has access to multiple stores or a single store. If they manage multiple, then a `listItem` is returned to add a top level item. In the case of single store management, then the `createStoreOffers()` function is returned.
At the top level, the returned values are spread into an array and a filter applied to remove empty items:
```typescript:src/structure/index.tsx
...[createOffers(S, context) as ListItemBuilder].filter(Boolean)
```
This allows us to return `undefined` from `createOffers` where the user does not have access to a store - as list items can’t accept undefined, this ensures compatibility with the expected types.
The `createStoreOffers()` function handles the output of the list item for each store, and includes a child `documentTypeList` which includes a filter to filter offers based on store ID.
1. Here we’ve customized just one section of our Structure, but you could create a completely unique Structures for different user roles in your business. For example, legal teams could just see legal content and merchandising teams could just see product information.
## Creating new documents
With this type of setup, it’s important to ensure that users can create new documents that they have relevant permissions for. Right now, even though a user profile may have “Store 1 Manager” and “Store 2 Manager” permissions, they won’t be able to create a new document:
The reason for this is that when a new offer document is created, the “store” field will be empty – and these users only have permission to make edits when this field matches their store.
### Initial Value Templates
To solve this, initial value templates can be implemented in the Structure. These allow parameters to be passed based on where the user is in the Structure, so users can create offers relevant to the store list they’re viewing.
1. **Update** your `sanity.config.ts` to define a new [parameterized initial value template](https://www.sanity.io/docs/initial-value-templates#66d873e2136f)
```typescript:sanity.config.ts
export default defineConfig({
// rest of config
schema: {
types: schemaTypes,
templates: (prev, context) => {
const {currentUser} = context
return [
...prev,
{
id: 'offer-by-store',
title: 'Offer by store',
description: 'Offer from a specific store',
schemaType: 'offer',
parameters: [
{name: 'store', type: 'string'},
{name: 'createdBy', type: 'string'},
],
value: (params: {store: string}) => ({
store: params.store,
createdBy: currentUser?.id,
}),
},
]
},
},
})
```
Note that context can be used here - so contextual values based on the user could be populated - like user ID to a `createdBy` field. The key here though is that a `store` parameter is defined which can be passed from our Structure.
1. **Update** the `createStoreOffers()` function in the Structure with the below code to set an initial value template for the store list
```typescript:src/structure/index.tsx
const createStoreOffers = defineStructure((S, context) => {
const roles = context?.currentUser?.roles.map((r) => r.name)
const userStores =
stores
.map((store) => {
if (roles?.includes(`${store.id}-manager`) || roles?.includes('administrator')) {
return S.listItem()
.title(`${store.name} Offers`)
.icon(HomeIcon)
.child(
S.documentTypeList('offer')
.title(`${store.name} Offers`)
.filter(`_type == "offer" && store == $storeId`)
.params({storeId: store.id})
.apiVersion(API_VERSION)
.initialValueTemplates([
S.initialValueTemplateItem('offer-by-store', {store: store.id}),
]),
)
}
})
.filter((item) => !!item) || []
return userStores?.length == 1 ? userStores[0] : userStores
})
```
Now that this is setup, users can create new offers based on the context of the store they’re looking at, and the `store` field will be populated automatically:
This concept can be very useful outside of the context of role-based customizations, too!
### New Document Options
In addition to adding new documents via the Structure, users might also look to the “Create +” button in the Studio navigation bar.
Similarly to the Structure, the default options here may be disabled due to the permissions and initial values set up, again meaning a user can’t create documents with blank fields.
1. **Update** your `sanity.config.ts` with the below code to change the available new document options
```typescript:sanity.config.ts
export default defineConfig({
// rest of config
document: {
newDocumentOptions: (prev, {currentUser}) => {
let removeTypes = ['media.tag', 'offer']
const storeTemplates = stores.map((store) => {
if (
userHasRole(currentUser, `${store.id}-manager`) ||
userHasRole(currentUser, 'administrator')
) {
return {
id: `${store.id}-offer`,
templateId: 'offer-by-store',
title: `${store.name} Offer`,
parameters: {
store: store.id,
},
type: 'template',
}
}
}) as TemplateItem[]
if (
!userHasRole(currentUser, 'administrator') &&
!userHasRole(currentUser, 'article-editor')
) {
removeTypes.push('article')
}
return [...prev, ...storeTemplates.filter(Boolean)].filter(
(templateItem) => !removeTypes.includes(templateItem.templateId),
)
},
},
})
```
This customizes the available options when creating new documents to hide some options based on the user role – for example, removing the article type for users who aren’t admins or article editors and hiding metadata documents created by `sanity-plugin-media` .
Additionally, we’re using this menu to add the parameterized initial value templates too. This allows users to create documents for their own stores from the global menu.
## Custom components
There are some occasions that you might want to create custom components that are conditional based on user or role. This might include form components such as custom input components or could include other components like customizing the Studio layout, navbar or tool menu.
1. **Create** a `StoreInput` component and add the below code to it
```typescript:src/components/StoreInput.tsx
import {Button, Grid, Text} from '@sanity/ui'
import {useCallback} from 'react'
import {set, type StringInputProps, type TitledListValue, useCurrentUser, userHasRole} from 'sanity'
export default function StoreInput(props: StringInputProps) {
const {value, onChange, schemaType} = props
const user = useCurrentUser()
const roles = user?.roles.flatMap((r) => r.name)
const handleClick = useCallback(
(event: React.MouseEvent) => {
const nextValue = event.currentTarget.value
onChange(set(nextValue))
},
[onChange],
)
const stores = (schemaType?.options?.list as Array>)?.filter(
(option) => {
return roles?.includes(`${option.value}-manager`) || userHasRole(user, 'administrator')
},
)
return (
{stores?.map((store) => (
))}
)
}
```
1. Add the custom input component to the `store` field of your offer document
```typescript:src/schemaTypes/offer.ts
defineField({
name: 'store',
title: 'Store',
type: 'string',
options: {
list: stores.map((store) => {
return {
value: store.id,
title: store.name,
}
}),
},
components: {
input: StoreInput,
},
}),
```
This input component demonstrates a few ideas:
1. Replacing the default radio input with buttons.
2. When the user is an admin, ensure the default options are rendered.
3. When the user is not an admin, adjust the available buttons to only show stores the user has access to, rather than the full list.
The screenshot below illustrates the Studio with no custom input alongside the views of an admin and a user with a limited number of stores. The custom component simplifies the user interface based on the users' role(s).
This is a simple example to illustrate the point – you could implement similar principles to:
* Provide additional instructions alongside a field for users of a certain role.
* Change how a third party API is called in an input component based on user role.
* Amend the UI for content input based on whether a user is a developer or marketer.
## Conditional plugin configuration
Unfortunately, it’s not currently possible to customize plugin initialization based on role, as there is no user context here.
However, it is possible to selective (de)compose elements of a plugin in order to remove elements of a plugin based on user role. For example, the custom tool in `sanity-plugin-media` could be removed for some users by adding a custom plugin _after_ the media plugin:
```typescript:sanity.config.ts
export default defineConfig({
// rest of config
plugins: [
// other plugins
media(),
{
name: 'disable-media-tool',
tools: (prev, {currentUser}) =>
userHasRole(currentUser, 'article-editor')
? prev.filter((tool) => tool.name !== 'media')
: prev,
},
],
})
```
## Workspaces per role
The Sanity Studio can have multiple workspaces - and each of these can have it’s own configuration. It’s a great idea to enable workspaces _per role…_ for example, if I’m in a certain team, I want to work on certain content, in a particular workspace.
This _is_ possible, but there is a caveat: when the Studio is initialized, the Studio configuration is handled before the user is authenticated - this means we don't know who the user is until after the workspaces are set up.
Because of this, you need to _wrap your Studio_ to embed it in another React application. This allows you to make an API call to the user endpoint prior to initialization and provide different configuration based on the result.
Alternatively, you can [amend the Vite configuration](https://www.sanity.io/docs/development#9c7158c423fb) to allow for top-level async – but this can impact on some CLI commands such as GraphQL deployments, Typegen and document validation.
If this is something you would like to achieve, please speak to your Solution Architect.## [Roles quiz](/learn/course/introduction-to-users-and-roles/roles-quiz)
A short test of everything you've learned through this course.
**Question:** Custom roles are great for
1. Customizing the user experience of the Studio
2. Ensuring security, compliance and content integrity
3. Content workflows
4. Localization and market-specific content
5. All of the above
**Question:** If a user is assigned the default "editor" role and a custom role which can only edit "article" documents, what can that user edit?
1. Nothing, because the roles conflict
2. Only the "article" documents
3. All documents
**Question:** If I need to restrict the ability of a role to view certain documents, how should I configure my dataset?
1. It should be public
2. It should be private
**Question:** What are content resources?
1. A set of documents in a dataset defined by a GROQ filter
2. Custom roles created for specific users
3. An API endpoint for selecting a group of documents
4. Schemas that define document structures
**Question:** What does SAML role mapping allow you to do?
1. Control Studio access for groups of users
2. Set conditional access rules for specific content
3. Assign roles to users based on roles from a third-party identity provider
4. Navigate between two users' geographical locations
**Question:** Which functions in Sanity Studio can you use to check the current user and validate their role?
1. getUser() and hasPermission()
2. useCurrentUser() and userHasRole()
3. fetchUser() and roleChecker()
4. whoAmI() and canIHazRole()
**Question:** What value do end users get from studio customizations based on their role(s)?
1. A tailored editing experience that aligns with their responsibilities
2. Access to all hidden fields and content, regardless of their role
3. Dynamic Studio themes that match their favorite colors and personal tastes
4. An additional eight week vacation because of the efficiencies they enjoy
{title}
{mainImage ? (
- Posts
- Sanity Studio
Posts index →
Post index
-
{posts.map((post) => (
- {post?.title} ))}
← Return home