Skip to main content
The sanity build command compiles your Sanity Studio into an optimized static bundle suitable for production deployment. It creates a dist/ directory containing HTML, JavaScript, CSS, and assets.

​
Basic Usage

sanity build
This builds the Studio to the dist/ directory with default production settings. 
Clean output folder (42ms)
✔ Build Sanity application (12.3s)

​
Syntax

sanity build [OUTPUT_DIR] [options]
  • OUTPUT_DIR - Optional output directory (default: ./dist)

​
Options

  • --source-maps - Enable source maps for built bundles (increases size)
  • --no-minify - Skip minifying built JavaScript (speeds up build, increases size)
  • -y, --yes - Unattended mode, answers “yes” to all prompts
  • --schema-path <path> - Specify custom path to schema files

​
Examples

sanity build

​
Build Output

The build creates a dist/ directory: 
dist/
├── index.html              # Entry point
├── static/
│   ├── css/
│   │   └── main.abc123.css
│   ├── js/
│   │   ├── main.abc123.js
│   │   └── vendor.def456.js
│   └── assets/
│       └── favicon.ico
└── importmap.json          # (if auto-updates enabled)

​
Build Process

The build process:
  1. Cleans output folder - Removes existing dist/ directory
  2. Bundles Studio - Compiles with Vite
  3. Minifies JavaScript - Reduces file size (unless --no-minify)
  4. Optimizes assets - Compresses images and other resources
  5. Generates import map - Creates auto-update configuration (if enabled)
  6. Extracts schema - Stores schema for runtime validation

​
Production Optimizations

The build includes several production optimizations:

​
Code Splitting

Automatic code splitting reduces initial load time:
  • Vendor dependencies in separate chunks
  • Route-based code splitting
  • Dynamic imports for plugins

​
Minification

JavaScript is minified by default:
  • Removes whitespace and comments
  • Shortens variable names
  • Tree-shakes unused code
  • Compresses with terser
# Disable for debugging
sanity build --no-minify

​
Asset Optimization

  • CSS is extracted and minified
  • Images are optimized
  • Fonts are subsetted
  • SVGs are compressed

​
Source Maps

Enable source maps for production debugging: 
sanity build --source-maps
This generates .map files alongside bundled JavaScript: 
dist/static/js/
├── main.abc123.js
├── main.abc123.js.map      # Source map
├── vendor.def456.js
└── vendor.def456.js.map    # Source map
Source maps increase bundle size. Only use in production if you need to debug production issues.

​
Auto-Updates

Sanity Studio supports auto-updates for runtime packages:
sanity.cli.ts
import {defineCliConfig} from 'sanity/cli'

export default defineCliConfig({
  api: {
    projectId: 'abc123',
    dataset: 'production',
  },
  autoUpdates: true,  // Enable auto-updates
})
With auto-updates enabled:
  • Latest versions served at runtime
  • No need to rebuild for package updates
  • Requires appId in deployment config
Auto-updates allow your Studio to receive patch updates without rebuilding and redeploying.

​
Environment Variables

Environment variables are embedded at build time:
.env.production
SANITY_STUDIO_PROJECT_ID=abc123
SANITY_STUDIO_DATASET=production
SANITY_STUDIO_API_VERSION=2024-03-03
Only variables prefixed with SANITY_STUDIO_ are included: 
Including the following environment variables:
- SANITY_STUDIO_PROJECT_ID
- SANITY_STUDIO_DATASET
- SANITY_STUDIO_API_VERSION

​
Custom Vite Configuration

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

export default defineConfig({
  // ... other config
  vite: {
    build: {
      sourcemap: true,
      minify: 'terser',
      rollupOptions: {
        output: {
          manualChunks: {
            vendor: ['react', 'react-dom'],
          },
        },
      },
    },
  },
})

​
Base Path Configuration

Deploy to a subdirectory:
sanity.cli.ts
import {defineCliConfig} from 'sanity/cli'

export default defineCliConfig({
  api: {
    projectId: 'abc123',
    dataset: 'production',
  },
  project: {
    basePath: '/studio',  // Deploy to /studio path
  },
})
Or use environment variable: 
SANITY_STUDIO_BASEPATH=/studio sanity build

​
Build Statistics

View detailed build statistics: 
sanity build --stats
This shows the largest module files: 
Largest module files:
  vendor.js           245 kB
  main.js             128 kB
  structure.js         89 kB
  ...

​
Unattended Mode

For CI/CD pipelines: 
sanity build -y
This skips all confirmation prompts:
  • Automatically cleans output directory
  • Accepts default settings
  • No interactive prompts

​
Troubleshooting

​
Build Fails

Check for common issues:
  1. Schema errors - Validate your schema files
  2. TypeScript errors - Run type checking first
  3. Memory issues - Increase Node.js memory
NODE_OPTIONS="--max-old-space-size=4096" sanity build

​
Module Not Found

If you see module resolution errors: 
# Clear node_modules and reinstall
rm -rf node_modules
npm install

# Then rebuild
sanity build

​
Large Bundle Size

If your bundle is too large:
  1. Use --stats to identify large modules
  2. Lazy load heavy dependencies
  3. Remove unused plugins
  4. Optimize images and assets
sanity build --stats

​
Port Conflicts During Build

The build process doesn’t use a port, but if you see port conflicts:
  1. Stop any running sanity dev processes
  2. Clear the build cache
  3. Try building again

​
Monorepo Build

When working in the Sanity monorepo: 
# Build all packages
pnpm build

# Build CLI only (faster)
pnpm build:cli
Tests require a build first because some tests use compiled output. Run pnpm build && pnpm test.

​
Deployment

After building, you can:
  1. Deploy to Sanity hosting: 
    sanity deploy
  2. Deploy to static hosting (Vercel, Netlify, etc.): 
    # Point hosting to ./dist directory
vercel --prod
  3. Self-host: 
    # Serve the dist folder
npx serve dist

​
Next Steps

Deploy Studio

Deploy your built Studio to Sanity hosting

Manage Projects

Manage your Sanity projects and settings

Build docs developers (and LLMs) love

Get started for freeTalk to us