Build Inside the Monorepo

EBRAINS’ own apps (Forms, TRL, Handbook Contribute…) live in the ebrains-ui-ecosystem monorepo, managed with Nx. An app there uses the design system from source: it builds the components and assets next to itself, compiles its own Tailwind with the shared factory, and ships with the shared release and Docker targets.

Start here if your app is (or will be) an EBRAINS-maintained app in this repository. For an app anywhere else, see Start Your Own App.

See it built: apps/live/sandbox is this guide followed step by step, with the Workflows dashboard from Build Your First Page as a Vue app. Run it with npx nx serve sandbox.

How it differs from a standalone app

Standalone appApp in the monorepo
Components@ebrains/components from npmBuilt from packages/components into dist/packages/components
Framework wrapper@ebrains/vue from npmpackages/vue/src, through tsconfig.base.json paths
StylesThe published output.cssYour own Tailwind build, from the shared tailwind.factory.js
Run and buildnpm run dev / npm run buildnpx nx serve <app> / npx nx build <app>
ReleaseYour own pipelineThe shared release and docker-push targets

Step 1: Create the app

Apps live in apps/live/<name>. Generate one with the Nx Vue generator (most EBRAINS apps use Vue):

Then tidy what the generator creates:

  • Revert tsconfig.base.json: the generator rewrites its formatting without changing anything (git checkout tsconfig.base.json).
  • Delete src/styles.css (a generic system-font reset that fights the EBRAINS styles), src/app/NxWelcome.vue and the App.spec.ts that tests it.
  • Note the mount point: the generated index.html uses <div id="root">, so mount on #root.

Building without a framework? See Without a framework below: three steps change.

Step 2: Make the targets build the design system first

In apps/live/workflows/project.json, make serve and build depend on the components and assets builds, so dist/packages/... is always fresh:

Step 3: Point Vite at the local build

In vite.config.ts, alias the component loader to the local build, and let the dev server read files outside the app folder:

nxViteTsPaths() resolves @ebrains/vue and the other workspace packages from tsconfig.base.json, so you use the wrappers’ source directly.

Pick a port no other app uses (several apps use 4200). If it’s taken, Vite moves to the next free one and prints it.

Step 4: Tailwind from the shared factory

The factory brings the EBRAINS theme: tokens, typography, spacing, colours and the layout primitives. Your build only keeps the classes your app uses. Tailwind Migration covers moving an existing app’s styles onto it.

Step 5: Load the styles and register the components

Why wait: Vue passes a bound value as a JavaScript property only if the element already has that property. Mounted before the components register, Vue falls back to attributes, and objects and arrays (:links, :fields, :data) arrive as the text "[object Object]". Waiting for defineCustomElements() fixes every binding at once, without .prop modifiers.

Then use the components through the wrapper, as in any Vue app:

Step 6: Bring in your page

Move the dashboard from Build Your First Page into App.vue’s template. The classes and components are the same; in a template:

  • Bind objects and arrays as props instead of JSON strings: :links="headerLinks", :fields="supportFields", :data="runs" (the table’s data prop is data; table-data is its HTML attribute).
  • Bind numbers and booleans with :: :value="62", :expanded="true", :pagination-enabled="false".
  • Listen with @event: @click, @edsclose="onClose", @form="onSupportForm".
  • Call methods through a template ref: ref="uploadModal", then uploadModal.value.$el.open(). The methods live on the web component, which is the wrapper’s $el.
  • Modal and accordion titles are the heading prop in Vue (title is only their HTML attribute; as a Vue attribute it also shows a browser tooltip).
  • Named slots stay plain attributes on child elements: <div slot="footer">, <div slot="panel-0">.

Step 7: Run, build and ship

To release and deploy like the other apps, copy the release and docker-push targets, and the Dockerfile and nginx default.conf, from an existing app such as apps/live/handbook-contribute.

Without a framework

All EBRAINS apps in the repository use Vue, but plain HTML and JavaScript work too. Three things change:

  1. Generate a web app instead of a Vue app:
  1. Leave out the Vue plugin in vite.config.ts (keep the loader alias, nxViteTsPaths(), the Tailwind PostCSS plugins and the output folder).
  2. Register the components yourself in src/main.ts, then write the <eds-*> tags straight into index.html, as in Build Your First Page:

Behaviour goes in main.ts the same way as in Start Your Own App: listen to the components’ events, call their methods, set properties for data.

React and Angular

The repository has a sandbox for each: apps/live/react-sandbox and apps/live/angular-sandbox build the same dashboard. What changes from the Vue steps:

React (@nx/react:application):

  • Use @vitejs/plugin-react instead of the Vue plugin; everything else in vite.config.ts stays.
  • Register first, then render: defineCustomElements().then(() => createRoot(el).render(<App />)).
  • Import from @ebrains/react. Props are camelCase (navAriaLabel, pressableUrl), events on + the event name (onForm, onEdsclose), and ref gives the element: uploadModal.current?.open().
  • In TypeScript, give literal options a literal type: { Workflow: { format: 'code' } } as const. A custom property in a style object needs a cast: { '--eds-form-padding': 0 } as CSSProperties.

Angular (@nx/angular:application --bundler=esbuild --standalone):

  • Keep the generated Angular builder; add "dependsOn": [{ "target": "build", "projects": ["components", "assets"] }] to build and serve.
  • Use the prebuilt stylesheet: list dist/packages/assets/styles/output.css first in "styles". Angular’s builder runs Tailwind on each CSS file separately, so the multi-file source packages/assets/styles/main.css can’t compile there.
  • Import the standalone components from @ebrains/angular into the component’s imports. They register themselves, so there is nothing to wait for.
  • Bind with [links]="headerLinks", listen with (form)="onForm($event)", and call methods through @ViewChild('uploadModal') uploadModal?: EdsModal: this.uploadModal?.open().
  • Raise the initial budget in project.json (about 1.1 MB with a full dashboard).

Changing the design system from your app

Because your app builds the components from source, you can fix or extend a component and see it in your app straight away:

  1. Edit the component in packages/components/src/components/…, with a spec test next to it.
  2. npx nx serve workflows rebuilds the components first.
  3. Check the component in Storybook and its docs page too: other apps use it.

What’s next