40. Extending Volto With Custom Add-on Package

As soon as you have repeating needs in Volto projects, you will want to move the code to an addon-on that can be applied to multiple projects. One of several ways to start with a new add-on is the Yeoman generator we already used to initiate a Volto app.

If you haven’t prepared Yeoman and the generator recently:

npm install -g yo
npm install -g @plone/generator-volto

Create a sandbox project

yo @plone/volto sandbox-volto-custom-addon

You see a dialog like this

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
yo @plone/volto sandbox-volto-custom-addon
Getting latest Volto version
Retrieving Volto's yarn.lock
Using latest released Volto version: 9.0.0
? Project description A Volto-powered Plone frontend
? Would you like to add addons? true
? Addon name, plus extra loaders, like: volto-addon:loadExtra,loadAnotherExtra @greenthumb/volto-custom-addon
? Would you like to add another addon? false
? Would you like to add workspaces? true
? Workspace path, like: src/addons/volto-addon src/addons/greenthumb-volto-custom-addon
? Would you like to add another workspace? false

@greenthumb/volto-custom-addon is the scoped package name of your add-on.

Go to the app folder:

cd sandbox-volto-custom-addon

You now have a Volto app configured for an add-on. An add-on is a Node package. It will live in the folder you specified: src/addons/greenthumb-volto-custom-addon. So you need a package.json. As it should customize your Volto app, it needs also a way to manipulate the main configuration. As a starter you can create a repository from template https://github.com/rohberg/volto-addon-template.git.

Voto add-on template

Your repo https://github.com/greenthumb/volto-custom-addon.git is the basis of your add-on. We are now integrating it in your Volto app.

Install mrs.developer to let the project know about the source of your add-on.

yarn add mrs-developer -WD

The configuration file mrs.developer.json instructs mrs.developer from where it has to pull the package. So, create mrs.developer.json and add:

{
    "greenthumb-volto-custom-addon": {
        "package": "@greenthumb/volto-custom-addon",
        "url": "git@github.com:greenthumb/volto-custom-addon.git",
        "path": "src"
    }
}

Run

yarn develop

You see your add-on cloned to src/addons/.

Read more about mrs.developer 2 configuration options.

Change to add-on folder and replace rohberg -> greenthumb and replace volto-addon-template -> volto-custom-addon.

With mrs.developer set up to code your add-on, its just left to add the add-on as any add-on to your Volto project:

Update package.json:

"workspaces": [
  "src/addons/*"
],
"addons": ["@greenthumb/volto-custom-addon"
],

Install and start

$ yarn
$ yarn start

Troubleshooting: Did you update the generator recently?

Step to the next chapter and come back here for a release.

We will create a new block type in the next chapter Extending Volto With a FAQ Block Type. We will do this in an add-on to apply the feature to multiple projects.

Note

Coming back here with the new block type, you can now release the new add-on to npm. @greenthumb is your space.

40.1. Enrich an existing project with your new released add-on

You already released your add-on. Go on with package.json and add your new add-on.

Update package.json:

"addons": ["@greenthumb/volto-custom-addon"
],
"workspaces": [
  "src/addons/*"
],
"dependencies": {"@greenthumb/volto-custom-addon": "1.0.1"
},

Modify versions as necessary.

Install new add-on and restart Volto:

$ yarn
$ yarn start

40.2. Create a new project with your new released add-on

yo @plone/volto my-volto-project --addon collective/volto-custom-addon

Install and start

$ yarn
$ yarn start

40.3. Footnotes

1

yarn workspaces Workspaces are a new way to set up your package architecture. It allows you to setup multiple packages in such a way that you only need to run yarn install once to install all of them in a single pass.

2

mrs.developer Pull a package from git and set it up as a dependency for the current project codebase.