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 app | App in the monorepo | |
|---|---|---|
| Components | @ebrains/components from npm | Built from packages/components into dist/packages/components |
| Framework wrapper | @ebrains/vue from npm | packages/vue/src, through tsconfig.base.json paths |
| Styles | The published output.css | Your own Tailwind build, from the shared tailwind.factory.js |
| Run and build | npm run dev / npm run build | npx nx serve <app> / npx nx build <app> |
| Release | Your own pipeline | The 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.vueand theApp.spec.tsthat tests it. - Note the mount point: the generated
index.htmluses<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 isdata;table-datais 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", thenuploadModal.value.$el.open(). The methods live on the web component, which is the wrapper’s$el. - Modal and accordion titles are the
headingprop in Vue (titleis 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:
- Generate a web app instead of a Vue app:
- Leave out the Vue plugin in
vite.config.ts(keep the loader alias,nxViteTsPaths(), the Tailwind PostCSS plugins and the output folder). - Register the components yourself in
src/main.ts, then write the<eds-*>tags straight intoindex.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-reactinstead of the Vue plugin; everything else invite.config.tsstays. - Register first, then render:
defineCustomElements().then(() => createRoot(el).render(<App />)). - Import from
@ebrains/react. Props are camelCase (navAriaLabel,pressableUrl), eventson+ the event name (onForm,onEdsclose), andrefgives 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"] }]tobuildandserve. - Use the prebuilt stylesheet: list
dist/packages/assets/styles/output.cssfirst in"styles". Angular’s builder runs Tailwind on each CSS file separately, so the multi-file sourcepackages/assets/styles/main.csscan’t compile there. - Import the standalone components from
@ebrains/angularinto the component’simports. 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
initialbudget inproject.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:
- Edit the component in
packages/components/src/components/…, with a spec test next to it. npx nx serve workflowsrebuilds the components first.- Check the component in Storybook and its docs page too: other apps use it.
What’s next
- Tailwind Migration: moving an existing app onto the shared Tailwind factory.
- Contributing: how changes to the design system are reviewed and released.