Studio project structure

The file structure of a typical Sanity Studio project

Sanity Studio’s file structure is a slim single-page React application where logic and code are contained in npm modules. The Studio comes with a framework that lets you customize and add your own components to different parts of it.

This makes it possible to confidently upgrade to new versions of Sanity Studio, and also to install and ship plugins in self-contained packages.

The file structure of Studio projects can look different depending on how you installed it. The example below is from the blog template example that you can initiate from the CLI:

.
├── README.md
├── dist
│   ├── index.html
│   └── static
│       ...
│       └── ...
├── package-lock.json
├── package.json
├── sanity.cli.ts
├── sanity.config.ts
├── schemas
│   ├── author.ts
│   ├── blockContent.ts
│   ├── category.ts
│   ├── index.ts
│   └── post.ts
├── static
└── tsconfig.json

Sanity Studio contains the following files and folders out of the box:

• package.json: Contains the necessary dependencies for the studio project. There will also be a dependency lock file that might look different depending on which package manager you use.
• sanity.cli.ts: The configuration file for the Sanity CLI. Contains information on what project ID and dataset the CLI should connect to for project-specific commands.
• sanity.config.ts: The configuration file for the Studio contains information about what project(s) that the Studio should connect to, as well as schemas, plugins, and other customizations.
• schemas: It's a convention to organize schema files in a dedicated folder. It's not required to have a schemas folder, as schemas are imported as JavaScript into the Studio config object.
• static: If you want to bundle static files in the studio, you can place these files in the static folder. The built-in developer tooling using Vite will pick these up automatically. If you use a different bundler, then you might need to configure this to bundle files from this folder as well.
• tsconfig.json (only if TypeScript is used) Contains the settings for the transpilation of TypeScript into JavaScript.
• dist: This folder is auto-generated and contains the production build of Sanity Studio as a result of running npm run build.

Configuration is split between sanity.config.ts (the Studio itself) and sanity.cli.ts (the CLI). The Studio config manages how your studio works and how it interacts with Content Lake, and the CLI config manages terminal actions like deployments, migrations, and queries from the CLI. See CLI Configuration for the details.

Switch a Studio between environments (such as a development dataset and a production dataset) by reading values from process.env. Variables that the bundled Studio reads must be prefixed with SANITY_STUDIO_. The Studio loads .env, .env.local, and mode-specific files such as .env.development automatically. See Environment Variables for the full prefix rules and loading priorities.

import {defineConfig} from 'sanity'

export default defineConfig({
  projectId: process.env.SANITY_STUDIO_PROJECT_ID!,
  dataset: process.env.SANITY_STUDIO_DATASET!,
  // ...
})

Run more than one Studio in the same project by passing an array of configs to defineConfig. Each workspace needs its own name and basePath. See Workspaces for typical layouts and visibility controls.

Many configuration properties accept a (prev, context) => ... callback so that you can compose values conditionally, for example per workspace, per current user, or per schema type. See Configuration for the full list of callback-aware properties.

Sanity Studio does not enforce a folder convention. The recommended pattern for Studios with more than a handful of customizations is to put custom code under a src/ directory, grouped by customization type. For smaller Studios with one or two customizations, keeping files at the project root is also fine.

my-studio/
├── sanity.config.ts
├── sanity.cli.ts
├── src/
│   ├── schemaTypes/
│   │   ├── index.ts
│   │   └── seoType/
│   │       ├── index.ts
│   │       └── seoInput.tsx
│   ├── actions/
│   ├── badges/
│   ├── structure/
│   └── plugins/
└── static/

When a schema type has its own custom input, preview, or field component, put those files in the same folder as the schema, as shown in src/schemaTypes/seoType/ above. Co-located customizations are easier to find later and easier to lift into a plugin if you want to share them across Studios.

• Document actions: custom buttons in the document pane action menu.
• Form Components: custom inputs, previews, fields, and items.
• Get started with Structure Builder API: custom navigation, lists, and panes.
• Installing and configuring plugins: adding third-party customizations.
• An opinionated guide to Sanity Studio: a worked example of the src/ pattern in practice.