@snorreeb/plugin-sdk v0.0.21
sanity-plugin-sdk
NOTE: This is Sanity v3 work in progress!
An opinionated, enhanced Sanity.io plugin development experience.
Install
npm install --save-dev @snorreeb/plugin-sdk
or
yar add -dev @snorreeb/plugin-sdk
Basic usage
Upgrade help for v2 -> v3
Install this package as a dev dependency.
Assumption:
- The project is already configured to use eslint; it has a eslint-config that works.
To check if a plugin is v3 compatible run
npx sanity-plugin upgrade-help
This will list things that will have to be fixed to port a v2 plugin to v3.
Use in Sanity studio
npx sanity-plugin upgrade-help --studio
Fail fast mode
npx sanity-plugin upgrade-help --single
This will only output the first validation that fails. Useful when working through the list of issues by fixing and rerunning the command.
Opinionated build
Add the following to your plugin package.json script section:
{
"build": "sanity-plugin build",
"watch": "sanity-plugin watch",
"link-watch": "sanity-plugin link-watch",
"prepublishOnly": "npm run build"
}
Run
npm run build
This will build a version of the package and verify that the output complies with the module configuration in package.json.
Plugin testing
In one terminal, run:
npm run link-watch
This will publish the plugin to a local yalc registry.
In another terminal, in your test Sanity Studio run:
npx yalc add --link && yarn install
You can now change your plugin code, which will:
- Trigger a rebuild using your watch task, which will
- Update the files in the plugin output directory, which will
- Trigger a yalc publish --push, which will
- Update the files in your Sanity Studio, wich will
- Trigger hot reload and you should see the plugin changes in the Studio
Advanced configuration
Provide a sanityPlugin config in package.json (defaults shown):
{
"sanityPlugin": {
"buildCommand": "microbundle --format modern,esm,cjs --jsx React.createElement --jsxImportSource react --css inline",
"watchCommand": "microbundle watch --format modern,esm,cjs --jsx React.createElement --jsxImportSource react --css inline",
"watch": {
"folder": "lib",
"command": "npm run watch",
"extensions": "js,png,svg,gif,jpeg,css"
}
},
"upgradeHelp": {
"module": true,
"tsconfig": true,
"dependencies": true,
"rollupConfig": true,
"babelConfig": true,
"sanityJson": true,
"eslintImports": true
}
}
Why use yalc
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.
OLD README
Features
- Bootstrap new plugins with (opinionated) tooling:
- ESLint (with Sanity config)
- Prettier (with Sanity settings)
- EditorConfig (with Sanity settings)
- .gitignore + .npmignore
- Build scripts (pre-publish build + verify)
- Verifies plugin conventions before publishing:
- No unused dependencies
- No undeclared dependencies
- Referenced files exist, has correct casing and is publishable
- Has an SPDX compatible license definition
- Has a valid plugin config, if present
react
/react-dom
declared as peer dependencies, if used- ... and more ...
- Compiles plugin source code using Babel
Quick start
# Initialize a new plugin (outside of your Sanity studio folder)
npx sanipack init sanity-plugin-spotify
# Make your plugin linkable, and compile an initial version
cd sanity-plugin-spotify
npm link
npm run build
# Link the plugin to your Sanity studio and start it
cd /path/to/my-studio
npm link sanity-plugin-spotify
sanity start
# In another terminal, start a watch task for your plugin
cd /path/to/sanity-plugin-spotify
npm run watch
Usage
Enhanced Sanity.io plugin development experience
Usage
$ sanipack [--help] [--debug] <command> [<args>]
These are common commands used in various situations:
build Compile a Sanity plugin (prior to publishing)
init Create a new Sanity plugin
splat Inject sanipack into an existing Sanity plugin
verify Verify a Sanity plugin prior to publishing
version Show the version of sanipack 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
# Build a Sanity plugin for publishing
$ sanipack build
# Verify that a Sanity plugin is ready to be published
# (great for pre-publish step!)
$ sanipack verify
Use the --help
flag on each command for more information on their usage, eg sanipack build --help
.
Publishing a plugin
Note: If you're writing a plugin that is only useful for yourself or your company, you might want to either put the plugin inside of the plugins
folder of your Sanity studio (saves you from having to publish at all), or if 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.
FAQ
Q: Do I have to use this for developing Sanity plugins?
A: Absolutely not! Make sure your Sanity plugin is ES5-compatible and that your sanity.json
file and any references parts refer to the right directories, and you're good to go. 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! :)
License
MIT © Espen Hovlandsdal