@rxbenefits/local-dev

Shared local development orchestrator for Admin Portal MFEs.

Usage

rxb-local-dev --all
rxb-local-dev --app=ben-admin
rxb-local-dev --all --config=./local-dev.config.json

MFE Discovery

The CLI discovers MFEs through a layered resolution chain (highest priority first):

1. local-dev.config.json slugToRepo -- explicit overrides from the caller repo and sibling repos.
2. mfe.manifest.json -- self-describing manifests in sibling repo directories. Each MFE declares its slug, port, basePath, and repo name.
3. mfe-registry.json -- central registry in the shell repo (admin-portal-shell/mfe-registry.json). Used as a fallback when sibling repos are not cloned locally.
4. @rxbenefits/constants/MfeConfig -- the shared constants package (baseline registry).

mfe.manifest.json (per MFE repo)

Place at the root of each MFE repo. The JSON schema at mfe-manifest.schema.json provides IDE autocompletion:

{
  "$schema": "./node_modules/@rxbenefits/local-dev/mfe-manifest.schema.json",
  "slug": "ben-admin",
  "name": "Ben Admin",
  "port": 3001,
  "basePath": "/ben-admin",
  "repo": "ben-admin"
}

When rxb-local-dev starts, it scans all sibling directories for mfe.manifest.json files. Each manifest provides an automatic slug-to-repo mapping, eliminating the need for manual local-dev.config.json entries.

mfe-registry.json (shell repo)

The shell repo maintains a central registry of all known MFEs. This is the fallback source for MFEs whose repos aren't cloned locally. MFEs not running locally will have their nav items disabled (no PROXY_URL is set).

Adding a New MFE

1. Create mfe.manifest.json in the new repo root.
2. Add the MFE to mfe-registry.json in the shell repo.
3. Add the MFE to MFE_CONFIG in @rxbenefits/constants and MFE_APPS in @rxbenefits/config.
4. Add a nav entry in admin-portal-shell/app/nav.config.ts.
5. Publish the updated libraries.

No changes are needed in existing MFE repos -- they will automatically discover the new MFE via manifests.

Legacy Config (local-dev.config.json)

{
  "slugToRepo": {
    "integrations": "data-management"
  }
}

This file is still supported as an explicit override. The CLI merges slugToRepo mappings from sibling repo configs (../*/local-dev.config.json) and then applies the caller repo config as the final override. With manifests in place, this file is optional.

Behavior

• Uses @rxbenefits/constants/MfeConfig as the MFE source of truth.
• Discovers MFEs from mfe.manifest.json in sibling repos and mfe-registry.json in the shell.
• Falls back to merged caller/sibling slugToRepo mappings from local-dev.config.json files.
• --all starts mapped apps plus unmapped apps that already exist locally with a package.json.
• --all skips unmapped/unavailable apps (no clone attempts for unknown repo names).
• Bootstraps missing repos from GitHub into the parent directory of the current repo.
• Uses safe sync for existing repos:
  • clean repo: git fetch + git pull --ff-only
  • dirty/diverged repo: warn and skip update
• Installs dependencies only when needed:
  • cloned repo
  • pnpm-lock.yaml changed after pull
  • node_modules missing
• Starts MFE apps with pnpm dev:standalone, waits for readiness, then starts shell with proxy env vars.
• Supports partial startup when one or more MFEs fail, but shell must start.
• MFEs not running locally are not proxied -- their nav items appear disabled.