Setup

2. Setup#

In this chapter, we create a Plone project with Blicca, and install the training add-on. At the end, your browser console proves that your first own bundle is loaded.

2.1. Install the prerequisites#

Install the prerequisites from the Plone documentation, Create a project with Cookieplone: uv, Make, and Git. The add-on’s JavaScript build additionally needs Node.js 22 or later, and pnpm. Enable pnpm with corepack enable, as the version is pinned in the add-on’s package.json.

2.2. Create a Plone project with Blicca#

Cookieplone 2.0 no longer has a separate template for Blicca. Generate a project with the project template, and answer the question Use Volto as frontend? with No:

uvx cookieplone project

Cookieplone asks 18 questions. The following answers matter for the training, keep the defaults for the rest:

Plone Version

6.2.2 or later.

Use Volto as frontend?

No, so that Cookieplone generates a Blicca project without a frontend.

Should we setup a caching server?, Add Ansible playbooks?, Add GitHub Action to Deploy this project?, Would you like to add a documentation scaffold to your project?

No, to keep the project small.

Then install and start the backend:

cd <project-slug>
make install
make backend-start

The installation creates a virtual environment with uv, and a Plone site named Plone. Your site now runs at http://localhost:8080/Plone with the login admin and password admin.

2.3. Add the add-on as a source checkout#

The generated project keeps the Plone backend in the backend directory, with mx.ini and pyproject.toml. Cookieplone projects manage source checkouts with mxdev. Add the training add-on to backend/mx.ini, and pin plone.staticresources to a release with Mockup 5.6.11 or later in the same file:

[settings]
main-package = -e .[test]
version-overrides =
    plone.staticresources==3.0.7

[blicca.staticresourceoverride]
url = https://github.com/collective/blicca.staticresourceoverride.git
branch = main

Then add the add-on to the dependencies of backend/pyproject.toml:

dependencies = [
    "Products.CMFPlone==6.2.2",
    "blicca.staticresourceoverride",
    "plone.api",
    "plone.restapi",
    "plone.classicui",
    "plone.app.caching",
    "z3c.jbot",
]

Run the installation again:

make install

mxdev clones the repository into backend/sources/blicca.staticresourceoverride, registers it as an editable package in the tool.uv.sources table of pyproject.toml, and turns the version override into a uv override-dependencies entry. uv then installs everything.

Note

The version-overrides entry is what gives you Mockup 5.6.11. Plone 6.2.2 ships plone.staticresources 3.0.6 with Mockup 5.6.10, which is enough for the first three chapters. Overriding a Svelte component needs the default component key from Mockup 5.6.11.

2.4. Build the JavaScript#

Build the add-on’s JavaScript inside the source checkout:

cd backend/sources/blicca.staticresourceoverride
pnpm install
pnpm run build

Start the backend again with make backend-start. Then install Blicca Static Resource Override (Training) in the add-ons control panel.

2.5. The pnpm caveats#

The package manager is pnpm, the same as Mockup itself uses. The file pnpm-workspace.yaml mirrors the known caveats of plone/mockup:

  • shamefullyHoist: true, because webpack module resolution needs a flat node_modules directory.

  • overrides that remove the git subdependencies slick-carousel, slides, and select2, because pnpm blocks exotic subdependencies. Only patterns that this add-on does not import need them.

  • An allowBuilds allowlist, because pnpm 10 and later block dependency build scripts by default.

2.6. Success check#

Open any page of your site, and open the browser console. You should see the following message:

Patternslib Module Federation: Loaded and initialized bundle "__patternslib_mf__bliccastaticresourceoverride".

The Plone bundle, the host, has found and initialized your add-on bundle, the remote. Now we can start overriding things.

Contents