Hi! I’ve been trying for a while to rebuild my Plone + Volto instance with Volto 18 and am unable to get npm addons included in my build image. I’ve adjusted my frontend build procedures for Volto 18, and have gotten the build to complete and produce a working docker image, but the resulting running instance does not include the specified addons. I seem to be missing something crucial.
Here’s what I’ve done:
Create the project using uvx cookieplone project.
I did a make install from the main directory of the new project.
Per Install an add-on in Volto — Plone Documentation v6 I used the Volto 18 choices to specify two add-ons to fetch from the npm registry: “@eeacms/volto-eea-kitkat” and “@eeacms/volto-pdf-block”. I included an “addons” section in the project frontend/package.json that looks like this:
I did pnpm --filter volto-myriadicity-net add @eeacms/volto-eea-kitkat @eeacms/volto-pdf-block to fetch the npms from the npm registry
Perhaps unnecessary, I did a make install in the project’s frontend subdirectory.
Note that the package.json was not revised by any of these recent steps to include “dependencies” for the addons I’m trying to include, as used to happen in my Volto 17 builds. Is there something further I’m supposed to do to get that to happen?
Then make build-image in the frontend subdirectory.
When visiting the running site I see that the features from those addons are missing. In the Site Setup page of the running site I see the new Volto version (18.23.0) but neither of the add-ons are indicated. I tried refreshing the Site Setup page in case it was showing cached info. I also tried building with just one of the addons (kitkat) but that doesn’t help.
I’ve also tried all this same stuff while also including the two addons in the volto.config.js ”const addons = […]” array. This also doesn’t help.
I’ve been trying to get this to work several times over the last few months. I’ve been thinking that maybe there’s some shaking out being done in the new build process, but now thinking I’m failing to see some crucial steps. Can someone point those out, or give me a clue about what might be going wrong?
The pnpm add command should update package.json (the one inside frontend/packages/volto-myriadicity-net, not frontend/package.json). I don’t know why that didn’t happen for you, but without it, the packages will not be fetched from NPM and installed.
The addons list in package.json (or alternatively, in volto.config.js) is used at runtime to find which addons to load config for, but it doesn’t affect what is installed into node_modules.
I didn’t know about frontend/packages/volto-myriadicity-net/package.json! It does exist, and the “dependencies” section does include entries for the two addons I specified. The “addons” section of that package.json is empty, but that may well be proper. (I just pnmp-added a third addon and see that the /packages/volto-myriadicity-net/package.jsondependencies have been updated with that acction to include the third item.)
Building still yields an image that does not include the addons.
Which package.json, the one in frontend or frontend/volto-myriadicity-net? The “addons” section of the latter is empty. I tried filling it in per the addons section in the frontend/ copy and rebuilding, but the build process then fails. (Similarly to how it fails if I specify the addons in frontend/volto.config.js.)
I’m flailing here. Is there documentation I’ve missed? Any suggestions about how I can start to figure out what’s going wrong?
Before we worry about the container image: are the add-ons there when you start Volto without using an image? (i.e. with make frontend-start) And how are you concluding whether they are there or not?
Which package.json, the one in frontend or frontend/volto-myriadicity-net? The “addons” section of the latter is empty. I tried filling it in per the addons section in the frontend/ copy and rebuilding, but the build process then fails. (Similarly to how it fails if I specify the addons in frontend/volto.config.js.)
“It fails” isn’t enough information for me to be helpful. Show me how it failed.
Volto starts looking for addons in package.json in the current working directory, then recursively goes into those addons’ package.json to look for more addons. So either one should work, but you do need to list volto-myriadicity-net in addons in the top level frontend/package.json.
First, I’m concluding they’re not there by (1) they’re not listed in the “Addons” section at the bottom of the Site Setup page. The page does show the right Volto version, 18.25.0, and these addons: @plone/volto-slate 18.5.1 and volto-myriadicity-net 1.0.0-alpha.0. (I refreshed the page to make sure I wasn’t getting cached info.)
I have tried starting the site using make frontend-start (with the backend and ZEO db running as docker images). The Site Setup page still does not show the addons I’m trying to include.
Which package.json, the one in frontend or frontend/volto-myriadicity-net? The “addons” section of the latter is empty. I tried filling it in per the addons section in the frontend/ copy and rebuilding, but the build process then fails. (Similarly to how it fails if I specify the addons in frontend/volto.config.js.)
“It fails” isn’t enough information for me to be helpful. Show me how it failed.
Good point. I will dig that up, probably tomorrow, and send that info in this thread.
I did not have volto-myriadicity-net in the package.json previously, but did include it in the most recent run. However, it is specified in the volto.config.js exported addons variable, which may be why volto-myriadicity-net 1.0.0-alpha.0 is listed among the addons even in the image-based frontend instance which I built before adding it to the package.json addons array.
I will get back to this tomorrow. Thanks for your help with this, I very much appreciate it!
First, I’m concluding they’re not there by (1) they’re not listed in the “Addons” section at the bottom of the Site Setup page.
I did not have volto-myriadicity-net in the package.json previously, but did include it in the most recent run. However, it is specified in the volto.config.js exported addons variable, which may be why volto-myriadicity-net 1.0.0-alpha.0 is listed among the addons even in the image-based frontend instance which I built before adding it to the package.json addons array.
Putting it in addons in frontend/package.json or frontend/volto.config.js are equivalent, so that makes sense.
If you’re up for sharing a repository with me, I could try installing it myself and see if I can spot what’s missing.
Great!! If the addons get included for you it will suggest that there’s something awry in my environment, and if they fail to add for you, too, then all the details will be there to delve.
I created a new instance so I could keep careful track of the steps I took. I included the details in the commits, along with the specific file changes. This new instance still fails to include the addons.
I added a copy of ~/.cookiecutter_replay/project_settings.json in case those details might shed light. It’s project_settings.json in the repository root.
pnpm operations show a warning about an update available (9.1.1 → 10.15.1). It looks like the 9.1.1 version is deliberately pinned, but I mention it in case it’s something wrong with my setup. (I’ve been noticing it for each of the projects I’ve been creating.)
In Volto, the addons configuration in volto.config.js has higher priority over the one in package.json . If both are present, Volto will use the list from volto.config.js and ignore the one in package.json .
@klm I have a hunch that you were putting the “addons” key in the main frontend/package.json. That is the “monorepo” package.json and it’s solely purpose is to glue everything together.
Thus, the “addons” in that file are not doing anything.
The Volto 18 monorepo uses what we call an add-on driven configuration, meaning you have a default package who is located in packages/name_of_your_default_addon who has a package.json. Here is where you put the dependencies of your website and the definition of the addons key.
@ksuessvolto.config.js has indeed higher priority than the inner default package package.json but the build does not ignore the subsequent “addons” keys in the add-on definition chain. It just has highest priority and should contain, at least the name of your default addon package `name_of_your_default_addon` since acts as an entry point of the whole build otherwise, the build has no clue which is your default add-on.
I hope I clarified some things in here.
In summary: You run the correct pnpm commands for getting the dependencies in the right place (the inner package.json, I guess that the problem is where the addons key is defined. It should be in the packages/name_of_your_default_addon/package.json.
I plan to work in clarifying the existing documentation before the conference. I have also a hands on video about the Volto 18 monorepo build.
Thanks, Victor - sounds like my answer is in what you’re saying! For anyone with similar questions I’ll follow up more when I have time to try using the info!
Thanks, @sneridagh, that worked! I had to sort through which of volto-eea-kitkat's constituents that I need are Volto 18 compatible – the collection as a whole is not – and did manage to figure out where to situate mrs.developer.json (in the surrounding frontend dir, not the contained monorepo one), so am able reliably build the instance image that’s fully working except for getting my favicon. That’s been an adventure that I’ll detail in a separate forum posting.
I have to say that I’m alarmed about lack of any correct documentation for including addons in Volto 18. I was tinkering for many months before asking about it, expecting some kind of guidance from the documentation. Even AI help didn’t lead find any useful guidance! And now it looks like Volto 17 instances can’t be built! I will take a look at your Hands On Creating a new Plone Project video, but why the heck doesn’t the Install an add-on in Volto — Plone Documentation v6 provide any clues about the monorepo? Without community access the project is going to fade.
I am not aware of the state of EEA kitkat distribution, but I was aware that not all the add-ons are Volto 18 compatible. I can distile from your lines that you had to checkout into the local build some of them in order to make them compatible, fixing all the issues. That is the way to go indeed, at least with the ones that are erroring.
I am very interested in hearing your feedback, and what did you lead to write this paragraph and anything that leads to have better documentation. So don’t hesitate to ping me via Discord.
Thanks, Victor! I very much appreciate your guidance. My concern is that there appears to crucial gaps in the documentation those not part of the development effort can build a comprehensive Volto-18 fronted site, even outsiders like me who have substantial experience working with Volto 17. I consider a necessary part of that being able to include arbitrary compatible addons.
A simple test of this would be for the documentation process to include identifying a “garden path” (or garden paths, considering that there are different approaches including cookieplone, buildout, and pip) and have part of the release process include building using just the garden path instructions to expose gaps. If that had been done with the current addons documentation (Install an add-on in Volto — Plone Documentation v6) it would hopefully have revealed that guidance was needed about where to issue the pnpm –filter … add … commands - in the project inner frontend directory rather than the root frontend directory, as you so helpfully pointed out. Even if those testing the garden paths don’t notice a documentation gap, their mission would include being notified when questions like mine expose documentation gaps and filling them in.
It looks like there already are documentation responsibilities, so maybe the essential part of my suggestion would be to establish a notion of “garden paths”, what “sufficient” means (for instance, being able to build and run the system with arbitrary addons), and having a process for identifying issues that concern the garden paths.
The fact that I’m the first person to identify this gap either means that I’m relatively clueless, failing to have found the needed information when other outsiders could, or very few outsiders are even trying. If it’s the former, then I’m eager to hear what I missed and hopefully learn from my mistake. If it’s the latter, then I think it’s in everyone’s interest to improve the process, and maybe the garden paths idea will help.
I’ll respond to some more details below.
More like I found some that were failing and, seeing that I could do without them, did not include them in my build. I have not had the time to debug them, and still need to file bug reports.
I appreciate the opportunity, Victor! I outlined my concern at the top of this message. Feel free to follow-up either here or reach out to me via Discord.
Can you provide one or two sentences in a pull request to improve the documentation from what you learned? Then future readers won’t stumble as you did.
