# next-sanity: the Sanity toolkit for a content-editable Next.js app

> next-sanity is the all-in-one Sanity toolkit for Next.js, and what it actually bundles is a set of decisions that are otherwise repeated in every project: how to configure the client with environment variables and CDN caching, how to write type safe GROQ queries, how to run a click-to-edit overlay with Draft Mode in the Presentation Tool, and how to control cache freshness with time, tag and path based revalidation. It is MIT licensed and published from a monorepo with a changeset based release process.

**sanity-io/next-sanity** — Sanity toolkit for Next.js

- Repository: https://github.com/sanity-io/next-sanity
- Website: https://www.sanity.io/
- Stars: 957 · Forks: 111
- Language: TypeScript
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/sanity-io-next-sanity

## What the package actually contains

The README describes next-sanity as the all-in-one Sanity toolkit for production-grade content-editable Next.js applications, and the table of contents at the top of the document is the most accurate description of the package's scope.

There is a quick start, which the README describes as getting a working Next.js and Sanity project running in minutes, from creating a Sanity project to querying the first content. There is an overview of everything the package has to offer. There is a guide to configuring the Sanity client, with environment variables, CDN caching and per-request overrides for different fetching contexts. There is a guide to making type safe queries with GROQ using the included Sanity client. There is a guide to visual editing and live preview, which enables click-to-edit overlays and real-time content updates in the Presentation Tool using Draft Mode, defineLive and the VisualEditing component. There is a guide to caching and revalidation, covering time-based, tag-based and path-based strategies for applications that need fine-grained cache management. And there is a full API reference with type signatures and configuration options.

That last item, a reference documentation site, is worth noting. The topics list includes team-ecosystem, which is a strange label for a package but an accurate one: this is a toolkit maintained by the company that makes the content platform, and the reference is generated from the source with type signatures, which means it cannot drift from the code the way a hand written API list does.

The package is MIT licensed, with the licence file in the repository root, and the release record shows frequent patch releases of the 13.x line, with next-sanity 13.3.4 on 2026-09-01, 13.3.3 on 2026-08-13 and 13.3.2 on 2026-08-11. The last push was on 2026-10-19 and the repository is not archived.

## Two ways in, and the image URL package that comes with it

The quick start is one command, and it is the reason many projects meet this package:

```bash
npx sanity@latest init
```

Run inside a Next.js project folder, it creates a new free Sanity project or links to an existing one. If you do not have a Sanity account you are prompted to create one, and the command creates the basic utilities required to query content from Sanity, and optionally embeds Sanity Studio, a configurable content management system, at a route in your Next.js application.

If you do not have a Next.js application yet, the README suggests:

```bash
npx create-next-app@latest
```

and notes that the rest of the document assumes the default options were chosen.

The manual installation is the package install, and the README gives it for four package managers, which is the first sign that this is a package expected to live in a lot of different repositories:

```bash
npm install next-sanity @sanity/image-url
```

```bash
yarn add next-sanity @sanity/image-url
```

```bash
pnpm install next-sanity @sanity/image-url
```

```bash
bun install next-sanity @sanity/image-url
```

The second package in that list is not optional in practice. The README says this also installs @sanity/image-url for on-demand image transformations, to render images from Sanity's CDN. That is the package that builds the URL with the right transformation parameters, and a Next.js application that renders Sanity images without it will serve the original upload rather than a resized variant.

So the real footprint of this toolkit for a new project is one command and two packages, and the Studio embed is one flag away.

## Peer dependencies, and the case of yarn v1

There is a short section about optional peer dependencies for the embedded Sanity Studio, and it is the kind of detail that saves an afternoon.

The README says that when using npm newer than v7, or pnpm newer than v8, you should end up with the needed dependencies like sanity and styled-components when you installed next-sanity. Those are the peer dependencies of the embedded Studio, since the Studio is a React application that has to be present in your dependency tree to be mounted at a route.

In yarn v1 that does not happen automatically, and the workaround is a separate tool:

```bash
npx install-peerdeps --yarn next-sanity
```

The asymmetry is a quirk of the package managers rather than of this package, but it is documented here because the failure it prevents is a build error deep inside a Studio route that is hard to trace back to an install step.

The two packages to be aware of, sanity and styled-components, are not small, and styled-components in particular is a significant dependency to pull into a project that may not otherwise have it. The section is labelled optional, and it is genuinely optional for a project that does not embed the Studio and only reads content through the client, which is the arrangement the README describes for the quick start where the Studio is embedded optionally.

## Visual editing, Draft Mode and the defineLive function

The visual editing guide is the feature that distinguishes this package from a plain query client, and the description is specific enough to be worth parsing.

It enables click-to-edit overlays and real-time content updates in the Presentation Tool. The Presentation Tool is Sanity's own environment for editors, and the overlay is the part of the page that highlights a field when an editor clicks it, so that the editor can change it in place rather than hunting through a form for the field that corresponds to a piece of text on the page.

The three pieces named in the guide are Draft Mode, defineLive and the VisualEditing component, and they fit together as one mechanism. Draft Mode is the Next.js mechanism that lets a route render draft content, and it is what makes the overlay show the editor's unsaved values rather than the published ones. defineLive is the function that wires a live subscription to the data on the page, so that when an editor changes a value, the page updates without a reload. And the VisualEditing component is what mounts the overlay itself.

The guide is linked under the app router, with a title that says visual editing with Next.js app router, and there is a separate pages router migration guide, which is the clue to the important limitation: this is the newer Next.js architecture, and the live editing path is built on it.

For a team whose editors want to change copy on a page without a developer, this is the feature that justifies the package. For a team that only wants to read content, it is the part that adds the weight, and it is worth knowing which of the two you are installing before you start.

## Caching, revalidation and the client's per-request overrides

The caching guide is where a Next.js and Sanity project usually loses an afternoon, because the two systems have their own ideas about how fresh a page should be.

The README describes three strategies. Time-based revalidation is a fixed interval after which the cached page is regenerated. Tag-based revalidation is on demand, tied to a tag you attach to a fetch, so that changing one document invalidates exactly the pages that used it. Path-based revalidation is per route, which is the middle ground between the two.

The client guide has its own set of knobs, and they interact with the caching ones. It covers environment variables, CDN caching, and per-request overrides for different fetching contexts. That last item is the useful idea: the same client is configured once with the project ID and the dataset, and a particular request can override parts of that configuration, which is how you ask for draft content in one place and published content in another without maintaining two clients.

Together these two guides are the real product. A Sanity dataset is read through a CDN, and Next.js caches what it fetches, and the question of when an editor's change appears on the site is answered by configuration in both systems. Getting it wrong produces a site that looks stale, and the documentation solving that in one place is the reason to use the toolkit rather than to write the client by hand.

## The migration guides are the real documentation

The README lists migration guides for every major version of the package, from v12 to v13, v11 to v12, and so on down to a guide from below 0.4 to v4, with the v4 to v5 step split into two, one for the app router and one for the pages router.

The list is long enough to be a warning. It tells you that this package has had a major version roughly every year, and that upgrading means reading a guide rather than bumping a version range. It also tells you something about the cause, because the split at v4 to v5 mirrors the change in Next.js itself, where the app router arrived and the pages router became the legacy path. A toolkit that wraps a framework inherits that framework's migrations.

The existence of the guides is a positive signal, even if the list is long. A package that has been through eleven documented major migrations is a package whose maintainers have dealt with breaking changes deliberately rather than by accident, and for an adopter the practical value is that the upgrade path is known and written down, with the app router and pages router cases separated where they differ.

It also sets the expectation for the next upgrade. A toolkit in this position will keep breaking, because the framework it wraps keeps breaking, and the cost of staying on the current major version is a periodic reading task rather than a rewrite. That is a reasonable trade for a package that removes the four integration problems it was built to solve, and it is the main thing to weigh before you depend on it.

## The monorepo, the release tooling and how the package is published

The repository is a monorepo built on pnpm workspaces and turbo, and the root package.json is named next-sanity-monorepo with version 0.0.0 and private set, which is the standard marker for a workspace root that is not itself published.

The top level listing shows the pieces: packages for the published code, apps for the applications, fixtures for test fixtures, a skills directory, and a turbo.json for the task runner. The scripts are the interesting part. Build runs turbo build filtered to the packages, dev runs turbo dev, and start runs turbo watch build start. The test script runs turbo test, and a separate test:e2e script filters to the next-sanity package, which points at Playwright, which is in the root dependencies at 1.62.1. There is a typegen script, a docs:generate script for a typedoc package in the workspace, and a knip script, with knip in the dev dependencies, which is the tool that finds unused files, dependencies and exports.

The linting is not the usual ESLint. The lint script runs oxlint with type checking, type awareness, unused disable directive reporting and warnings denied, and the format script runs oxfmt. The oxlint-tsgolint dependency alongside it is the type-aware linting backend.

Releases go through changesets, with the release script being changeset publish, and the bump scripts for the visual editing package bump it to the canary or the latest tag and then dedupe. The package manager is pinned to pnpm 10.34.5, and pkg-pr-new is a dev dependency, which is the tool that publishes a preview build of a pull request.

The repository also carries AGENTS.md, a CLAUDE.md and an .agents directory alongside a .claude directory, and there is a skills-lock.json next to the skills directory, which is the same pattern of a project that expects AI coding assistants to work in the codebase and wants their configuration kept in the tree. The top level entries include knip.config.ts, an .oxfmtrc.json and an .oxlintrc.json, and the licence is MIT with the LICENSE file at the root.

## Conclusion

Adopt next-sanity when you are building a Next.js front end on Sanity and want the client configuration, the typed query story, the visual editing overlay and the cache invalidation approach to arrive as one maintained package rather than as four hand rolled integrations. It is the wrong tool if you are not using Sanity, if you are on the pages router and want the app router features such as defineLive, and it is a poor fit for a project that cannot accept a dependency that ships its own opinion about caching. Before adopting, read the migration guide for the version you are moving from, since the toolkit has had a major release roughly every year and the guides exist for a reason, and check the peer dependency instructions for your package manager before you hit the install step.

## FAQ

### What does the next-sanity package do?

It is the all-in-one Sanity toolkit for Next.js applications. It provides the configured Sanity client with environment variables, CDN caching and per-request overrides, type safe GROQ queries, visual editing with click-to-edit overlays and real-time updates through Draft Mode and defineLive, cache revalidation strategies, and optionally an embedded Sanity Studio.

### How do I set up next-sanity in a new Next.js project?

Run npx sanity@latest init in the project folder, which creates or links a Sanity project, sets up the utilities for querying content and can embed Sanity Studio at a route. For manual setup, install next-sanity and @sanity/image-url with your package manager, the second being used for on-demand image transformations from Sanity's CDN.

### Do I need to install peer dependencies for the embedded Studio?

With npm newer than v7 or pnpm newer than v8 they are installed automatically, and the packages involved are sanity and styled-components. With yarn v1 you have to install them yourself, for example with npx install-peerdeps --yarn next-sanity.

### What revalidation strategies does next-sanity support?

The caching guide covers time-based, tag-based and path-based revalidation, for applications that need fine-grained control over how fresh each page is, alongside the client's own environment variable and CDN caching settings and its per-request overrides for different fetching contexts.

### Is upgrading next-sanity a breaking change?

Often. The repository publishes a migration guide for every major version, from below 0.4 to v4 and then v4 to v13, with the v4 to v5 step split into app router and pages router guides, because the toolkit follows the breaking changes in Next.js itself.

## Sources

- [License: MIT](https://github.com/sanity-io/next-sanity/blob/main/LICENSE)
- [Project website](https://www.sanity.io/)
- [README](https://github.com/sanity-io/next-sanity/blob/main/README.md)
- [Releases](https://github.com/sanity-io/next-sanity/releases)
- [sanity-io/next-sanity on GitHub](https://github.com/sanity-io/next-sanity)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/sanity-io-next-sanity