Sanity Studio v3: Release Candidate

This is the first Release Candidate of Sanity Studio v3. That means that you can expect APIs marked @public to be stable going forward. We are still ironing out bugs and making improvements, and appreciate any input or questions you might have.

We also want to invite you to a Sanity virtual event on December 8th, where we will dive into customer stories, demos, and talk about where the Sanity platform is headed.

You might also want to check out the notes for recent releases.

Installation and upgrading

To globally install/upgrade the v3 Sanity CLI:

npm install --global sanity@dev-preview

To validate you're on @3.0.0-rc.0:

$ sanity --version
> sanity version 3.0.0-rc.0

The new CLI should work with existing v2 studios, but you won't be able to initialize new v2 studios with it.

To initiate a new Studio without installing the CLI globally:

npx create-sanity@dev-preview

To upgrade a v3 Studio:

npm install sanity@3.0.0-rc.0

Make sure your package.json are up to date with these dependencies:

{
  "dependencies": {
    // if you’re depending on `@sanity/ui`
    "@sanity/ui": "1.0.0-beta.32",
    "sanity": "3.0.0-rc.0"
  }
}

You might also have to upgrade your Sanity v3 plugins to their latest versions. The following command might be useful for checking for plugin updates:

npx npm-check-updates --target @studio-v3 --filter sanity

Breaking change: sanity start is now sanity dev

In Studio v2 and earlier developer preview releases, the command sanity start was used to start the development server. To better align with other frameworks such as Next.js, Remix, and Gatsby, we have renamed the command to sanity dev. The sanity start command is now used to start a static server that can be used to preview a production build (it is also available as sanity preview).

For existing studios, you might want to add a new dev npm script to your package.json file to make sure your team knows about the change:

{
  // ...
  "scripts": {
    "build": "sanity build",
    "dev": "sanity dev",
    "deploy": "sanity deploy",
    "start": "sanity start"
  }
}

Breaking change: createConfig is now defineConfig

To better align with other frameworks, we have renamed the following create-methods:

• createConfig -> defineConfig
• createCliConfig -> defineCliConfig
• createPlugin -> definePlugin

The old create-methods will still work for the time being, but are deprecated and will be removed prior to the final release of v3.

Beta: Add custom functionality to array inputs

It is now possible to customize the array input with custom functions. The API allows you to replace the Add button and exposes different methods through its properties for interacting with array content.

This feature also introduces breaking changes for callback namings and typings (see below).

Example of custom array functionality in defineConfig:

// sanity.config.ts

import {defineConfig, isArrayOfPrimitivesInputProps} from 'sanity'

function MyArrayFunction(props) {
  const {onItemAppend} = props

  const handleAdd = useCallback(() => {
    // Adds 'Hello!' to new string items in the array
    onItemAppend('Hello!')
  }, [onItemAppend])

  return <Button text={`Add "Hello!" to the array`} onClick={handleAdd} />
}

export default defineConfig({
  // ...,
  // other config
  form: {
    components: {
      input: (props) => {
        const {renderDefault}  = props

        // Check if the input is an array of primitives (strings etc)
        if (isArrayOfPrimitivesInputProps(props)) {
          return renderDefault({...props, arrayFunctions: MyArrayFunction})
        }

        return renderDefault(props)
      },
    },
  },
})

For feedback and questions on this API, go to GitHub Discussions.

Breaking change: Advanced input component callbacks

We've aligned our API naming policy for callbacks to be on<Subject><Verb>. For improved consistency, we have renamed the following callbacks:

• onFocusPath -> onPathFocus
• onCollapseFieldSet -> onFieldSetCollapse
• onExpandFieldSet -> onFieldSetExpand
• onCollapseField -> onFieldCollapse
• onExpandField -> onFieldExpand
• onOpenField -> onFieldOpen
• onOpenItem -> onItemOpen
• onCloseItem -> onItemClose
• onRemoveItem -> onItemRemove
• onPrependItem -> onItemPrepend
• onAppendItem -> onItemAppend
• onCollapseItem -> onItemCollapse
• onExpandItem -> onItemExpand
• onCreateValue -> onValueCreate

These callbacks are mostly used for complex custom object/array inputs.

Breaking change: Array functions components/types

We've improved "array functions" - see above. With this change comes a few naming changes:

• DefaultArrayOfPrimitivesFunctions -> ArrayOfPrimitivesFunctions
• DefaultArrayFunctions -> ArrayOfObjectsFunctions
• FormArrayInputFunctionsProps -> ArrayInputFunctionsProps

The default array functions components (ArrayOfPrimitivesFunctions and ArrayOfObjectsFunctions) are now exported from the sanity package.

All default input components are now exported

All the standard inputs are now exported and available in the sanity package for use when building custom input components.

Notable bugfixes

• Fixed an issue where the review changes panel might not use the selected document revision, and the content form would go into read-only mode

📓 Full changelog