Introduction to Sanity Studio v3
Sanity Studio is one of the cornerstones of the Sanity Platform. Since its first version launched in 2017, it has gone through 2 major iterations. Last year, we completed the full refactor of all our UI components moving from CSS modules to Sanity UI. A major undertaking that brought visual consistency, improved accessibility, and easier customization. For us, it was also a necessary step in preparing to refactor the underlying studio architecture. We’ve been hard at work on this and we’re finally able to share this developer preview with you. We can’t wait to hear what you think!
Sanity Studio v3 brings the following improvements:
- New out-of-the-box tooling for faster hot module reloading and lighter builds based using Vite (https://vitejs.dev/)
sanitymono-package with full ECMAScript Modules (ESM) support and CommonJS fallback
- New APIs for configuration, plugins, form customization, and theming (coming soon)
- New methods for wrapping input fields in custom components and improved support for custom array inputs
- You can use context about the current project and logged-in user to return specific schemas, structures, plugins, etc., in the new configuration API to personalize the Studio
- All the new APIs are fully typed in TypeScript, and we’ll document using TSDoc. This gives autocomplete and instant validation in code editors that support it.
- New Sanity Docs Beta (https://beta.sanity.io/docs) with migration guides, conceptual introduction, and complete API reference of all public Studio APIs
- A new plugin toolkit (https://github.com/sanity-io/plugin-kit) to support plugin development, publishing, and migrations
- Sanity Studio v3 supports dark mode based on user preference, with theming support on the way
- Cleaner and more consistent APIs, for example a new
componentsproperty in the Schema API
- …and a lot of other small fixes!
Let’s be frank: Breaking changes for code you rely on sucks. Even when it’s to make things better. It’s not something we do lightly. We have had basically no breaking changes in studio APIs since the public launch in late 2017. The major version changes have mainly been to signal maturity and to introduce new functionality.
While we hope that the new features and possibilities will sweeten the deal, we’re also committed to:
- Providing migration guides and improved documentation
- Following up in channels for feedback and support customers and community in migrating to and using V3
- Helping to migrate the most popular plugins and provide PRs for plugin authors
- Keep supporting V2 with bug and stability fixes after V3 is generally available
We will cover this in dedicated migration guides, but the points below should give you a quick sense of the work that’s involved in migrating from V2 to V3.
The amount of work depends on how much customization you have done that relies on importing Parts.
You’ll have to:
- port your Studio configuration in
- replace any
import X from part:Xstatement with new public Studio APIs
- move custom components to the new
componentsproperty in the schema API
- update any plugin you use to a new version that supports the V3 APIs (we’re actively helping popular plugins to become compatible)
- You’ll need to port the configuration for your plugin from
sanity.jsonto the new Plugin API
- replace any
import X from part:Xstatement over to the new public Studio APIs
- Distribute the plugin on npm with a tagged version (
- Verify the plugin package with our plugin tooling
Hopefully, the users of the studio won’t have to do anything as everything will look and work the same. In refactoring the studio APIs we’ve also made sure that it’s either as performant or more performant than V2. After V3 has reached GA, we can also move much faster with higher confidence with further Studio improvements and new features (which has been a huge motivating factor behind this project).
These guides are under development. If you have questions or suggestions for improvements, then we want to hear from you. Get in touch on GitHub.