sanity-io / next-sanity

next-sanity The all-in-one [Sanity][sanity] toolkit for production-grade content-editable Next.js applications. **Features:** • [Sanity Client][sanity-client] for queries and mutations, fully compatible with the [Next.js cache][next-cache] • [Visual Editing][visual-editing] for interactive live preview of draft content • [Embedded Sanity Studio][sanity-studio], a deeply-configurable content editing dashboard • [GROQ][groq-syntax-highlighting] for powerful content querying with type generation and syntax highlighting • [Portable Text][portable-text] for rendering rich text and block content **Quicklinks**: [Sanity docs][sanity-docs] | [Next.js docs][next-docs] | [Clean starter template][sanity-next-clean-starter] | [Fully-featured starter template][sanity-next-featured-starter] Table of contents • Installation • Quick Start • Manual installation • Install • Optional: peer dependencies for embedded Sanity Studio • Manual configuration • Write GROQ queries • Generate TypeScript Types • Using query result types • Query content from Sanity Content Lake • Configuring Sanity Client • Fetching in App Router Components • Fetching in Page Router Components • Should be or ? • How does  work? • Caching and revalidation • helper function • Time-based revalidation • Path-based revalidation • Tag-based revalidation • Debugging caching and revalidation • Example implementation • Visual Editing • Live Content API • Setup • How does it revalidate and refresh in real time • Embedded Sanity Studio • Creating a Studio route • Automatic installation of embedded Studio • Manual installation of embedded Studio • Studio route with App Router • Lower-level control with and • Migration guides • License Installation Quick Start Instantly create a new free Sanity project – or link to an existing one – from the command line and connect it to your Next.js application by the following terminal command _in your Next.js project folder_: If you do not yet have a Sanity account you will be prompted to create one. This command will create basic utilities required to query content from Sanity. And optionally embed Sanity Studio - a configurable content management system - at a route in your Next.js application. See the Embedded Sanity Studio section. Manual installation If you do not yet have a Next.js application, you can create one with the following command: This README assumes you have chosen all of the default options, but should be fairly similar for most bootstrapped Next.js projects. Install Inside your Next.js application, run the following command in the package manager of your choice to install the next-sanity toolkit: This also installs for [On-Demand Image Transformations][image-url] to render images from Sanity's CDN. Optional: peer dependencies for embedded Sanity Studio When using newer than , or newer than , you should end up with needed dependencies like and when you installed . In you can use : Manual configuration The command offers to write some configuration files for your Next.js application. Most importantly is one that writes your chosen Sanity project ID and dataset name to your local environment variables. Note that unlike access tokens, the project ID and dataset name are **not** considered sensitive information. **Create** this file at the root of your Next.js application if it does not already exist. **Create** a file to access and export these values Remember to add these environment variables to your hosting provider's environment as well. Write GROQ queries exports the function which will give you syntax highlighting in [VS Code with the Sanity extension installed][vs-code-extension]. It’s also used for GROQ query result type generation with [Sanity TypeGen][sanity-typegen]. Generate TypeScript Types You can use [Sanity TypeGen to generate TypeScript types][sanity-typegen] for your schema types and GROQ query results in your Next.js application. It should be readily available if you have used and chosen the embedded Studio. > [!TIP] > Sanity TypeGen will [create Types for queries][sanity-typegen-queries] that are assigned to a variable and use the template literal or function. If your Sanity Studio schema types are in a different project or repository, you can [configure Sanity TypeGen to write types to your Next.js project][sanity-typegen-monorepo]. **Create** a file at the root of your project to configure Sanity TypeGen: Note: This configuration is strongly opinionated that the generated Types and the schema extraction are both within the directory, not the root which is the default. This configuration is complimented by setting the path of the schema extraction in the updated package.json scripts below. **Run** the following command in your terminal to extract your Sanity Studio schema to a JSON file **Run** the following command in your terminal to generate TypeScript types for both your Sanity Studio schema and GROQ queries **Update** your Next.js project's to perform both of these commands by running Using query result types Sanity TypeGen creates TypeScript types for the results of your GROQ queries, which _can_ be used as generics like this: However, it is much simpler to use automatic type inference. So long as your GROQ queries are wrapped in , the results should be inferred automatically: Query content from Sanity Content Lake Sanity content is typically queried with GROQ queries from a configured Sanity Client. [Sanity also supports GraphQL][sanity-graphql]. Configuring Sanity Client To interact with Sanity content in a Next.js application, we recommend creating a  file: Fetching in App Router Components To fetch data in a React Server Component using the [App Router][app-router] you can await results from the Sanity Client inside a server component: Fetching in Page Router Components If you're using the [Pages Router][pages-router] you can await results from Sanity Client inside a function: Should be or ? You might notice that you ha…