A boilerplate for creating Netlify CMS widgets.
Widgets are inputs for the Netlify CMS editor interface. It's a React component that receives user input and outputs a serialized value. Those are the only rules - the component can be extremely simple, like a text input, or extremely complicated, like a full blown markdown editor. They can make calls to external services, and generally do anything that JavaScript can do.
The starter currently provides a basic string widget, which you can customize, extend, or replace entirely with your own widget.
Check out the docs for more details.
Clone or fork the repo, then install dependencies:
git clone --depth=1 https://github.com/netlify/netlify-cms-widget-starter.git netlify-cms-widget-<name>
cd netlify-cms-widget-<name>
npm install
To run a copy of Netlify CMS with your widget loaded for development, use the start script:
npm start
Your widget source is in the src
directory, where there are separate files for the Control
and Preview
components.
You'll want to take a few steps before publishing a production built package to npm:
- Customize
package.json
with details for your specific widget, e.g. name, description, author, version, etc. - For discoverability, ensure that your package name follows the pattern
netlify-cms-widget-<name>
. - Delete this
README.md
, renameREADME_TEMPLATE.md
toREADME.md
, and update the new file for your specific widget. - Rename the exports in
src/index.js
. For example, if your widget isnetlify-cms-widget-awesome
, you would do:
if (typeof window !== 'undefined') {
window.AwesomeControl = Control
window.AwesomePreview = Preview
}
export { Control as AwesomeControl, Preview as AwesomePreview }
- Optional: customize the component and file names in
src
. - If you haven't already, push your repo to your GitHub account so the source available to other developers.
- Create a production build, which will be output to
dist
:
npm run build
- Finally, if you're sure things are tested and working, publish!
npm publish
The development (start) task provides a locally served preview of your widget in the CMS editor. This starter also includes a demo
task for deploying this view live. Here's how to get your demo deployed using Netlify.
- Assuming your repo is on GitHub, head over to Netlify and create a site from your repo.
- The proper settings will be pre-filled based on what's in the
netlify.toml
file in this repo, so you can just click through to deploy. - Add your deployed site url to
README.md
, replacing the placeholder url in the demo link.
Note: Be sure to retain the "/demo" at the end of url, as that will automatically redirect to the editor view with your widget.
Once deployed, your demo should look like this, except with your custom widget.