Plugins

Introduction

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.

Finding plugins

  • On GitHub Pages Explore live demos of first-party plugins.
  • On npm Search for @blockly to 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.

Installing plugins

  1. Find the plugin you wish to install using one of the above resources, and locate the README.

  2. 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';

  3. Some plugins may require additional steps, such as initializing or registering the plugin. These steps will be listed in the README.

Plugin versions

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 plugin's 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

"@blockly/block-plus-minus": "^2.0.15"

This will let npm install any minor version at or above the listed version, so version 2.0.20 or 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.

<script src="https://unpkg.com/@blockly/block-plus-minus"></script>

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.