Develop Volto core

Develop Volto core#

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

See also

For previous versions of Volto core, you should follow the guide in the relevant version branch to build and run the backend.

Additionally you can build each version of Volto documentation by running make docs-html from the root of the repository, and reading the relevant developer and contributing documentation.

See also

To create a full Plone project with both frontend and backend, see Install Plone with cookiecutter-plone-starter (deprecated) 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
│  └─ rr7
├─ 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 prerequisites#

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

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.

Create your shell profile, if it does not exist.
```
touch ~/.bash_profile
```

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

curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.39.5/install.sh | bash

Source your profile. Alternatively close the session and open a new one.
```
source ~/.bash_profile
```
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.

Install or update the supported LTS versions of Node.js, then activate the version supported in Volto.
```
nvm install --lts
nvm use --lts
```
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.

make install

Start Plone#

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.

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

Start the backend#

Added in version 18.0.0-alpha.42: Persist backend data across Docker sessions.

Warning

Do not use this method of persistence in a production environment. It is intended only for development.

See also

Deploying

In the first session, start the backend. You can browse to the backend running at http://localhost:8080.

make backend-docker-start

When you run this command for the first time, it will download Docker images, configure the backend, create a Docker volume to persist the data named volto-backend-data, and start the backend.

Subsequently, when you run make backend-docker-start, it will only start the backend using the existing configuration and Docker image and volume.

Note

If you would like to start the backend with a clean data volume, you can run the following command.

docker volume rm volto-backend-data

Then run make backend-docker-start again to start the backend with a clean data volume.

Configure backend language#

If you use the Docker image plone-backend, you can set its LANGUAGE environment variable, overriding the default of en, when you start it.

This variable is applied only when the Plone site is created. If you persist data through restarts, you only need to do this once. Conversely, if you create a Plone site in the wrong language, you can delete the data volume, and recreate it with the correct language.

You can either pass an environment variable into the make command to start the backend, or export an environment variable in your shell session and start the backend.

# pass method
LANGUAGE=pt-br make backend-docker-start

# export method
export LANGUAGE=pt-br
make backend-docker-start

Start the frontend#

In the second session, start the frontend, Volto.

pnpm start

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

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.

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.

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.

Deprecated since version 18.0.0-alpha.43: For Volto 18, @plone/generator-volto is replaced by Cookieplone.

Supported frontends#

Plone 6 comes with two frontend reference implementations. Volto is the default frontend, and is React-based. Classic UI is the Python-based, server-side rendered frontend.

In Volto's apps folder, you'll find a Volto project scaffolding that uses Volto as a library. This is the same as that which you'll have when you follow the instructions in Install Plone with cookiecutter-plone-starter (deprecated)).

Experimental frontends#

Other frontends are currently under heavy development. They are marked as experimental and, for now, they are a proof of concept demonstrating that other frontends are possible. Although they do work now in an acceptable way, the implementation might change in the future. These implementations only show how to access the public Plone content in the current site, dealing with data fetching and routing. All implementations are located in the apps directory in a subdirectory according to their implementation name. They use the Plone frontend strategic packages, including @plone/registry, @plone/client, and @plone/components.