Skip to content
Unlock seamless workflows and faster delivery with our latest releases - Join the deep dive

sanity.json

Configure APIs, plugins and parts

sanity.json is a configuration file for Sanity components. There's one in the root of your project that contains the basic configuration for your studio.

Here's an example:

{
  "root": true,
  "project": {
    "name": "Movies",
    "basePath": "/studio"
  },
  "api": {
    "projectId": "<yourProjectID>",
    "dataset": "production"
  },
  "plugins": [
    "@sanity/base",
    "@sanity/components",
    "@sanity/default-layout",
    "@sanity/default-login",
    "@sanity/desk-tool",
    "@sanity/google-maps-input"
  ],
  "parts": [
    {
      "name": "part:@sanity/base/schema",
      "path": "./schemas/schema.js"
    }
  ]
}

Environments

If you want to target different datasets in your local development environment and in production you can configure sanity.json like this: 

{
  //...,
  "api": {
    "projectId": "<yourProjectId>",
    "dataset": "production"
  },
  "env": {
    "development": {
      "api": {
        "dataset": "staging"
      }
    }
  },
  //...
}

When running sanity start (for local development), the development environment is used. When running the output of sanity build or sanity deploy, the production environment is used.

Development server host/port

If you want the local development server to listen to a different hostname or port number, you can set a server property and specify overrides. This can be useful if you're running multiple studios at the same time, or you want to access the development server from a different device on your network.

{
  //...,
  "server": {
    "hostname": "0.0.0.0", // Listen on all devices
    "port": 3333
  }
  //...
}

Gotcha

When changing these values, make sure you add a new whitelisted CORS-origin which allows credentials.

Properties

  • rootboolean

    Defines whether this is the root sanity.json file of your project. Plugins also have a sanity.json configuration file that defines their named parts, but plugins should have the root property set to false (or omitted entirely).

  • projectobject

    Defines the name of the studio displayed in the upper left corner (if no logo is set). Optionally is may also contain a basePath that defines the root path for the studio. This lets you build the Studio to a static bundle with sanity build and embed it in existing management interfaces.

  • apiobject

    Defines the projectId and dataset that this Studio will be connected to. You can find the projectId on sanity.io/manage when looking at your project. A project can have multiple datasets so you need to configure that as well.

  • pluginsarray

    Defines the basic plugins for your studio. These plugins may themselves define their own plugins with their own sanity.json files. If you want to provide your own implementations for any of these you may do so below under parts.

  • partsarray

    Defines named parts for the plugin system. In this example, we only define a single part – our schema that defines the data model for this studio.

  • serverobject

    Defines properties for the development server, namely hostname and port to listen on. The default hostname is localhost and the default port number is 3333. When changing these values, make sure you add a new whitelisted CORS-origin which allows credentials.

  • envobject

    An object with environment names as keys and an object of sanity.json values you want to override for that specific environment. See example here.

Updated on February 13, 2024

Was this article helpful?