Cristal 1.3.0+

Cristal packages have dependencies on packages managed by the xwiki-platform repository, which has its own release cycle.

In some instances, you might have to make changes to these packages' sources while working on Cristal, and will need to build them locally to use them. This is not a trivial process, mainly because npm and pnpm were not designed around the use-case of arbitrarily using a set of locally built packages in an otherwise "normal" build.

To help with this, Cristal's codebase includes a script to take care of all of the plumbing. From Cristal's repository root, you can run:

node ./scripts/external-deps-start.js <xwiki-platform-root> <start|dev>

Where <xwiki-platform-root> is the location of your local copy of xwiki-platform's repository, and start and dev correspond to the start mode of Vite's server.

Ideally, if you run this in dev mode, it should take care of everything and even detect, rebuild and restart Vite's server on changes made to xwiki-platform's codebase. Be careful to not commit anything while this is running (because it makes changes to Cristal's configuration), and close it beforehand using CTRL+C (which should clean up any change).

The next part is a detail of all the different actions of this script :

• On start, uncomment the line in .npmrc that declares a local package registry,
• Detect all the node packages in <xwiki-platform-root>, build them, and move the outputs to a .xwiki-platform inside the current folder,
• Start a local npm server, which is a custom-made proxy provided in the npm-server directory. Its function is to return the locally built versions of packages available in .xwiki-platform and defer to the xwiki nexus server if not found,
• Run a dependency update to use the "new" (i.e., local) versions of the packages,
• Run the Vite server,
• If the Vite server is run in dev mode, also add resources watchers to the detected local packages, handling rebuild and updates to the .xwiki-platform folder. Also, the Vite server is started with a custom plugin that detects changes in .xwiki-platform and triggers a server restart if needed,
• On stop, stop all servers and clean up every change (enabled repositories and packages versions).