Develop Volto core#

This chapter describes how to develop Volto core and its libraries, packages, and apps as open source software contributions.

See also

To create a full Plone project with both frontend and backend, see Create a project instead.

Monorepo structure#

The Volto core repository has the shape of a monorepo, where "mono" means "single" and "repo" is short for "repository". This means that several apps and libraries related to each other are stored in the same repository. They are managed together but released individually. This allows the code to be shared effectively, and unifies tracking of changes across all of the apps and libraries.

This monorepo uses pnpm as a package manager, extensively using its workspace feature. It's organized in two folders, depending on whether it's a library (package) or an app. The workspaces are located in the packages or apps folder.

Folder layout#

Volto has the following folder structure.

(volto-monorepo)/
├─ apps/
│  ├─ plone
│  ├─ nextjs
│  └─ remix
├─ packages/
│  ├─ volto
│  ├─ client
│  ├─ components
│  ├─ registry
│  ├─ types
│  ├─ coresandbox
│  ├─ generator-volto
│  ├─ scripts
│  ├─ tsconfig
│  ├─ volto-guillotina
│  ├─ volto-slate
│  └─ volto-testing
├─ .gitignore
├─ package.json
├─ pnpm-workspace.yaml
├─ turbo.json
├─ tsconfig.json
├─ ...

Development pre-requisites#

To set up a Volto core development environment, your system must satisfy the following pre-requisites.

  • An operating system that runs all the requirements mentioned. Most UNIX-based operating systems are supported, including many Linux distributions, macOS, or Windows Subsystem for Linux (WSL) on Windows. A UNIX-based operating system is recommended.

    Important

    Windows alone is not recommended because it does not support GNU make. If you get Plone to run on Windows alone, please feel free to document and share your process.

Note

When developing Volto core, pnpm is required. When developing a project using Plone, Yarn or other package managers may be used.

nvm#

The following terminal session commands use bash for the shell. Adapt them for your flavor of shell.

See also

See the nvm install and update script documentation. For the fish shell, see nvm.fish.

  1. Create your shell profile, if it does not exist.

    touch ~/.bash_profile

  2. Download and run the nvm install and update script, and pipe it into bash.

    curl -o- https://raw.githubusercontent.com/creationix/nvm/v{NVM_VERSION}/install.sh | bash

  3. Source your profile. Alternatively close the session and open a new one.

    source ~/.bash_profile

  4. Verify that the nvm version is that which you just installed or updated:

    nvm --version

Node.js#

We recommend that you install Node.js using nvm. Alternatively you can install Node.js using Homebrew or other package installer.

  1. Install or update the supported LTS versions of Node.js, then activate the version supported in Volto.

    nvm install --lts
nvm use --lts

  2. Verify that the supported version of Node.js is activated.

    node -v

pnpm#

Using corepack:

corepack prepare pnpm@latest --activate

or using npm:

npm install -g pnpm@latest

Verify the latest version.

pnpm --version

Compare the output to the latest pnpm release number.

See also

pnpm installation.

Make#

Make comes installed on most Linux distributions. On macOS, you must first install Xcode, then install its command line tools. On Windows, it is strongly recommended to Install Linux on Windows with WSL, which will include make.

Finally, it is a good idea to update your system's version of make, because some distributions, especially macOS, have an outdated version. Use your favorite search engine or trusted online resource for how to update make.

Docker#

Install Docker Desktop for your operating system. Docker Desktop includes all Docker tools.

Note

For some Linux distributions, you might need to create a group docker and add your user to this group. See Linux post-installation steps for Docker Engine for details.

Git#

Install git for your operating system.

Set up the environment#

You need to perform the steps in this section only once to set up your environment.

Clone the Volto repo, and change your working directory to the cloned repository:

git clone https://github.com/plone/volto.git
cd volto

Install the frontend dependencies.

pnpm install

Start the backend and Volto#

Every time you want to run Volto for core development, you will need to create two terminal sessions, one for the backend and one for the frontend. For both sessions, change your working directory to the root of your Volto clone.

In the first session, start the backend.

make start-backend-docker

When you run this command for the first time, it will download Docker images, configure the backend, and start the backend. Browse to the backend running at http://localhost:8080.

In the second session, start the frontend.

pnpm start

Browse to the frontend running at http://localhost:3000.

To stop either the backend or frontend, use ctrl-c.

Run commands for pnpm workspaces#

As mentioned in Monorepo structure, pnpm has the concept of workspace. Every package or app located in the packages or apps folders is declared as a pnpm workspace.

When developing Volto, you can run pnpm commands from either the repository root or inside the package's or app's workspace in packages/<package_name> or apps/<app_name>.

pnpm commands will apply in the context from which they are run. That means when you run a pnpm command from the repository root, it will apply to all workspaces. It also means when you run a pnpm command from inside a workspace, it will apply only to that workspace.

You can also use the pnpm --filter feature from the repository root to apply to only the specified workspaces, as shown in the following examples.

pnpm --filter @plone/volto start

The above command when run from the repository root will start Volto.

pnpm --filter @plone/registry build

The above command when run from the repository root will build the Volto registry.

See also

For more information about pnpm workspaces, read the documentation of pnpm workspaces.

Developing Volto#

The Volto core code is located in the packages/volto folder.

Changed in version 18.x.x: Since December 2023, the Volto repository is now a monorepo. Volto is located now in the packages/volto folder. You can run all the usual commands from inside that folder, but replacing yarn with pnpm, since they have similar commands and features. For example, to start Volto:

pnpm start

You can also run commands for a specific workspace using the --filter feature as shown in the previous section, Run commands for pnpm workspaces.

Develop other libraries in a workspace#

If a package is a dependency of another package in the monorepo, and it's declared as a workspace, they can be declared as usual in the package.json as follows:

"dependencies": {
  "@plone/types": "workspace:*"
}

See also

Documentation of pnpm workspaces.

TypeScript#

By default, the use of TypeScript is required in Plone frontend libraries, Volto itself being an exception.

See also

TypeScript policy in core.

Core libraries#

The monorepository consists of several core libraries.

Volto project generator#

@plone/generator-volto is a Yeoman generator that helps you set up Volto via command line. It generates all the boilerplate needed to start developing a Plone Volto project. It is used by CookieCutter Plone Starter, the recommended way to set up Plone projects. The generator features an addon template for scaffolding Volto add-ons in your projects.

Registry#

@plone/registry provides support for building an add-on registry and infrastructure for JavaScript and TypeScript-based apps. Used by Volto, you can also use it in other JavaScript frameworks and environments to help create an add-on driven extensiblility story.

Scripts#

@plone/scripts is the placeholder of tools used by Volto and its add-ons, such as the i18n internationalization scripts.

Types#

@plone/types is the package that contains the TypeScript types in used in Plone.

Slate support for Volto#

@plone/volto-slate is the glue package that provides support for the Slate library in Volto.

Supported frameworks#

Plone supports several frontend implementations, the main one being Volto as the default frontend and reference React-based implementation. There are plans to support implementations in other frontends, including NextJS and Remix.

Plone#

The default frontend and reference React-based implementation in Plone is Volto. In the apps folder you'll find a Volto project scaffolding that uses Volto as a library. This is the same as the one that you'll have when running the Volto generator or cookiecutter-plone-starter.

NextJS#

Coming soon.

Remix#

Coming soon.

Support libraries#

Volto uses serveral libraries to support development.

volto-coresandbox#

@plone/volto-coresandbox is a support library used mainly for testing purposes. It provides fixtures to bootstrap projects with configurations different than the default one. It is used by the acceptance tests to set up different test fixtures, such as multilingual or workingcopy.

Volto testing package#

The @plone/testing stub library helps set up the testing libraries used by Volto without having to install the whole Volto package. It is mainly used in CI to reduce installation times.

Volto Guillotina#

@plone/volto-guillotina is the support library used to interact with Guillotina as the Plone backend.