sanity-plugin-schema-diagnostic-tool
v0.1.2
Published
Export your Sanity Studio's schema as a TypeScript file support can rebuild a Studio from
Maintainers
Readme
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.
▶️ New here? Watch the walkthrough (1:35)
How to add the Diagnostics tool to your Studio and export your schema.
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: choose from the Studio's registered schema types,
review captured code, 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-toolIn 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 devVerifying either install
- A Diagnostics item appears in the Studio's nav.
- Opening it lists your document and object types.
- Selecting a type shows Fields, Raw JSON, and TypeScript views.
- Download schemaTypes.ts in the header produces a single
.tsfile.
If creating the export or starting the download fails, the share dialog shows the error with Copy error details and Retry download. Retrying preserves your selection. If clipboard access is blocked, select and copy the details manually.
The browser handles saving the file after the download starts. The plugin cannot detect later download blocks, cancellation, or disk errors; check your browser's downloads if the file does not appear, then use the download button to try again.
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; for the drop-in, use the generated file provided by support,
not index.template.tsx from the repository.
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.tsx2. 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 devUpdating 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/depsWhat's in the exported file
every included schema type as
defineType()source, plus a commented reference block per type holding the runtime shapethe source of your functions: custom validators,
readOnly/hiddencallbacks, and custom input/preview components are captured as textworkspace metadata: name, title, Studio version, configured tools, and initial-value templates
default values from initial-value templates, which are literals your schema declares rather than dataset content
The tool never queries your dataset, so no documents or assets are read or exported, and it handles no API tokens or credentials.
Because function bodies travel with it, treat the file as source code: open it and check before sharing. Type and namespace checkboxes let you narrow the selection. Referenced types are added automatically when a selected type needs them, even if unchecked or in an excluded namespace.
Sanity support reads that source, then rebuilds an equivalent Studio from it in a scratch project — never in yours.
Removing the tool
Once you have your export, you can remove the tool. The downloaded file remains available to review and share.
Plugin
- Remove the
schemaDiagnosticTool()entry and its import from your Studio configuration, keeping your other plugins. - Run
npm uninstall sanity-plugin-schema-diagnostic-toolin your Studio package. For npm workspaces, runnpm uninstall sanity-plugin-schema-diagnostic-tool -w studiofrom the repository root, using the same workspace you installed into. - Restart your local Studio.
Drop-in
- Remove
diagnosticsToolfrom thetoolsconfiguration and remove its import. Keep any other tools; remove thetoolsoption only if you added it solely for Diagnostics. - Delete the diagnostics file you copied into your Studio.
- Restart your local Studio.
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 the repository README for generation
and validation instructions.
Downloading your schema for support
Before you share an export
The exported schemaTypes.ts contains your schema including the source of
custom validation functions and custom component functions, plus workspace
metadata and declared default values. Review it before attaching it to your
support ticket. If you need help installing the tool, ask whoever maintains your
Studio or ask support for install steps.
Download the file
- Open your Studio and click Diagnostics in the nav. (Depending on how it was installed, it may be labelled Schema Diagnostics.)
- You'll land on Schema Inspector, listing the schema types your Studio has registered. You don't need to select anything — the export always covers every type currently included.
- Click Download schemaTypes.ts in the top right.
- A Share schema with support dialog summarises what the file contains. Read it, then click Download to share. Review captured code closes the dialog and takes you directly to the optional code review.
- Your browser saves
schemaTypes.tslocally — nothing is uploaded. Review the file, then attach it to your support ticket.
Choosing what's included
All types outside excluded namespaces start selected. Each type's checkbox controls its selection for export; clicking its name only opens the inspector. All and None apply to the currently listed types, including the search filter. Browsing types and reviewing captured code are optional; neither is required to create an export.
The export includes your selection plus any registered types it depends on. The share dialog reports automatically included referenced types. These can include unchecked types and types from excluded namespaces.
Above the type list there's an Exclude namespaces section with a checkbox per
namespace, such as mux, media, or sanity.
A ticked namespace box hides its types and removes them from the direct selection. All namespaces start ticked. This applies to names containing a namespace prefix, including any your team defines, not only plugin types. Referenced types can still be added automatically. The count above the list shows how many types are hidden, not necessarily absent from the export.
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 can make the file smaller. Types required by your remaining selection are still included; types absent from the export are unavailable to support.
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
Default values declared by initial-value templates
Not included
- The tool never queries your dataset — no documents or dataset records are read or exported
- The exporter does not collect authentication credentials or read environment files. It does preserve values and function text already present in captured schema and workspace settings; it does not redact their contents.
- No dataset or project data beyond the identifiers your Studio config already contains
What support does with it
Support reads the source, then rebuilds an equivalent Studio from it in a scratch project — never in yours.
Reviewing captured code (optional)
Open Review captured code to browse validation rules, visibility and editing conditions, components, other callbacks, and defaults. Group by schema role or schema type, and search paths or captured source. Shared types are listed under their own registration rather than repeated under each referring document. Show surrounding shape displays the containing object for context.
- Select a member and read what omitting it would change. Stage omission marks the whole member; it does not edit your Studio or download anything.
- Open Review omissions to inspect the staged source. Use Keep this member to undo an omission, or confirm the listed omissions.
- Return to the main Download button. It remains unavailable while an omission is staged but unconfirmed. The share dialog reports how many confirmed omissions will be applied; its download action applies them to both generated definitions and captured reference data. The file records the omitted paths for support.
Review only covers the types currently included by Schema Inspector, including unchecked types that were added automatically because a selected type depends on them. Changing that selection immediately changes the review set. Choices for types no longer included are not applied.
Confirmed members have a Restore to export action. Choices remain while you switch inspector views, but are not saved across reloads. A schema or workspace change clears choices. Choices that no longer match the current export selection or captured source are not applied and are reported in the interface.
This view indexes schema roles; it does not detect secrets or cover every literal in the export. Omitting a validation member removes its entire chain, including any built-in rules. An omission does not remove matching text from other members. Review the resulting file before sharing.
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. Captured source can appear in both generated definitions and commented reference blocks, even when the runnable definition uses a placeholder. Check both places if you remove something. Editing the downloaded file does not change your Studio, but can break the reproduction or remove behavior support needs to investigate. Let support know what you changed.
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. Check the search filter and namespace exclusions, then confirm that you have the intended workspace open. Switch workspaces in the nav if you have more than one.
Your Studio opens on a "Schema errors" screen. The tool reads the compiled schema, so it cannot export if those errors prevent it from loading. Send support the error text; that's diagnostic on its own. You do not need to fix the original issue before asking support for the next step.
The download does nothing. If the dialog shows an error, use Retry download or Copy error details as described under Verifying either install. If no error appears, check your browser's downloads and any download prompt or block. The tool can catch failures while preparing and requesting the download, but cannot confirm browser acceptance or saving. If it still fails, tell support what happened and include any browser-console error.
