@sanity/plugin-kit
Advanced tools
NOTE
This is a developer preview package meant for Sanity Studio v3 plugin development.
For a v2 alternative, consider using Sanipack.
@sanity/plugin-kit is an opinionated, enhanced Sanity.io v3 plugin development experience.
It provides a set of CLI commands for initializing, verifying and testing a Sanity plugin for Sanity Studio v3. The verify-package command can be used when upgrading V2 plugins to Studio V3 versions.
@sanity/plugin-kit also comes with a verify-studio command that can be used to recommend upgrade steps in existing Sanity Studio v2 studio.
This package assumes and recommends @sanity/pkg-utils for building, and Yalc with watch for testing the plugin in Sanity Studio. Check the FAQ fro more on these.
npm install --save-dev @sanity/plugin-kit
@sanity/plugin-kit assumes the plugin will use @sanity/pkg-utils for build and watch:
npm install --save-dev @sanity/plugin-kit
First, run the init command:
# Initialize a new plugin (outside of your Sanity studio folder)
npx @sanity/plugin-kit init sanity-plugin-testing-it-out
# Make your plugin linkable, and compile an initial version
cd sanity-plugin-testing-it-out
npm run link-watch
# In another shell, link the plugin to your Sanity studio
cd /path/to/my-studio
yalc add --link sanity-plugin-testing-it-out && yarn install
Now, configure the plugin in sanity.config.ts (or .js) in Sanity Studio:
import {createConfig} from 'sanity'
import {myPlugin} from 'sanity-plugin-testing-it-out'
export const createConfig({
//...
plugins: [
myPlugin({})
]
})
Start the studio:
sanity start
Check browser console: the plugin should have logged "hello from my-sanity-plugin".
Since the plugin is running in watch mode, any changes you make to the plugin code will be reloaded in the studio.
The init commands has several config flags, run
npx @sanity/plugin-kit init --help
for up-to-date specifics.
Verify that the plugin package is configured correctly by running:
npx @sanity/plugin-kit verify-package
tsc --noEmit when all other checks have passedEach check will explain why it is needed, steps to fix it and how it can be individually disabled.
verify-package is not a codemod tool (yet). It will only check files and recommended settings: it will not change any files.
Simply use the verify-package command in a v2 plugin package, and it will notify you about steps you need to take to upgrade the
plugin to v3.
npx @sanity/plugin-kit verify-package
You can use the verify-studio command in a v2 Sanity Studio to get some of the same validation there, to help in the upgrade from v2
to v3.
npx @sanity/plugin-kit verify-studio
This will:
sanity.json, sanity.config.(ts|js) and sanity.cli.(ts|js) and advice on how to convert the former to the latter two.## for plugins
npx @sanity/plugin-kit verify-package --single
## for studio
npx @sanity/plugin-kit verify-package --studio --single
This will only output the first validation that fails. Useful when working through the list of issues by fixing and rerunning the command.
Consult the inject command CLI help:
npx @sanity/plugin-kit inject --help
for up-to-date specifics.
Ensure you have the following script setup in package.json:
{
"scripts": {
"link-watch": "plugin-kit link-watch"
}
}
Then, in a shell, run:
npm run link-watch
This will publish the plugin to a local yalc registry.
In another shell, in your test Sanity Studio directory, run:
npx yalc add <your-plugin-package> && npx yalc add <your-plugin-package> --link && npm install
You can now change your plugin code, which will:
yalc publish --pushNote: Yalc will modify your studio package.json when linking; remember to revert it when you are done testing.
You should also put .yalc and yalc.lock into .gitignore.
When you are done testing, you can run
npx yalc remove <your-plugin-package> && yarn install
to restore the version in package.json.
This command can be configured using sanityPlugin.linkWatch in package.json:
{
"sanityPlugin": {
"linkWatch": {
// directory to watch
"folder": "lib",
// command to run when content in linkWatch.folder changes
"command": "npm run watch",
// file extensions to watch for changes in the linkWatch.folder
"extensions": "js,png,svg,gif,jpeg,css"
}
}
}
See the FAQ.
Note: If you're writing a plugin that is only useful for yourself or your company, you might want to develop the plugin directly in the Studio (saves you from having to publish at all, and has improved hot-reload dev experience).
If the plugin is shared across multiple "private" studios: register an organization on npm and make sure your module is
prefixed with the organization scope, eg @your-company/plugin-name.
Also; you cannot easily remove modules/versions from npm once published.
Take a good look at your package.json to see that the fields in there makes sense to you,
and make sure there are no "secrets" (authorization tokens, API keys or similar) in the plugin directory -
anything not listed in .npmignore will be part of the published module.
When you're ready to publish, run npm publish (or yarn publish if you prefer).
The prepublishOnly task should kick in and compile the source files, then verify the built output to ensure it looks good.
If you have not published any modules to npm before, you will be asked to create a user first.
For an opinionated template for publication based on semantic-release, see semver-workflow preset
To upgrade a plugin that already uses @sanity/plugin-kit 1.x:
@sanity/plugin-kit to version to 2.x in package.jsonnpx @sanity/plugin-kit inject
npm installnpm run buildA: Absolutely not! Make sure your Sanity plugin is ES6-compatible. This package was created to make it easier to set up the build toolchain and prevent common mistakes.
If you know what you're doing and don't like any magic, roll your own thing! :)
npm link & yarn link unfortunately can easily break the rules of hooks due to the way packages are resolved using symlinks.
Yalc bypass this problem as it more closely resembles installing a dependency as normal.
A: No!
Feel free to use any variation of npm link or yarn link alongside npm run watch for testing,
but beware that if you get errors from React along the lines of
Error: Invalid hook call. Hooks can only be called inside of the body of a function component.
This could happen for one of the following reasons:
- You might have mismatching versions of React and the renderer (such as React DOM)
- You might be breaking the Rules of Hooks
- You might have more than one copy of React in the same app
See https://reactjs.org/link/invalid-hook-call for tips about how to debug and fix this problem.
you probably have to revert to using yalc, or use npm pack + and install the resulting tzg-file.
At the time of writing (Nov 2022) the latest version of parcel (2.7) failed to build Sanity plugins. The previous version (2.6) did not work with the latest version of TypeScript. Pinning these versions was confusing and caused issues.
We also saw issues with modules using nested async imports.
As such, we decided to standardize plugins on the same build-tool used by Sanity studio, @sanity/pkg-utils.
@sanity/pkg-utils is the build tool used to build the sanity
package. It is based on esbuild and rollup and sports an array of validation to ensure that package.json can build
both commonjs and ems packages that can be used in a variety of js runtimes.
Using this internal tool for plugins allows Sanity to more quickly address common build-related issues with plugins, and aims to standardize how this is done thought the community.
A: Yes!
Feel free to make any changes to package.config.ts as is needed.
@sanity/plugin-sdk verify-package output is only recommendations for defaults that has been tested to work in Sanity Studio.
Your plugin may have other needs.
You are also free to not use @sanity/pkg-utils at all; simply change your package.json build script, and disable any verification-steps
you don't care for with sanityPlugin.verifyPackage.
$ npx @sanity/plugin-kit --help
Usage
$ plugin-kit [--help] [--debug] <command> [<args>]
These are common commands used in various situations:
init Create a new Sanity plugin
verify-package Verify that a Sanity plugin follows plugin-kit conventions
inject Inject plugin-kit complatible package config into an existing plugin directory
link-watch Recompile plugin automatically on changes and push to yalc
version Show the version of ${cliName} currently installed
Options
--silent Do not print info and warning messages
--verbose Log everything. This option conflicts with --silent
--debug Print stack trace on errors
--version Output the version number
--help Output usage information
Examples
# Init a new plugin
$ plugin-kit init
# Verify that a Sanity plugin follows plugin-kit conventions
$ plugin-kit verify-package
Provide a sanityPlugin config in package.json (defaults shown):
{
"sanityPlugin": {
"linkWatch": {
"folder": "lib",
"command": "npm run watch",
"extensions": "js,png,svg,gif,jpeg,css"
}
},
"verifyPackage": {
"packageName": true,
"module": true,
"tsconfig": true,
"tsc": true,
"dependencies": true,
"rollupConfig": true,
"babelConfig": true,
"sanityV2Json": true,
"eslintImports": true,
"scripts": true,
"pkg-utils": true,
"nodeEngine": true
}
}
MIT © Espen Hovlandsdal and Sanity.io
In one shell, run
npm link
npm run watch
In the package where you want to test plugin kit, run:
npm link @sanity/plugin-kit
Now you can run commands:
npx @sanity/plugin-kit verify-package
or use them in package.json scripts:
"verify": "plugin-kit verify-package"
npm run test
npm run test -- test/verify-package.test.ts
npm run test -- test/verify-package.test.ts --snapshot
Run "CI & Release" workflow. Make sure to select the main branch and check "Release new version".
Semantic release will only release on configured branches, so it is safe to run release on any branch.
FAQs
Enhanced Sanity.io plugin development experience
The npm package @sanity/plugin-kit receives a total of 1,366 weekly downloads. As such, @sanity/plugin-kit popularity was classified as popular.
We found that @sanity/plugin-kit demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 55 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
The Socket Research Team uncovered a malicious Python package typosquatting the popular 'fabric' SSH library, silently exfiltrating AWS credentials from unsuspecting developers.
Security News
At its inaugural meeting, the JSR Working Group outlined plans for an open governance model and a roadmap to enhance JavaScript package management.
Security News
Research
An advanced npm supply chain attack is leveraging Ethereum smart contracts for decentralized, persistent malware control, evading traditional defenses.