OpenMicrofrontends Specification 1.0.0

A complete setup with Host Backend integration looks like this:

If the Microfrontends do not require a Host Backend integration (everything is publicly available, no security, no proxying required, no SSR), here a simplified, Browser Standalone, setup:

A Microfrontend is a JavaScript frontend bundled into JS and CSS files.

It MUST be possible to start the Microfrontend within an arbitrary DOM element.

A Microfrontend SHOULD NOT affect anything outside that host element, in particular:

• It SHOULD use CSS selectors that specifically target elements within the Microfrontend
• It SHOULD NOT install any global libraries like polyfills

A Microfrontend SHOULD be themable and provide a way to align the Look&Feel to the Host Application.

A Microfrontend MAY support Server-Side Rendering (SSR).

A Microfrontend MAY receive a config object during startup, and it MAY support asynchronous, pub/sub-based, communication with other Microfrontends on the same page.

A Microfrontend MAY use Backend APIs to send and receive data.

A Microfrontend MAY share common libraries and code with other Microfrontends and the Host Application.

A Microfrontend Server serves the Microfrontend assets, according to the OpenMicrofrontend Description.

A Microfrontend Server SHOULD expose the OpenMicrofrontend Description (microfrontends.yaml or microfrontends.json), so Host Applications can dynamically register Microfrontends and react to changes after new deployments.

A Microfrontend Server MAY provide a route for server-side rendering.

A Microfrontend Server MAY provide an internal Backend API, commonly referred to as a Backend For Frontend (BFF).

A Host Application is any Web Application that hosts one or more Microfrontends.

It can be built in arbitrary frontend and backend technologies, such as Express.js with a template engine, Next.js, PHP, ASP.NET, Java Servlet, or Spring WebMVC. It its simplest form, it could be a simple single-page application (SPA) without a dedicated backend if the Microfrontends don't need security or proxying of Backend APIs.

The backend part of the Host Application, which can be used to provide security, proxying of Backend APIs and Server-Side Rendering (SSR).

The frontend part of the Host Application, which is used to start Microfrontends and provide means to interact with them.

The API Microfrontends use to fetch data or perform actions. This can be a REST API, GraphQL, or any other type of API that Microfrontends need to function correctly.

A Backend API which runs on Microfrontend Server and is only used internally by Microfrontends hosted there.

A Meta Specification to describe Microfrontends and how to load and interact with them, i.e., this document.

A formal description of a set of Microfrontends on a Microfrontend Server based on this Specification.

It is used to generate type-safe Renderers, Starters, and Host Backend Integrations.

A JavaScript function with a specified signature that needs to be implemented by the Microfrontend, so it can be loaded by OpenMicrofrontends compatible Host Applications.

The function MUST conform to the signature described in this Specification document.

A generator (such as OpenMicrofrontends Generator) SHOULD be used to create type-safe signatures based on a given OpenMicrofrontends Description.

A server-side route with a specified interface that needs to be implemented by the Microfrontend, so a server-side rendered HTML can be fetched by OpenMicrofrontends compatible Host Applications.

The function MUST conform to the interface described in this Specification document.

A generator (such as OpenMicrofrontends Generator) SHOULD be used to create type-safe signatures based on a given OpenMicrofrontends Description.

A function in the Host Frontend that starts Microfrontends.

This function is not covered by this Specification, but is essential for integrating Microfrontends into the Host Application.

A generator (such as OpenMicrofrontends Generator) SHOULD be used to create type-safe starters based on a given OpenMicrofrontends Description.

Host Backend components for security, proxying, SSR, etc. used to provide the necessary infrastructure for Microfrontends to interact with backend services in a secure and efficient way.

This integration is not covered by this Specification and might work differently for different backend technologies.

A generator (such as OpenMicrofrontends Generator) SHOULD be used to create type-safe backend integrations based on a given OpenMicrofrontends Description.

The OpenMicrofrontend Specification is versioned using a major.minor.patch versioning scheme. The major.minor portion of the version string (for example, 1.0) SHALL designate the Specification feature set. .patch versions address errors in, or provide clarifications to, this document, not the feature set. Tooling which supports Specification 1.1 SHOULD be compatible with all OMS 1.1.* versions. The patch version SHOULD NOT be considered by tooling, making no distinction between 1.1.0 and 1.1.1 for example.

An OpenMicrofrontend Description MAY be made up of a single JSON or YAML document, or it MAY be divided into multiple, connected parts at the author’s discretion. In the latter case, Schema Object $ref fields are used to identify the referenced elements.

Host Applications MAY ignore referenced schema objects and only process the main document.

openMicrofrontends: 1.0.0
microfrontends:
  - name: My First Microfrontend
    assets:
      initial:
        js:
          - app.js
    rendererFunctionName: startMyFirstMicrofrontend

type UndefinedToOptional = {
  [K in keyof T as T[K] extends undefined ? never : K]: T[K];
} & Partial;

type MessageBus<
  MESSAGES_PUBLISH extends Record | undefined,
  MESSAGES_SUBSCRIBE extends Record | undefined
> = {
  publish(topic: T, data: MESSAGES_PUBLISH[T]): void;
  subscribe(topic: T, cb: (data: MESSAGES_SUBSCRIBE[T]) => void): void;
  unsubscribe(topic: T, cb: (data: MESSAGES_SUBSCRIBE[T]) => void): void;
};

export type OpenMicrofrontendLifecycleHooks = {
  /**
   * Lifecycle callbacks.
   * MAY be provided by the Renderer.
   * MUST be called by the Host Application when the Microfrontend is going to be removed.
   */
  readonly onRemove?: () => void | Promise;
};

export type OpenMicrofrontendsClientContext<
  CONFIG extends Record,
  PERMISSIONS extends Record | undefined,
  API_PROXY_PATHS extends Record | undefined,
  MESSAGES_PUBLISH extends Record | undefined,
  MESSAGES_SUBSCRIBE extends Record | undefined
> = UndefinedToOptional<{
  /**
   * The unique ID of this Microfrontend instance.
   * MUST be provided by the Host Application, because it MAY be used to store prefetched state.
   */
  readonly id: string;
  /**
   * Two-letter language code.
   * SHOULD be provided by the Host Application for internationalization.
   */
  readonly lang?: string;
  /**
   * Some basic user information.
   * SHOULD be provided by the Host Application (if a user is logged in).
   */
  readonly user?: {
    readonly username: string;
    readonly displayName: string;
    readonly [otherProp: string]: unknown;
  };
  /**
   * Evaluated user permissions.
   * MUST be provided by the Host Application if *userPermissions* are defined in the Microfrontend Description.
   */
  readonly permissions: PERMISSIONS;
  /**
   * Evaluated API proxy paths.
   * MUST be provided by the Host Application if *apiProxies* are defined in the Microfrontend Description.
   */
  readonly apiProxyPaths: API_PROXY_PATHS;
  /**
   * The Microfrontend config.
   * MUST be provided by the Host Application. The Host Application MAY use the default config.
   */
  readonly config: CONFIG;
  /**
   * A message bus for communication between Microfrontends.
   * MUST be provided by the Host Application if *messages* are defined in the Microfrontend Description.
   */
  readonly messageBus: MESSAGES_PUBLISH extends undefined
    ? MESSAGES_SUBSCRIBE extends undefined
      ? undefined
      : MessageBus
    : MessageBus;

  /**
   * The Microfrontend was rendered server-side, and the host element already contains the initial HTML.
   * MUST be provided by the Host Application if the Microfrontend was rendered server-side.
   */
  readonly serverSideRendered?: boolean;
  /**
   * Some Host Application context.
   * MAY be provided by the Host Application.
   */
  readonly hostContext?: {
    readonly hostApplicationName: string;
    readonly [propName: string]: any;
  };
}>;

export type OpenMicrofrontendsRenderer<
  CONFIG extends Record,
  PERMISSIONS extends Record | undefined = undefined,
  API_PROXY_PATHS extends Record | undefined = undefined,
  MESSAGES_PUBLISH extends Record | undefined = undefined,
  MESSAGES_SUBSCIBE extends Record | undefined = undefined
> = (
  hostEl: HTMLElement,
  context: OpenMicrofrontendsClientContext
) => Promise;

The generic type-parameters CONFIG, PERMISSIONS, API_PROXY_PATHS, MESSAGES_PUBLISH, and MESSAGES_SUBSCRIBE of the OpenMicrofrontendsRenderer MUST be derived from their respective definition in the Microfrontend Description.

type UndefinedToOptional = {
  [K in keyof T as T[K] extends undefined ? never : K]: T[K];
} & Partial;

export type OpenMicrofrontendsSSRResponse = {
  /**
   * The rendered HTML.
   * MUST be delivered by the Renderer.
   */
  readonly html: string;
  /**
   * JavaScript code to be injected into the  of the Host Application page.
   * MAY be delivered by the Renderer.
   */
  readonly injectHeadScript?: string;
};

export type OpenMicrofrontendsServerContext<
  CONFIG extends Record,
  PERMISSIONS extends Record | undefined
> = UndefinedToOptional<{
  /**
   * The unique ID of this Microfrontend instance.
   * MUST be provided by the Host Application, because it MAY be used to store prefetched state.
   */
  readonly id: string;
  /**
   * Two-letter language code.
   * SHOULD be provided by the Host Application for internationalization.
   */
  readonly lang?: string;
  /**
   * Some basic user information.
   * SHOULD be provided by the Host Application (if a user is logged in).
   */
  readonly user?: {
    readonly username: string;
    readonly displayName: string;
    readonly [otherProp: string]: unknown;
  };
  /**
   * Evaluated user permissions.
   * MUST be provided by the Host Application if *userPermissions* are defined in the Microfrontend Description.
   */
  readonly permissions: PERMISSIONS;
  /**
   * The Microfrontend config.
   * MUST be provided by the Host Application. The Host Application MAY use the default config.
   */
  readonly config: CONFIG;
  /**
   * Some Host Application context.
   * MAY be provided by the Host Application.
   */
  readonly hostContext?: {
    readonly hostApplicationName: string;
    readonly [propName: string]: any;
  };
}>;

export type OpenMicrofrontendsServerSideRenderer<
  CONFIG extends Record,
  PERMISSIONS extends Record | undefined = undefined
> = (requestBody: OpenMicrofrontendsServerContext) => Promise;

The generic type-parameters CONFIG, and PERMISSIONS, of the OpenMicrofrontendsServerRenderer MUST be derived from their respective definition in the Microfrontend Description.

The request and response structure of the JSON payload to an SSR endpoint MUST follow the argument- and return-type of the OpenMicrofrontendsServerSiderRendererFunction type.