How to upgrade a distribution-based project

How to upgrade a distribution-based project#

Use this guide in projects based on a frontend distribution where frontend/Makefile provides an upgrade target.

Prerequisites#

  • repository.toml contains [frontend.package] with:

    • base_package

    • path

  • The add-on package at path declares the distribution package in package.json.

  • frontend/scripts/upgrade-distribution.js exists in the project.

  • frontend/Makefile has an upgrade target that runs:

upgrade:
  node scripts/upgrade-distribution.js
  pnpm exec prettier --log-level silent --write volto.config.js

For setup details, see How to configure a project based on a distribution to ensure versions are consistent with the distribution.

Upgrade steps#

  1. First, update and pin the frontend distribution version in your project dependencies, as described in How to upgrade a distribution version.

    To upgrade the frontend distribution to the latest version, run:

    uvx repoplone deps upgrade frontend

    Or pin a specific version:

    uvx repoplone deps upgrade frontend <version>

  2. From the project root, run:

    make -C frontend upgrade

    or

    cd frontend
make upgrade

  3. Install and sync dependencies:

    make frontend-install

  4. Review generated changes in:

    • frontend/volto.config.js

    • frontend/mrs.developer.json

  5. Run tests:

    make test

What make upgrade updates#

  • Rewrites frontend/volto.config.js distribution block with:

    • distribution name

    • distribution version

    • resolved volto_version

    • distribution dependencies

  • Preserves existing addons and theme in volto.config.js.

  • Updates frontend/mrs.developer.json with the resolved core.tag (volto_version).

  • The effective dependency sync happens when you run make frontend-install after running make upgrade.

  • During install, frontend/scripts/.pnpmfile.cjs enforces the versions listed in distribution.dependencies from volto.config.js.

Contents