npm package: @rxbenefits/local-dev
Description: Shared local development orchestrator for Admin Portal MFEs.
Latest version: 0.3.0

# @rxbenefits/local-dev

Shared local development orchestrator for Admin Portal MFEs.

## Usage

```bash
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:

```json
{
  "$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`)

```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.