How to Set Up the UI Ecosystem Monorepo

Get the UI Ecosystem running on your machine: clone it, use the right Node version, install, and serve an app. Do this once before the tutorials.

You need: Git, an EBRAINS GitLab account, and nvm (recommended) or Node.js.

Clone the repository

If Git asks for a password and refuses yours, include your username and use a personal access token as the password:

Use the Node and npm versions the repository expects

The versions are in the engines field of the root package.json (currently Node 22.23.4 and npm 10.9), and in .nvmrc. With nvm, from the repository root:

Install the dependencies

This installs Nx too. Run Nx commands with npx nx …, or install the CLI globally (npm install -g nx) to type nx …. The guides use the short form.

Serve an app to check everything works

Nx builds the design system first (a minute the first time, cached afterwards), then starts the app:

Open the address: you should see the Workflows dashboard from the design system’s tutorial. Stop it with Ctrl+C.

Troubleshooting

Problem: npm install fails with engine or peer-dependency errors. Solution: check node --version matches .nvmrc, then delete node_modules and run npm install again.

Problem: nx: command not found. Solution: use npx nx …, or install the CLI globally.

Problem: the port is already in use. Solution: Vite picks the next free port and prints it; open that one.

Problem: Warning: Failed to load the ES module: packages/assets/frontend.config.js. Solution: harmless; the build continues.

Next