vitest-migration

---
name: vitest-migration
description: Migrate an Nx repo package's unit tests from Jest to Vitest, reusing the shared setup that packages/workspace established. Use when asked to "move <pkg> to vitest", "migrate <pkg> tests off jest", or "run <pkg> unit tests with vitest".
allowed-tools: Read, Glob, Grep, Agent, Edit(*), Write(*), Bash(pnpm nx *), Bash(npx nx *), Bash(nx *), Bash(git *), Bash(ls *), Bash(cat *), Bash(head *), Bash(tail *), Bash(sed *), Bash(grep *), Bash(rg *), Bash(find *), Bash(wc *), Bash(echo *), Bash(mkdir *), Bash(rm *), Bash(mv *), Bash(node *), Bash(npx oxfmt *), Bash(gh pr view *), Bash(gh pr diff *)
---

# Migrate a package's unit tests to Vitest

Move `packages/<name>`'s unit tests from Jest to Vitest 4, inferred through the
`@nx/vitest` plugin.

**Start from `packages/workspace`, not `packages/nx`.** The shared machinery a
sibling package needs already exists — read these first and reuse them as-is:

- `tools/vitest/setup.mts` — the port of `scripts/unit-test-setup.js`; every
  migrated package loads it as its `setupFiles`
- `tools/vitest/nx-source-resolver.mts` — resolves `nx` / `@nx/*` to this
  repo's source, for both vite and node
- `tools/vitest/tsconfig.json` — a leaf tsconfig whose only job is to stop
  vite's tsconfig lookup. **Do not move these files to the workspace root.**
  With no tsconfig beside them, the nearest one is the root solution file, and
  vite walks its `references` — reading all ~114 project tsconfigs on every
  run, which lands as a sandbox violation. `tools/vitest` is deliberately a
  plain directory, not an Nx project: adding `project.json` makes
  `@nx/js:typescript-sync` demand a project reference to a test-only tool from
  each consuming package's _published_ `tsconfig.lib.json` (`composite: false`
  does not suppress it)
- `packages/workspace/vitest.config.mts` — the config those two plug into
- `packages/workspace/project.json` — `test.inputs` naming the shared scripts

`packages/nx` (PR #36754, commit `32dd3fb533`) is the _original_ migration but a
poor template: it is the one package that imports almost no siblings, so it
needs neither the source resolver nor the CJS-channel mocks. Consult it only for
`vitest-write-guard.cjs` and `src/internal-testing-utils/cjs-mock.ts`.
`packages/angular-rspack/vitest.config.mts` is the simple end of the spectrum
(no nx source at all).

## Argument

The package name (e.g. `js`, `devkit`, `workspace`). The package lives at
`packages/<name>/`.

## Why this is not a find-and-replace

Jest and Vitest disagree on module semantics, not just API names. The
mechanical `jest.*` → `vi.*` rename is maybe 80% of the diff and 20% of the
work. The rest is: which _channel_ a mock reaches (ESM graph vs CJS
`require()`), whether a namespace is frozen, and what `resetAllMocks` does to a
spy. Budget for hand-fixing specs after the codemod.

---

## Step 0 — Survey the package

Run these and write the answers into `tmp/notes/vitest-migration-<name>.md`
before touching anything:

```bash
ls packages/<name>/jest.config.cts packages/<name>/jest*.js 2>/dev/null
cat packages/<name>/jest.config.cts
cat packages/<name>/tsconfig.spec.json
grep -rl "\.spec\.ts" -c packages/<name>/src | wc -l   # rough spec count
pnpm nx show project <name> --json | head -40
```

Capture:

1. **Spec count and current runtime.** Run `pnpm nx test <name> --skip-nx-cache`
   once and record the reported test count and wall time. That number is the
   parity target in Step 6 — you cannot verify the migration without it.
2. **Jest config specials** — anything beyond `displayName`/`preset`/
   `moduleFileExtensions` is behavior you must reproduce:
   - `setupFiles` (e.g. `packages/devkit/jest-setup-nx-workspace-data-dir.js`)
   - `moduleNameMapper` (path shims; also `identity-obj-proxy` for CSS)
   - `testEnvironment: 'jsdom'` → needs `environment: 'jsdom'` and the
     `jsdom` dep
   - `modulePathIgnorePatterns` / `testPathIgnorePatterns` → `exclude`
   - `resolver` → `resolve.conditions` (see Step 2)
3. **Inherited preset behavior** (`jest.preset.js`) that Vitest does _not_ get
   for free:
   - `setupFiles: ['../../scripts/unit-test-setup.js']` — the workspace-wide
     project-graph / workspace-context / native guards. **This must be ported**
     (Step 3).
   - `resolver: '../../scripts/patched-jest-resolver.js'` — maps `@nx/*` and
     `nx/*` onto `packages/*` source, **and** sets
     `NX_WORKSPACE_ROOT_PATH=<repo>/tmp/unit` as a side effect. Both are
     reproduced by the shared scripts (Steps 2 and 3).
   - `moduleNameMapper` ESM shims (`@clack/prompts`, `ora`, `chalk`,
     `yargs-parser`, `prettier`, `magic-string`, `oxfmt`). Most are pure ESM
     interop Vitest does not need — but check each for _behavior_ before
     dropping it. `@clack/prompts` is load-bearing: the stub answers `undefined`
     where the real library drives a **synchronous** prompt, and a generator
     that asks a question blocks the worker forever with no test timeout.
     `tools/vitest/setup.mts` already keeps that one. `prettier`'s stub also
     pins `resolveConfig: () => null`, which matters if the package snapshots
     formatted output.
   - `maxWorkers: 1` — Vitest runs files in parallel. Any spec relying on
     cross-file ordering or a shared mutable temp dir will now fail. This is
     the main source of "it passed under jest" flakes.
4. **Native bindings** — does the package load `nx/src/native` or a `.node`
   file? If yes you need `pool: 'forks'` and the native shim plugin from
   `packages/nx/vitest.config.mts`.
5. **Lazy `require()` of TS source** — `grep -rn "require(" packages/<name>/src
   --include=*.ts | grep -v "^.*spec"`. Every bare `require()` of a local `.ts`
   file needs `@swc-node/register` (Step 2) and can only be mocked through
   `mockCjsModule` (Step 4).

---

## Step 1 — Target inference

`@nx/vitest` is already registered in `nx.json` for `packages/**/*`, so a
`vitest.config.mts` at the package root is enough to infer `<name>:test`.
Verify the plugin block still reads:

```json
{
  "plugin": "@nx/vitest",
  "options": { "testTargetName": "test" },
  "include": ["packages/**/*"],
  "exclude": ["**/out-tsc/**"]
}
```

`@nx/jest` infers `test` from `jest.config.*` presence. **Both plugins would
claim `test`**, so `jest.config.cts` must be deleted in the same change, not
left behind "just in case". Also delete any `jest-resolver.js` and drop
`project.json` target overrides that reference jest inputs (see the
`packages/nx` diff — a `"test": { "inputs": [..., "patched-jest-resolver.js"] }`
block was removed).

---

## Step 2 — Write `packages/<name>/vitest.config.mts`

Start from `packages/nx/vitest.config.mts` and keep only what the survey
justified. The load-bearing pieces and why:

```ts
export default defineConfig({
  root: import.meta.dirname,
  cacheDir: '../../node_modules/.vite/<name>/unit',
  test: {
    watch: false,
    globals: true, // specs use bare describe/it/expect/vi
    environment: 'node', // or 'jsdom' if the jest config said so
    include: ['**/*.spec.ts'],
    exclude: ['**/node_modules/**'],
    setupFiles: ['./vitest.setup.mts'],
    testTimeout: 35000, // matches jest.preset.js
    pool: 'forks', // ONLY if native .node bindings are loaded;
    // they are not thread-safe across workers
    teardownTimeout: 60_000, // specs holding native contexts exit slowly;
    // the jest setup hid this behind --forceExit
    execArgv: ['--conditions=@nx/nx-source'],
    server: { deps: { external: [/\.node$/] } },
  },
  resolve: {
    conditions: ['@nx/nx-source'],
  },
  plugins: [nxSourceResolver()], // tools/vitest/nx-source-resolver.mts
});
```

Rules for resolution — the part that most looks solved and isn't:

- **`conditions: ['@nx/nx-source']` does NOT replace the jest resolver.**
  `node_modules/nx` and `node_modules/@nx/*` are the _published_ tarballs (dist
  only, no source), and their exports maps advertise `@nx/nx-source` entries
  pointing at `./src/index.ts` files the tarball does not ship — so the
  condition resolves to a file that isn't there. Use `nxSourceResolver()` from
  `tools/vitest/nx-source-resolver.mts`, which maps `nx` / `@nx/*` through
  the _local_ `packages/<pkg>/package.json`, with a file fallback for deep
  imports no exports entry covers (`@nx/workspace/src/...`).
- **`execArgv: ['--conditions=@nx/nx-source']` on its own actively breaks node
  resolution**, for the same reason: a lazy `require('@nx/js')` dies with
  `Cannot find module '.../node_modules/@nx/js/src/index.ts'`. Keep the flag,
  but `tools/vitest/setup.mts` must also patch `Module._resolveFilename`
  with the same mapping so both channels agree.
- **Aliases use regex, not strings.** Vite string aliases do prefix matching,
  so `'@nx/devkit'` would rewrite `@nx/devkit/internal` too. Use
  `{ find: /^@nx\/devkit$/, replacement: ... }`.
- `packages/nx` predates the shared resolver and hard-codes `nx/src/*` and
  `nx/bin/*` aliases instead. Don't copy that — the resolver covers it.
- If the package imports `yargs` with CJS-namespace style
  (`yargs.terminalWidth()`), alias it to `node_modules/yargs/index.cjs`.
- If the package loads `nx/src/native`, copy the `nx-native-shim` plugin
  verbatim — `src/native/index.js` requires TS files and cannot run outside a
  transform, so it must be routed to the generated `native-bindings.js` and
  externalized.

---

## Step 3 — Wire up the shared setup

Point the config at the shared file; do not write a per-package copy:

```ts
setupFiles: ['../../tools/vitest/setup.mts'],
```

`tools/vitest/setup.mts` is the port of `scripts/unit-test-setup.js` (which
is jest-only — `jest.doMock` — so it can never be imported from vitest). Read
it before assuming anything is missing; it already does all of the following,
and each line is there because its absence broke `packages/workspace`:

- `NX_DAEMON=false`, `npm_config_user_agent` deleted, `FORCE_COLOR` deleted and
  `NO_COLOR=1` (snapshots are recorded colorless).
- `NX_WORKSPACE_ROOT_PATH` under `tmp/unit/<pid>` — **per worker process**,
  unlike jest. The jest resolver set a single `tmp/unit` as a side effect;
  with vitest's parallel workers one shared root makes every worker queue on
  the same lock ("Waiting for graph construction in another process to
  complete", 35s timeouts).
- `NX_ISOLATE_PLUGINS=false`. Otherwise plugin isolation spawns a worker
  subprocess per plugin that is never torn down, and the spec file stalls to
  its timeout. Two `packages/nx` specs already carry this same note.
- `@swc-node/register`, with `Error.prepareStackTrace` **restored immediately
  after**: the hook installs source-map-support, which mis-maps
  vite-transformed frames and breaks error locations _and_ inline-snapshot
  updates.
- `Module._resolveFilename` patched with the source mapping (Step 2), plus
  `@clack/prompts` → `scripts/jest-mocks/clack-prompts.js`.
- `vi.doMock` graph/workspace-context/native guards, keyed by **absolute
  physical path** — mocking the `nx/src/...` specifier routes through the pnpm
  symlink and keys as a different module, so the mock silently never applies.
- **The same graph mocks again, on the CJS channel**, via a `Module._load`
  patch. This is the one most easily missed and the most expensive to debug:
  generators reach graph builders through lazy `require()`, which `vi.mock`
  cannot see, and the unmocked `createProjectGraphAsync` takes
  `project-graph.lock` and **deadlocks the worker** — no output, and no test
  timeout fires, because the main thread is blocked in a futex.
- Pass-through helpers are plain functions, not `vi.fn()`, so a suite's
  `vi.resetAllMocks()` cannot wipe them into `() => undefined`.

Add to the shared file (not a package-local one) if the package needs a guard
nothing else does, and say so in the PR — every migrated package loads it.

Two more rules:

1. **Do not alias a `jest` global in the setup.** A stray `jest.mock` would not
   be hoisted by vitest's transform and would silently fail to intercept. Let
   it throw.
2. If the package's specs can write repo files, copy
   `packages/nx/vitest-write-guard.cjs` and load it through
   `execArgv: ['--require', ...]`. It must be `execArgv`, not `setupFiles`:
   node snapshots a module's ESM named exports on first import, so a patch
   applied from a setup file is invisible to `import { writeFile } from 'fs'`.
   (The `packages/nx` migration found a spec that had been overwriting the
   repo's real `nx.json`.)

Finally, name the shared files in the package's `project.json` so the cache
sees them — they live outside `{projectRoot}`, so nothing else invalidates on
an edit:

```json
"test": {
  "inputs": [
    "...",
    "{workspaceRoot}/tools/vitest/**/*",
    "{workspaceRoot}/scripts/jest-mocks/clack-prompts.js"
  ]
}
```

These are not optional bookkeeping. `@nx/vitest` infers `setup.mts` and its
tsconfig (nx#36920), but nothing infers the resolver the config imports or the
clack mock the setup loads by path — `default` is project-scoped — so leaving
them off does not fail loudly; it serves a **stale cache hit** the next time
someone edits them. Keep the whole `tools/vitest/**/*` glob rather than naming
the resolver alone, so a helper added there later is covered too.

---

## Step 4 — `tsconfig.spec.json`

```jsonc
{
  "compilerOptions": {
    "types": ["vitest/globals", "node"], // was ["jest", "node"]
  },
  "include": [
    // ...
    "vitest.config.mts", // replaces "jest.config.ts"
    "vitest.setup.mts",
  ],
}
```

Drop `@types/jest` from the package's `devDependencies` only if no other
project in the repo still needs it there.

---

## Step 5 — Codemod the specs

Apply mechanically, then hand-fix. Prefer one script over 200 manual edits, and
commit the codemod pass separately from the hand fixes so review can follow.

Two rules before you run anything:

- **Never codemod the whole package blindly.** Some files contain `jest.*` in
  _strings_, not calls — a spec for a codemod that rewrites `jest.mock(...)`
  text, generator specs asserting on `jest.config.cts` contents, or
  `'@nx/jest:jest'` executor names. Build the file list from a grep for real
  API usage (`grep -l 'jest\.[a-z]' | grep -v` the string-only ones) and
  eyeball it.
- **Match across newlines.** `jest\n  .fn()` and `jest\n  .spyOn(...)` are
  common in this repo and a line-based `s/jest\.fn(/vi.fn(/` silently misses
  them, leaving `ReferenceError: jest is not defined` at collection. Use
  `perl -0p` (or equivalent) and re-grep for a bare `\bjest\b` afterwards.

| Jest                                                                                                                                                         | Vitest                                           | Note                                                                                       |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| `jest.fn` / `jest.spyOn` / `jest.mock` / `jest.doMock` / `jest.unmock` / `jest.clearAllMocks` / `jest.restoreAllMocks` / `jest.resetModules` / `jest.mocked` | same with `vi.`                                  | pure rename                                                                                |
| `jest.requireActual<T>(x)`                                                                                                                                   | `await vi.importActual<T>(x)`                    | factory must become `async`                                                                |
| `jest.requireMock(x)`                                                                                                                                        | `await vi.importMock(x)`                         | factory must become `async`                                                                |
| `jest.isolateModules(() => { require(x) })`                                                                                                                  | `vi.resetModules()` + `await import(x)`          | for CJS-loaded modules use `delete cjsRequire.cache[cjsRequire.resolve(x)]; cjsRequire(x)` |
| `jest.isolateModulesAsync(async () => …)`                                                                                                                    | `vi.resetModules()` then fresh `await import()`s |                                                                                            |
| `jest.Mock`                                                                                                                                                  | `import type { Mock } from 'vitest'`             | type-only import                                                                           |
| `jest.SpyInstance`                                                                                                                                           | `import type { MockInstance } from 'vitest'`     | type-only import                                                                           |
| `jest.MockedFunction`                                                                                                                                        | `import type { MockedFunction } from 'vitest'`   | type-only import                                                                           |
| `it('x', (done) => …)`                                                                                                                                       | return a promise                                 | Vitest has no `done` callback                                                              |
| `xdescribe` / `xit`                                                                                                                                          | `describe.skip` / `it.skip`                      | not defined in Vitest                                                                      |
| `import { jest } from '@jest/globals'`                                                                                                                       | delete                                           | `vi` is global with `globals: true`                                                        |

Hoisting is real in Vitest: `vi.mock` calls are lifted to the top of the file,
above imports _and_ above any `const` the factory closes over. Anything a
factory needs must go through `vi.hoisted(() => …)`.

---

## Step 6 — Hand-fix the semantic gaps

This is where the time goes. The catalogue, from the `packages/nx` migration:

**Frozen ESM namespaces.** `vi.spyOn(semverNamespace, 'gt')` throws on a
node builtin or an external ESM package — the namespace object is frozen.
Mock at the module level in spy mode, which keeps the real implementations
until a test overrides one:

```ts
vi.mock('semver', { spy: true });
vi.mock('child_process', { spy: true });
```

**Modules the source loads with bare `require()`.** `vi.mock` never sees that
channel. Use the helper (add it if the package does not have one — it lives in
`packages/nx/src/internal-testing-utils/cjs-mock.ts` and patches
`Module._load`):

```ts
import { mockCjsModule } from '<path>/internal-testing-utils/cjs-mock';
mockCjsModule(import.meta.url, './run', { runCommand: vi.fn() });
```

Registrations are per-file (Vitest forks per file), but a swap made for a
single test must be undone with `unmockCjsModule` / `resetCjsMocks` or it leaks
into later tests in the same file.

**Class mocks must be constructible.** `vi.fn()` returning an object is not
`new`-able the way jest's auto-mock was. Return a real function with a
`prototype`, as `GuardedWorkspaceContext` does in `vitest.setup.mts`.

**`vi.resetAllMocks()` restores a spy's real implementation** rather than
leaving `() => undefined` like jest. Specs that relied on the jest behavior
(expecting `undefined` after a reset) need explicit `mockReturnValue(undefined)`.

**Setup-file mocks must not use `vi.fn()` for pass-through helpers.** A spec
calling `vi.resetAllMocks()` would wipe the implementation and surface as
"is not iterable" downstream. Use plain functions, as the workspace-context
mock does.

**Hooks that must not return a mock.** `beforeEach(() => vi.fn())` — Vitest
treats a returned function as a teardown callback. Make the body a block.

**Parallelism.** With `maxWorkers: 1` gone, two spec files sharing a temp dir,
a `process.chdir`, or a module-level singleton will now collide. Fix by giving
each file its own `TempFs` root; reach for `test.sequential`/`isolate: false`
only after proving the collision is not the spec's own bug.

**A spec that hangs with no output and no timeout.** The test timeout cannot
fire, because the worker's main thread is blocked in a futex — so the usual
"which test is slow" reflexes give you nothing. Diagnose it from the outside:

```bash
p=$(pgrep -f "workers/forks" | head -1)
cat /proc/$p/wchan                      # futex_do_wait == blocked, not busy
ps -o pcpu= -p $p                       # ~0% confirms it is not just slow
ls -l /proc/$p/fd | grep -v socket      # the lock file it is stuck on
pgrep -aP $p                            # a spawned worker/install it waits for
```

In `packages/workspace` this was `project-graph.lock`: real graph construction
running on the CJS channel. The three causes seen so far are all handled by
`tools/vitest/setup.mts` — CJS graph mocks, `NX_ISOLATE_PLUGINS=false`, and
the `@clack/prompts` stub — so first check the setup is actually loaded before
hunting further.

**Watch for latent test bugs.** Both spec bugs the `packages/nx` migration
uncovered were assertions that passed while the mock never applied. If a spec
starts failing after the mock finally lands, the _test_ was wrong — fix the
expectation, do not paper over it by restoring the broken mock.

---

## Step 7 — Snapshots

Vitest joins describe and test names with `>` where jest used a space, so
**every** existing key reads as new: a plain run appends a full second copy of
the file and leaves the jest entries orphaned. Regenerate from a pristine tree
so `-u` also drops the old keys:

```bash
git checkout -- 'packages/<name>/**/__snapshots__/*.snap'
cp -r <snapshots> tmp/snapshot-baseline/          # keep the jest originals
pnpm nx test <name> --skip-nx-cache -- -u
```

Then prove the _values_ did not move: parse both sides into `{key: value}`,
normalize the separator (`' > '` → `' '`), and diff. Key counts and every value
must match — that is the real parity check, not the pass/fail.

`toThrowErrorMatchingInlineSnapshot` is the known exception: vitest records
`[Error: msg]` where jest recorded `"msg"`. Same message, different serializer.

Vitest's serializer differs from Jest's elsewhere too. Regenerate, then **read the diff**:

```bash
pnpm nx test <name> --skip-nx-cache -- -u
git diff --stat -- 'packages/<name>/**/__snapshots__/*'
```

Snapshot churn should be formatting only (quoting, indentation, `Object {` →
`{`). Any change in _content_ is a real behavior difference — investigate it
before accepting. Colorless output is guaranteed by the `NO_COLOR` pin in the
setup file; if you see ANSI codes land in a snapshot, that pin is missing.

---

## Step 8 — Verify

```bash
# same test count as Step 0, and it should be dramatically faster
pnpm nx test <name> --skip-nx-cache

# parallel-safety: repeat runs must be stable, not just green once
pnpm nx test <name> --skip-nx-cache
pnpm nx test <name> --skip-nx-cache

# a single file still works (paths relative to the package root)
pnpm nx run <name>:test -- src/utils/some-file.spec.ts

# nothing else broke - EVERY target the project has, not a set you picked
pnpm nx show project <name> --json | jq '.targets | keys'
pnpm nx run-many -t test,build,lint,oxlint -p <name> --skip-nx-cache
pnpm nx sync:check
```

**`oxlint` is a separate target from `lint`.** Running `test,build,lint` and
calling it green is how a restricted-import error reaches CI: this repo bans
`nx/src/...` imports in favour of `@nx/devkit/internal*`, and only `oxlint`
catches it. Read the target list rather than assuming the usual three.

Parity is **test count**, not just a green run. A dropped `include` pattern or
a silently-skipped directory shows up as a lower count, and a green suite hides
it. If the count differs, find every missing file before proceeding.

Note the caching caveat: after a mechanical sweep, `nx affected` can replay a
stale cached pass. Always validate with `--skip-nx-cache`.

Do **not** run a full `nx affected`: a new or moved file under a workspace-root
directory marks all ~90 projects affected, which is hours of jest for changes
that touch nothing jest reads. Run one still-on-jest package as a canary
instead — `devkit` is the most entangled.

---

## Step 8b — Sandbox violations

The migration is not done when CI is green. Nx Cloud reports the task's file
reads against its declared inputs, and a vitest suite reads things the jest one
did not. Fetch them once the PR has run:

```bash
npx nx-cloud get sandbox-reports --branch <PR-number> --since 1d
npx nx-cloud validate sandbox-violations \
  .nx/workspace-data/sandbox-reports/<PR-number>/index.json --json
```

`nx reset` deletes `.nx/workspace-data`, and the downloaded reports with it —
re-download after one.

The per-task JSON carries `processTree` plus a `pid` on every read, which is
how you attribute a violation instead of guessing. Map them:

```python
tree = {p['pid']: p for p in report['processTree']}
for r in report['unexpectedReads']:
    print(r['path'], tree.get(r['pid'], {}).get('cmd'))
```

The two this migration produced, both worth checking for:

- **Every project's `tsconfig.json`, read by the vitest main process.** The
  timestamps show the root solution tsconfig read milliseconds after a
  workspace-root source file. Cause and fix are in the Step 3 note about where
  the shared setup lives. Confirm with the resolver vite itself uses rather
  than a filesystem tracer — `tsconfck`'s `parse()` reports what it consulted,
  and a tracer on `fs` misses it because the ESM `node:fs/promises` bindings
  are snapshotted before a `--require` preload can patch them:

  ```js
  const { parse } =
    await import('<repo>/node_modules/.pnpm/tsconfck@*/node_modules/tsconfck/src/index.js');
  console.log((await parse('tools/vitest/setup.mts')).referenced?.length); // 0 == leaf, 114 == solution root
  ```

- **The repo's `.editorconfig`, read by a worker.** `formatFiles` resolves
  prettier config from disk at `tree.root`, and a spec that points
  `tree.root` into the repo (e.g. `process.cwd()`) picks it up; the jest
  prettier shim pinned `resolveConfig: () => null` and hid it. Give that spec a
  `TempFs` root instead of declaring the file as an input.

Prefer declaring an input over excluding a path: an over-broad input costs
cache misses, an over-broad exclusion buys wrong cache hits. But a violation
that only exists because a file sits in the wrong place is a **layout** bug —
fix the layout. Declaring 114 tsconfigs as inputs would have been "correct"
and would have quietly wrecked the cache for every vitest suite in the repo.

---

## Step 9 — Clean up and document

- Delete `packages/<name>/jest.config.cts` and any package-local jest resolver
  or setup file whose behavior you ported.
- If this was the last jest project touching a `scripts/jest-mocks/*` shim or a
  branch of `scripts/unit-test-setup.js`, delete it. If not, leave it and say
  so in the PR body — the `packages/nx` PR explicitly deferred the dead
  `scripts/unit-test-setup.js` branches to a follow-up rather than mixing them
  in.
- Update `CONTRIBUTING.md` — it documents `npx jest <path>` for targeting a
  single test. Add the package to the vitest note next to `packages/nx`.
- Format: `npx oxfmt <changed files>` (check the branch's own `check` target
  first — a feature branch may still run pretty-quick).
- Do **not** run a full `nx affected`: a new file under `scripts/` marks all 90+
  projects affected, which is hours of jest. Nothing jest reads has changed
  (`jest.preset.js`, `scripts/unit-test-setup.js`,
  `scripts/patched-jest-resolver.js` are untouched), so run one still-on-jest
  package as a canary instead — `devkit` is the most entangled.
- Write `tmp/notes/vitest-migration-<name>.md`: before/after test count and
  wall time, the list of hand-fixed specs and why, and anything deferred.

## Commit shape

Follow the reference PR — small, reviewable, conventional-commit slices:

1. `chore(<scope>): add vitest config and setup for <name> unit tests`
2. `chore(<scope>): codemod jest.* to vi.* in <name> specs`
3. one commit per class of hand fix (CJS-channel mocks, frozen namespaces,
   constructor mocks, hook cleanup, …)
4. `chore(<scope>): regen <name> snapshots for vitest`
5. `chore(<scope>): remove <name> jest config`

PR body: fill the template, state the before/after test count and wall time,
list what the vitest config reproduces from the jest setup, and call out any
latent test bug the migration exposed.

More agent context in nrwl/nx

38 other files this repository gives its agents.