@meltwater/engage-app-chrome

Shared app chrome (navigation, layout, shell) for the Meltwater Engage suite — Conversations, Publish, and Measure.

Install

npm install @meltwater/engage-app-chrome

The package is scoped @meltwater and lives on the private npm registry. Consumer apps must be authenticated to the scope (either via a .npmrc _authToken or via npm login).

Use — React apps

import { AppChrome } from "@meltwater/engage-app-chrome";

export function App({ children }) {
  return <AppChrome>{children}</AppChrome>;
}

The chrome ships with its own styles, providers (React Query, App Router fallback), and layout — consumer apps do not need to import CSS or wire up context.

Optional props:

| Prop | Type | Purpose | |---|---|---| | hideChrome | boolean | Renders children with no chrome shell around them | | theme | "light" \| "dark" | Initial colour theme; defaults to the user's persisted preference | | options | ManifestPayload | Force-enables the listed company/user treatments on top of the fetched manifest | | disableIdentityClient | boolean | Opt out of the built-in session keep-alive (see below) |

Session keep-alive

The chrome bootstraps gaf-identity-client on mount: it loads the client from the CDN (reusing a copy the host already provides, if any), initializes it for the detected environment, and logs the user out on session-ending auth errors. This gives every consumer silent gyda-token refresh and idle-timeout logout without app-side wiring — the same behaviour the legacy CDN app-chrome provided.

Hosts that manage identity themselves should opt out with the disableIdentityClient prop (React) or the disable-identity-client attribute (custom element) and remove any duplicate initialization to avoid double refresh cycles.

Environment

The chrome resolves its backends at runtime: any *.meltwater.com host is treated as production, everything else (staging.meltwater.net, *.preview.meltwater.net, localhost.meltwater.net) as staging — the same heuristic the Engage apps use. Hosts can override either decision before the chrome is imported:

<script>
  window.__MW_APP_CHROME_ENV__ = "staging"; // force "production" | "staging"
  window.__MW_APP_CHROME_ENV_OVERRIDES__ = {
    // any environment value, e.g. rotate a key or pin the translations CDN
    TRANSLATION_CDN_VERSION: "1.31.682",
  };
</script>

What the chrome owns vs. what hosts own

Owned by the chrome (no host wiring needed): navigation, header, workspace/app switchers, user menu, universal search, Meltwaiter/Companion, i18n, theming, the flux design tokens (see below), manifest, session keep-alive (see above), an error boundary (a chrome crash renders your content bare instead of a white page), and the notification bell mount point — the chrome renders <mi-notification-bell>; keep loading the mi-notification-bell CDN script for the bell to light up.

Design tokens

The chrome inlines the --flux-* custom properties from @meltwater/flux-design-tokens onto the page, the way the legacy CDN chrome shipped them via a global <link>. Host apps therefore need no tokens stylesheet of their own — and must not drop the tokens when they remove the legacy chrome: every flux web component in the host's own UI reads them, so without them borders, spacing and colours fall back to unstyled defaults across the app, not just inside the chrome.

Hosts that still load the tokens themselves are not broken by this — the values are identical and the duplicate :root block is harmless — but the dependency can be dropped.

Host responsibilities (by design — every Engage app already does these itself):

| Concern | Host provides | |---|---| | Segment analytics | the analytics.js snippet / window.analytics | | Pendo (tracking, guides, onboarding) | the Pendo agent snippet | | Intercom / help widget | window.Intercom (e.g. via gaf-my-precious); the chrome's help button calls it | | Live feature flags (Split) | own Split client if needed; the chrome only consumes manifest treatments (+ options overrides) |

Bundler notes

• The package guards process, global and __dirname itself (first import of both entries) — host apps do not need window.process shims.
• Bundlers that don't read package.json exports (e.g. Stencil's rollup) resolve @meltwater/engage-app-chrome/elements through classic root files — no dist/ deep imports needed.

Use — Vue / vanilla apps (custom elements)

import "@meltwater/engage-app-chrome/elements";

Then use the custom-element markup in your templates:

<mi-app-chrome>
  <mi-app-chrome-content>
    <!-- your app content -->
  </mi-app-chrome-content>
</mi-app-chrome>

An appChromeComponentRendered event fires on the host element when the chrome has mounted.

Development

nvm use
npm ci
npm run build
npm test

Releases

Merges to main are versioned automatically by semantic-release based on Conventional Commits messages, then published to npm. Prerelease branches: next, beta, alpha.

Publish authentication uses npm OIDC Trusted Publishing — the workflow presents a GitHub OIDC token that npm validates against the trusted-publisher configuration on this package. No long-lived npm token is stored anywhere.

Status

See epic SMM-9312.