2. Bootstrapping an Add-on – Effective Volto – Getting Started

Bootstrapping an Add-on

2. Bootstrapping an Add-on#

2.1. 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 have a 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.

2.2. Developing in isolation using a full dockerized project approach#

You can develop an add-on in isolation using the boilerplate already provided by the add-on generator. The project is configured to have the current add-on installed and ready to work with. This 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.

The dockerized approach performs all these actions in a custom built docker environment:

  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. Links the root of the add-on inside the created project

After that you can use the inner dockerized project, and run any standard Volto command for linting, acceptance test or unit tests using Makefile commands provided for your convenience.

2.2.1. Setup the environment#

Run once

make dev

which will build and launch the backend and frontend containers. There's no need to build them again after doing it the first time unless something has changed from the container setup.

In order to make the local IDE play well with this setup, is it required to run once yarn to install locally the required packages (ESlint, Prettier, Stylelint).

Run

yarn

2.2.2. Build the containers manually#

Run

make build-backend
make build-addon

2.2.3. Run the containers#

Run

make start-dev

This will start both the frontend and backend containers.

2.2.4. Stop Backend (Docker)#

After developing, in order to stop the running backend, don't forget to run:

Run

make stop-backend

2.2.5. Linting#

Run

make lint

2.2.6. Formatting#

Run

make format

2.2.7. i18n#

Run

make i18n

2.2.8. Unit tests#

Run

make test

2.2.9. Acceptance tests#

Run once

make install-acceptance

For starting the servers

Run

make start-test-acceptance-server

The frontend is run in dev mode, so development while writing tests is possible.

Run

make test-acceptance

To run Cypress tests afterwards.

When finished, don't forget to shutdown the backend server.

make stop-test-acceptance-server

2.2.10. Release#

Run

make release
Contents