Skip to main content
The sanity dev command starts a local development server for your Sanity Studio with live reloading and hot module replacement. This is the primary command you’ll use during development.

​
Basic Usage

sanity dev
This starts the development server at http://localhost:3333 by default. 
Starting dev server
Dev server started on port 3333
Local:    http://localhost:3333
Network:  http://192.168.1.100:3333
In the Sanity monorepo, the dev studio runs at http://localhost:3333 and requires browser authentication on first visit.

​
Options

  • --port <port> - TCP port to start server on (default: 3333)
  • --host <host> - The local network interface at which to listen (default: "127.0.0.1")

​
Examples

sanity dev

​
Development Server Features

​
Hot Module Replacement (HMR)

The dev server includes HMR for instant updates:
  • Schema changes reload automatically
  • Component updates apply without full page refresh
  • Configuration changes trigger rebuilds

​
Vite-Powered

Sanity Studio uses Vite for fast, modern development:
  • Lightning-fast cold starts
  • Instant HMR
  • Optimized dependency pre-bundling
  • Native ES modules

​
Studio Configuration

The dev server reads from sanity.config.ts:
sanity.config.ts
import {defineConfig} from 'sanity'
import {structureTool} from 'sanity/structure'

export default defineConfig({
  name: 'default',
  title: 'My Studio',
  projectId: 'your-project-id',
  dataset: 'production',
  plugins: [structureTool()],
  // Custom Vite config
  vite: {
    server: {
      port: 3333,
    },
  },
})

​
Network Access

By default, the server only listens on localhost (127.0.0.1). To allow access from other devices on your network: 
sanity dev --host 0.0.0.0
The server will display all available URLs: 
Local:    http://localhost:3333
Network:  http://192.168.1.100:3333
Changing the hostname might require adding a new entry to your project’s CORS-origins allow list.

​
CORS Configuration

If you access the Studio from a different hostname, you may need to add it to the CORS allow list:
  1. Go to manage.sanity.io
  2. Select your project
  3. Navigate to API → CORS Origins
  4. Add your development URL (e.g., http://192.168.1.100:3333)

​
Authentication

The dev server requires authentication to access Sanity APIs:
  1. Open the Studio URL in your browser
  2. You’ll be prompted to log in on first visit
  3. Session persists in browser for subsequent visits
Run sanity login in the terminal before starting the dev server to authenticate in advance.

​
Environment Variables

The dev server loads environment variables from:
  • .env - All environments
  • .env.local - Local overrides (gitignored)
  • .env.development - Development only
Example .env.local:
.env.local
SANITY_STUDIO_PROJECT_ID=abc123
SANITY_STUDIO_DATASET=development
SANITY_STUDIO_API_VERSION=2024-03-03
Environment variables must be prefixed with SANITY_STUDIO_ to be included in the browser bundle.

​
Custom Vite Configuration

Extend Vite configuration in sanity.config.ts:
sanity.config.ts
import {defineConfig} from 'sanity'
import {structureTool} from 'sanity/structure'

export default defineConfig({
  // ... other config
  vite: {
    server: {
      port: 3333,
      host: '0.0.0.0',
      open: true, // Open browser on start
    },
    define: {
      'process.env.CUSTOM_VAR': JSON.stringify('value'),
    },
  },
})

​
Troubleshooting

​
Port Already in Use

If port 3333 is already in use: 
sanity dev --port 3334
Or find and kill the process: 
# macOS/Linux
lsof -ti:3333 | xargs kill -9

# Windows
netstat -ano | findstr :3333
taskkill /PID <PID> /F

​
CORS Errors

If you see CORS errors in the browser console:
  1. Check your project’s CORS settings at manage.sanity.io
  2. Add your development URL to the allow list
  3. Include http://localhost:3333 for local development

​
Authentication Issues

If authentication fails: 
# Log out and log in again
sanity logout
sanity login

# Then restart dev server
sanity dev

​
Schema Errors

If the server crashes on schema errors:
  1. Check the terminal output for error details
  2. Fix schema validation issues in schemas/
  3. The server will automatically restart after saving

​
Performance Tips

​
Dependency Pre-bundling

Vite pre-bundles dependencies on first run. This may take a moment initially, but subsequent starts are instant.

​
Large Projects

For large projects with many schemas:
sanity.config.ts
export default defineConfig({
  // ... other config
  vite: {
    optimizeDeps: {
      include: ['your-heavy-dependency'],
    },
  },
})

​
Memory Issues

If you encounter memory issues with large projects: 
NODE_OPTIONS="--max-old-space-size=4096" sanity dev

​
Development Workflow

Typical development workflow:
  1. Start the dev server: sanity dev
  2. Open http://localhost:3333 in your browser
  3. Edit schemas, components, or configuration
  4. Changes appear instantly via HMR
  5. Test in the Studio UI
  6. Commit your changes
sanity dev

​
Monorepo Development

When working in the Sanity monorepo: 
# Build packages first (required before testing)
pnpm build

# Start dev studio
pnpm dev  # Starts at http://localhost:3333
The dev studio in the monorepo requires Sanity user authentication in the browser. It’s a Vite application that communicates with Sanity API endpoints.

​
Next Steps

Build for Production

Create production-ready static bundles

Deploy Studio

Deploy your Studio to Sanity hosting

Build docs developers (and LLMs) love

Get started for freeTalk to us