@granite-js/micro-frontend 2.0.0

package/src/plugin/intoShared.ts

@@ -0,0 +1,50 @@
+import type { MicroFrontendPluginOptions } from './types';
+import type { SharedConfig, SharedModuleConfig } from '../runtime/registry';
+
+const SHARED_PRESETS = {
+  react: ['react/jsx-runtime', 'react/jsx-dev-runtime'],
+  'react-native': [
+    'react-native/Libraries/BatchedBridge/BatchedBridge',
+    'react-native/Libraries/BatchedBridge/NativeModules',
+    'react-native/Libraries/BatchedBridge/MessageQueue',
+    'react-native/Libraries/NativeComponent/NativeComponentRegistry',
+    'react-native/Libraries/NativeComponent/NativeComponentRegistryUnstable',
+    'react-native/Libraries/NativeComponent/ViewConfigIgnore',
+    'react-native/Libraries/ReactNative/RendererProxy',
+    'react-native/Libraries/StyleSheet/PlatformColorValueTypes',
+    'react-native/Libraries/StyleSheet/normalizeColor',
+    'react-native/Libraries/StyleSheet/processColor',
+    'react-native/Libraries/TurboModule/TurboModuleRegistry',
+    'react-native/Libraries/Utilities/NativePlatformConstantsIOS',
+    'react-native/Libraries/Utilities/Platform',
+    'react-native/Libraries/Utilities/defineLazyObjectProperty',
+  ],
+} as const;
+
+export function intoShared(shared: MicroFrontendPluginOptions['shared']): SharedConfig | undefined {
+  if (shared == null) {
+    return undefined;
+  }
+
+  const normalized: Record<string, SharedModuleConfig> = {};
+  if (Array.isArray(shared)) {
+    for (const moduleName of shared) {
+      normalized[moduleName] = {};
+    }
+  } else {
+    Object.assign(normalized, shared);
+  }
+
+  for (const [moduleName, subpaths] of Object.entries(SHARED_PRESETS)) {
+    const moduleConfig = normalized[moduleName];
+    if (moduleConfig == null) {
+      continue;
+    }
+
+    for (const subpath of subpaths) {
+      normalized[subpath] ??= { ...moduleConfig };
+    }
+  }
+
+  return normalized;
+}

package/src/plugin/microFrontendPlugin.ts

@@ -0,0 +1,57 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import type { GranitePluginCore } from '@granite-js/plugin-core';
+import { prepareLocalDirectory } from '@granite-js/utils';
+import { intoShared } from './intoShared';
+import { getPreludeConfig } from './prelude';
+import { createSharedResolverConfig } from './resolver';
+import type { MicroFrontendPluginOptions } from './types';
+
+export async function microFrontend(options: MicroFrontendPluginOptions = {}): Promise<GranitePluginCore> {
+  const shared = intoShared(options.shared);
+  const normalizedOptions: MicroFrontendPluginOptions = {
+    ...options,
+    shared,
+  };
+  const nonEagerEntries = Object.entries(shared ?? {}).filter(([, config]) => config.eager !== true);
+  const localDirectory = prepareLocalDirectory(process.cwd());
+  const preludePath = path.join(localDirectory, 'micro-frontend-runtime.js');
+  const prelude = getPreludeConfig(normalizedOptions);
+  const resolver = createSharedResolverConfig(nonEagerEntries);
+
+  function writePrelude(appName?: string) {
+    const config = getPreludeConfig(normalizedOptions, appName);
+    fs.writeFileSync(preludePath, config.preludeScript, 'utf8');
+  }
+
+  writePrelude();
+
+  return {
+    name: 'micro-frontend',
+    dev: {
+      order: 'pre',
+      handler({ appName }) {
+        writePrelude(appName);
+      },
+    },
+    build: {
+      order: 'pre',
+      handler({ appName }) {
+        writePrelude(appName);
+      },
+    },
+    config: {
+      extra: nonEagerEntries.some(([moduleName]) => moduleName === 'react-native')
+        ? {
+            skipReactNativeInitializeCore: true,
+            skipReactNativePolyfills: true,
+          }
+        : undefined,
+      resolver,
+      esbuild: {
+        prelude: [preludePath],
+        banner: { js: prelude.banner },
+      },
+    },
+  };
+}

package/src/plugin/prelude.ts

@@ -0,0 +1,73 @@
+import path from 'path';
+import type { MicroFrontendPluginOptions } from './types';
+
+export interface MicroFrontendPreludeConfig {
+  readonly banner: string;
+  readonly preludeScript: string;
+}
+
+export function getPreludeConfig(
+  options: MicroFrontendPluginOptions,
+  appName?: string
+): MicroFrontendPreludeConfig {
+  const eagerSharedModules = Object.entries(options.shared ?? {}).filter(
+    ([, config]) => !Array.isArray(options.shared) && config.eager === true
+  );
+  const registerStatements = eagerSharedModules.map(([moduleName], index) => {
+    const identifier = `__shared${index}`;
+    return [
+      `import * as ${identifier} from ${JSON.stringify(moduleName)};`,
+      `registerShared(${JSON.stringify(moduleName)}, ${identifier});`,
+    ].join('\n');
+  });
+  const exposeStatements = Object.entries(options.exposes ?? {}).map(([exposedModule, modulePath], index) => {
+    const identifier = `__expose${index}`;
+    return [
+      `import * as ${identifier} from ${JSON.stringify(path.resolve(modulePath))};`,
+      `exposeModule(__container, ${JSON.stringify(exposedModule)}, ${identifier});`,
+    ].join('\n');
+  });
+  const containerConfig = JSON.stringify({ shared: options.shared });
+  const containerName = appName == null ? 'global.__granite.app.name' : JSON.stringify(appName);
+
+  return {
+    banner: [
+      'global._graniteMicroFrontend = global._graniteMicroFrontend || {',
+      '  containers: {},',
+      '  sharedModules: {},',
+      '};',
+    ].join('\n'),
+    preludeScript: [
+      'function createContainer(appName, config) {',
+      '  const containers = global._graniteMicroFrontend.containers;',
+      '  if (containers[appName] != null) {',
+      '    throw new Error(`App container \'${appName}\' is already registered`);',
+      '  }',
+      '  const container = { appName, config, exposedModules: {} };',
+      '  containers[appName] = container;',
+      '  return container;',
+      '}',
+      'function exposeModule(container, exposedModule, moduleValue) {',
+      "  const normalizedModule = exposedModule.startsWith('./') ? exposedModule : `./${exposedModule}`;",
+      '  if (container.exposedModules[normalizedModule] != null) {',
+      '    throw new Error(`Exposed module \'${normalizedModule}\' is already registered in app container \'${container.appName}\'`);',
+      '  }',
+      '  container.exposedModules[normalizedModule] = moduleValue;',
+      '}',
+      'function registerShared(moduleName, moduleValue) {',
+      '  const sharedModules = global._graniteMicroFrontend.sharedModules;',
+      '  const existingModule = sharedModules[moduleName];',
+      '  if (existingModule != null) {',
+      '    if (Object.is(existingModule.get(), moduleValue)) {',
+      '      return;',
+      '    }',
+      '    throw new Error(`Shared module \'${moduleName}\' is already registered`);',
+      '  }',
+      '  sharedModules[moduleName] = { get: () => moduleValue, loaded: true };',
+      '}',
+      `const __container = createContainer(${containerName}, ${containerConfig});`,
+      ...registerStatements,
+      ...exposeStatements,
+    ].join('\n'),
+  };
+}

package/src/plugin/resolver.ts

@@ -0,0 +1,73 @@
+import type { ResolverConfig } from '@granite-js/plugin-core';
+import type { SharedModuleConfig } from '../runtime/registry';
+
+const VIRTUAL_SHARED_PROTOCOL = 'granite-micro-frontend-shared';
+
+export function createSharedResolverConfig(
+  moduleEntries: readonly (readonly [string, SharedModuleConfig])[]
+): Pick<ResolverConfig, 'alias' | 'protocols'> {
+  const alias: ResolverConfig['alias'] = moduleEntries.map(([moduleName]) => ({
+    exact: true,
+    from: moduleName,
+    to: `${VIRTUAL_SHARED_PROTOCOL}:${moduleName}`,
+  }));
+
+  return {
+    alias,
+    protocols:
+      alias.length === 0
+        ? undefined
+        : {
+            [VIRTUAL_SHARED_PROTOCOL]: {
+              load(args: { readonly path: string }) {
+                const moduleName = JSON.stringify(args.path);
+                return {
+                  loader: 'js',
+                  contents: [
+                    `var sharedModule = global._graniteMicroFrontend.sharedModules[${moduleName}];`,
+                    'if (sharedModule == null) {',
+                    `  throw new Error('Shared module ' + ${moduleName} + ' is not registered');`,
+                    '}',
+                    'var sharedExports = sharedModule.get();',
+                    'var moduleExports = {};',
+                    'if (sharedExports != null) {',
+                    '  var sharedKeys = Reflect.ownKeys(sharedExports);',
+                    '  for (var i = 0; i < sharedKeys.length; i++) {',
+                    '    var sharedKey = sharedKeys[i];',
+                    '    var sharedDescriptor = Object.getOwnPropertyDescriptor(sharedExports, sharedKey);',
+                    '    if (sharedDescriptor == null || sharedDescriptor.enumerable !== true) {',
+                    '      continue;',
+                    '    }',
+                    '    (function (key) {',
+                    '      Object.defineProperty(moduleExports, key, {',
+                    '        enumerable: true,',
+                    '        configurable: true,',
+                    '        get: function () {',
+                    '          return sharedExports[key];',
+                    '        },',
+                    '        set: function (value) {',
+                    '          Object.defineProperty(moduleExports, key, {',
+                    '            enumerable: true,',
+                    '            configurable: true,',
+                    '            writable: true,',
+                    '            value: value,',
+                    '          });',
+                    '        },',
+                    '      });',
+                    '    })(sharedKey);',
+                    '  }',
+                    '}',
+                    "Object.defineProperty(moduleExports, '__esModule', {",
+                    '  enumerable: true,',
+                    '  configurable: true,',
+                    '  writable: true,',
+                    '  value: true,',
+                    '});',
+                    'module.exports = moduleExports;',
+                  ].join('\n'),
+                };
+              },
+            },
+          },
+  };
+}

package/src/plugin/types.ts

@@ -0,0 +1,6 @@
+import type { SharedConfig } from '../runtime/registry';
+
+export interface MicroFrontendPluginOptions {
+  readonly shared?: SharedConfig | readonly string[];
+  readonly exposes?: Readonly<Record<string, string>>;
+}

package/src/runtime/createMicroFrontendRuntime.ts

@@ -0,0 +1,115 @@
+import type {
+  AppRequest,
+  MicroFrontendAdapter,
+  MicroFrontendRuntimeApi,
+  MicroFrontendRuntimeEvent,
+  MicroFrontendRuntimeEventSubscription,
+} from '../types';
+import { AppContainerNotFoundError, InvalidAppNameError } from './errors';
+import { parseAppRequest } from './parseAppRequest';
+
+export interface NativeMicroFrontendRuntimeEvent {
+  readonly name: string;
+  readonly params: {
+    readonly appName?: string;
+    readonly sessionId?: string;
+    readonly scheme?: string;
+    readonly isVisible?: boolean;
+  };
+}
+
+export interface NativeMicroFrontendRuntime {
+  readonly evaluateScript: (request: { readonly filePath: string }) => Promise<void>;
+  readonly startEventDelivery: () => void;
+  readonly onEvent: (
+    listener: (event: NativeMicroFrontendRuntimeEvent) => void
+  ) => MicroFrontendRuntimeEventSubscription;
+}
+
+export interface MicroFrontendModuleRegistry {
+  readonly hasContainer: (appName: string) => boolean;
+  readonly removeContainer: (appName: string) => void;
+  readonly importModule: <TModule>(request: AppRequest) => TModule;
+}
+
+export interface CreateMicroFrontendRuntimeDependencies {
+  readonly adapter: MicroFrontendAdapter;
+  readonly nativeRuntime: NativeMicroFrontendRuntime;
+  readonly onPreloadError: (error: unknown) => void;
+  readonly registry: MicroFrontendModuleRegistry;
+  readonly removePendingHostComponentRoutes: (appName: string) => void;
+  readonly parseEvent: (event: NativeMicroFrontendRuntimeEvent) => MicroFrontendRuntimeEvent;
+}
+
+export function createMicroFrontendRuntimeWithDependencies(
+  dependencies: CreateMicroFrontendRuntimeDependencies
+): MicroFrontendRuntimeApi {
+  // A fulfilled promise is the evaluated-state cache. Rejected evaluations remove themselves.
+  const appEvaluations = new Map<string, Promise<void>>();
+
+  function resetFailedEvaluation(appName: string) {
+    appEvaluations.delete(appName);
+    dependencies.registry.removeContainer(appName);
+    dependencies.removePendingHostComponentRoutes(appName);
+  }
+
+  function preloadApp(appName: string): Promise<void> {
+    if (appName.length === 0) {
+      return Promise.reject(new InvalidAppNameError(appName));
+    }
+
+    const existingEvaluation = appEvaluations.get(appName);
+    if (existingEvaluation != null) {
+      return existingEvaluation;
+    }
+
+    const evaluation = evaluateApp(appName);
+    appEvaluations.set(appName, evaluation);
+    return evaluation;
+  }
+
+  async function evaluateApp(appName: string): Promise<void> {
+    try {
+      const { filePath } = await dependencies.adapter.loadBundle({ appName });
+      await dependencies.nativeRuntime.evaluateScript({ filePath });
+
+      if (!dependencies.registry.hasContainer(appName)) {
+        throw new AppContainerNotFoundError(appName);
+      }
+    } catch (error) {
+      resetFailedEvaluation(appName);
+      throw error;
+    }
+  }
+
+  return {
+    evaluateScript: (filePath) => dependencies.nativeRuntime.evaluateScript({ filePath }),
+    preloadApp,
+    async importApp<TModule>(request: AppRequest): Promise<TModule> {
+      const { appName } = parseAppRequest(request);
+      await preloadApp(appName);
+      return dependencies.registry.importModule<TModule>(request);
+    },
+    onEvent(listener) {
+      const subscription = dependencies.nativeRuntime.onEvent((event) => {
+        const parsedEvent = dependencies.parseEvent(event);
+        switch (parsedEvent.name) {
+          case 'preloadApp':
+            void preloadApp(parsedEvent.params.appName).catch(dependencies.onPreloadError);
+            return;
+          case 'openApp':
+          case 'closeApp':
+          case 'sessionVisibilityChanged':
+            listener(parsedEvent);
+            return;
+          default: {
+            const exhaustiveEvent: never = parsedEvent;
+            return exhaustiveEvent;
+          }
+        }
+      });
+      dependencies.nativeRuntime.startEventDelivery();
+      return subscription;
+    },
+  };
+}

package/src/runtime/errors.ts

@@ -0,0 +1,86 @@
+export class InvalidAppRequestError extends Error {
+  readonly request: string;
+
+  constructor(request: string) {
+    super(`Invalid micro-frontend app request: '${request}'`);
+    this.name = 'InvalidAppRequestError';
+    this.request = request;
+  }
+}
+
+export class InvalidAppNameError extends Error {
+  readonly appName: string;
+
+  constructor(appName: string) {
+    super('Micro-frontend app name must not be empty');
+    this.name = 'InvalidAppNameError';
+    this.appName = appName;
+  }
+}
+
+export class AppContainerNotFoundError extends Error {
+  readonly appName: string;
+
+  constructor(appName: string) {
+    super(`App container '${appName}' was not registered after bundle evaluation`);
+    this.name = 'AppContainerNotFoundError';
+    this.appName = appName;
+  }
+}
+
+export class AppContainerAlreadyRegisteredError extends Error {
+  readonly appName: string;
+
+  constructor(appName: string) {
+    super(`App container '${appName}' is already registered`);
+    this.name = 'AppContainerAlreadyRegisteredError';
+    this.appName = appName;
+  }
+}
+
+export class ExposedModuleNotFoundError extends Error {
+  readonly appName: string;
+  readonly exposedModule: string;
+
+  constructor(appName: string, exposedModule: string) {
+    super(`Could not resolve '${exposedModule}' from app container '${appName}'`);
+    this.name = 'ExposedModuleNotFoundError';
+    this.appName = appName;
+    this.exposedModule = exposedModule;
+  }
+}
+
+export class ExposedModuleAlreadyRegisteredError extends Error {
+  readonly appName: string;
+  readonly exposedModule: string;
+
+  constructor(appName: string, exposedModule: string) {
+    super(`Exposed module '${exposedModule}' is already registered in app container '${appName}'`);
+    this.name = 'ExposedModuleAlreadyRegisteredError';
+    this.appName = appName;
+    this.exposedModule = exposedModule;
+  }
+}
+
+export class SharedModuleAlreadyRegisteredError extends Error {
+  readonly moduleName: string;
+
+  constructor(moduleName: string) {
+    super(`Shared module '${moduleName}' is already registered`);
+    this.name = 'SharedModuleAlreadyRegisteredError';
+    this.moduleName = moduleName;
+  }
+}
+
+export class InvalidNativeRuntimeEventError extends Error {
+  readonly eventName: string;
+  readonly fieldName?: string;
+
+  constructor(eventName: string, fieldName?: string) {
+    const detail = fieldName == null ? '' : `: missing or invalid '${fieldName}'`;
+    super(`Invalid native micro-frontend event '${eventName}'${detail}`);
+    this.name = 'InvalidNativeRuntimeEventError';
+    this.eventName = eventName;
+    this.fieldName = fieldName;
+  }
+}

package/src/runtime/parseAppRequest.ts

@@ -0,0 +1,22 @@
+import type { AppRequest } from '../types';
+import { InvalidAppRequestError } from './errors';
+
+export interface ParsedAppRequest {
+  readonly appName: string;
+  readonly exposedModule: string;
+}
+
+export function parseAppRequest(request: AppRequest): ParsedAppRequest {
+  const separatorIndex = request.indexOf('/');
+  const appName = request.slice(0, separatorIndex);
+  const moduleName = request.slice(separatorIndex + 1);
+
+  if (separatorIndex <= 0 || moduleName.length === 0) {
+    throw new InvalidAppRequestError(request);
+  }
+
+  return {
+    appName,
+    exposedModule: moduleName.startsWith('./') ? moduleName : `./${moduleName}`,
+  };
+}

package/src/runtime/parseNativeRuntimeEvent.ts

@@ -0,0 +1,54 @@
+import type { MicroFrontendRuntimeEvent } from '../types';
+import type { NativeMicroFrontendRuntimeEvent } from './createMicroFrontendRuntime';
+import { InvalidNativeRuntimeEventError } from './errors';
+
+function requireString(event: NativeMicroFrontendRuntimeEvent, fieldName: 'appName' | 'scheme' | 'sessionId'): string {
+  const value = event.params[fieldName];
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new InvalidNativeRuntimeEventError(event.name, fieldName);
+  }
+  return value;
+}
+
+export function parseNativeRuntimeEvent(event: NativeMicroFrontendRuntimeEvent): MicroFrontendRuntimeEvent {
+  switch (event.name) {
+    case 'preloadApp':
+      return {
+        name: 'preloadApp',
+        params: { appName: requireString(event, 'appName') },
+      };
+
+    case 'openApp':
+      return {
+        name: 'openApp',
+        params: {
+          appName: requireString(event, 'appName'),
+          scheme: requireString(event, 'scheme'),
+          sessionId: requireString(event, 'sessionId'),
+        },
+      };
+
+    case 'closeApp':
+      return {
+        name: 'closeApp',
+        params: { sessionId: requireString(event, 'sessionId') },
+      };
+
+    case 'sessionVisibilityChanged': {
+      const isVisible = event.params.isVisible;
+      if (typeof isVisible !== 'boolean') {
+        throw new InvalidNativeRuntimeEventError(event.name, 'isVisible');
+      }
+      return {
+        name: 'sessionVisibilityChanged',
+        params: {
+          isVisible,
+          sessionId: requireString(event, 'sessionId'),
+        },
+      };
+    }
+
+    default:
+      throw new InvalidNativeRuntimeEventError(event.name);
+  }
+}

package/src/runtime/registry.ts

@@ -0,0 +1,131 @@
+import type { AppRequest } from '../types';
+import type { MicroFrontendModuleRegistry } from './createMicroFrontendRuntime';
+import {
+  AppContainerAlreadyRegisteredError,
+  ExposedModuleAlreadyRegisteredError,
+  ExposedModuleNotFoundError,
+  SharedModuleAlreadyRegisteredError,
+} from './errors';
+import { parseAppRequest } from './parseAppRequest';
+
+export interface SharedModuleConfig {
+  readonly eager?: boolean;
+}
+
+export type SharedConfig = Readonly<Record<string, SharedModuleConfig>>;
+
+export interface AppContainerConfig {
+  readonly shared?: SharedConfig;
+}
+
+export interface AppContainer {
+  readonly appName: string;
+  readonly config: AppContainerConfig;
+  readonly exposedModules: Record<string, unknown>;
+}
+
+interface SharedModule {
+  readonly get: () => unknown;
+  readonly loaded: boolean;
+}
+
+export interface MicroFrontendRuntimeContext {
+  readonly containers: Record<string, AppContainer>;
+  readonly sharedModules: Record<string, SharedModule>;
+}
+
+declare global {
+  var _graniteMicroFrontend: MicroFrontendRuntimeContext | undefined;
+}
+
+export function getMicroFrontendRuntimeContext(): MicroFrontendRuntimeContext {
+  const existingContext = globalThis._graniteMicroFrontend;
+  if (existingContext != null) {
+    return existingContext;
+  }
+
+  const context: MicroFrontendRuntimeContext = {
+    containers: {},
+    sharedModules: {},
+  };
+  globalThis._graniteMicroFrontend = context;
+  return context;
+}
+
+export function createContainer(appName: string, config: AppContainerConfig = {}): AppContainer {
+  const containers = getMicroFrontendRuntimeContext().containers;
+  if (containers[appName] != null) {
+    throw new AppContainerAlreadyRegisteredError(appName);
+  }
+
+  const container: AppContainer = {
+    appName,
+    config,
+    exposedModules: {},
+  };
+  containers[appName] = container;
+  return container;
+}
+
+export function exposeModule(container: AppContainer, exposedModule: string, module: unknown): void {
+  const normalizedModule = normalizeExposedModule(exposedModule);
+  if (container.exposedModules[normalizedModule] != null) {
+    throw new ExposedModuleAlreadyRegisteredError(container.appName, normalizedModule);
+  }
+  container.exposedModules[normalizedModule] = module;
+}
+
+export function registerShared(moduleName: string, module: unknown): void {
+  const sharedModules = getMicroFrontendRuntimeContext().sharedModules;
+  const existingModule = sharedModules[moduleName];
+  if (existingModule != null) {
+    if (Object.is(existingModule.get(), module)) {
+      return;
+    }
+    throw new SharedModuleAlreadyRegisteredError(moduleName);
+  }
+  sharedModules[moduleName] = {
+    get: () => module,
+    loaded: true,
+  };
+}
+
+export function getContainer(appName: string): AppContainer | null {
+  return getMicroFrontendRuntimeContext().containers[appName] ?? null;
+}
+
+export function removeContainer(appName: string): void {
+  const containers = getMicroFrontendRuntimeContext().containers;
+  const container = containers[appName];
+  if (container == null) {
+    return;
+  }
+
+  for (const exposedModule of Object.keys(container.exposedModules)) {
+    Reflect.deleteProperty(container.exposedModules, exposedModule);
+  }
+  Reflect.deleteProperty(containers, appName);
+}
+
+export function hasContainer(appName: string): boolean {
+  return getContainer(appName) != null;
+}
+
+export function importModule<TModule>(request: AppRequest): TModule {
+  const { appName, exposedModule } = parseAppRequest(request);
+  const module = getContainer(appName)?.exposedModules[exposedModule];
+  if (module == null) {
+    throw new ExposedModuleNotFoundError(appName, exposedModule);
+  }
+  return module as TModule;
+}
+
+function normalizeExposedModule(exposedModule: string): string {
+  return exposedModule.startsWith('./') ? exposedModule : `./${exposedModule}`;
+}
+
+export const microFrontendModuleRegistry: MicroFrontendModuleRegistry = {
+  hasContainer,
+  importModule,
+  removeContainer,
+};