NOTE: with this release we highly recommend to upgrade @sanity/ui in package.json to:

"@sanity/ui": "1.0.0-beta.30"

✨ Highlights

At-a-glance

This version introduces several breaking changes that we are really excited to share with everyone:

• Improved Components API
• Consolidated sanity package and exports
• React 18 as new baseline version
• Removing the Schema namespace

These changes will make the Studio's customization API easier to discover and will vastly improve DX when implementing plugins and customizations moving forward.

NOTE: This release vastly reduces the number of breaking changes that will be introduced as we are getting closer to the first official stable v3 release.

Components API

We have made changes to the new Components API that allows a lot more flexibility in terms of wrapping, replacing, and modifying components in the Studio.

These components are now available for customization:

• Studio components: the general components of the studio. In this iteration, the components that can be customized are navbar, tool menu, layout and logo.
• Form components: field, input, item and preview.

Example:

import {createConfig} from 'sanity'

export default createConfig({
  // ...,

  form: {
    components: {
      field: MyField,
      input: MyInput,
      item: MyItem,
      preview: MyPreview,
    },
  },

  studio: {
    components: {
      layout: MyLayout,
      logo: MyLogo,
      navbar: MyNavbar,
      toolMenu: MyToolMenu,
    },
  },
})

The components available in this API are rendered using a middleware pattern. This means that plugin customizations are applied in a chain. Each plugin may call props.renderDefault(props) to defer to default rendering (this API was next(props) in 3.0.0-dev-preview.20).

What is renderDefault?

The props for each component available in the API includes a callback function called renderDefault. As the name implies, renderDefault renders the default component. When you call renderDefault, you also pass the props needed to render the default component, and these props can be modified. In the example below, we create a custom tool menu plugin that filters out the vision tool when the studio is running in non-development mode:

import {useMemo} from 'react'
import {
  ToolMenuProps,
  createConfig,
  createPlugin,
  isDev,
} from 'sanity'

// Plugin's `ToolMenu` component
function MyToolMenu(props: ToolMenuProps) {
  const {renderDefault, tools} = props
    
  const filteredTools = useMemo(() => {
    return isDev ? tools : tools.filter((t) => t.name !== 'vision')
  }, [isDev, tools])

  return renderDefault({
    ...props,
    tools: filteredTools, // Pass the custom array of tools
  })
}

// Plugin
const toolPlugin = createPlugin({
  name: 'tool-plugin',
  studio: {
    components: {
      toolMenu: MyToolMenu,
    },
  },
})

// Config
export default createConfig({
  ...,
  name: 'studio-config',
  plugins: [toolPlugin()],
})

If yet another plugin makes customizations of toolMenu – then the props received in that plugin will be the result of the previous customization (that is, no vision tool in non-development mode).

NOTE: If renderDefault is not called, the middleware chain stops and the next plugin will have no effect.

Using renderDefault in schema

The renderDefault function may also be used directly in a schema definition to render a default component. In the example below, we create a component that renders the default string input with a character counter, directly in the schema:

import {Stack, Text} from '@sanity/ui'
import {defineField, StringInputProps} from 'sanity'

function StringInputCharacterCount(props: StringInputProps) {
  return (
    <Stack space={2}>
      {/* Render the default string input */}
      {props.renderDefault(props)}

      <Text align="right" size={1}>
        Characters: <strong>{props.value?.length || 0}</strong>
      </Text>
    </Stack>
  )
}

export const myDocument = defineField({
  type: 'document',
  name: 'myDocument',
  fields: [
    {
      name: 'title',
      type: 'string',
      title: 'Title',
      components: {
        input: StringInputCharacterCount,
      },
    },
  ],
})

Result:

Consolidated sanity package and exports

Breaking changes to export bundles

The sanity package is now split up into these export bundles:

• sanity
• sanity/cli
• sanity/desk
• sanity/router

There have been necessary changes made in order to make the exports clean and independent bundles: no API member is now exported twice (as was the case before). And there are no longer cyclic dependencies between exports.

Why? These changes are mainly introduced to prevent API confusion.

// Before: this is not great
import {Chunk} from 'sanity'
import {Chunk} from 'sanity/desk'
import {Chunk} from 'sanity/form'

// Now: an API member is only available in one of the exports
import {Chunk} from 'sanity'

This also means we have removed duplicate code in the export bundles, which could cause issues with React contexts and bundle size.

API release tags

All the API members in the sanity package now have API release tags. These are TSDoc release tags that are understood by Intellisense and can be seen in your IDE.

Example:

How to reason about the various tags:

React 18

The Studio internals are upgraded to React 18 and use the new concurrent renderer. Support for React v17 is dropped and v18 is the new baseline in order to make full use of the new features and performance improvements.

Why we're doing this now

Structured content creation should be a delightful and exceptional experience. Everything should feel responsive. That means the UI needs to keep up with your interactions no matter what. If 300 people are editing the same document as you are and your phone's CPU just can't keep up that's ok. Everyone else's changes can wait for a second or two before they show up. As long as you can type as fast as you want without ever feeling held back by a sluggish text field that struggles to keep up with your thoughts. The edits of your peers have time to render whenever you stop to gather your thoughts. It's more important for you to stay in the zone, and for the studio to prioritize responding to your interactions.

With new APIs like startTransition, useTransition, useDeferredValue and Suspense we can start moving towards making this vision a reality.

While it is possible to do this in a way that gives theoretical support for both react v17 and v18, we ultimately decided against it after a thorough evaluation with the goal of maintaining compatibility with v17. It came down to which option allow us to deliver the highest quality product, and unless everything is tested on both versions of react for every release we'll either:

• Have good v17 support but unable to adopt v18 features that can't be shimmed on v17. Such as startTransition, useTransition and useDeferredValue.
• Great v18 support but the v17 becomes increasingly buggy and slow as devs become used to how v18 behaves. For example v18 automatically batches state updates while v17 does not. A component that in v18 have few re-renders might have a ton of re-renders in v17 if the component author isn't aware of this difference and there's great v17 testing routines in place.

Upgrade info

Official guide: https://reactjs.org/blog/2022/03/08/react-18-upgrade-guide.html#updates-to-client-rendering-apis
If you're on react v17 today and don't see any warnings in your console when running your studio locally then upgrading is pretty much just a matter of bumping react, react-dom and react-is to ^18 in your package.json.

Read the official upgrade guide to get a sense of what components you might need to give a little refactor.
While migrating studio internals we found that if there's a problem in a component it's usually related to one of these factors:

• A class component that is using lifecycle method with a UNSAFE_ prefix, for example UNSAFE_componentWillMount or UNSAFE_componentWillReceiveProps. Detailed guide.
• The component had useEffect logic that assumed that useEffect(() => () => teardown(), []) the teardown() is only called once, and on unmount. Get a refresher on how useEffect works to make it easier to find and resolve these bugs.
• Incorrect dependency arrays in hooks like useEffect, useMemo, useCallback and such either because they were suppressed in the linter due to // eslint-disable or custom hooks and layers of abstractions made the linter unable to detect them.
• If you're on TypeScript and are seeing a lot of typing errors you can try the automated migration script. Or hold off on upgrading @types/react until you have the bandwidth to fix the problems that the stricter typings uncover in your code.

@sanity/ui

If you have a dependency on @sanity/ui and use it in your project make sure to bump it to v1 as it's upgraded to support the new concurrent renderer.

Other changes

renderStudio now returns a function for unmounting it, to make it easier to use in other libraries such as vue, svelte, solid, angular, jqueryui, mootools, whatever floats your boat. How about as a Web Component? ⛵

<script type="module">
import {createConfig, renderStudio} from 'sanity'
import {deskTool} from 'sanity/desk'

customElements.define(
  'sanity-studio',
  class extends HTMLElement {
    connectedCallback() {
      const config = createConfig({
        projectId: this.getAttribute("projectId"),
        dataset: this.getAttribute("dataset"),
        plugins: [deskTool()],
        schema: {
          types: []
        }
      })

      this.unmount = renderStudio(this, config)
    }

    disconnectedCallback() {
      this.unmount?.()
    }
  }
)
</script>

<sanity-studio projectId="pnkijp0b" dataset="codesandbox"></sanity-studio>

See Codesandbox with example using Sanity Studio v3 in a web component.

React Strict Mode

You can opt-in to React's Strict Mode checks for your custom studio components in these ways:

• Add reactStrictMode: true to your sanity.cli.ts file.
• Create a .env.development file and add SANITY_STUDIO_REACT_STRICT_MODE=true to it.
• Set the env var while starting sanity: SANITY_STUDIO_REACT_STRICT_MODE=true sanity start

We strongly suggest you opt-in to better prepare your custom studio for the future of React. This only affects development mode, production mode or sanity build is unaffected by this setting.

Schema namespace removed

The Schema namespace has been removed. The same types can now be accessed as regular imports from the sanity package.

// Before
import {Schema} from 'sanity'

const stringDef: Schema.StringDefinition = {...}

// Now
import {StringDefinition} from 'sanity'

const stringDef: StringDefinition = {...}

With this change it is now be possible to augment definition interfaces using declaration merging. This allows us to improve typesafety and intellisense in defineType schema helpers for plugins moving forward.

See TSDoc on defineType for examples on this.

Support for v2 theming

import {buildLegacyTheme} from 'sanity'

export default createConfig({
  // ... studio config ...
  
  theme: buildLegacyTheme({
    // here you can add CSS properties that
    // were used to customize Studio v2 theming
    '--black': '#000',
    '--default-button-color': '#666',
    // etc
  })
})

Improved search 🕵️

• Adds support for filtering search results by any number of document types. You can also browse documents from any number of types without entering a search query.
• Search is now toggleable with a hotkey (Command/Control-K) and fully navigable by keyboard.
• Recent searches (including selected document types) are stored for later use
• Search terms and results are retained upon close: handy if you want to quickly revisit or amend your last search
• Improves performance when rendering and scrolling through large result sets
• The search dialog is wider, giving you more space for the search result listing

NOTE: Documents listed in search results will no longer resolve custom components for block content and array views

Slug functions context

Slug options source and slugify are now passed a context parameter as the last argument. It contains getClient, schema and currentUser.

🐛 Notable bugfixes

• The Studio now includes global CSS with font-family, and will no longer use serif in cases where you don't use <Text> from @sanity/ui.
• Various minor bug fixes in the Portable Text Editor.
• Fixes various bugs related to React 18 support.
• Adds strict validation of predefined list options for array types.
• Fixes various issues with array inputs and makes sure all variations of array inputs have parity with v2.

📓 Full changelog