Assets

In OneCX, assets are the non-code files a user interface needs at runtime: icons, images, fonts, and translation (i18n) files. This page is a technology-agnostic overview of how assets are treated in OneCX and why they need special treatment; it does not cover the build configuration, which will be added per-technology on the Recommended Setup how-to pages once they are published.

Why assets need special treatment in OneCX

In a standalone web application, static assets are served from the application’s own origin: the browser requests /assets/icons/logo.svg, the server resolves that path against the application’s build output, and the asset loads.

OneCX applications do not run standalone. Each application is packaged as a Micro Frontend and loaded into the OneCX shell. When the shell loads a Micro Frontend, it is loaded relative to the shell’s deployment rather than from the application’s own origin. This changes how asset URLs are resolved: a path that the application’s build emitted is no longer guaranteed to resolve against the location the browser actually loads the application from.

As a result, an asset that is merely present in a library’s npm package — or that is bundled into the application’s build output — is not enough for the application to reference it at runtime from the shell. The asset must be published to a path the application’s own build serves, and the code must reference it through that published path. This is why asset handling in OneCX is not the same as in a standalone app: the special treatment exists to make library- and application-provided assets resolvable even though the application runs from the shell.

The same principle applies in both directions:

  • Library-provided assets (e.g. the translation files or icons a OneCX library ships) must be exposed by the application so the application can resolve them at runtime.

  • Application-provided assets (the app’s own styles and other static files) must be exposed so the shell can load and apply them when the application is active.

Library assets

OneCX libraries ship the assets their functionality depends on: translation files, icons, fonts, and other static files. Because the application is what loads and runs in the shell, exposing the assets of the libraries it uses is the application’s responsibility. Other library assets (icons, fonts, and other static files) should be exposed so the application resolves them at runtime; the application still loads and runs without them, but it renders with missing or broken assets.

The exact build configuration — how to declare the assets of a given library in an Angular or React application — will be described on the Recommended Setup Expose Library Assets page for each technology once that guidance is published. The conceptual requirement, regardless of technology, is: make the assets of the libraries you use part of your build output, at a path you reference them from.

Translation assets (required)

The most important library assets are translation files: a library that provides user-facing text ships i18n files for the languages it supports, and the application that uses the library is responsible for making those files available. Without them, library-provided strings fall back to untranslated keys or missing text.

The translation files of the OneCX libraries the application uses are required to be exposed: they are what carry the user-facing text, and without them the library’s strings fall back to untranslated keys or missing text.

Application assets

An application should also expose its own assets so the shell can apply them when the application is active.

Application styles (recommended)

In OneCX, an application’s own styles live in a styles.css file (the entry point for the application’s global stylesheet), and that file is what the application exposes to the shell.

Exposing the application’s styles.css is recommended rather than strictly required: the application still loads and runs without it, but the shell has no stylesheet to apply for that application, so the application may render without its intended global styling. How to expose styles.css — the per-technology mechanism — will be described on the Recommended Setup Expose Component Styles page once that guidance is published.

Note the boundary with the Style Isolation concept: exposing styles.css is the what and how — the mechanics of publishing the file so the shell can load it. What belongs inside that stylesheet, and how it is scoped so it does not leak into or out of the application, is a separate concern owned by the Style Isolation concept page.

A link to the Translations concept page will be added here once that page is published — it covers the library-translation exposure requirement described above in depth.

  • Style Isolation — rules for what belongs in an application’s styles.css and how the platform scopes it.

Once the Recommended Setup Expose Library Assets and Expose Component Styles pages are published, link them here as the practical step-by-step how-to for the two exposure steps described above.