Detect

1. Locate the Studio and check the version floor
2. Resolve installed versions
3. Read the configuration
4. Resolve the TypeScript setup
5. Detect custom code surface
6. Detect deprecated and removed API usage
7. Detect environment and CI
8. Record sheet

1. Locate the Studio and check the version floor

A Studio is the directory containing sanity.config.ts (v3 and later) or sanity.json (v2). It may not be the repository root.

Check the floor before anything else. Studio v2 is a hard stop for this skill. Any of these means v2:

• The resolved sanity major is below 3
• There is no sanity dependency and the project depends on v2-era packages such as @sanity/base or @sanity/desk-tool
• There is a sanity.json and no sanity.config.*

If so, stop and report per the scope section of SKILL.md. Do not continue through the rest of this file, and do not write a plan file.

If both sanity.json and sanity.config.* exist, the resolved sanity version wins. A stray sanity.json in a v3+ project is cleanup worth mentioning, not a reason to stop.

If you find several Studios, ask which one to plan for, or plan for each and say so. Monorepos with one Studio per tenant or per environment are common.

2. Resolve installed versions

Read the lockfile, not package.json. "sanity": "^4.20.0" tells you what was requested; the lockfile tells you what is installed, and the gap between them is often several minor versions of breaking changes.

Every command in this section runs from the Studio directory, not the repository root. The Studio is frequently a subdirectory, and the node_modules and lockfile that matter are the ones governing it. Set the directory from the path chosen in step 1, and do not auto-pick when step 1 found more than one Studio:

Two things to check before trusting a path here. In a pnpm or Yarn workspace the lockfile usually sits at the workspace root while node_modules is local to the Studio, so the two facts come from different directories. And a Studio with no lockfile of its own is being resolved by a parent manifest, which is itself a finding worth reporting.

Record the resolved version of: sanity, every @sanity/* package, react, react-dom, styled-components, and every third-party plugin (anything matching sanity-plugin-* or that appears in the config’s plugins array).

Note the package manager and its version. It determines whether deduplication is overrides, resolutions, or pnpm.overrides, and pnpm’s stricter resolution changes how duplicate majors behave.

Report duplicates that already exist

Any package appearing more than once in the tree is a finding to report now, not only something to verify after the upgrade.

Two majors of a shared package such as @sanity/ui, or a plugin dragging in @sanity/util and @sanity/types from a different Studio major than the installed core, means the tree is already in the state that produces duplicate-context errors and unstyled components. That is worth telling the reader before they change anything, because it may explain bugs they already have, and because fixing it first removes a variable from the upgrade.

Read the dependency tree output rather than only the top-level list. Nested entries are where this shows up:

Use the package manager’s own output, and treat the grep below as a last resort. pnpm why and npm ls parse the lockfile with the tool that wrote it; a regex does not. It will keep working when the lockfile format changes and it cannot confuse one package’s name for a substring of another’s. --json also makes the result parseable rather than scraped, which matters when you need the parent that pulled a version in, not just the version.

Reach for the lockfile directly only when neither is available: no node_modules, or the matching package manager is not on the machine. Then anchor the package name and keep prerelease suffixes, or you will report findings that do not exist. A loose pattern turns babel-plugin-styled-components@5.1.36 into a styled-components v5 duplicate, @sanity/ui@5.0.0-alpha.3 into a nonexistent stable 5.0.0, and @sentry/react@8.55.2 into a React version:

Put what you find in the report as a finding with the specific versions and which dependency pulled each one in. Do not reduce it to a generic “check for duplicates after installing” line.

This is the observed tree, so it is a finding. What the tree will look like after the upgrade is a prediction, and package-coupling.md covers why a planner must not assert it.

Watch for more than one dependency tree

A repository can contain several installs, and they can disagree. Common shapes: a Studio in a subdirectory with its own lockfile while the repository root has another; a root manifest that depends on sanity for linting; a monorepo with a Studio and a frontend using different package managers.

When this happens:

• Record which tree you are planning for, and say so in the report header
• Record the sibling trees’ sanity versions too, because two different Studio majors resolving in one repository will confuse editor TypeScript and can mislead anyone reading versions from the wrong place
• Take every version fact from the target tree’s lockfile. A version read from the wrong tree looks authoritative and is simply about a different install
• If a deployment pipeline builds from a different tree or a different manifest than the one you are planning for, that mismatch is a finding on its own

3. Read the configuration

Read these in full, not by grep. They are short and they answer many questions at once.

• sanity.config.ts (or .js, or the workspace array if there are several)
• sanity.cli.ts (or .js)
• package.json, including the scripts block
• sanity.json if this is v2

From sanity.config.*, record whether each of these is present:

From sanity.cli.ts, record:

If config values come from a helper function or environment variables, read the helper. A templated studioHost or a per-tenant projectId means there are multiple deployments to upgrade, which belongs in the plan.

4. Resolve the TypeScript setup

You need the effective moduleResolution. Recent @sanity/* packages resolve types through exports and drop typesVersions, so legacy node10 resolution cannot resolve subpath types at all.

If tsconfig.json has an extends pointing outside the repository, follow it if you can and say so if you cannot. An unresolved moduleResolution is a genuine blocker for any plan involving subpath imports, and it belongs in the human questions section by name rather than being quietly skipped.

If that prints nothing, TypeScript is not installed in this directory. Read tsconfig.json and follow its extends chain by hand instead of installing anything, and if the chain leaves the repository, say so rather than guessing. An unresolved moduleResolution belongs in the human questions section by name.

Also record whether typescript and @types/react-dom are actual devDependencies or are being inherited from a workspace root.

5. Detect custom code surface

The size of the upgrade is mostly determined by this. Count, then look at examples.

If sanity/_internal or sanity/_singletons imports exist, raise it prominently. Internal APIs carry no compatibility guarantee and change without changelog entries. A multi-major upgrade over internal APIs is a different, riskier project, and the honest recommendation may be to get off them first.

Look at one or two representative custom components rather than all of them. One example reveals the patterns in use, which is what determines whether a rename is twenty edits or four hundred.

6. Detect deprecated and removed API usage

7. Detect environment and CI

The Node version that matters is the one in CI and on the build host, not the one on this machine. If you can only see the local version, say so and ask.

Also check whether the Studio shares a repository with other applications. If it does, a Node bump should be scoped to this project’s CI job rather than the whole runner, and hoisted React may be shared with an app that pins a different version.

8. Record sheet

Carry this forward into the report. If a value is unknown, write “unknown” rather than guessing, and add it to the human questions.