Schema Diagnostic Tool

sanity-plugin-schema-diagnostic-tool

Adds a Schema Diagnostics tool to your Studio that serializes your registered schema to a single schemaTypes.ts file. Sanity support can rebuild an equivalent Studio from that file, so a schema-specific bug can be reproduced without access to your project or your content.

Installing Schema Diagnostics

Two ways to get the Diagnostics tool into a Sanity Studio. The drop-in is a single file you paste in — no dependency, no release needed. The plugin is a normal npm install, for customers and anyone who'd rather not paste code.

Both give you the same tool: browse the Studio's registered schema types, search schema paths, and download a schemaTypes.ts export.

Works on Studio v3–v6. No new dependencies either way — both use sanity, @sanity/ui and @sanity/icons, which every Studio already has.

Option A: Plugin

1. Install

npm install sanity-plugin-schema-diagnostic-tool

In a monorepo, target the Studio workspace: npm install ... -w studio. Run it from the repo root afterwards so peer deps resolve against one copy of react and sanity — a second copy is what produces "Invalid hook call".

2. Register it

// sanity.config.ts
import {defineConfig} from 'sanity'
import {structureTool} from 'sanity/structure'
import {schemaDiagnosticTool} from 'sanity-plugin-schema-diagnostic-tool'

export default defineConfig({
  // ...projectId, dataset, schema
  plugins: [structureTool(), schemaDiagnosticTool()],
})

Options, both optional:

schemaDiagnosticTool({
  title: 'Schema export',        // nav label, default "Schema Diagnostics"
  name: 'schema-export',         // URL segment, default "schema-diagnostic-tool"
})

3. Restart

npm run dev

Verifying either install

1. A Diagnostics item appears in the Studio's nav.
2. Opening it lists your document and object types.
3. Selecting a type shows Fields, Raw JSON, and TypeScript views.
4. Download schemaTypes.ts in the header produces a single .ts file.

If the nav item is missing, the tool didn't register — check tools vs plugins for the option you chose. If the nav item is there but the panel is blank, check the browser console; on the drop-in that's usually the template-vs-generated mistake above.

Option B — Drop-in (single file)

Use this for internal work, for testing an unreleased branch, or when you can't add a dependency to the Studio.

1. Copy the file provided by support

cp <DOWNLOADED_PWD>/index.tsx <MY_PROJECT_PWD>/<studio>/src/tools/diagnostics.tsx

2. Register it

// sanity.config.ts
import {defineConfig} from 'sanity'
import {diagnosticsTool} from './src/tools/diagnostics'

export default defineConfig({
  // ...projectId, dataset, schema
  tools: (prev) => [...prev, diagnosticsTool],
})

diagnosticsTool is a plain tool object (name: 'diagnostics', title Diagnostics), so it needs no call and takes no options. Rename the tab by spreading it: {...diagnosticsTool, title: 'Schema export'}.

3. Restart

npm run dev

Updating the drop-in later: copy the new file over the old one, then clear the Studio's pre-bundle cache or you may keep seeing the previous build:

rm -rf <studio>/node_modules/.sanity/vite/deps

What's in the exported file

• every registered schema type as defineType() source, plus a commented reference block per type holding the runtime shape
• the source of your functions: custom validators, readOnly/hidden callbacks, and custom input/preview components are captured as text
• workspace metadata: name, title, Studio version, configured tools, and initial-value templates

It does not contain documents, assets, API tokens or credentials.

Because function bodies travel with it, treat the file as source code: open it and check before sharing. The type-exclusion checkboxes let you leave namespaced types out of the export.

Studio support

Peer range is sanity: ^3 || ^4 || ^5 || ^6, React 18 or 19. The tool reads the compiled schema through useSchema(), which every Studio 3+ provides.

What ships in the package

dist/ (compiled ESM + CJS + types) and src/ (the TypeScript sources the sourcemaps point at). Source is included deliberately: this tool reads your schema and writes a file you may send to Sanity support, so being able to audit exactly what it does without unpacking a bundle is worth the extra ~250 kB. It makes no network requests and carries no keys or telemetry.

src/SchemaDiagnostics.tsx and src/transpiler.generated.ts are build output — see Development below for where to edit.

Downloading your schema for support

Verifying the plugin or Drop-In installed

1. A Diagnostics item appears in the Studio's nav.
2. Opening it lists your document and object types.
3. Selecting a type shows Fields, Raw JSON, and TypeScript views.
4. Download schemaTypes.ts in the header produces a single .ts file.

If the nav item is missing, the tool didn't register — check tools vs plugins for the option you chose. If the nav item is there but the panel is blank, check the browser console; on the drop-in that's usually the template-vs-generated mistake above.

Before you share an export

The exported schemaTypes.ts contains your schema including the source of custom validation functions and custom component functions, plus your whoever maintains your Studio to add it, or ask support for install steps.

Download the file

1. Open your Studio and click Diagnostics in the nav. (Depending on how it was installed, it may be labelled Schema Diagnostics.)
2. You'll land on Browse types, listing the schema types your Studio has registered. You don't need to select anything — the export always covers every type currently included.
3. Click Download schemaTypes.ts in the top right.
4. A Share schema with support dialog summarises what's about to leave your Studio. Read it, then click Download & share.
5. Your browser saves schemaTypes.ts. Attach that file to your support ticket.

Choosing what's included

Under the type list there's an Exclude namespaces section with a checkbox per namespace, such as mux, media, or sanity.

A ticked box means that namespace is left out of the export. All namespaced types start ticked, so types that come from plugins rather than from your own schema are excluded by default. The count above the list tells you how many types that removes.

Usually you can leave this alone. Two cases where you shouldn't:

• Your issue involves a plugin's type — for example a Mux video field or a Media Library asset. Untick that namespace so support can see it.
• You want to narrow the export for a large schema. Ticking more namespaces makes the file smaller, but anything you exclude is something support can't reproduce.

The Filter types… box only filters what's on screen. It doesn't change what gets exported.

What's in the file

Included

• Every included schema type: field names, field types, titles, and validation rules
• Your workspace configuration: which tools and initial-value templates are configured, and your Studio version
• The source of any custom validation functions and custom input or preview components you wrote

Not included

• No documents, no dataset records, no content of any kind
• No API tokens, no credentials, no environment variables
• No dataset or project data beyond the identifiers your Studio config already contains

Review it before you send

schemaTypes.ts is a plain text file — open it in any editor.

Because it carries the source of your custom validation and component functions, it can include code your team wrote, and occasionally that code contains internal URLs, service names, or comments you'd rather not share. Skim it before attaching. Anything you delete is simply something support won't be able to reproduce, so removing a block is always safe from your side.

The file is often large — a few hundred kilobytes to several megabytes for a big schema. That's expected. Attach it as a file rather than pasting the contents into a message.

If something doesn't work

No Diagnostics item in the nav. The tool isn't installed, or it's registered in the wrong place in sanity.config.ts. Whoever installed it can check whether it belongs in plugins or tools.

The type list is empty. Your Studio has no registered schema types, which usually means the config points at a different workspace than you expect. Switch workspaces in the nav if you have more than one.

Your Studio opens on a "Schema errors" screen. Fix those errors first — the tool reads the compiled schema, so it can't export a schema that doesn't compile. Send support the error text; that's diagnostic on its own.

The download does nothing. Check whether your browser blocked it, and try again with the browser console open — an error there tells support exactly what happened.

Download the file

1. Open your Studio and click Diagnostics in the nav. (Depending on how it was installed, it may be labelled Schema Diagnostics.)
2. You'll land on Browse types, listing the schema types your Studio has registered. You don't need to select anything — the export always covers every type currently included.
3. Click Download schemaTypes.ts in the top right.
4. A Share schema with support dialog summarises what's about to leave your Studio. Read it, then click Download & share.
5. Your browser saves `schemaType