Sanity Studio v4: A major version bump for a minor reason
The sanity npm package now requires Node.js 20. That's it. Your Studio code works exactly as before. Here's what you need to know about this update.
Knut Melvær
Head of Developer Community and Education
Published
We're moving the sanity package from v3 to v4. The only breaking change? We now require Node.js 20 instead of Node.js 18.
That's it. That's the post.
The boring details
Node.js 18 hit end-of-life in April 2024. Our dependencies are dropping support for it, which means we need to as well.
This ecosystem-wide shift includes tools like Vite 7, which now requires Node.js 20. While we haven't upgraded to Vite 7 yet, moving to Node.js 20 means we can bring you these improvements when we do: faster builds and reduced memory usage during development. Staying on Node.js 18 would lock us out of these developer experience improvements.
According to semantic versioning rules, dropping Node.js version support is technically a breaking change that requires a major version bump. Why? Because if you're on Node.js 18 and try to install the new version, it won't work. That's the textbook definition of "backward incompatible."
We could have bent the rules (we've done it before), but we decided it's time to align the sanity package with how the rest of the npm ecosystem handles versioning. All our other packages already follow standard semver—sanity has been the odd one out.
And for those of you who were here for it, this isn't like the v2 to v3 jump, where we completely reimagined how Sanity Studio worked. That was a true platform shift that took serious migration effort. That kind of migration effort taught us a lot about managing change (especially on how to not do it). This v4 bump is different—it's purely about Node.js compatibility.
What changes for you
Your code
Nothing. Your schemas, Studio customizations, and content work exactly as before.
Your Node.js version
Quick reminder: Sanity Studio is a single-page application that compiles to static files. Node.js is only required for development tooling and building—not for running Studio in the browser. Your users won't notice a thing.
If you're on Node.js 20 or higher, run npm update sanity@latest when v4 ships on July 15th.
If you're still on Node.js 18, you'll need to upgrade. The good news? Node.js 20 brings native ES module support, better performance, and a built-in test runner.
To check if your dependencies are compatible with Node.js 20:
# npm/pnpm will warn about incompatible packages during install
npm install
# To check a specific package's Node requirements:
npm info <package-name> engines
# To check if your custom code uses deprecated APIs:
node --trace-deprecation studio/sanity.cli.js start(You probably won't find any issues if you've kept dependencies up to date.)
What this means going forward
We're adopting standard semantic versioning for the sanity package:
- Patch versions (4.0.x): Bug fixes only
- Minor versions (4.x.0): New features, no breaking changes
- Major versions (x.0.0): Breaking changes (like Node version requirements)
Major bumps will happen more often but be far less dramatic. Think maintenance updates, not platform overhauls.
Our commitment stays the same
We still go to great lengths to avoid breaking changes. We still maintain backward compatibility longer than we probably should. This versioning change just makes it clearer when something might affect your setup.
Timeline
- This week: You'll see a CLI notice about this change
- July 15th: v4 ships
- After July 15th: All new features and fixes go to v4
Ready? Check your Node version with node --version. If you're below 20, grab the latest from nodejs.org.
Questions? Hit us up in the community or check the changelog.