Bootstrapping an Add-on#

Use the generator#

Volto addon packages are just CommonJS packages. The only requirement is that they point the main key of their package.json to a module that exports, as a default function that acts as a Volto configuration loader.

Although you could simply use npm init to generate an addon initial code, we now have a nice Yeoman-based generator that you can use:

npm install -g @plone/generator-volto
yo @plone/volto:addon [<addonName>] [options]

Volto will automatically provide aliases for your (unreleased) package, so that once you've released it, you don't need to change import paths, since you can use the final ones from the very beginning. This means that you can use imports such as import { Something } from '@plone/my-volto-addon' without any extra configuration.

Developing in isolation with a vanilla Volto project#

You can develop an add-on in isolation using the @plone/scripts addon command line. This script creates and configures a vanilla project using the Volto generator. The project is configured to have the current add-on installed and ready to work with. This script is useful to bootstrap an isolated environment that can be used to quickly develop the add-on or for demo purposes. It's also useful when testing an add-on in a CI environment.

Note

It's quite similar when you develop a Plone backend add-on in the Python side, and embed a ready to use Plone build (using buildout or pip) in order to develop and test the package.

Unfortunately, the NodeJS tooling does not work well with symlinks or outside the root of the project. This script proceeds in the following way:

  1. Generates a vanilla project using the official Volto Yo Generator (@plone/generator-volto)

  2. Configures it to use the add-on with the name stated in the package.json

  3. Copies over the root of the add-on (src and essential files) inside the created project

After this, you can change directory to the created project, by default addon-testing-project. The name of the created project is parameterizable.

After that you can use the full fledged project, and run any standard Volto command for linting, acceptance test or unit tests.

clone (git)#

Given the add-on remote git repository, it pulls and configures it into the vanilla project generated by the script.

npx -p @plone/scripts addon clone [options] <source> [destination]

    Usage: addon clone [options] <source> [destination]

    clone a repository into a newly created directory

    Options:
      -p, --private          set if the repo is private, then GITHUB_TOKEN is used
      -b, --branch <branch>  set the repo branch, defaults to main
      -c, --canary           downloads latest Volto canary (alpha) version
      -h, --help             display help for command

This next command downloads the volto-blocks-grid add-on from its git repository's main branch, and will generate a project with the latest Volto canary (alpha) version.

npx -p @plone/scripts addon clone https://github.com/kitconcept/volto-blocks-grid.git --branch main --canary

This will create a directory named addon-testing-project, and will bootstrap a new project using Volto's standard project generator. It will adjust the configuration of this project to setup the add-on in the project using mrs-developer, and the git URL given to fetch the add-on contents. You can specify the branch to be used, if the project should use the latest alpha available. For private repositories, it uses the GITHUB_TOKEN present in your environment variables to fetch it.

After this, as a developer you can use the usual project commands to run tests (unit, linting, acceptance) inside the generated addon-testing-project. You can configure the CI of your choice for automated testing, you can take a look at how it's done in: kitconcept/volto-blocks-grid

The idea is to issue commands inside the generated addon-testing-project project and do your checks. Take special care on how to pass down to the npx command the current pull request branch. Depending on your CI system, this might be different.

clone local#

You can also clone the local add-on using:

npx -p @plone/scripts addon clone .

This only works if you execute the command from the root of your add-on directory.

consolidate#

While developing, you might have done changes inside the generated project, and you most probably want to consolidate them, back into the root of the repository. By running this script, it copies over from addon-testing-project/src/addons/<my-addon> to the root of your repository.

It should be run at the root of the add-on, and it gets an optional source argument in case you have specified a directory other than addon-testing-project.

npx -p @plone/scripts addon consolidate --help

    Usage: addon consolidate [options] [source]

    Consolidate a cloned project

    Options:
      -h, --help  display help for command