A plugin is a self-contained piece of code that adds functionality to Blockly. Plugins can add fields, define themes, create renderers, and much more.
The target user for a plugin is a developer who finds and uses the plugin through npm. For more information on building a plugin you can also watch our 2021 How to Build a Plugin talk and our 2021 Plugins Overview talk.
First-party vs third-party
Plugins defined in the
blockly-samples repository are
first-party plugins, which means that they are supported by the Blockly team and
published under the
@blockly scope on npm.
Great first party plugins:
- have obvious use cases
- are general-purpose
- are stable
- are easy to use
Third party plugins are maintained and published independently. Third party plugins may be more complex, more experimental, or more targeted.
For instance, a field for setting motor speed could be used in many robotics projects. On the other hand, a field for editing a specific object defined by your database schema is better as a third party plugin.
First party criteria
First party plugins must meet these requirements:
- Works on all major platforms, unless granted an exemption by the Blockly team.
- Chrome, Firefox, Safari, Edge
- Has an author who is willing to handle bugs for the first year.
- Does not monkeypatch Blockly.
- Has a clearly defined and documented API.
- Does not call private or package functions from Blockly core, unless granted
an exemption by the Blockly team.
- Overriding package functions on a subclass that you define is allowed.
- If you want an exemption, ask us in an issue on blockly-samples.
- Has tests.
- On GitHub Pages Explore live demos of first-party plugins.
- On npm Search for
@blocklyto see a list of the plugins published by the Blockly team.
- On GitHub Look at the plugins directory in the blockly-samples repository. Each plugin has a README that describes its behaviour and intended use.
- Find the plugin you wish to install using one of the above resources, and locate the README.
Follow any installation directions in the README. In general, you will need to install the plugin from npm, e.g.
npm install @blockly/block-plus-minus --save
and import it in your code, e.g.
import Blockly from 'blockly'; import '@blockly/block-plus-minus';
Some plugins may require additional steps, such as initializing or registering the plugin. These steps will be listed in the README.
Plugins in blockly-samples follow semantic versioning, so any breaking changes will be in a new major version. Any new plugin that relies on monkey patching core will have a major version of 0 to signify initial development as stated in the semver specification.
Most plugins include the main
blockly package as a peerDependency rather than
a dependency. This is because we expect you to have already installed Blockly
yourself in your own application (it wouldn't make sense to use a plugin without
also using Blockly) and so you can manage the version of Blockly yourself.
However, many plugins are developed to use new APIs found in the most recent
version of Blockly, so you do need to be aware of the version requirements. The
package.json will tell you which is the minimum version of Blockly
that is compatible with that plugin. If a plugin is updated to need a newer
version of Blockly, e.g. to take advantage of a brand new API, the major version
of the plugin will be increased, as we consider this a breaking change.
When you add the plugin to your
package.json, the default is to include a
caret before the version such as
This will let npm install any minor version at or above the listed version, so
2.1.0 could work, but not a new major version such as
3.0.1. When you update to a new version of Blockly, it's a good idea to check
if any of your plugins could be updated to a new major version as well.
Installing plugins without npm
While we generally recommend using npm in order to easily receive updates, it is possible to use plugins without npm.
You could use unpkg to include the plugin files without cloning them, e.g.
Or you could clone the
blockly-samples repository and include the files
locally similar to how you might if you have cloned Blockly. However, we
encourage you to use a package manager if possible, as it will help you stay up
to date with the latest features and bugfixes in the plugin.
With this method, you will still need to perform any initialization or registration steps listed in the plugin's README.