Assigning Layer Namespaces per Micro-Frontend

/* shell/src/styles/layers.css — parsed before any remote loads.

   WHY a single `apps` band: it guarantees no remote can occupy a top-level
   position, so the shell's design system, utilities and overrides keep their
   relationship to every app regardless of how many apps exist. */
@layer reset, vendor, base, theme, ds, apps, utilities, overrides;

// packages/mfe-contract/src/layer.js
// WHY derive rather than let each team choose: two teams independently
// picking `app` or `main` is a collision that produces silent cross-app
// overrides, and nothing in the browser reports it.
export const APPS_BAND = 'apps';

export function layerNameFor(appId) {
  if (!/^[a-z][a-z0-9-]*$/.test(appId)) {
    throw new Error(`invalid app id "${appId}" — lowercase kebab-case only`);
  }
  return `${APPS_BAND}.${appId}`;
}

/* shell/src/styles/layers.css — the shell owns this list.

   WHY here and not in each remote: remotes deploy independently, so if each
   declared its own position the resolved order would depend on which bundle
   the network delivered first. Declaring all siblings up front makes the
   result identical on every load. */
@layer apps.catalog, apps.search, apps.checkout, apps.account;

// apps/checkout/vite.config.js
// WHY at build time in the remote: the shell cannot reliably wrap CSS it
// receives through a JS module, and wrapping after injection always leaves a
// window where the unlayered rules are live.
import { layerNameFor } from '@org/mfe-contract';

const LAYER = layerNameFor('checkout');   // → "apps.checkout"

export default {
  css: {
    postcss: {
      plugins: [
        {
          postcssPlugin: 'wrap-in-layer',
          Once(root) {
            // WHY skip if already wrapped: hot reload can run this twice,
            // which would produce apps.checkout.apps.checkout.
            if (root.first?.type === 'atrule' && root.first.name === 'layer') return;
            const layer = root.clone().removeAll();
            root.each((node) => layer.append(node.clone()));
            root.removeAll();
            root.append({ name: 'layer', params: LAYER, nodes: layer.nodes });
          },
        },
      ],
    },
  },
};

// packages/mfe-contract/src/assert-layer.js
// WHY development-only: the check walks every stylesheet, which is too
// expensive for production, and the failure it catches is a build
// misconfiguration that should never reach a user.
export function assertAppStyles(appId) {
  if (process.env.NODE_ENV === 'production') return;
  const expected = `apps.${appId}`;
  const found = new Set();

  const walk = (rules, path = []) => {
    for (const r of rules) {
      if (r.constructor.name === 'CSSLayerBlockRule') {
        const next = r.name ? [...path, r.name] : path;
        found.add(next.join('.'));
        walk(r.cssRules, next);
      } else if (r.cssRules) {
        walk(r.cssRules, path);
      } else if (r.selectorText && path.length === 0) {
        found.add('(unlayered)');
      }
    }
  };
  for (const s of document.styleSheets) {
    try { walk(s.cssRules); } catch { /* cross-origin */ }
  }

  if (found.has('(unlayered)')) {
    console.error(`[${appId}] unlayered CSS detected — it outranks every layer`);
  }
  if (!found.has(expected)) {
    console.warn(`[${appId}] expected layer ${expected} was never registered`);
  }
}

// packages/mfe-contract/src/index.js — the shared contract, one small file.

/** WHY a single reserved band: no remote can ever take a top-level slot,
 *  so the shell's own layers keep their relationships as apps come and go. */
export const APPS_BAND = 'apps';

/** The registry is the source of truth for both the namespace and the
 *  sibling order. Adding an app is a change to THIS file, reviewed by the
 *  platform team, and it must ship before the app deploys. */
export const APP_ORDER = ['catalog', 'search', 'checkout', 'account'];

export function layerNameFor(appId) {
  if (!APP_ORDER.includes(appId)) {
    throw new Error(`"${appId}" is not registered — add it to APP_ORDER first`);
  }
  return `${APPS_BAND}.${appId}`;
}

/** WHY generated rather than hand-written: the shell's declaration and the
 *  registry cannot drift apart if one is derived from the other. */
export function appsLayerStatement() {
  return `@layer ${APP_ORDER.map((id) => `${APPS_BAND}.${id}`).join(', ')};`;
}

/* shell/src/styles/layers.css — generated at build time from the contract.
   WHY the shell owns both statements: remotes deploy independently, so the
   only file guaranteed to be parsed before all of them is this one. */
@layer reset, vendor, base, theme, ds, apps, utilities, overrides;
@layer apps.catalog, apps.search, apps.checkout, apps.account;

@import url("./reset.css")     layer(reset);
@import url("./base.css")      layer(base);
@import url("./theme.css")     layer(theme);
@import url("@org/design-system/dist/index.css") layer(ds);
@import url("./utilities.css") layer(utilities);

// apps/checkout/src/bootstrap.js — every remote does exactly this.
import { assertAppStyles } from '@org/mfe-contract/assert-layer';
import './styles/index.css';   // already wrapped in apps.checkout at build time

export function mount(el) {
  // WHY assert at mount rather than at import: stylesheets injected by the
  // bundler are present by then, so the check sees the real state.
  assertAppStyles('checkout');
  // …render…
}