@edynamix/mf-isolation

CSS isolation and Angular overlay helpers for microfrontends.

Install

bun add @edynamix/mf-isolation@latest

Runtime boundary

import { prepareMfBoundary } from '@edynamix/mf-isolation';

const disposeBoundary = prepareMfBoundary(element, {
  scopeId: 'portal',
});

// When the microfrontend unmounts:
disposeBoundary();

Build-time CSS isolation

For global and vendor CSS:

import { scopeRemoteCss } from '@edynamix/mf-isolation/postcss';

export default {
  css: {
    postcss: {
      plugins: [scopeRemoteCss({ scopeId: 'portal' })],
    },
  },
};

The host and remote must use the same scopeId. Both PostCSS plugins keep ordinary global and vendor selectors under the zero-specificity :where([data-edyn-mf="<scope-id>"]) boundary. Document-root descendants such as html body#app button instead use [data-edyn-mf="<scope-id>"] so module overrides retain sufficient cascade strength.

Angular with Vite

Angular applications must use the Angular-aware plugin so component CSS remains compatible with Emulated view encapsulation:

import { scopeAngularRemoteCss } from '@edynamix/mf-isolation/postcss';
import { defineConfig } from 'vite';

export default defineConfig({
  css: {
    postcss: {
      plugins: [scopeAngularRemoteCss({ scopeId: 'portal' })],
    },
  },
});

The Angular-aware plugin uses :host-context([data-edyn-mf="<scope-id>"]) for Emulated .component.css, .component.scss, .component.sass, and .component.less files. Components declaring ViewEncapsulation.None use the global selector behavior described above.

Run this plugin through Vite/PostCSS before Angular AOT compilation. Do not combine it with scopeRemoteCss in the same Vite configuration.

Navigation manifest

Declare module-owned navigation as validated data and emit navigation.json from the same Vite build:

import {
  defineMfNavigation,
  MF_NAVIGATION_CONTRACT_VERSION,
} from '@edynamix/mf-isolation/navigation';
import { mfNavigationPlugin } from '@edynamix/mf-isolation/vite';
import { defineConfig } from 'vite';

const navigation = defineMfNavigation({
  applicationId: 22,
  contractVersion: MF_NAVIGATION_CONTRACT_VERSION,
  items: [
    {
      id: 'stockmaster.for-sale',
      label: 'For Sale',
      order: 1,
      path: 'usedstock/for-sale',
    },
  ],
  label: 'Stock Master',
  landingPath: 'usedstock',
  moduleId: 'stockmaster',
});

export default defineConfig({
  plugins: [mfNavigationPlugin({ navigation })],
});

Routes are module-relative and contain no leading slash. The plugin validates the complete tree, emits deterministic JSON with a SHA-256 revision during builds, and serves the same manifest with Cache-Control: no-cache in development.

For standalone development, combine the manifest with the host-owned navigation browser entry and development BFF:

import {
  MF_DEVELOPMENT_HOST_NAVIGATION_PATH,
  mfDevelopmentBffPlugin,
} from '@edynamix/mf-isolation/vite-development';

mfDevelopmentBffPlugin({
  hostNavigationUrl: 'https://host.example.test/host-navigation/index.js',
  moduleApiOrigin: 'https://module.example.test',
  moduleApiPath: '/stockmasterapi/',
});

const localHostNavigationUrl = new URL(
  MF_DEVELOPMENT_HOST_NAVIGATION_PATH,
  'https://localhost:4200',
).href;

hostNavigationUrl selects the host environment. Load the browser entry from localHostNavigationUrl; the BFF serves the selected bundle and its host-owned logo assets through the secure local origin, avoiding mixed-content failures when the selected host is an HTTP localhost instance. Host API calls go to the selected host origin, while module API calls go to the explicit moduleApiOrigin. The BFF performs OIDC authorization code with PKCE, retains tokens and module API cookies in the development process, and forwards authenticated API requests without exposing either to module JavaScript. It also forwards the host-validated navigation selection through X-Edyn-Navigation-Group-Id and X-Edyn-Navigation-Dealer-Id; module backends must still authorize those values before constructing module-specific session state.

Angular CDK overlays

The Angular integration targets Angular/CDK 19.x. In a hosted application, install the complete provider array so global and connected overlays share the module boundary's viewport and coordinate system:

import { provideMfOverlayRoot } from '@edynamix/mf-isolation/angular';

const providers = provideMfOverlayRoot(overlayRoot);

Pass all of providers through the application bootstrap. Calling provideMfOverlayRoot() without an element preserves CDK's normal document-viewport behavior.

Legacy NgModule applications that receive the root through an injection token must install both providers through the token-aware helper:

import { InjectionToken, NgModule } from '@angular/core';
import { provideMfOverlayRootFromToken } from '@edynamix/mf-isolation/angular';

export const MF_OVERLAY_ROOT = new InjectionToken<HTMLElement>('MF_OVERLAY_ROOT');

@NgModule({
  providers: [...provideMfOverlayRootFromToken(MF_OVERLAY_ROOT)],
})
export class AppModule {}

Provide the runtime MF_OVERLAY_ROOT value through the existing platform/bootstrap injector. Do not extract only the first provider from provideMfOverlayRoot(); that installs the container but omits boundary-aware connected positioning.

The Angular entry point requires @angular/core, @angular/common, and @angular/cdk 19.x.

Host-owned Zone.js

Standalone Angular applications load their own Zone.js runtime as usual:

import 'zone.js';

When the application runs as a hosted lifecycle, the host owns the single Zone.js runtime. Check that runtime before dynamically importing any Angular code:

import { assertHostZoneRuntime } from '@edynamix/mf-isolation/angular-runtime';
import type { IShellContext } from './shell-context';

export const mount = async (host: HTMLElement, context: IShellContext): Promise<void> => {
  assertHostZoneRuntime();

  const lifecycle = await import('./lifecycle-impl');
  return lifecycle.mount(host, context);
};

angular-runtime is framework-free. It verifies that globalThis.Zone is a function; it does not load or modify Zone.js.

Exports

• @edynamix/mf-isolation
• @edynamix/mf-isolation/angular
• @edynamix/mf-isolation/angular-runtime
• @edynamix/mf-isolation/postcss