End-to-end application integration

Create your own frontend by installing a released Atrium application package and running its local publish command. Choose the minimal starter or the complete showcase. Both install the shared library and publisher as dependencies. You do not need Atrium’s source repository, workspace setup, or a locally packed archive.

All commands below run in your own frontend project directory. Package releases must already exist in the remote registry. A version in this repository’s manifest does not establish that it has been published.

1. Prepare the runtime and registry

Use Node 24.15.0 or newer within Node 24, with Yarn 4.18.0 available through Corepack. Node 24.20.0 is the repository’s verified runtime. Check node --version and yarn --version before starting. Use the requirements of the selected release if integrating a later version.

Obtain the Atrium GitLab package project’s numeric ID and a token with package-read access. A deploy token needs read_package_registry. All four packages live in the same project registry. You need package access, not a Git source checkout. See GitLab’s npm authentication guidance.

In the frontend directory, create .yarnrc.yml with the endpoint supplied by the maintainer. Replace ATRIUM_PROJECT_ID with the Atrium package project’s numeric ID, not your application’s ID:

nodeLinker: node-modules
enableGlobalCache: false
enableMirror: false

npmScopes:
  agon:
    npmRegistryServer: 'https://git.konzeptplus.ch/api/v4/projects/ATRIUM_PROJECT_ID/packages/npm/'
    npmAlwaysAuth: true
    npmAuthToken: '${ATRIUM_NPM_TOKEN}'

This is installation configuration for your application. Atrium’s repository has separate registry-publication settings. Preserve the environment-variable reference above in version control and supply its value from your shell or secret manager. The publisher leaves .yarnrc.yml unchanged. See Yarn’s scoped registry settings.

Alternatively, in Bash or zsh, run this command, paste the token at the silent prompt, and press Enter. Its value is not entered as a shell command:

read -r -s ATRIUM_NPM_TOKEN
export ATRIUM_NPM_TOKEN

Load the variable before invoking Yarn. Yarn reads it when loading its configuration, including during init and dev. Do not put the token into application code or a VITE_ environment variable.

2. Initialize and choose one application package

Start in an empty frontend directory and initialize its manifest:

yarn init

Choose one of the following paths. The unversioned package name selects the registry’s current release. For a reproducible initial selection, append an existing version, for example @agon/atrium-starter@0.1.0 when that version is available.

Minimal starter

yarn add @agon/atrium-starter
yarn atrium-starter publish
yarn dev

Open the starter application. It provides the shell, theme, basic routes, preferences, notifications, and a demonstration identity. Stop the server with Ctrl+C.

Complete showcase

yarn add @agon/atrium-showcase
yarn atrium-showcase publish
yarn dev

Open the showcase application and its component catalogue. It includes demonstration pages, local fixtures, translations, and media. Stop the server with Ctrl+C. Replace its demo adapters and authentication handlers before using it with real records.

3. Understand the generated project

publish here means write the selected application template into your current project. It never uploads a package or creates a registry release. Both commands use @agon/atrium-publisher internally. You do not need to add that infrastructure package yourself.

The command validates the entire copy plan before writing, copies source and public assets, merges the required manifest settings, adds ignore entries, and runs yarn install. Your application name, version, unrelated scripts, and other manifest fields are preserved. It adds a direct, exact @agon/atrium dependency matching the template release, plus the required build dependencies. The application becomes a private ES module project with the supported Node engine and pinned Yarn manager.

Existing files with different contents and incompatible manifest settings cause a clear error before template files are copied. The command does not overwrite your customized pages. Matching files are left alone, so an unchanged publication can be repeated. Resolve conflicts deliberately or publish into a fresh project. For command options and failure recovery, see local application publication.

The starter produces this source layout:

frontend/
  package.json
  yarn.lock
  .yarnrc.yml
  .gitignore
  vite.config.mjs
  index.html
  main.js
  routes.js
  theme.scss
  home.html
  login.html
  not-found.html
  notifications.html
  preferences.html
  public/favicon.svg
  public/favicon.ico

The showcase uses config/routes.js, pages/, partials/, adapters/, fixtures/, locales/, styles/, and assets/ alongside its root entry points and public/ directory. The publisher copies nested assets, including its favicon, media, and local map geometry. Dependencies, generated builds, package CLI files, and package metadata are not copied as application source.

Commit your generated source, manifest, lockfile, ignore file, and registry configuration containing only the variable reference. Do not commit dependencies, credentials, or build output. Later reproducible installations use yarn install --immutable.

4. Configure your application

Configure the generated application’s appearance.config.mjs before building to choose theme and layout defaults, preference persistence, and whether the settings panel is included. See the dedicated appearance build configuration guide.

In main.js, choose a unique preference namespace, branding, groups, messages, and service context. Replace the title and description in index.html and the icon under public/. Configure public Sass variables in theme.scss using theming and layout.

Keep adminHtml, adminBuild, route compilation, and PostCSS RTL processing in vite.config.mjs. Retain the generated virtual:atrium/pages registry and base: import.meta.env.BASE_URL in createAdmin. Import the theme once and call app.start() once.

The header links to /profile, /settings, /notifications, and /login. Implement these destinations for your product or customize the header. The application files are now yours. Do not edit installed package contents under node_modules/.

5. Add a page and components

Follow your first page to add a route, a template, and translations in the generated project. The guide identifies the starter and showcase path differences. Verify sidebar navigation, the example notification button, and a direct reload of the new route.

Use the component guides for individual controls and component contracts for configuration, lazy controllers, and lifecycle. Your own pages can reuse shared components while defining their own application services.

6. Replace demo behavior with your backend

Follow backend and session integration. Replace demonstration identities and wildcard capabilities with the real session. Implement authentication, logout, server authorization, and API adapters. In a showcase-derived application, remove fixture-backed behavior from each feature you retain.

Neither template provides a production authentication backend. Verify real login, expiry, forbidden operations, logout, empty data, and request failures before using real records. The frontend base and API base remain separate, for example /control-panel/ and /api/v1/.

7. Build and preview

From the application root:

yarn build
yarn preview

The starter preview is localhost:4174. The showcase preview is localhost:4173. Stop it with Ctrl+C. Production output is in dist/. For readable diagnostic output, run yarn build:development, which writes dist-development/.

For a frontend hosted under /control-panel/, build and preview with the same base:

APP_BASE=/control-panel/ yarn build
APP_BASE=/control-panel/ yarn preview

Open /control-panel/ on the chosen preview port. Rebuild when changing the base. Preview does not validate the real host’s response headers, rewrite configuration, or backend.

8. Deploy and maintain

Follow deployment and upgrades for application CI, history fallback, asset/API errors, CSP, and the production acceptance checklist. Deploy dist/ and its fingerprinted assets together. The static host does not need Yarn, the registry token, or Atrium’s repository.

After initialization, the generated files belong to your application. Updating packages does not automatically merge template changes into those files. Review package upgrades, commit the updated lockfile, and run your application checks. The publishing guide explains when you can remove the template package.

Troubleshooting

Symptom	Action
Registry authentication or package resolution fails.	Verify the package project’s endpoint, token permissions, expiry, and published version.
Yarn reports a missing token variable.	Export `ATRIUM_NPM_TOKEN` in the current shell or CI job.
The publisher reports a manifest conflict.	Review the identified field and reconcile it with the selected release’s requirements.
The publisher reports a file conflict.	Keep the existing file and compare deliberately, or start in a fresh application directory.
Files were published but installation failed.	Correct the dependency or network problem and run `yarn install`. The files remain available.
A deep link fails only on the real host.	Check the deployed base, history fallback, and asset/API exclusions.

Author

Laurent Declercq l.declercq@agon-innovation.ch

License

Unless otherwise stated all source code is licensed under LGPL 2.1 and has the following copyright:

© 2026, Agon Partners Innovation AG, All rights reserved.

The design material and the “Agon Ātrium” trademark is the property of their authors. Reuse of them without prior consent of their respective authors is strictly prohibited.

Version

Version: 20260921