Skip to main content

Sanity Studio Cache Actions

This guide explains how to use the custom cache management and deployment actions directly from Sanity Studio.

Alternative Tool

For a dedicated UI tool that clears cache from multiple sources (Next.js, Vercel, Redis/Upstash), see the Cache Clear Tool. This page covers document-level actions that appear in the document menu.

Overview​

The Sanity Studio has been enhanced with custom document actions that allow you to:

  1. Clear Cache - Clear all cached content
  2. Clear Cache for Document Type - Clear cache for a specific content type
  3. Trigger Redeploy - Trigger a Vercel redeployment
  4. Clear Cache & Redeploy - Combined action for both

These actions appear in the document actions menu (three dots menu) in Sanity Studio.

Setup​

1. Environment Variables​

Add these to your .env.local file (or Vercel environment variables):

# Required for cache actions
SANITY_STUDIO_SITE_URL=https://your-domain.com
SANITY_STUDIO_CACHE_AUTH_TOKEN=your-secret-token-here

# Optional: For redeploy actions
SANITY_STUDIO_VERCEL_DEPLOY_HOOK=https://api.vercel.com/v1/integrations/deploy/...
# OR
SANITY_STUDIO_VERCEL_TOKEN=your-vercel-token
SANITY_STUDIO_VERCEL_PROJECT_ID=your-project-id

2. Get Vercel Deploy Hook (Optional)​

If you want to trigger redeployments from Sanity:

  1. Go to your Vercel Project Dashboard
  2. Navigate to Settings → Git → Deploy Hooks
  3. Click "Create Hook"
  4. Name it: "Sanity Studio Deploy"
  5. Copy the hook URL
  6. Add to environment variables as SANITY_STUDIO_VERCEL_DEPLOY_HOOK

Alternative: Use Vercel API token:

  1. Go to https://vercel.com/account/tokens
  2. Create a new token
  3. Get your project ID from Vercel dashboard
  4. Add SANITY_STUDIO_VERCEL_TOKEN and SANITY_STUDIO_VERCEL_PROJECT_ID

Usage​

From Sanity Studio​

  1. Open any document in Sanity Studio
  2. Click the three dots menu (⋮) in the top right
  3. Select an action:
    • "Clear Cache" - Clears all cached content
    • "Clear Cache for This Type" - Clears cache only for this document type
    • "Trigger Redeploy" - Triggers a Vercel redeployment
    • "Clear Cache & Redeploy" - Does both actions

Actions Explained​

Clear Cache​

  • Clears all cached content across all locales
  • Useful when you've made multiple content changes
  • Takes effect immediately

Clear Cache for This Type​

  • Clears cache only for the specific document type (e.g., "hero", "service")
  • More targeted - only affects related content
  • Faster than clearing everything

Trigger Redeploy​

  • Triggers a new Vercel deployment
  • Useful when you want to rebuild the site with latest changes
  • Check Vercel dashboard for deployment status

Clear Cache & Redeploy​

  • Combines both actions
  • Clears cache first, then triggers redeploy
  • Best for major content updates

Configuration​

For Local Development​

Add to studio/.env.local:

SANITY_STUDIO_SITE_URL=http://localhost:3000
SANITY_STUDIO_CACHE_AUTH_TOKEN=your-local-token

For Production​

Add to Vercel Environment Variables:

  1. Go to Project Settings → Environment Variables
  2. Add variables for Production, Preview, and Development
  3. Make sure SANITY_STUDIO_SITE_URL points to your production URL

Troubleshooting​

"Site URL not configured"​

Solution: Set SANITY_STUDIO_SITE_URL in your environment variables.

"Failed to clear cache"​

Possible causes:

  1. SANITY_STUDIO_CACHE_AUTH_TOKEN doesn't match CACHE_AUTH_TOKEN in your Next.js app
  2. Site URL is incorrect
  3. API endpoint is not accessible

Solution:

  • Verify both tokens match
  • Check site URL is correct
  • Test API endpoint manually: curl -X POST https://your-domain.com/api/cache/clear?all=true -H "Authorization: Bearer your-token"

"Deploy hook not configured"​

Solution:

  • Set up Vercel Deploy Hook (see setup instructions above)
  • Or configure Vercel API token + project ID

Actions not appearing in menu​

Solution:

  1. Restart Sanity Studio: cd studio && npm run dev
  2. Check browser console for errors
  3. Verify environment variables are loaded

Security Notes​

⚠️ Important Security Considerations:

  1. Keep tokens secret - Never commit tokens to git
  2. Use environment variables - Store in Vercel, not in code
  3. Restrict access - Only authorized users should have access to Sanity Studio
  4. Use strong tokens - Generate secure random tokens

Best Practices​

  1. Use "Clear Cache for This Type" for single document updates
  2. Use "Clear Cache" after bulk updates
  3. Use "Clear Cache & Redeploy" for major content changes
  4. Monitor cache performance - Check logs to see cache hit rates
  5. Set up webhooks - For automatic cache invalidation (see Sanity Webhooks)

Integration with Webhooks​

These manual actions complement the automatic webhook-based cache invalidation:

  • Webhooks - Automatic cache clearing when content is published
  • Manual Actions - On-demand cache clearing and redeployment

Use both for maximum flexibility!

Example Workflow​

  1. Edit content in Sanity Studio
  2. Publish changes
  3. Click "Clear Cache for This Type" to see changes immediately
  4. Or wait for automatic webhook to clear cache (if configured)
  5. Use "Trigger Redeploy" if you need to rebuild the site

Support​

For issues: