Configuring Browser.element for zero‑downtime incremental Elm migration alongside legacy JavaScript

Answer

To embed an Elm Browser.element app into an existing server-rendered page while keeping legacy JavaScript running, the following three concerns must be addressed:

1. CSS leakage - Elm's generated styles are global, so they can be overridden by or override page styles.
2. Port safety - Elm ports are untyped on the JS side, which can cause silent failures or runtime errors.
3. Feature-flag bootstrap - The Elm script must be loaded only when the flag is active, and the mount must not run twice.

Below are concrete, step‑by‑step recommendations for each area, followed by a minimal bootstrap snippet that ties them together.

1. Isolating Elm-Generated CSS

• Wrap the Elm root in a uniquely‑named container, e.g. <div id="elm-root" class="elm-namespace"></div>.
  • All Elm CSS selectors should be prefixed with that namespace. If you use elm-css or elm-styled, configure the namespace option so that generated classes become elm-namespace__button, elm-namespace__card, etc.
  • Alternatively, mount Elm inside a <custom-elm> element that attaches a Shadow DOM. The Shadow DOM automatically scopes styles, but you must ensure no external scripts query the subtree.
• When generating elm.js, inspect the --stats output to confirm that all class names contain the chosen namespace or are otherwise scoped.

2. Enforcing Type-Safe Port Contracts

• Define a JSON schema that mirrors the Elm port payloads. Use a validator such as ajv on the JavaScript side to reject malformed messages before they reach Elm.
  • Example: If Elm exposes a port sendMsg : (String, Int) -> msg, the JS validator should enforce that the payload is an array with a string and a number.
• Write TypeScript interfaces that match the Elm types and use them in unit tests. A Jest snapshot that serialises a sample Elm message and feeds it through the JS port will surface mismatches early.
• Run elm-test to test the Elm side’s handling of the same payloads. Any runtime error in Elm caused by a port mismatch will surface during this test stage.

3. Coordinating Feature-Flagged Script Loading

• Serve elm.js as a static asset with a cache‑busting hash (e.g. elm.abc123.js). Use the defer attribute so the script does not block page rendering.
• Create a lightweight bootstrap script (elm-loader.js) that performs the following:
  1. Checks a global flag, e.g. window.FEATURE_ELM, which is set by the server or a feature-flag service.
  2. If the flag is true and no Elm app has been mounted yet, load elm.js via import() or a <script> tag.
  3. After elm.js resolves, call Elm.Main.init({ node: document.getElementById('elm-root'), flags: /*…*/ }).
  4. Set a global guard, e.g. window.__ELM_APP__ = true, to prevent duplicate mounts if the page re‑renders.
• In the server template, render the elm-root container only when the feature flag is enabled. If the flag is off, render the legacy UI as usual.
• Test the zero‑downtime path by enabling the flag in a staging environment, verifying that both legacy and Elm UIs coexist, that event handlers work, and that no duplicate elements appear.

Missing Diagnostic Detail

To fine‑tune the bootstrap logic, could you let us know whether the feature flag is delivered as a static JavaScript variable, a cookie, or via a remote feature‑flag service? This will affect whether you need to poll for the flag or can rely on a single read during page load.