Skip to main content
The sanity deploy command builds your Sanity Studio and deploys it to Sanity’s hosting infrastructure. This provides a globally distributed, secure, and fast hosting solution for your Studio.

​
Basic Usage

sanity deploy
This builds the Studio (unless --no-build is passed) and deploys it to Sanity hosting. 
✔ Checking application info
✔ Build Sanity application (12.3s)
✔ Verifying local content
✔ Deploying...

Success! Studio deployed to https://your-project.sanity.studio

​
Syntax

sanity deploy [SOURCE_DIR] [options]
  • SOURCE_DIR - Optional source directory to deploy (default: ./dist)

​
Options

​
Build Options

  • --no-build - Don’t build the Studio prior to deploy, use existing dist/ folder
  • --source-maps - Enable source maps for built bundles (increases size)
  • --no-minify - Skip minifying built JavaScript (speeds up build, increases size)

​
Deployment Options

  • --external - Register an externally hosted studio (ignores build flags)
  • --schema-required - Fail-fast deployment if schema store fails
  • --verbose - Enable verbose logging
  • -y, --yes - Unattended mode, answers “yes” to all prompts

​
Examples

sanity deploy

​
Deployment Process

The deployment follows these steps:
  1. Authentication check - Ensures you’re logged in
  2. Application verification - Checks or creates hosting configuration
  3. Build Studio (unless --no-build) - Compiles production bundle
  4. Content verification - Validates the dist/ directory
  5. Create tarball - Packages files for upload
  6. Upload & deploy - Uploads to Sanity hosting
  7. Schema extraction - Stores schema for runtime (optional)

​
Hosting URLs

Your Studio is deployed to: 
https://<project-id>.sanity.studio
For custom hostnames, see the Custom Domains section below.

​
First-Time Deployment

On first deployment, you’ll be prompted for:
  1. Studio hostname - Choose a unique hostname
  2. Project confirmation - Confirm the project to deploy
Example: 
? Studio hostname: my-awesome-studio
✔ Checking application info
...
Success! Studio deployed to https://my-awesome-studio.sanity.studio

​
App ID Configuration

For auto-updates and consistent deployments, add an appId to your config:
sanity.cli.ts
import {defineCliConfig} from 'sanity/cli'

export default defineCliConfig({
  api: {
    projectId: 'abc123',
    dataset: 'production',
  },
  deployment: {
    appId: 'your-app-id',  // Get this from first deploy
  },
})
The appId is displayed after your first deployment. Add it to sanity.cli.ts to avoid prompting on subsequent deploys.

​
External Hosting

If you host your Studio elsewhere (Vercel, Netlify, etc.), register it with Sanity: 
sanity deploy --external
This:
  • Skips the build and upload process
  • Registers your Studio’s URL with Sanity
  • Enables Studio features that require registration
  • Optionally deploys schema (unless you skip it)
When using --external, the --source-maps, --no-minify, and --no-build flags are ignored.

​
Schema Deployment

By default, your schema is extracted and stored during deployment. This enables:
  • Runtime schema validation
  • GraphQL API generation
  • Sanity.io features that rely on schema metadata

​
Require Schema Deployment

Fail the deployment if schema storage fails: 
sanity deploy --schema-required
Use this when:
  • Other services depend on the stored schema
  • GraphQL API must stay in sync
  • Schema validation is critical

​
Base Path Deployment

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

export default defineCliConfig({
  api: {
    projectId: 'abc123',
    dataset: 'production',
  },
  project: {
    basePath: '/studio',  // Studio accessible at /studio
  },
})
The Studio will be deployed with the base path configured: 
https://your-project.sanity.studio/studio

​
Environment Variables

Environment variables are embedded at build time:
.env.production
SANITY_STUDIO_PROJECT_ID=abc123
SANITY_STUDIO_DATASET=production
SANITY_STUDIO_PREVIEW_URL=https://preview.example.com
Environment variables with SANITY_STUDIO_ prefix are publicly accessible in the browser bundle. Never include secrets.

​
Auto-Updates

Enable auto-updates for automatic runtime updates:
sanity.cli.ts
import {defineCliConfig} from 'sanity/cli'

export default defineCliConfig({
  api: {
    projectId: 'abc123',
    dataset: 'production',
  },
  deployment: {
    appId: 'your-app-id',
  },
  autoUpdates: true,  // Enable auto-updates
})
With auto-updates:
  • Sanity packages auto-update at runtime
  • No rebuild needed for patch updates
  • Manually redeploy for major updates
Auto-updates keep your Studio current without constant rebuilds and redeploys.

​
Custom Domains

To use a custom domain:
  1. Deploy your Studio normally: 
    sanity deploy
  2. Go to manage.sanity.io
  3. Select your project
  4. Navigate to API → Studio Hostname
  5. Add your custom domain
  6. Configure DNS: 
    CNAME  studio.yourdomain.com  → <project-id>.sanity.studio
  7. SSL certificates are automatically provisioned

​
Deployment History

View deployment history in the Sanity management interface:
  1. Go to manage.sanity.io
  2. Select your project
  3. Navigate to Deployments
You’ll see:
  • Deployment timestamps
  • Sanity version deployed
  • Deploy status
  • Rollback options

​
Rollback

Rollback to a previous deployment:
  1. Go to project deployments in manage.sanity.io
  2. Find the deployment to restore
  3. Click Rollback
Or redeploy from a previous git commit: 
git checkout <commit-hash>
sanity deploy

​
CI/CD Integration

Deploy from continuous integration:
.github/workflows/deploy.yml
name: Deploy Studio

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '20'
      - run: npm ci
      - run: npx sanity deploy --yes
        env:
          SANITY_AUTH_TOKEN: ${{ secrets.SANITY_AUTH_TOKEN }}
Set SANITY_AUTH_TOKEN in your CI environment. Get a token from manage.sanity.io → API → Tokens.

​
Unattended Mode

For scripts and automation: 
sanity deploy -y
This:
  • Skips all interactive prompts
  • Uses defaults for all questions
  • Automatically proceeds with deployment

​
Troubleshooting

​
Authentication Required

If deployment fails with authentication errors: 
sanity login
sanity deploy

​
Build Errors

If the build fails during deployment:
  1. Test the build locally: 
    sanity build
  2. Fix any errors
  3. Deploy again: 
    sanity deploy

​
Upload Failures

If the upload fails:
  1. Check your internet connection
  2. Verify you have write access to the project
  3. Try deploying with verbose logging: 
    sanity deploy --verbose

​
Schema Store Failures

If schema extraction fails but you want to proceed: 
# Deploy without requiring schema success
sanity deploy

# Or fail fast if schema is critical
sanity deploy --schema-required

​
Large Bundle Size

If deployment is slow due to large bundle:
  1. Analyze bundle size: 
    sanity build --stats
  2. Remove unused plugins and dependencies
  3. Optimize images and assets

​
Alternative Hosting

You can self-host the Studio on:

​
Vercel

# Build the Studio
sanity build

# Deploy to Vercel
vercel --prod

# Register with Sanity
sanity deploy --external

​
Netlify

# Build the Studio
sanity build

# Deploy to Netlify
netlify deploy --prod --dir=dist

# Register with Sanity
sanity deploy --external

​
Custom Server

# Build the Studio
sanity build

# Copy dist/ to your server
scp -r dist/* user@server:/var/www/studio/

# Register with Sanity
sanity deploy --external
When self-hosting, ensure you:
  • Configure CORS origins in your project settings
  • Set up HTTPS/SSL
  • Configure proper cache headers
  • Run sanity deploy --external to register the Studio

​
Next Steps

Manage Projects

Open project management and configure settings

Development Server

Return to local development with the dev server

Build docs developers (and LLMs) love

Get started for freeTalk to us