@elliemae/pui-cli 9.0.0-alpha.12 → 9.0.0-alpha.13

package/dist/esm/skills/migrate-storybook-out-of-cjs/SKILL.md

@@ -3,12 +3,12 @@ name: migrate-storybook-out-of-cjs
 description: >-
   Migrate PUI Storybook from CJS wrappers and @elliemae/pui-app-sdk/storybook/cjs/* to ESM
   (.storybook/*.mjs) and @elliemae/pui-app-sdk/storybook/* imports. Use when upgrading Storybook
-  10 with pui-cli 9, replacing require() in .storybook/main.js, removing storybook/cjs/main or
-  storybook/cjs/middleware, deleting .storybook/middleware.js, or converting preview/manager/theme
-  to ESM.
+  10 with pui-cli 9, bumping to latest pui-app-sdk, replacing require() in .storybook/main.js,
+  removing storybook/cjs/main or storybook/cjs/middleware, deleting .storybook/middleware.js,
+  or converting preview/manager/theme to ESM.
 ---
 
-# Migrate Storybook out of CJS
+# Migrate Storybook out of CJS (Storybook 10 + latest pui-app-sdk)
 
 Moves consumer repos from legacy CommonJS Storybook wrappers (`require('@elliemae/pui-app-sdk/storybook/cjs/...')`) to ESM (`.storybook/*.mjs` + `@elliemae/pui-app-sdk/storybook/*`).
 
@@ -21,28 +21,56 @@ For the full pui-cli 9 upgrade (Node 24, ESLint 10, etc.), install `migrate-to-p
 - `.storybook/main.js` uses `require('@elliemae/pui-app-sdk/storybook/cjs/main')`
 - `.storybook/middleware.js` exists or imports `storybook/cjs/middleware`
 - Storybook fails after bumping pui-app-sdk with “Cannot find module …/storybook/cjs/…”
+- Storybook fails with `Cannot find module '…/dist/esm/utils/storybook/main.js'` (app-sdk not built)
 - Moving from Storybook 6 CJS config to Storybook 10 ESM config with pui-cli
 
-## What changed
+## pui-app-sdk changes (latest Storybook 10 train)
 
-| Topic             | Before (CJS / SB6)                         | After (ESM / SB10)                                               |
-| ----------------- | ------------------------------------------ | ---------------------------------------------------------------- |
-| Consumer config   | `.storybook/main.js`                       | `.storybook/main.mjs`                                            |
-| Shared import     | `@elliemae/pui-app-sdk/storybook/cjs/main` | `@elliemae/pui-app-sdk/storybook/main`                           |
-| Export name       | `getConfig()` (CJS default)                | **`getStorybookConfig()`** (named export)                        |
-| API mocks         | `.storybook/middleware.js`                 | Built into pui-cli Storybook dev server                          |
-| Preview / manager | `.storybook/preview.js`, `manager.js`      | `.storybook/preview.mjs`, `manager.mjs` (when using ESM imports) |
-| CLI               | `start-storybook` / `build-storybook`      | `pui-cli storybook` → `storybook dev` / `storybook build`        |
-| Addons            | Installed in consumer `package.json`       | Bundled in pui-cli; resolved via pui-app-sdk                     |
+| Topic           | Before                                          | After                                                                                |
+| --------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------ |
+| Import path     | `@elliemae/pui-app-sdk/storybook/cjs/main`      | `@elliemae/pui-app-sdk/storybook/main`                                               |
+| Export name     | `getConfig()`                                   | **`getStorybookConfig(viteBuilder?)`**                                               |
+| Published files | CJS under `storybook/cjs/`                      | TypeScript in repo; **`dist/esm\|cjs/utils/storybook/*`** at runtime                 |
+| Shared modules  | `cjs/main`, `cjs/webpack`, …                    | `main`, `preview`, `manager`, `theme`, `webpack`, `vite`, `middleware` (deprecated)  |
+| app-sdk dogfood | CJS + SB6 webpack hacks in `.storybook/main.js` | **`.storybook/*.ts`** → `../lib/utils/storybook/*` (source; not package self-import) |
+
+Consumers **must** import compiled dist (`@elliemae/pui-app-sdk/storybook/*`). After a local `file:` link, run **`pnpm run build`** in app-sdk before Storybook.
+
+## What changed (consumers)
+
+| Topic             | Before (CJS / SB6)                         | After (ESM / SB10)                                                                                                                         |
+| ----------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| Consumer config   | `.storybook/main.js`                       | `.storybook/main.mjs`                                                                                                                      |
+| Shared import     | `@elliemae/pui-app-sdk/storybook/cjs/main` | `@elliemae/pui-app-sdk/storybook/main`                                                                                                     |
+| Export name       | `getConfig()` (CJS default)                | **`getStorybookConfig()`** (named export)                                                                                                  |
+| API mocks         | `.storybook/middleware.js`                 | Built into pui-cli Storybook dev server                                                                                                    |
+| Preview / manager | `.storybook/preview.js`, `manager.js`      | `.storybook/preview.mjs`, `manager.mjs` (when using ESM imports)                                                                           |
+| CLI               | `start-storybook` / `build-storybook`      | `pui-cli storybook` → `storybook dev` / `storybook build`                                                                                  |
+| Addons            | Installed in consumer `package.json`       | Bundled in pui-cli; referenced by package name in app-sdk config                                                                           |
+| MDX docs          | `*.stories.mdx`                            | Docs-only pages: **`*.mdx`** + `@storybook/addon-docs/blocks`                                                                              |
+| Babel (Storybook) | SWC / ad-hoc overrides                     | `@storybook/addon-webpack5-compiler-babel` + project **`babel.config.ts`** → pui-cli `babelConfig` (includes private class fields/methods) |
 
 ## Pre-flight
 
 1. Bump `@elliemae/pui-cli@9` and `@elliemae/pui-app-sdk@*` together.
-2. Run `pnpm install`. If using a local `file:` link to pui-app-sdk, reinstall after rebuilding app-sdk so workspace `node_modules` picks up fresh dist.
+2. Run `pnpm install`. If using a local `file:` link to pui-app-sdk, **`pnpm run build`** in app-sdk, then reinstall in the consumer so `dist/` storybook exports exist.
 3. Confirm the repo uses `pui-cli storybook` (not raw `start-storybook` scripts).
+4. Consumer **`babel.config.ts`** should re-export pui-cli only — migrate from `babel.config.cjs` if present. **Do not** add `@babel/plugin-transform-private-methods` locally (included in pui-cli 9).
 
 ## Migration steps
 
+### Step 0 — Babel config (if not done in `migrate-to-pui-cli-9`)
+
+Replace `babel.config.cjs` with `babel.config.ts`:
+
+```typescript
+import { babelConfig } from '@elliemae/pui-cli';
+
+export default babelConfig;
+```
+
+Delete `babel.config.cjs`. Do **not** add private-method Babel plugins locally.
+
 ### Step 1 — Replace `.storybook/main.js`
 
 Delete `main.js`. Create `.storybook/main.mjs`:
@@ -53,7 +81,9 @@ import { getStorybookConfig } from '@elliemae/pui-app-sdk/storybook/main';
 export default getStorybookConfig();
 ```
 
-**Do not** use `getConfig` or `require('…/storybook/cjs/main')` — those paths and names are removed.
+**Do not** use `getConfig`, `require('…/storybook/cjs/main')`, or import storybook from app-sdk before dist is built.
+
+Optional Vite builder (experimental): `export default getStorybookConfig(true);`
 
 ### Step 2 — Remove middleware
 
@@ -76,7 +106,7 @@ export {
 } from '@elliemae/pui-app-sdk/storybook/preview';
 ```
 
-**Preview with local theme** (see `pui-react-boilerplate`, `pui-app-sdk`):
+**Preview with local theme** (see `pui-react-boilerplate`):
 
 ```javascript
 // .storybook/preview.mjs
@@ -92,23 +122,40 @@ const parameters = getParameters(theme);
 export { decorators, parameters, loaders };
 ```
 
-**Manager / theme** — convert `manager.js` → `manager.mjs`, `theme.js` → `theme.mjs` when they use `import`/`export`:
+**Manager / theme** — convert `manager.js` → `manager.mjs`, `theme.js` → `theme.mjs` when customized:
 
 ```javascript
 // .storybook/manager.mjs
-export { managerConfig } from '@elliemae/pui-app-sdk/storybook/manager';
+import { initSBManager } from '@elliemae/pui-app-sdk/storybook/manager';
+import { theme } from './theme.mjs';
+
+initSBManager(theme);
 ```
 
 ```javascript
 // .storybook/theme.mjs
-export { theme } from '@elliemae/pui-app-sdk/storybook/theme';
+export const theme = {
+  brandTitle: 'My App',
+  brandUrl: 'https://example.com',
+};
 ```
 
 Keep `.storybook/preview-head.html` unchanged.
 
 Delete obsolete `.js` duplicates after creating `.mjs` files (`preview.js`, `manager.js`, `theme.js`, `middleware.js`).
 
-### Step 4 — Monorepo lib packages (no `app/` directory)
+### Step 4 — MDX docs (Storybook 10 / MDX3)
+
+- Docs-only pages: rename **`intro.stories.mdx`** → **`intro.mdx`** (avoid `.stories.mdx` unless the file exports CSF stories).
+- Import Meta from **`@storybook/addon-docs/blocks`**:
+
+```mdx
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Getting Started/Introduction" />
+```
+
+### Step 5 — Monorepo lib packages (no `app/` directory)
 
 pui-app-sdk omits `../app/**` story globs when no `app/` folder exists. If globs still fail, filter explicitly in `main.mjs`:
 
@@ -123,13 +170,13 @@ export default config;
 
 Pilot: `pui-mono-repo-boilerplate/libs/foo`.
 
-### Step 5 — Stories and types
+### Step 6 — Stories and types
 
 - Prefer CSF3 and `@storybook/react-webpack5` types where TypeScript fails.
 - Remove Storybook 6 webpack alias workarounds (MDX pinning, react-select hacks) unless a story still breaks after upgrade.
-- Consumers do **not** install `@storybook/addon-*` separately — addons resolve from pui-cli via pui-app-sdk.
+- Consumers do **not** install `@storybook/addon-*` separately — addons resolve from pui-cli via NODE_PATH.
 
-### Step 6 — ESLint
+### Step 7 — ESLint
 
 Ensure `.storybook/**` is linted. After pui-cli 9 ESLint flat config migration, run `pnpm exec pui-cli lint` on story files.
 
@@ -144,29 +191,35 @@ pnpm exec pui-cli lint
 
 Checklist:
 
+- [ ] `babel.config.ts` re-exports pui-cli; no `babel.config.cjs`
 - [ ] No `require('@elliemae/pui-app-sdk/storybook/cjs/…')` anywhere
 - [ ] `.storybook/main.mjs` exists; `main.js` removed
 - [ ] `.storybook/middleware.js` removed (if it existed)
+- [ ] app-sdk dist built when using local link
 - [ ] Story dev server starts; mock API routes work without middleware file
 - [ ] Static build succeeds
 
 ## Troubleshooting
 
-| Symptom                                      | Fix                                                                                   |
-| -------------------------------------------- | ------------------------------------------------------------------------------------- |
-| `Cannot find module '…/storybook/cjs/main'`  | Migrate to `@elliemae/pui-app-sdk/storybook/main` in `main.mjs`                       |
-| `getConfig is not a function`                | Use named import **`getStorybookConfig`**, not `getConfig`                            |
-| `Can't resolve './app'` in lib-only package  | Use conditional globs in app-sdk or filter `config.stories` in `main.mjs`             |
-| `Failed to load native binding` / SWC errors | Rebuild pui-app-sdk; reinstall workspace; Babel compiler addon is bundled via pui-cli |
-| “Using default Webpack5 setup” (no Babel)    | Refresh pnpm install after bumping `file:` pui-cli / pui-app-sdk links                |
-| API mocks missing                            | Delete middleware file; use `pui-cli storybook` (not legacy CLI)                      |
-| Stale app-sdk in monorepo                    | `pnpm install --ignore-scripts` after rebuilding linked packages                      |
+| Symptom                                                   | Fix                                                                                  |
+| --------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| `Cannot find module '…/storybook/cjs/main'`               | Migrate to `@elliemae/pui-app-sdk/storybook/main` in `main.mjs`                      |
+| `Cannot find module '…/dist/esm/utils/storybook/main.js'` | Run `pnpm run build` in app-sdk; or install published app-sdk alpha                  |
+| `getConfig is not a function`                             | Use named import **`getStorybookConfig`**, not `getConfig`                           |
+| `Can't resolve './app'` in lib-only package               | Use conditional globs in app-sdk or filter `config.stories` in `main.mjs`            |
+| `Class private methods are not enabled`                   | Upgrade pui-cli 9; remove duplicate Babel plugins from consumer Babel config         |
+| Babel cannot load `babel.config.ts`                       | Confirm Node 24; migrate from `babel.config.cjs` per `migrate-to-pui-cli-9` Phase 2b |
+| `Unable to index …stories.mdx`                            | Rename docs-only file to `.mdx`; fix `<Meta>` import                                 |
+| `Failed to load native binding` / SWC errors              | Reinstall deps; pui-cli uses Babel compiler addon, not SWC                           |
+| “Using default Webpack5 setup” (no Babel)                 | Refresh pnpm install after bumping pui-cli / pui-app-sdk                             |
+| API mocks missing                                         | Delete middleware file; use `pui-cli storybook` (not legacy CLI)                     |
+| Stale app-sdk in monorepo                                 | Rebuild linked app-sdk; `pnpm install` in consumer                                   |
 
 ## Reference repos
 
-- `pui-react-boilerplate` — app with `app/` stories
+- `pui-react-boilerplate` — app with `app/` stories; `.storybook/*.mjs` + package imports
 - `pui-mono-repo-boilerplate/libs/foo` — lib-only package
-- `pui-app-sdk/.storybook/` — dogfood ESM wrappers
+- `pui-app-sdk/.storybook/` — dogfood **`.storybook/*.ts`** with relative `../lib/utils/storybook/*` imports
 
 Full guide: [pui-cli 9 migration — Storybook 10](https://docs.pui.mortgagetech.q1.ice.com/cli/pui-cli-9-migration) (`docs/pui-cli-9-migration.md` in pui-cli).
 
@@ -186,3 +239,4 @@ Skills are copied to `.cursor/skills/`, `.claude/skills/`, and `.github/skills/`
 - Production Webpack build config — Storybook migration is dev/docs tooling only
 - Business logic in stories unless types or CSF3 require it
 - Do not re-add `@storybook/*` addon packages to consumer `package.json` unless pui-cli docs explicitly require an exception
+- Do not add private-method Babel plugins to consumer Babel config when using pui-cli 9 shared config

package/dist/esm/skills/migrate-to-pui-cli-9/SKILL.md

@@ -2,8 +2,9 @@
 name: migrate-to-pui-cli-9
 description: >-
   Migrate a PUI app or library to pui-cli 9 (Node 24, pnpm 11, ESLint 10 flat config, Stylelint 17,
-  Husky 9, Vitest 4, semantic-release 25, Lerna 9, Nx 22). Use when upgrading @elliemae/pui-cli,
-  migrating from .eslintrc.cjs to eslint.config.mjs, release.config.cjs to release.config.mjs,
+  Husky 9, Vitest 4, Jest 30, semantic-release 25, Lerna 9, Nx 22). Use when upgrading @elliemae/pui-cli,
+  migrating from .eslintrc.cjs to eslint.config.mjs, jest.config.cjs to jest.config.mjs, release.config.cjs to release.config.mjs,
+  babel.config.cjs to babel.config.ts, prettier.config.cjs / commitlint.config.cjs to .mjs subpath imports (pui-cli 9 is ESM-only),
   upgrading Husky 8 hooks, fixing Vitest 4 / coverage-v8 breakages, migrating monorepo nx.json from
   @nrwl/workspace to nx 22, moving shamefully-hoist from .npmrc to pnpm-workspace.yaml for pnpm 11,
   or adopting shared configs from pui-cli. App/library production builds stay on Webpack.
@@ -83,6 +84,52 @@ pnpm add -D @elliemae/pui-cli@9
 
 Re-run install and smoke-test build/test without ESLint changes yet if the bump is large.
 
+### Phase 2b — Babel config (`babel.config.ts`)
+
+pui-cli 9 requires Node 24, which natively loads TypeScript config files. Babel 7.28+ (shipped with pui-cli 9) supports **`babel.config.ts`** without extra loaders.
+
+1. Replace root `babel.config.cjs` with `babel.config.ts`:
+
+```typescript
+import { babelConfig } from '@elliemae/pui-cli';
+
+export default babelConfig;
+```
+
+2. Delete `babel.config.cjs`. Repeat for monorepo packages that have their own Babel file (for example `libs/foo/babel.config.cjs`).
+
+3. **Do not** add `@babel/plugin-transform-private-methods` or `@babel/plugin-transform-private-property-in-object` locally — pui-cli 9 includes them in shared `babelConfig` (Storybook and app-sdk private class syntax).
+
+4. Verify: `pnpm run build`; if the repo uses Storybook, `pnpm exec pui-cli storybook -b`.
+
+See migration guide section **2b. Migrate Babel config to TypeScript**.
+
+### Phase 2c — Prettier and Commitlint (`.mjs`)
+
+pui-cli 9 ships shared Prettier and Commitlint configs as ESM. Migrate root configs from `.cjs` to `.mjs` using subpath exports (same pattern as Stylelint and Jest).
+
+1. Replace `prettier.config.cjs` with `prettier.config.mjs`:
+
+```javascript
+import { prettierConfig } from '@elliemae/pui-cli/prettier';
+
+export default prettierConfig;
+```
+
+2. Replace `commitlint.config.cjs` with `commitlint.config.mjs`:
+
+```javascript
+import { commitlintConfig } from '@elliemae/pui-cli/commitlint';
+
+export default commitlintConfig;
+```
+
+3. Delete the old `.cjs` files. **`require('@elliemae/pui-cli')` is removed in pui-cli 9** — use ESM subpath imports only.
+
+4. Verify: `pnpm exec prettier --check .`; test a commit through Husky if commitlint is enabled.
+
+See migration guide section **2c. Migrate Prettier and Commitlint configs to ESM**.
+
 ### Phase 3 — ESLint 10 flat config
 
 **React apps and libraries:**
@@ -190,12 +237,43 @@ Reference hooks: [pui-cli/.husky](https://git.elliemae.io/platform-ui/pui-cli/tr
 
 ### Phase 6 — Stylelint 17 (if CSS / styled-components)
 
-1. Simplify `stylelint.config.cjs` — remove `stylelint-config-styled-components` workarounds.
-2. Optional ESM: `stylelint.config.mjs` importing `@elliemae/pui-cli/stylelint`.
-3. Run `pnpm exec pui-cli lint` (CSS pass).
+1. Simplify or migrate to `stylelint.config.mjs` importing `@elliemae/pui-cli/stylelint` — remove `stylelint-config-styled-components` workarounds.
+2. Run `pnpm exec pui-cli lint` (CSS pass).
 
 See [stylelint-migration.md](https://docs.pui.mortgagetech.q1.ice.com/cli/stylelint-migration) in pui-cli docs.
 
+### Phase 6b — Jest 30 (if using `pui-cli test`)
+
+Skip if the repo uses Vitest (`pui-cli vitest`) only.
+
+1. Replace `jest.config.cjs` with `jest.config.mjs`:
+
+```javascript
+import { jestConfig } from '@elliemae/pui-cli';
+
+delete jestConfig.moduleNameMapper['@elliemae/pui-diagnostics'];
+
+export default jestConfig;
+```
+
+Delete `jest.config.cjs` after creating `jest.config.mjs`.
+
+2. Align local Jest devDependencies with pui-cli 9:
+
+```bash
+pnpm add -D jest-cli@30 jest-environment-jsdom@30 @types/jest@30 jest-watch-typeahead@3
+```
+
+3. Search for deprecated matcher aliases (`toBeCalled`, `toReturn`, `toThrowError`, etc.) and update to canonical names (`toHaveBeenCalled`, `toHaveReturned`, `toThrow`). Use `eslint-plugin-jest` `no-alias-methods` autofix when available.
+
+4. Regenerate snapshots if needed: `pnpm exec pui-cli test --fix` or `jest -u`.
+
+5. Run `pnpm exec pui-cli test`.
+
+**Do not** replace `setupFiles` wholesale — spread pui-cli defaults when adding repo-specific setup. Remove any local `jest-textencoder-setup.cjs` (built into shared `jestConfig`).
+
+See migration guide section **Jest 30 (`pui-cli test`)**.
+
 ### Phase 7 — Vitest 4 (if using `pui-cli vitest`)
 
 Skip if the repo uses Jest (`pui-cli test`) only.
@@ -280,11 +358,12 @@ pnpm exec lerna --version # 9.x
    - Remove `tasksRunnerOptions`; move cacheable targets to `"cache": true` in `targetDefaults`
    - Optional: `pnpm exec nx migrate latest && pnpm exec nx migrate --run-migrations`
 
-4. Lerna 9: stop using `lerna bootstrap` / `lerna add` / `lerna link` — use pnpm workspaces. Keep existing `lerna.json` unless it referenced removed commands. `pui-cli version` unchanged.
+4. Lerna 9: stop using `lerna bootstrap` / `lerna add` / `lerna link` — use pnpm workspaces. Remove `"useWorkspaces": true` from `lerna.json` (Lerna 9 errors with `ECONFIGWORKSPACES` if present). Keep `"npmClient": "pnpm"` so Lerna reads `pnpm-workspace.yaml`. Optional: `pnpm exec lerna repair`. `pui-cli version` unchanged.
 
 5. Smoke-test:
 
 ```bash
+pnpm exec lerna list
 pnpm exec nx run-many --target=build --all --parallel
 pnpm exec nx affected --target=lint --uncommitted
 pnpm exec pui-cli lint
@@ -292,9 +371,9 @@ pnpm exec pui-cli lint
 
 See [pui-cli 9 migration guide](https://docs.pui.mortgagetech.q1.ice.com/cli/pui-cli-9-migration) — **Lerna 9 and Nx 22** section for the full `nx.json` template.
 
-### Phase 11 — Storybook 10 (out of CJS)
+### Phase 11 — Storybook 10 + latest pui-app-sdk
 
-Applies when the repo uses `pui-cli storybook`. Requires pui-cli 9 **and** a matching pui-app-sdk release.
+Applies when the repo uses `pui-cli storybook`. Requires pui-cli 9 **and** a matching **pui-app-sdk** release on the same train (`storybook/cjs/*` removed; shared config is TypeScript in app-sdk, consumed from **compiled dist**).
 
 Install the dedicated skill for agents:
 
@@ -302,12 +381,14 @@ Install the dedicated skill for agents:
 pnpm exec pui-cli skills install migrate-storybook-out-of-cjs --target all
 ```
 
-Follow **`migrate-storybook-out-of-cjs`** for the full CJS → ESM playbook (`storybook/cjs/*` removed; use `.storybook/main.mjs` + `getStorybookConfig()`). Summary:
+Follow **`migrate-storybook-out-of-cjs`** for the full CJS → ESM playbook. Summary:
 
-1. Bump `@elliemae/pui-app-sdk` with `@elliemae/pui-cli@9`.
-2. Replace `.storybook/main.js` with `.storybook/main.mjs` importing `@elliemae/pui-app-sdk/storybook/main`.
+1. Bump `@elliemae/pui-cli@9` and `@elliemae/pui-app-sdk@*` together; reinstall (rebuild app-sdk if using a `file:` link).
+2. Replace `.storybook/main.js` with `.storybook/main.mjs` importing **`getStorybookConfig`** from `@elliemae/pui-app-sdk/storybook/main` (not `getConfig` or `storybook/cjs/main`).
 3. Delete `.storybook/middleware.js`; migrate `preview` / `manager` / `theme` to `.mjs` when customized.
-4. Update stories to CSF3 where types fail; remove SB6 webpack alias workarounds unless still required.
+4. Rename docs-only **`*.stories.mdx`** → **`*.mdx`**; use `@storybook/addon-docs/blocks` for `<Meta>` (MDX3).
+5. Update stories to CSF3 where types fail; remove SB6 webpack alias workarounds unless still required.
+6. Migrate consumer **`babel.config.cjs` → `babel.config.ts`** (re-export pui-cli `babelConfig`) — see Phase 2b; **do not** duplicate private-method Babel plugins (pui-cli 9 includes them for Storybook).
 
 Verify:
 
@@ -317,10 +398,12 @@ pnpm exec pui-cli storybook -b
 pnpm exec pui-cli lint
 ```
 
-See [pui-cli 9 migration guide — Storybook 10](https://docs.pui.mortgagetech.q1.ice.com/cli/pui-cli-9-migration) for addon removals and troubleshooting.
+See [pui-cli 9 migration guide — Storybook 10](https://docs.pui.mortgagetech.q1.ice.com/cli/pui-cli-9-migration) for pui-app-sdk export changes, dist build requirement, and troubleshooting.
 
 ### Phase 10 — Verify
 
+- [ ] `babel.config.ts` re-exports pui-cli `babelConfig`; `babel.config.cjs` removed
+- [ ] `prettier.config.mjs` and `commitlint.config.mjs` import subpath exports; legacy `.cjs` removed
 - [ ] `shamefullyHoist` in `pnpm-workspace.yaml` (not `.npmrc`); `publicHoistPattern` not `[]` in `.modules.yaml`
 - [ ] `pnpm exec pui-cli lint` — 0 errors
 - [ ] `pnpm exec pui-cli tscheck --files`
@@ -332,30 +415,35 @@ See [pui-cli 9 migration guide — Storybook 10](https://docs.pui.mortgagetech.q
 
 ## Common lint fixes after upgrade
 
-| Symptom                                                     | Fix                                                                                                                                                                |
-| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `import-x/no-unresolved`                                    | Use `import type` for type-only imports                                                                                                                            |
-| `@typescript-eslint/no-explicit-any`                        | Type the value or add targeted override (warn) during transition                                                                                                   |
-| `@typescript-eslint/no-unused-vars`                         | Remove or prefix with `_`                                                                                                                                          |
-| Stale `eslint-disable` comments                             | Remove disables for rules no longer in config                                                                                                                      |
-| Test/fixture files flagged                                  | Shared config includes `lib/**/tests/**` globs — ensure pui-cli 9.0.0+                                                                                             |
-| `.d.ts` files                                               | pui-cli turns off `no-explicit-any` for `**/*.d.ts`                                                                                                                |
-| Cannot find module `vite` in tscheck                        | Set `moduleResolution: "bundler"` or extend pui-cli 9 tsconfig                                                                                                     |
-| Vitest `optimizer.web` unknown                              | Rename to `test.deps.optimizer.client` (Vitest 4)                                                                                                                  |
-| Coverage fails after upgrade                                | Remove `@vitest/coverage-c8`; use `@vitest/coverage-v8@4`                                                                                                          |
-| `release.config.cjs` extends fails                          | Migrate to `release.config.mjs`; requires semantic-release 22+ (pui-cli 9 ships 25)                                                                                |
-| `nx` fails after pui-cli 9 bump                             | Migrate `nx.json` off `@nrwl/*`; use `targetDefaults` not `targetDependencies`                                                                                     |
-| `lerna bootstrap` / `add` / `link`                          | Removed in lerna 9 — use `pnpm` workspaces and `pnpm add --filter`                                                                                                 |
-| Stale `@nrwl/workspace` in lockfile                         | Remove direct `@nrwl/*` pins; rely on pui-cli's `nx` + `@nx/workspace`                                                                                             |
-| `Can't resolve 'esbuild-loader'`                            | Move `shamefullyHoist: true` to `pnpm-workspace.yaml`; clean reinstall                                                                                             |
-| `Can't resolve 'styled-components'` / `@elliemae/pui-theme` | Same — hoisting ignored if still only in `.npmrc`                                                                                                                  |
-| `publicHoistPattern: []` in `.modules.yaml`                 | Migrate hoist settings from `.npmrc` to `pnpm-workspace.yaml`                                                                                                      |
-| `ERR_PNPM_IGNORED_BUILDS`                                   | Set real `allowBuilds` in `pnpm-workspace.yaml` or run `pnpm approve-builds`                                                                                       |
-| `husky: command not found` on prepare                       | `shamefullyHoist` + `publicHoistPattern: [husky]` or direct root `devDependency`                                                                                   |
-| Storybook fails after pui-cli 9 bump                        | Migrate `.storybook/main.js` → `main.mjs`; import `@elliemae/pui-app-sdk/storybook/main`                                                                           |
-| `Failed to load native binding` / SWC errors                | Ensure pui-app-sdk resolves Babel compiler from pui-cli; rebuild app-sdk and reinstall workspace deps                                                              |
-| `middleware.js` ignored / API mocks missing                 | Delete middleware file; pui-cli Storybook dev server loads routes automatically                                                                                    |
-| Jest `TextEncoder is not defined`                           | Built into pui-cli `jestConfig` — remove repo `jest-textencoder-setup.cjs`; keep `delete moduleNameMapper['@elliemae/pui-diagnostics']` only if using real package |
+| Symptom                                                     | Fix                                                                                                                                                                                               |
+| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `import-x/no-unresolved`                                    | Use `import type` for type-only imports                                                                                                                                                           |
+| `@typescript-eslint/no-explicit-any`                        | Type the value or add targeted override (warn) during transition                                                                                                                                  |
+| `@typescript-eslint/no-unused-vars`                         | Remove or prefix with `_`                                                                                                                                                                         |
+| Stale `eslint-disable` comments                             | Remove disables for rules no longer in config                                                                                                                                                     |
+| Test/fixture files flagged                                  | Shared config includes `lib/**/tests/**` globs — ensure pui-cli 9.0.0+                                                                                                                            |
+| `.d.ts` files                                               | pui-cli turns off `no-explicit-any` for `**/*.d.ts`                                                                                                                                               |
+| Cannot find module `vite` in tscheck                        | Set `moduleResolution: "bundler"` or extend pui-cli 9 tsconfig                                                                                                                                    |
+| Vitest `optimizer.web` unknown                              | Rename to `test.deps.optimizer.client` (Vitest 4)                                                                                                                                                 |
+| Coverage fails after upgrade                                | Remove `@vitest/coverage-c8`; use `@vitest/coverage-v8@4`                                                                                                                                         |
+| `release.config.cjs` extends fails                          | Migrate to `release.config.mjs`; requires semantic-release 22+ (pui-cli 9 ships 25)                                                                                                               |
+| `nx` fails after pui-cli 9 bump                             | Migrate `nx.json` off `@nrwl/*`; use `targetDefaults` not `targetDependencies`                                                                                                                    |
+| `lerna bootstrap` / `add` / `link`                          | Removed in lerna 9 — use `pnpm` workspaces and `pnpm add --filter`                                                                                                                                |
+| `ECONFIGWORKSPACES` / `useWorkspaces` has been removed      | Delete `"useWorkspaces": true` from `lerna.json`; keep `"npmClient": "pnpm"`; run `pnpm exec lerna list` to verify                                                                                |
+| Stale `@nrwl/workspace` in lockfile                         | Remove direct `@nrwl/*` pins; rely on pui-cli's `nx` + `@nx/workspace`                                                                                                                            |
+| `Can't resolve 'esbuild-loader'`                            | Move `shamefullyHoist: true` to `pnpm-workspace.yaml`; clean reinstall                                                                                                                            |
+| `Can't resolve 'styled-components'` / `@elliemae/pui-theme` | Same — hoisting ignored if still only in `.npmrc`                                                                                                                                                 |
+| `publicHoistPattern: []` in `.modules.yaml`                 | Migrate hoist settings from `.npmrc` to `pnpm-workspace.yaml`                                                                                                                                     |
+| `ERR_PNPM_IGNORED_BUILDS`                                   | Set real `allowBuilds` in `pnpm-workspace.yaml` or run `pnpm approve-builds`                                                                                                                      |
+| `husky: command not found` on prepare                       | `shamefullyHoist` + `publicHoistPattern: [husky]` or direct root `devDependency`                                                                                                                  |
+| Storybook fails after pui-cli 9 bump                        | Migrate `.storybook/main.js` → `main.mjs`; import `getStorybookConfig` from `@elliemae/pui-app-sdk/storybook/main`; build app-sdk if using `file:` link                                           |
+| `Class private methods are not enabled` (Storybook build)   | Upgrade pui-cli 9 (private-method Babel plugins in shared `babelConfig`); remove duplicate plugins from consumer Babel config                                                                     |
+| Babel cannot load `babel.config.ts`                         | Confirm Node 24 (`.node-version`, CI); pui-cli 9 requires Node 24 for native TS config loading                                                                                                    |
+| `Failed to load native binding` / SWC errors                | pui-cli removes SWC from Storybook webpack; reinstall deps; Babel compiler addon uses pui-cli `babelConfig`                                                                                       |
+| `middleware.js` ignored / API mocks missing                 | Delete middleware file; pui-cli Storybook dev server loads routes automatically                                                                                                                   |
+| Jest `TextEncoder is not defined`                           | Built into pui-cli `jestConfig` — remove repo `jest-textencoder-setup.cjs`; keep `delete moduleNameMapper['@elliemae/pui-diagnostics']` only if using real package                                |
+| `require('@elliemae/pui-cli')` fails / `ERR_REQUIRE_ESM`    | pui-cli 9 is ESM-only — migrate configs to `.mjs`/`.ts` and use subpath imports (`@elliemae/pui-cli/eslint`, `/prettier`, `/jest`, etc.)                                                          |
+| Jest fails after pui-cli 9 bump                             | Migrate `jest.config.cjs` → `jest.config.mjs`; align `jest-cli@30`, `jest-environment-jsdom@30`, `@types/jest@30`, `jest-watch-typeahead@3`; fix deprecated matcher aliases; regenerate snapshots |
 
 Full rule comparison: [eslint-rules-migration.md](https://docs.pui.mortgagetech.q1.ice.com/cli/eslint-rules-migration) (also at `docs/eslint-rules-migration.md` in pui-cli).
 
@@ -373,7 +461,7 @@ Skills are copied to `.cursor/skills/`, `.claude/skills/`, and `.github/skills/`
 
 - Application business logic — migration is tooling/config only
 - Webpack/babel production build config — pui-cli 9 does not migrate apps to Vite for bundling
-- Prettier / commitlint configs unless pui-cli 9 bumps those presets
+- Prettier / commitlint preset values — migrate config **format** to `.mjs` when touching those files; do not change shared rule/preset content unless pui-cli 9 bumps them
 - **Org hoisting policy** — keep `shamefullyHoist: true`; do not remove hoisting or duplicate webpack deps in root `package.json` as a workaround
 
 ## Additional resources

package/dist/esm/testing/{jest.config.cjs → jest.config.mjs}

@@ -1,15 +1,19 @@
-const path = require('path');
-const normalizePath = require('normalize-path');
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import normalizePath from 'normalize-path';
+
+const require = createRequire(import.meta.url);
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
 const { getAppConfig, basePath } = require('../utils.cjs');
 const { swcrcConfig } = require('../transpile/swcrc.config.cjs');
 const { findMonoRepoRoot } = require('../monorepo/utils.cjs');
 
 let isReactModule = true;
 try {
-   
   require('react');
   require('styled-components');
-   
 } catch {
   isReactModule = false;
 }
@@ -117,4 +121,4 @@ if (isReactModule && jestConfig.setupFilesAfterEnv)
     path.resolve(__dirname, './setup-react-env.js'),
   );
 
-exports.jestConfig = jestConfig;
+export { jestConfig };

package/dist/{cjs/testing/jest.node.config.cjs → esm/testing/jest.node.config.mjs}

@@ -1,5 +1,6 @@
-const { jestConfig } = require('./jest.config.cjs');
-exports.jestNodeConfig = {
+import { jestConfig } from './jest.config.mjs';
+
+export const jestNodeConfig = {
   ...jestConfig,
   testEnvironment: 'node',
   transformIgnorePatterns: [],

package/dist/types/lib/babel.config.d.ts

@@ -0,0 +1,3 @@
+import type { TransformOptions } from '@babel/core';
+export declare const babelConfig: TransformOptions;
+export default babelConfig;

package/dist/types/lib/index.d.ts

@@ -1,16 +1,12 @@
 export type LIB_NAME = 'pui-cli';
-export { babelConfig } from './babel.config.cjs';
+export { babelConfig } from './babel.config.js';
 export { eslintFlatBaseConfig, eslintFlatBaseConfigStrict, } from './lint-config/eslint/flat/non-react-export.mjs';
 export { eslintFlatConfig, eslintFlatConfigStrict, } from './lint-config/eslint/flat/react-export.mjs';
-/** @deprecated Use eslintFlatBaseConfig in eslint.config.mjs */
-export { esConfig as eslintBaseConfig } from './lint-config/eslint/non-react.cjs';
-/** @deprecated Use eslintFlatConfig in eslint.config.mjs */
-export { esReactConfig as eslintConfig } from './lint-config/eslint/react.cjs';
 export { stylelintConfig } from './lint-config/stylelint/export.mjs';
-export { prettierConfig } from './lint-config/prettier.config.cjs';
-export { commitlintConfig } from './lint-config/commitlint.config.cjs';
-export { jestConfig } from './testing/jest.config.cjs';
+export { prettierConfig } from './lint-config/prettier.config.mjs';
+export { commitlintConfig } from './lint-config/commitlint.config.mjs';
+export { jestConfig } from './testing/jest.config.mjs';
 export { vitestConfig } from './testing/vitest.config.js';
-export { jestNodeConfig } from './testing/jest.node.config.cjs';
+export { jestNodeConfig } from './testing/jest.node.config.mjs';
 export { lintStagedConfig } from './lint-config/lint-staged.config.js';
 export { loadRoutes } from './server/appRoutes.js';

package/dist/types/lib/lint-config/commitlint/export.d.mts

@@ -0,0 +1 @@
+export { commitlintConfig, default } from "../commitlint.config.mjs";

package/dist/types/lib/lint-config/commitlint.config.d.mts

@@ -0,0 +1,3 @@
+/** @type {import('@commitlint/types').UserConfig} */
+export const commitlintConfig: import("@commitlint/types").UserConfig;
+export default commitlintConfig;

package/dist/types/lib/lint-config/eslint/common.d.cts

@@ -40,7 +40,14 @@ export namespace baseConfig {
 }
 export const basePlugins: string[];
 export const baseRules: {
-    "prettier/prettier": (string | typeof prettierOptions)[];
+    "prettier/prettier": (string | {
+        printWidth: number;
+        tabWidth: number;
+        useTabs: boolean;
+        semi: boolean;
+        singleQuote: boolean;
+        trailingComma: string;
+    })[];
     "arrow-body-style": (string | number)[];
     "class-methods-use-this": number;
     "import/imports-first": number;
@@ -127,4 +134,3 @@ export const reactRules: {
     "redux-saga/no-yield-in-race": number;
     "redux-saga/yield-effects": number;
 };
-import prettierOptions = require("../prettier.config.cjs");

package/dist/types/lib/lint-config/eslint/non-react.d.cts

@@ -1,7 +1,14 @@
 export const esConfig: {
     extends: string[];
     rules: {
-        "prettier/prettier": (string | typeof import("../prettier.config.cjs"))[];
+        "prettier/prettier": (string | {
+            printWidth: number;
+            tabWidth: number;
+            useTabs: boolean;
+            semi: boolean;
+            singleQuote: boolean;
+            trailingComma: string;
+        })[];
         "arrow-body-style": (string | number)[];
         "class-methods-use-this": number;
         "import/imports-first": number;

package/dist/types/lib/lint-config/eslint/react.d.cts

@@ -31,7 +31,14 @@ export const esReactConfig: {
         })[];
         "redux-saga/no-yield-in-race": number;
         "redux-saga/yield-effects": number;
-        "prettier/prettier": (string | typeof import("../prettier.config.cjs"))[];
+        "prettier/prettier": (string | {
+            printWidth: number;
+            tabWidth: number;
+            useTabs: boolean;
+            semi: boolean;
+            singleQuote: boolean;
+            trailingComma: string;
+        })[];
         "arrow-body-style": (string | number)[];
         "class-methods-use-this": number;
         "import/imports-first": number;