Skip to main content

Add a plugin

This document discusses how to create a new plugin. While the process it describes is for creating first-party plugins, you can use it as a guideline for creating third-party plugins.

For an overview of plugins, see Plugins.

For a quick introduction to creating a plugin, see our How to Build a Plugin talk (2021).

First-party vs third-party​

The way that plugins are maintained falls into two categories:

First-party plugins are:

  • Supported by the Blockly team.
  • Stored in the blockly repository.
  • Published under the @blockly scope on npm.
  • Usable in a wide range of Blockly applications.
  • Stable, well-documented, and easy to use.
Example

A field for setting motor speed could be used in many robotics projects and is a good candidate for a first-party plugin.

Third-party plugins are:

  • Maintained and published independently.
  • More complex, more experimental, or targeted to a narrower range of Blockly applications.
Example

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:

  • Work on all major platforms, unless granted an exemption by the Blockly team.
    • Chrome, Firefox, Safari, Edge
  • Have an author who is willing to handle bugs for the first year.
  • Do not monkeypatch Blockly.
  • Have a clearly defined and documented API.
  • Do 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.
  • Have tests.

The process​

Plugins go through three stages: suggestion, implementation, and publishing.

Suggestion​

A plugin starts as a suggestion. You can suggest a plugin by creating a new issue with the Feature Request template. For more information, read about how to write a feature request.

In addition to the basic feature request information, a plugin suggestion should include:

  • The API the plugin would expose.
  • APIs that need to be added or changed in core Blockly to support the plugin.
  • Screenshots, GIFs, or mock-ups if the plugin includes UI features.
  • An explanation of why it should be a first-party plugin rather than a third-party plugin.

The Blockly team reviews suggestions as they come in. On the GitHub issue, the Blockly team will:

  • Clarify the desired functionality of the plugin
  • Plan implementation steps and tests
  • Discuss API changes in core Blockly

During discussion we may decide that a plugin should be a third-party plugin, and not be published under the @blockly scope. In that case we will explain why and close the issue.

Implementation​

Once a Blockly team member notes that the plugin is ready, implementation will begin.

Implementation steps include:

  • Running npx @blockly/create-package to set up the plugin and its directory from a template. Learn more...
  • Implementing the plugin.
  • Testing the plugin, using Mocha.
  • Documenting the plugin, including the README.

If a suggested plugin has been approved for implementation and you would like to work on it, comment on the issue and ask if it's still open for contributions.

Implementation may be done by multiple contributors in parallel. You may implement a plugin collaboratively on your own fork, or through pull requests. If you want to collaborate on a plugin, ask the Blockly team to create a feature branch for you.

Plugins should be added to the gh-pages/_index.html file in the main branch of blockly-samples. This will cause them to appear on our Plugins site. First-party plugins should point to their test page. Third-party plugins can also be added to this page, and can point to a link of their owner's choosing, such as a hosted demo or the npm page.

Publishing​

Finally, publishing. The Blockly team uses Lerna to manage versioning and publishing for all plugins.

Starting with Blockly v13, plugin version numbers match Blockly version numbers. This means that:

  • You can easily know which version of a plugin is compatible with your specific version of Blockly.
  • Plugin updates will be released when Blockly is released, unless the changes are urgent enough to warrant a release of Blockly.
  • Plugin version numbers may be incremented even when there are no changes to the plugin's code.

Note that Blockly uses semantic versioning to determine version numbers.

Plugins that are not ready for publishing should be marked private in their package.json.

The plugins site will be updated whenever plugins are published.