Development
Learn how the default local development environment for Sanity Studio works
Sanity Studio is distributed as a single package on npm. It also comes with built-in tooling for local development based on Vite. The package also exports the Studio as a React component, including a render function for mounting it on a DOM node in an HTML document.
Protip
Sanity Studio always connects to a dataset in the hosted Content Lake, also when run locally. Your content is never stored locally. This means that you can have differences in the schema between a local and a hosted Studio. If the Studio finds content in a document that doesn't match its schema, it will display a warning.
You can safely change schemas with the confidence that no existing content will be changed. To change content to comply with schema changes, you will need to run a migration script.
Local development
You can start a local development server with the following command within the Studio project folder:
# For Studios initated with the CLI
npm run dev
# Alternative method
npx sanity devTo start the development server on a different port
The local development server will make the Studio available on http://localhost:3333 by default. You can specify the port with the following command:
# For Studios initated with the CLI
npm run dev -- --port 3000
# Alternative method
npx sanity dev --port 3000Gotcha
To run the Studio on a different port locally, you will have to enable CORS origins for that domain with authenticated requests enabled.
You can add this with the Sanity CLI by running the following command in your Studio project folder:
npx sanity cors add http://localhost:3000 --credentials
Local production build
To build your Studio for production locally, run the following command in the Studio project folder:
# For Studios initated with the Sanity CLI
npm run build
# Alternative method
npx sanity buildThe build command will bundle the Studio files into a dist folder by default. You can specify the production folder name (for example public) by passing it as a parameter:
# For Studios initated with the Sanity CLI
npm run build -- public
# To build the Studio to a folder named "public"
npx sanity build publicThis can be useful if your hosting provider requires a specific filename when you are self-hosting the Studio.
Preview a production build locally
To preview the local production build, you can run the following command:
npx sanity preview
# To specify the folder ("./public") for the production build
npx sanity preview publicThis will run a local server for the production build of the Studio on http://localhost:3333 .
Gotcha
It's easy to forget that any changes you make to the Studio files won't get reflected when running the preview of the production build. To enable hot-module reloading, you have to run npm run dev or npx sanity dev.
Customizing the built-in Vite configuration
To extend or change the built-in Vite configuration, you need a configuration file for the Sanity CLI. Let‘s say you want to alias your root folder to enable relative imports like import CustomComponent from '@/components/CustomComponent'. The following code examples show you how you can overwrite certain properties in the Studio's Vite configuration to do so:
// sanity.cli.js
import {defineCliConfig} from 'sanity/cli'
export default defineCliConfig({
api: {
// the rest of the config...
},
vite: {
resolve: {
alias: {
'@': __dirname,
},
}
},
})You can learn more about configuring Vite in their documentation.
Was this page helpful?