👋 Next.js Conf 2024: Come build, party, run, and connect with us! See all events

Auto-updating Sanity Studio

Learn about automatic updates to your studios.

Sanity Studio is auto-updating by default. Keeping up with frequent releases and making sure your editorial teams get access to all the latest improvements and bugfixes is more convenient than ever before.

The core Sanity Studio app will automatically be kept up to date whenever a patch or minor release drops (3.X.X), while your custom code remains untouched and continues to work seamlessly.

No breaking changes. Just the good stuff.

Protip

Existing studio projects that were deployed before automatic updates became the default with version 3.57.3 of Sanity Studio are not automatically opted in to this behavior. To enable automatic updates in an existing project, run sanity build or sanity deploy either using the --auto-updates flag, or after setting autoUpdates: true in your studio config.

Prerequisites

  • Using auto-updating studios requires a browser that supports import maps. This feature has been considered a baseline feature in modern browsers since March 2023, and is supported in all the latest versions of common browsers.
  • Auto-updates is only supported for studios compiled with Sanity build tooling. I.e., running sanity deploy or sanity build in your command line. Third-party build tools and embedded studios are not currently in scope for this feature.

Build or deploy?

For the auto-update feature to work, you must compile your studio using the build tooling provided in the core Sanity Studio package. Somewhat confusingly we refer to both the sanity deploy and sanity build commands in this article, but what's the difference?

In short, the --auto-updates flag or autoUpdates config parameter works with either command. If your studio is hosted on a free *.sanity.studio-domain you probably use sanity deploy to build and deploy your studio in one fell swoop, while if you are hosting the studio elsewhere chances are that you compile the studio with sanity build, and then deal with deployment with a custom workflow.

Opting Out

With auto-updates, your studio keeps itself current with the latest patch and minor version (i.e., 3.X.X) without intervention. Instead of building and re-deploying your studio for each new version, the core Sanity Studio application is streamed on-demand to your browser, which means you'll always get access to the latest updates as they are released. Note that releases are gradually rolled out, so you may not immediately see a new release after a new version is out.

If you need to support older browsers without support for import maps, if you have customized your studio using internal APIs or simply need full control over the studio dependencies, you can opt out of auto-updates. If you decide to opt out of auto-updates, set autoUpdates: false in your sanity.cli.ts configuration file, and then build and deploy. Alternatively, build your studio with the --no-auto-updates flag set.

// sanity.cli.ts
import { defineCliConfig } from 'sanity/cli'

export default defineCliConfig({
  api: {
    projectId: 'your-project-id',
    dataset: 'production',
  },
  autoUpdates: false,
})

Developing auto-updating studios

Your local development process remains unchanged. You will still install the latest version of the Sanity Studio package locally and run your dev server on localhost, quite possibly at port 3333. When you are ready to commit, build and deploy your studio, explicitly setting the feature flag or CLI config property if needed.

If you have auto-updating enabled and are developing locally against a version that is not up-to-date you will receive a warning in your build step to ensure you are aware of any potential discrepancies.

Caveats and key takeaways

  • Auto-updating is currently only supported for studios built with the sanity build command. Other build tools and embedded studios are not supported.
  • Auto-updates requires a browser that supports import maps, which has been considered a baseline feature in modern browsers since March 2023, and is supported in all the latest versions of common browsers.
  • When developing with auto-updates enabled, you may receive warnings in your build step if your local version is out of sync with the auto-updated deployed version. Keep an eye out for these to ensure you're aware of any discrepancies between your development and production environments.
  • Auto-updating keeps your studio current with patch releases and minor updates, but will not automatically update to major releases. Rest assured that breaking changes will be announced clearly and in a timely fashion, as always.
  • To opt out of auto-updating, rebuild and redeploy your studio using the --no-auto-updates feature flag or the autoUpdates configuration property set to false. Changes will take effect for your editorial teams once the new build has been successfully deployed.
  • Auto-updating keeps your studio up-to-date, but you're still responsible for updating and maintaining any custom code, plugins, or configurations layered on top of the base Sanity Studio.

Was this article helpful?