Index
Edit

Plugins

Need a plugin for your Content Studio? You have the choice of two options:

1. Install an existing plugin

Install a pre-existing plugin into the node_modules folder. This is the consumer option. You download and use a plugin which is maintained somewhere else.

2. Create a new plugin

Create a new plugin directly in the plugins folder. This is the developer option when creating a plugin for your Sanity installation. You can extract it later, if you want to make it available to others.

A closer look at the options

Say you want to use Sanity for managing a movie database, and you need a plugin for pulling, filtering and conditionally publishing third-party reviews. Let's call the plugin third-party-reviews.

Option 1

The third-party-reviews plugin already exists, and you want to install it. Run the Sanity plugin install command: sanity install third-party-reviews

Assuming there is an NPM package named sanity-plugin-third-party-reviews available, a few things will happen:

  • The plugin will be installed into the node_modules folder.
  • The plugin name will be appended to the plugins section of your sanity.json file.
  • If the plugin includes a config.json.dist file, two more things will happen:
  1. The config.json.dist file will be copied to configs/third-party-reviews.json
  2. A checksum based on the config.json.dist file will be appended to configs/.checksums file. This provides a fast way of checking if the installed plugin is up to date.

Option 2

You are a developer and want to create the  third-party-reviews plugin yourself.

  1. Create a folder for your plugin mkdir plugins/third-party-reviews && cd plugins/third-party-reviews
  2. Run the Sanity plugin bootstrap command: sanity init plugin. Follow the prompts along the way.
  3. Add your plugin name to plugins section of your root sanity.json. Usually you want to place the plugin at the bottom, like this:
{
  "plugins": [
    "@sanity/base",
    "@sanity/default-layout",
    "third-party-reviews"
  ]
}

You can now start writing your plugin! Check out this sample plugin if you're unsure on how to get started.

As mentioned above, a plugin can reside in one of two locations:

  • In the node_modules folder.
  • In the plugins folder.

Sanity treats plugins differently, based on their location.

Plugins within node_modules

  • Need to be prefixed with sanity-plugin- to be recognized (optionally with a scope; @yourcompany/<plugin-name>).
  • Need to be runnable in a browser (ES5-compatible). ES6, JSX and similar are usually compiled as part of a pre-publish step for each plugin.

Plugins within plugins

  • Do not need to be prefixed with sanity-plugin- to be recognized.
  • Are automatically run through Babel if the paths property is set and has a compiled location. See the part system documentation for more information.

In general, you can think of plugins installed to node_modules as plugins you consume, while plugins inside of the plugins directory contain functionality local to your Sanity instance.

Environment-specific plugins

Sometimes you might have plugins that you only want to expose in development mode (when you are running the studio through sanity start locally). This can be achieved by putting it in the env section of your studios sanity.json.

For instance, to only load the vision plugin in development, you can do:

{
  // ...
  "plugins": [
    "your",
    "regular",
    "plugins"
  ],
  
  "env": {
    "development": {
      "plugins": [
        "vision"  
      ]
    }
  }
}

Examples

If you're unsure about how to create a plugin, some examples might be of help.

Previous: StylingNext: Custom Input Widgets