@cobranza-apps/mfe-events

TypeScript contract library for Shell–MFE communication.

Table of Contents

• Purpose
• Installation
• Quick Usage
• Event Catalog
• Design Principles
• Tech Stack
• Documentation
• Development & Contributing (for AI Agents)
• Related Packages

Purpose

• Named event constants: MFE_EVENTS, SHELL_EVENTS with stable mfe: / shell: prefixes.
• Strongly typed payload interfaces and EventMap types for type-safe dispatch and listen.
• Thin type-level + runtime helpers over the browser CustomEvent / window APIs: createMfeEvent, createShellEvent, isMfeEvent, isShellEvent.
• JSDoc + copy-paste usage examples on every public export.
• Does NOT provide: an event bus or RxJS subjects, Angular services/components/DI, workspace layout logic, BFF/API communication, UI chrome (owned by @cobranza-apps/ui), or DOM manipulation by MFEs outside their own container.
• Core rule: MFEs dispatch mfe:*; only the Shell listens. The Shell pushes info to MFEs via Angular Inputs and/or shell:* events.

Installation

Package manager and registry are not yet finalized (see .agent/project-info/tech.md). Once published, install with the adopted manager:

# npm
npm install @cobranza-apps/mfe-events

# pnpm
pnpm add @cobranza-apps/mfe-events

No Angular peer dependency is required. TypeScript 5.x and a modern browser CustomEvent/window API are the only runtime expectations.

Quick Usage

MFE dispatch (from the MFE side):

import {
  MFE_EVENTS,
  SCHEMA_VERSION,
  createMfeEvent,
  type UpdateHeaderPayload,
} from '@cobranza-apps/mfe-events';

const detail: UpdateHeaderPayload = {
  moduleType: 'clients',
  instanceId: myInstanceId,
  status: 'dirty',
  title: 'Clientes — sin guardar',
  schemaVersion: SCHEMA_VERSION,
};

window.dispatchEvent(createMfeEvent(MFE_EVENTS.UPDATE_HEADER, detail));

Shell listen (from the Shell side):

import { MFE_EVENTS, isMfeEvent } from '@cobranza-apps/mfe-events';

window.addEventListener(MFE_EVENTS.REQUEST_FULLSCREEN, (event: Event) => {
  if (!isMfeEvent(event, MFE_EVENTS.REQUEST_FULLSCREEN)) return;
  const { moduleType, instanceId } = event.detail;
  // Shell navigates to fullscreen for this instance
});

Full examples (Shell→MFE broadcast + filter, multi-instance handling) live in docs/USAGE.md.

Event Catalog

MFE -> Shell

| Constant | Event name | Purpose | | --- | --- | --- | | REQUEST_ADD_MODULE | mfe:request-add-module | Ask the Shell to add a new module instance to the workbench | | REQUEST_FULLSCREEN | mfe:request-fullscreen | Ask the Shell to switch this instance to fullscreen | | REQUEST_REMOVE | mfe:request-remove | Ask the Shell to remove this instance from the workbench | | UPDATE_HEADER | mfe:update-header | MFE updates its own header chrome (title, status) | | SHOW_NOTIFICATION | mfe:show-notification | Ask the Shell to show a global toast/notification | | MODULE_READY | mfe:module-ready | MFE finished mounting and is ready | | MODULE_ERROR | mfe:module-error | Unrecoverable load/init error for this instance |

Shell -> MFE

| Constant | Event name | Purpose | | --- | --- | --- | | MODULE_STATE | shell:module-state | Notify size / collapse / fullscreen / pixel dimensions and optional drag-and-drop state for this instance | | THEME_CHANGED | shell:theme-changed | Theme token set changed | | VISIBILITY_CHANGED | shell:visibility-changed | Instance became visible or hidden |

Naming rules

• MFE → Shell: prefix mfe:; Shell → MFE: prefix shell:.
• kebab-case after the prefix.
• No company/domain segment, no version suffix in the name.

Deferred (not in v1)

• WORKSPACE_CONTEXT (sibling instances list)
• Auth / session / token events
• Domain-specific events (mfe:client:*, etc.)
• Notification actions (button that fires another event)

Design Principles

• Typed first. Every event has a typed payload; no detail: any.
• Serializable only. Payloads are plain JSON-serializable data (no functions, DOM nodes, class instances).
• Stable names. Event name strings never change for a given meaning; evolve via optional new fields + package major version.
• Many focused events over a few overloaded ones that keep growing props.
• Shell is the only listener of mfe:* events. MFEs do not listen to each other.
• Broadcast + filter. shell:* events are dispatched on window; each MFE instance filters by instanceId (and usually moduleType).
• Multi-instance aware. The same moduleType can appear multiple times; almost every payload carries moduleType + instanceId.

Tech Stack

| Item | Choice | Notes | | --- | --- | --- | | Language | TypeScript 5.x | Angular 22 ecosystem | | Module format | ESM + typings | publishable package | | Angular | Not a dependency | types + thin helpers only | | Runtime | Browser CustomEvent + window | no Node runtime at consumer side | | Node | 22.22.3 (.nvmrc) | dev toolchain | | Build | tsc | plain TypeScript compiler; no bundler needed for a types + thin-helpers library | | Testing | Vitest or Jest (helpers) + tsc --noEmit (types) | no browser/E2E | | Docs | JSDoc + README + docs/USAGE.md | no Storybook |

Development Scripts

| Script | Command | Purpose | | --- | --- | --- | | npm run build | tsc | Compile sources to dist/ (.js + .d.ts) | | npm run typecheck | tsc --noEmit | Type-check without emitting output | | npm run clean | rimraf dist | Remove the dist/ directory |

Documentation

• Quick Usage (above) — minimal dispatch + listen.
• Copy-paste examples (broadcast, filtering, multi-instance): docs/USAGE.md.
• Anti-patterns — what NOT to do and why.
• JSDoc on every public export (event constants, payload interfaces, type maps, helpers).
• Project knowledge base: .agent/project-info/.

Development & Contributing (for AI Agents)

This repo is maintained AI-agent-first via the Kilo Code critical workflow — read AGENTS.md before any change and follow .kilo/commands/critical-workflow.md; rules, project structure, and plans live in .kilo/rules/, .agent/project-structure.md, and .kilo/plans/.

Related Packages

| Package | Relationship | | --- | --- | | @cobranza-apps/ui | Owns ModuleHeader/ModuleContainer visuals and the ModuleStatus union (keep values in sync). Does NOT dispatch these events. | | @cobranza-apps/entities | Domain models. Not imported by mfe-events; payloads stay generic. | | Shell | Sole mfe:* listener; owns workbench state, fullscreen URL, notification host. | | Individual MFEs | Dispatch mfe:*; filter shell:* by instanceId. |

Important Note for AI Agents

All agents working on this project MUST adhere to the workflows and rules outlined in AI Agent Onboarding document.

Before starting any task:

1. Review AGENTS.md: it is the primary source of instructions for agents.
2. Follow Workflows: follow the procedures defined in .agent/WORKFLOWS.md, especially the .kilo/commands/critical-workflow.md.