Application deployment and upgrades

Run these procedures in your application repository after initial integration and backend setup. Atrium’s maintainer test servers and package-release pipeline are separate from your application’s hosting and CI.

Build the frontend

Both generated applications expose these scripts. The table shows starter ports. Showcase uses 5173 for development and 4173 for preview.

Command	Result
`yarn dev`.	Vite development server at `http://127.0.0.1:5174/`.
`yarn build`.	Production frontend in `dist/`.
`yarn build:development`.	Readable output and source maps in `dist-development/`.
`yarn preview`.	Local preview of `dist/` at `http://127.0.0.1:4174/`.

Stop development and preview servers with Ctrl+C. They are local development tools, not production hosting services. A standalone application uses these scripts directly. Commands such as yarn workspace @agon/atrium-showcase build belong to Atrium’s own repository.

Production output minifies JavaScript, CSS, entry HTML, and lazy page templates. It removes HTML source metadata comments. The retained adminBuild policy accepts ATRIUM_MINIFY=true or false for an explicit override. Keep the shared native Oxc minification policy and HTML/RTL integration when adjusting build configuration.

Frontend base and API base

For an application hosted at the origin root, run yarn build. For /control-panel/, run:

APP_BASE=/control-panel/ yarn build

The starter reads APP_BASE in Vite and passes import.meta.env.BASE_URL to createAdmin. Asset URLs and router URLs must use that same frontend base. The API base in createHttpClient remains independent, for example /api/v1/.

Use the shell’s base-aware href helper in native internal links:

<a :href="href('/resources')" x-link>Resources</a>

Route definitions and $router.push('/resources') use logical application paths. A hardcoded native href="/resources" points to the origin root and can escape the application base when opened in another tab or followed without JavaScript.

Hosting and history fallback

Deploy the contents of dist/, including assets/ and public files such as favicon.svg and favicon.ico, to your static host or backend’s frontend directory. Use HTTPS and configure the history fallback for application routes. API paths and missing assets must retain real errors.

The following Nginx example assumes the built files are copied into /srv/www/control-panel/ and the application API lives at /api/. Place these locations inside your server configuration and replace the API placeholder with your actual backend routing:

root /srv/www;

location = /control-panel {
    return 301 /control-panel/;
}
location ^~ /api/ {
    # Replace with the application's backend proxy or handler.
    return 404;
}
location ^~ /control-panel/api/ {
    # Keep accidental API requests out of the frontend fallback.
    return 404;
}
location ^~ /control-panel/assets/ {
    try_files $uri =404;
}
location ~* ^/control-panel/.*\.(js|mjs|css|map|json|svg|png|jpg|jpeg|gif|webp|ico|woff|woff2|webm|mp4|vtt)$ {
    try_files $uri =404;
}
location /control-panel/ {
    try_files $uri $uri/ /control-panel/index.html;
}

Adapt static-file matching to your asset types and route naming. This is a routing example, not a complete server configuration. Configure MIME types, TLS, response headers, and your real API separately. For an origin-root deployment, adapt the locations and fallback to /index.html while keeping API and asset exclusions.

The shipped applications use history routing. The router exposes mode: 'hash' for hosts without rewrite control, but Atrium’s production acceptance suite verifies history mode. Test any hash deployment in your application before adopting it.

Content security policy

Atrium’s production fixture uses the following policy:

default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline';
img-src 'self' data:; connect-src 'self'; font-src 'self';
object-src 'none'; base-uri 'self'

Set your actual policy as an HTTP response header on the deployed application. The CSP build of Alpine works without script unsafe-eval or inline scripts. Dynamic styles and the initial cloak rule currently require the inline-style allowance. Vite development’s HMR behavior is not a production CSP check. The PDF viewer uses a same-origin module worker and local support assets. Serve .mjs as JavaScript and permit same-origin workers if you define worker-src separately.

Adapt connect-src for your API and authorized WebSocket gateways, img-src for external images or map tiles, and media-src for remote video. Add only the origins your application actually uses. Package dependencies are bundled locally, so the frontend does not require a runtime CDN.

Application CI and credentials

In your application’s build job, use the selected Node 24 runtime, enable Corepack, and provide ATRIUM_NPM_TOKEN through CI secrets. Keep the Atrium registry endpoint in the application’s .yarnrc.yml. The essential commands from the application root are:

corepack enable
yarn install --immutable
yarn build

Set APP_BASE for the build job when deploying under a subdirectory. Run your own lint, unit, and browser checks as part of this pipeline. The generated applications do not include Atrium’s repository-wide yarn check or browser suite. Retain dist/ as the deployable artifact according to your CI system’s configuration.

You can use a read-only deploy token, or map an authorized GitLab CI_JOB_TOKEN to ATRIUM_NPM_TOKEN. For the latter, the Atrium package project must allow the application’s project or group through its job-token permissions, and the triggering user needs the required access. The registry URL continues to identify the Atrium project. See GitLab job-token access.

The registry token is used for installation only. Do not give it a VITE_ prefix, put it in browser code, print it in job logs, or deploy it with static files. An unconfigured .env file is not a substitute for exporting the variable to Yarn’s process.

Application acceptance checklist

Run these checks against the deployed production build and actual backend, using the application’s own tests and manual review:

Open the root and a deep route directly, reload them, and exercise back/forward navigation and query parameters.
Confirm the configured frontend base works for assets, native links, new tabs, lazy page requests, and the favicon.
Request a missing asset and an invalid API path. Both must return an appropriate error instead of index.html.
Verify real login, session expiry, logout, forbidden operations, and backend authorization with representative roles.
Exercise loading, empty, validation, and retry states. Navigate away during a pending request and confirm it cannot update the next page.
Check keyboard navigation, modal focus, mobile navigation, light/dark themes, configured locales, and RTL where supported by your product.
Inspect browser console and network failures under the real CSP and check that no registry credentials or demo adapters enter the deployed application.
Verify optional map, media, and console integrations only against the services your application actually enables.

Atrium’s package tests establish shared behavior. They do not certify your authentication, API permissions, hosting configuration, or business workflows.

Deployments and upgrades

Deploy entry HTML and its fingerprinted assets together. Avoid long-lived caching of index.html. Retain older fingerprinted assets for existing browser sessions while rolling out a new version. Otherwise, a session with old route import URLs can encounter missing chunks. Atrium offers retry and reload recovery, but correct asset retention prevents avoidable failures.

To upgrade Atrium, choose a version that already exists in the registry, review its release notes, then run from the application root with the registry token available:

ATRIUM_VERSION=0.1.0
yarn add --exact "@agon/atrium@$ATRIUM_VERSION"
yarn build

Replace the example version with your chosen release. Review changes to package.json and yarn.lock, compare relevant starter build settings with that release, and run your application acceptance checks. Update your own source deliberately if a public contract changed. Package upgrades do not merge template files into your application. If retaining @agon/atrium-starter or @agon/atrium-showcase, update it to the same release, or remove it as described in after initialization. Do not rerun local publication as an automatic upgrade procedure.

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