create-stencil-components 1.0.7 → 1.0.9

package/dist/templates/base/.github/skills/nx-import/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: nx-import
+description: Import, merge, or combine repositories into an Nx workspace using nx import. USE WHEN the user asks to adopt Nx across repos, move projects into a monorepo, or bring code/history from another repository.
+---
+
+## Quick Start
+
+- `nx import` brings code from a source repository or folder into the current workspace, preserving commit history.
+- After nx `22.6.0`, `nx import` responds with .ndjson outputs and follow-up questions. For earlier versions, always run with `--no-interactive` and specify all flags directly.
+- Run `nx import --help` for available options.
+- Make sure the destination directory is empty before importing.
+  EXAMPLE: target has `libs/utils` and `libs/models`; source has `libs/ui` and `libs/data-access` — you cannot import `libs/` into `libs/` directly. Import each source library individually.
+
+Primary docs:
+
+- https://nx.dev/docs/guides/adopting-nx/import-project
+- https://nx.dev/docs/guides/adopting-nx/preserving-git-histories
+
+Read the nx docs if you have the tools for it.
+
+## Import Strategy
+
+**Subdirectory-at-a-time** (`nx import <source> apps --source=apps`):
+
+- **Recommended for monorepo sources** — files land at top level, no redundant config
+- Caveats: multiple import commands (separate merge commits each); dest must not have conflicting directories; root configs (deps, plugins, targetDefaults) not imported
+- **Directory conflicts**: Import into alternate-named dir (e.g. `imported-apps/`), then rename
+
+**Whole repo** (`nx import <source> imported --source=.`):
+
+- **Only for non-monorepo sources** (single-project repos)
+- For monorepos, creates messy nested config (`imported/nx.json`, `imported/tsconfig.base.json`, etc.)
+- If you must: keep imported `tsconfig.base.json` (projects extend it), prefix workspace globs and executor paths
+
+### Directory Conventions
+
+- **Always prefer the destination's existing conventions.** Source uses `libs/`but dest uses `packages/`? Import into `packages/` (`nx import <source> packages/foo --source=libs/foo`).
+- If dest has no convention (empty workspace), ask the user.
+
+### Application vs Library Detection
+
+Before importing, identify whether the source is an **application** or a **library**:
+
+- **Applications**: Deployable end products. Common indicators:
+    - _Frontend_: `next.config.*`, `vite.config.*` with a build entry point, framework-specific app scaffolding (CRA, Angular CLI app, etc.)
+    - _Backend (Node.js)_: Express/Fastify/NestJS server entrypoint, no `"exports"` field in `package.json`
+    - _JVM_: Maven `pom.xml` with `<packaging>jar</packaging>` or `<packaging>war</packaging>` and a `main` class; Gradle `application` plugin or `mainClass` setting
+    - _.NET_: `.csproj`/`.fsproj` with `<OutputType>Exe</OutputType>` or `<OutputType>WinExe</OutputType>`
+    - _General_: Dockerfile, a runnable entrypoint, no public API surface intended for import by other projects
+- **Libraries**: Reusable packages consumed by other projects. Common indicators: `"main"`/`"exports"` in `package.json`, Maven/Gradle packaging as a library jar, .NET `<OutputType>Library</OutputType>`, named exports intended for import by other packages.
+
+**Destination directory rules**:
+
+- Applications → `apps/<name>`. Check workspace globs (e.g. `pnpm-workspace.yaml`, `workspaces` in root `package.json`) for an existing `apps/*` entry.
+    - If `apps/*` is **not** present, add it before importing: update the workspace glob config and commit (or stage) the change.
+    - Example: `nx import <source> apps/my-app --source=packages/my-app`
+- Libraries → follow the dest's existing convention (`packages/`, `libs/`, etc.).
+
+## Common Issues
+
+### pnpm Workspace Globs (Critical)
+
+`nx import` adds the imported directory itself (e.g. `apps`) to `pnpm-workspace.yaml`, **NOT** glob patterns for packages within it. Cross-package imports will fail with `Cannot find module`.
+
+**Fix**: Replace with proper globs from the source config (e.g. `apps/*`, `libs/shared/*`), then `pnpm install`.
+
+### Root Dependencies and Config Not Imported (Critical)
+
+`nx import` does **NOT** merge from the source's root:
+
+- `dependencies`/`devDependencies` from `package.json`
+- `targetDefaults` from `nx.json` (e.g. `"@nx/esbuild:esbuild": { "dependsOn": ["^build"] }` — critical for build ordering)
+- `namedInputs` from `nx.json` (e.g. `production` exclusion patterns for test files)
+- Plugin configurations from `nx.json`
+
+**Fix**: Diff source and dest `package.json` + `nx.json`. Add missing deps, merge relevant `targetDefaults` and `namedInputs`.
+
+### TypeScript Project References
+
+After import, run `nx sync --yes`. If it reports nothing but typecheck still fails, `nx reset` first, then `nx sync --yes` again.
+
+### Explicit Executor Path Fixups
+
+Inferred targets (via Nx plugins) resolve config relative to project root — no changes needed. Explicit executor targets (e.g. `@nx/esbuild:esbuild`) have workspace-root-relative paths (`main`, `outputPath`, `tsConfig`, `assets`, `sourceRoot`) that must be prefixed with the import destination directory.
+
+### Plugin Detection
+
+- **Whole-repo import**: `nx import` detects and offers to install plugins. Accept them.
+- **Subdirectory import**: Plugins NOT auto-detected. Manually add with `npx nx add @nx/PLUGIN`. Check `include`/`exclude` patterns — defaults won't match alternate directories (e.g. `apps-beta/`).
+- Run `npx nx reset` after any plugin config changes.
+
+### Redundant Root Files (Whole-Repo Only)
+
+Whole-repo import brings ALL source root files into the dest subdirectory. Clean up:
+
+- `pnpm-lock.yaml` — stale; dest has its own lockfile
+- `pnpm-workspace.yaml` — source workspace config; conflicts with dest
+- `node_modules/` — stale symlinks pointing to source filesystem
+- `.gitignore` — redundant with dest root `.gitignore`
+- `nx.json` — source Nx config; dest has its own
+- `README.md` — optional; keep or remove
+
+**Don't blindly delete** `tsconfig.base.json` — imported projects may extend it via relative paths.
+
+### Root ESLint Config Missing (Subdirectory Import)
+
+Subdirectory import doesn't bring the source's root `eslint.config.mjs`, but project configs reference `../../eslint.config.mjs`.
+
+**Fix order**:
+
+1. Install ESLint deps first: `pnpm add -wD eslint@^9 @nx/eslint-plugin typescript-eslint` (plus framework-specific plugins)
+2. Create root `eslint.config.mjs` (copy from source or create with `@nx/eslint-plugin` base rules)
+3. Then `npx nx add @nx/eslint` to register the plugin in `nx.json`
+
+Install `typescript-eslint` explicitly — pnpm's strict hoisting won't auto-resolve this transitive dep of `@nx/eslint-plugin`.
+
+### ESLint Version Pinning (Critical)
+
+**Pin ESLint to v9** (`eslint@^9.0.0`). ESLint 10 breaks `@nx/eslint` and many plugins with cryptic errors like `Cannot read properties of undefined (reading 'version')`.
+
+`@nx/eslint` may peer-depend on ESLint 8, causing the wrong version to resolve. If lint fails with `Cannot read properties of undefined (reading 'allow')`, add `pnpm.overrides`:
+
+```json
+{ "pnpm": { "overrides": { "eslint": "^9.0.0" } } }
+```
+
+### Dependency Version Conflicts
+
+After import, compare key deps (`typescript`, `eslint`, framework-specific). If dest uses newer versions, upgrade imported packages to match (usually safe). If source is newer, may need to upgrade dest first. Use `pnpm.overrides` to enforce single-version policy if desired.
+
+### Module Boundaries
+
+Imported projects may lack `tags`. Add tags or update `@nx/enforce-module-boundaries` rules.
+
+### Project Name Collisions (Multi-Import)
+
+Same `name` in `package.json` across source and dest causes `MultipleProjectsWithSameNameError`. **Fix**: Rename conflicting names (e.g. `@org/api` → `@org/teama-api`), update all dep references and import statements, `pnpm install`. The root `package.json` of each imported repo also becomes a project — rename those too.
+
+### Workspace Dep Import Ordering
+
+`pnpm install` fails during `nx import` if a `"workspace:*"` dependency hasn't been imported yet. File operations still succeed. **Fix**: Import all projects first, then `pnpm install --no-frozen-lockfile`.
+
+### `.gitkeep` Blocking Subdirectory Import
+
+The TS preset creates `packages/.gitkeep`. Remove it and commit before importing.
+
+### Frontend tsconfig Base Settings (Critical)
+
+The TS preset defaults (`module: "nodenext"`, `moduleResolution: "nodenext"`, `lib: ["es2022"]`) are incompatible with frontend frameworks (React, Next.js, Vue, Vite). After importing frontend projects, verify the dest root `tsconfig.base.json`:
+
+- **`moduleResolution`**: Must be `"bundler"` (not `"nodenext"`)
+- **`module`**: Must be `"esnext"` (not `"nodenext"`)
+- **`lib`**: Must include `"dom"` and `"dom.iterable"` (frontend projects need these)
+- **`jsx`**: `"react-jsx"` for React-only workspaces, per-project for mixed frameworks
+
+For **subdirectory imports**, the dest root tsconfig is authoritative — update it. For **whole-repo imports**, imported projects may extend their own nested `tsconfig.base.json`, making this less critical.
+
+If the dest also has backend projects needing `nodenext`, use per-project overrides instead of changing the root.
+
+**Gotcha**: TypeScript does NOT merge `lib` arrays — a project-level override **replaces** the base array entirely. Always include all needed entries (e.g. `es2022`, `dom`, `dom.iterable`) in any project-level `lib`.
+
+### `@nx/react` Typings for Libraries
+
+React libraries generated with `@nx/react:library` reference `@nx/react/typings/cssmodule.d.ts` and `@nx/react/typings/image.d.ts` in their tsconfig `types`. These fail with `Cannot find type definition file` unless `@nx/react` is installed in the dest workspace.
+
+**Fix**: `pnpm add -wD @nx/react`
+
+### Jest Preset Missing (Subdirectory Import)
+
+Nx presets create `jest.preset.js` at the workspace root, and project jest configs reference it (e.g. `../../jest.preset.js`). Subdirectory import does NOT bring this file.
+
+**Fix**:
+
+1. Run `npx nx add @nx/jest` — registers `@nx/jest/plugin` in `nx.json` and updates `namedInputs`
+2. Create `jest.preset.js` at workspace root (see `references/JEST.md` for content) — `nx add` only creates this when a generator runs, not on bare `nx add`
+3. Install test runner deps: `pnpm add -wD jest jest-environment-jsdom ts-jest @types/jest`
+4. Install framework-specific test deps as needed (see `references/JEST.md`)
+
+For deeper Jest issues (tsconfig.spec.json, Babel transforms, CI atomization, Jest vs Vitest coexistence), see `references/JEST.md`.
+
+### Target Name Prefixing (Whole-Repo Import)
+
+When importing a project with existing npm scripts (`build`, `dev`, `start`, `lint`), Nx plugins auto-prefix inferred target names to avoid conflicts: e.g. `next:build`, `vite:build`, `eslint:lint`.
+
+**Fix**: Remove the Nx-rewritten npm scripts from the imported `package.json`, then either:
+
+- Accept the prefixed names (e.g. `nx run app:next:build`)
+- Rename plugin target names in `nx.json` to use unprefixed names
+
+## Non-Nx Source Issues
+
+When the source is a plain pnpm/npm workspace without `nx.json`.
+
+### npm Script Rewriting (Critical)
+
+Nx rewrites `package.json` scripts during init, creating broken commands (e.g. `vitest run` → `nx test run`). **Fix**: Remove all rewritten scripts — Nx plugins infer targets from config files.
+
+### `noEmit` → `composite` + `emitDeclarationOnly` (Critical)
+
+Plain TS projects use `"noEmit": true`, incompatible with Nx project references.
+
+**Symptoms**: "typecheck target is disabled because one or more project references set 'noEmit: true'" or TS6310.
+
+**Fix** in **all** imported tsconfigs:
+
+1. Remove `"noEmit": true`. If inherited via extends chain, set `"noEmit": false` explicitly.
+2. Add `"composite": true`, `"emitDeclarationOnly": true`, `"declarationMap": true`
+3. Add `"outDir": "dist"` and `"tsBuildInfoFile": "dist/tsconfig.tsbuildinfo"`
+4. Add `"extends": "../../tsconfig.base.json"` if missing. Remove settings now inherited from base.
+
+### Stale node_modules and Lockfiles
+
+`nx import` may bring `node_modules/` (pnpm symlinks pointing to the source filesystem) and `pnpm-lock.yaml` from the source. Both are stale.
+
+**Fix**: `rm -rf imported/node_modules imported/pnpm-lock.yaml imported/pnpm-workspace.yaml imported/.gitignore`, then `pnpm install`.
+
+### ESLint Config Handling
+
+- **Legacy `.eslintrc.json` (ESLint 8)**: Delete all `.eslintrc.*`, remove v8 deps, create flat `eslint.config.mjs`.
+- **Flat config (`eslint.config.js`)**: Self-contained configs can often be left as-is.
+- **No ESLint**: Create both root and project-level configs from scratch.
+
+### TypeScript `paths` Aliases
+
+Nx uses `package.json` `"exports"` + pnpm workspace linking instead of tsconfig `"paths"`. If packages have proper `"exports"`, paths are redundant. Otherwise, update paths for the new directory structure.
+
+## Technology-specific Guidance
+
+Identify technologies in the source repo, then read and apply the matching reference file(s).
+
+Available references:
+
+- `references/ESLINT.md` — ESLint projects: duplicate `lint`/`eslint:lint` targets, legacy `.eslintrc.*` linting generated files, flat config `.cjs` self-linting, `typescript-eslint` v7/v9 peer dep conflict, mixed ESLint v8+v9 in one workspace.
+- `references/GRADLE.md`
+- `references/JEST.md` — Jest testing: `@nx/jest/plugin` setup, jest.preset.js, testing deps by framework, tsconfig.spec.json, Jest vs Vitest coexistence, Babel transforms, CI atomization.
+- `references/NEXT.md` — Next.js projects: `@nx/next/plugin` targets, `withNx`, Next.js TS config (`noEmit`, `jsx: "preserve"`), auto-installing deps via wrong PM, non-Nx `create-next-app` imports, mixed Next.js+Vite coexistence.
+- `references/TURBOREPO.md`
+- `references/VITE.md` — Vite projects (React, Vue, or both): `@nx/vite/plugin` typecheck target, `resolve.alias`/`__dirname` fixes, framework deps, Vue-specific setup, mixed React+Vue coexistence.

package/dist/templates/base/.github/skills/nx-import/references/ESLINT.md

@@ -0,0 +1,109 @@
+## ESLint
+
+ESLint-specific guidance for `nx import`. For generic import issues (root deps, pnpm globs, project references), see `SKILL.md`.
+
+---
+
+### How `@nx/eslint/plugin` Works
+
+`@nx/eslint/plugin` scans for ESLint config files and creates a lint target for each project. It detects **both** flat config files (`eslint.config.{js,mjs,cjs,ts,mts,cts}`) and legacy config files (`.eslintrc.{json,js,cjs,mjs,yml,yaml}`).
+
+**Plugin options (set during `nx add @nx/eslint`):**
+
+```json
+{
+    "plugin": "@nx/eslint/plugin",
+    "options": {
+        "targetName": "eslint:lint"
+    }
+}
+```
+
+**Auto-installation**: `nx import` auto-detects ESLint config files and offers to install `@nx/eslint`. Accept the offer — it registers the plugin and updates `namedInputs.production` to exclude ESLint config files.
+
+---
+
+### Duplicate `lint` and `eslint:lint` Targets
+
+After import, projects will have **two** lint-related targets if the source `package.json` has a `"lint"` npm script:
+
+- `eslint:lint` — inferred by `@nx/eslint/plugin`; has proper caching and input/output tracking
+- `lint` — created by Nx from the npm script via `nx:run-script`; no caching intelligence, just wraps `npm run lint`
+
+**Fix**: Remove the `"lint"` script from each project's `package.json`. Keep `"lint:fix"` if present — there is no plugin-inferred equivalent for auto-fixing.
+
+---
+
+### Legacy `.eslintrc.*` Configs Linting Generated Files
+
+When `@nx/eslint/plugin` runs `eslint .` on a project with a legacy `.eslintrc.*` config that uses `parserOptions.project`, it tries to lint **all** files in the project directory including:
+
+- Generated `dist/**/*.d.ts` files (not in tsconfig `include`)
+- The `.eslintrc.js` config file itself (not in tsconfig `include`)
+
+This causes `Parsing error: ESLint was configured to run on X using parserOptions.project, however that TSConfig does not include this file`.
+
+**Fix**: Add `ignorePatterns` to the `.eslintrc.*` config:
+
+```json
+// .eslintrc.json
+{
+    "ignorePatterns": ["dist/**"]
+}
+```
+
+```js
+// .eslintrc.js — also ignore the config file itself since module.exports isn't in tsconfig
+module.exports = {
+    ignorePatterns: ['dist/**', '.eslintrc.js'],
+    // ...
+};
+```
+
+---
+
+### Flat Config `.cjs` Files Self-Linting
+
+When a project uses `eslint.config.cjs` (CJS flat config), `eslint .` lints the config file itself. The `require()` call on line 1 triggers `@typescript-eslint/no-require-imports`.
+
+**Fix**: Add the config filename to the top-level `ignores` array:
+
+```js
+module.exports = tseslint.config(
+    {
+        ignores: ['dist/**', 'node_modules/**', 'eslint.config.cjs'],
+    },
+    // ...
+);
+```
+
+The same applies to `eslint.config.js` in a CJS project (no `"type": "module"`) if it uses `require()`.
+
+---
+
+### `typescript-eslint` Version Conflict With ESLint 9
+
+`typescript-eslint@7.x` declares `peerDependencies: { "eslint": "^8.56.0" }`, but it is commonly used alongside `"eslint": "^9.0.0"`. npm treats this as a hard peer dep conflict and refuses to install.
+
+**Root cause**: `@nx/eslint` init adds `eslint@~8.57.0` at the workspace root (for its own peer deps). Workspace packages that request `eslint@^9.0.0` + `typescript-eslint@^7.0.0` trigger the conflict when npm resolves their deps.
+
+**Fix**: Upgrade `typescript-eslint` from `^7.0.0` to `^8.0.0` directly in the affected workspace package's `package.json`. The `tseslint.config()` API and `tseslint.configs.recommended` are identical between v7 and v8 — no config changes needed.
+
+```json
+// packages/my-package/package.json
+{
+    "devDependencies": {
+        "typescript-eslint": "^8.0.0"
+    }
+}
+```
+
+**Note**: npm's root-level `"overrides"` field does not force versions for workspace packages' direct dependencies — update each package.json individually.
+
+---
+
+### Mixed ESLint v8 and v9 in One Workspace
+
+Legacy v8 and flat-config v9 packages can coexist in the same workspace. Each package resolves its own `eslint` version. The root `eslint@~8.57.0` (added by `@nx/eslint` init) is used by legacy v8 packages; v9 packages get their own hoisted `eslint@9`.
+
+`@nx/eslint/plugin` infers `eslint:lint` targets for **both** config formats. Legacy packages run ESLint v8 with `.eslintrc.*`; flat-config packages run ESLint v9 with `eslint.config.*`. No special nx.json configuration is needed to support both simultaneously.

package/dist/templates/base/.github/skills/nx-import/references/GRADLE.md

@@ -0,0 +1,12 @@
+## Gradle
+
+- If you import an entire Gradle repository into a subfolder, files like `gradlew`, `gradlew.bat`, and `gradle/wrapper` will end up inside that imported subfolder.
+- The `@nx/gradle` plugin expects those files at the workspace root to infer Gradle projects/tasks automatically.
+- If the target workspace has no Gradle setup yet, consider moving those files to the root (especially when using `@nx/gradle`).
+- If the target workspace already has Gradle configured, avoid duplicate wrappers: remove imported duplicates from the subfolder or merge carefully.
+- Because the import lands in a subfolder, Gradle project references can break; review settings and project path references, then fix any errors.
+- If `@nx/gradle` is installed, run `nx show projects` to verify that Gradle projects are being inferred.
+
+Helpful docs:
+
+- https://nx.dev/docs/technologies/java/gradle/introduction

package/dist/templates/base/.github/skills/nx-import/references/JEST.md

@@ -0,0 +1,223 @@
+## Jest
+
+Jest-specific guidance for `nx import`. For the basic "Jest Preset Missing" fix (create `jest.preset.js`, install deps), see `SKILL.md`. This file covers deeper Jest integration issues.
+
+---
+
+### How `@nx/jest` Works
+
+`@nx/jest/plugin` scans for `jest.config.{ts,js,cjs,mjs,cts,mts}` and creates a `test` target for each project.
+
+**Plugin options:**
+
+```json
+{
+    "plugin": "@nx/jest/plugin",
+    "options": {
+        "targetName": "test"
+    }
+}
+```
+
+`npx nx add @nx/jest` does two things:
+
+1. **Registers `@nx/jest/plugin` in `nx.json`** — without this, no `test` targets are inferred
+2. Updates `namedInputs.production` to exclude test files
+
+**Gotcha**: `nx add @nx/jest` does NOT create `jest.preset.js` — that file is only generated when you run a generator (e.g. `@nx/jest:configuration`). For imports, you must create it manually (see "Jest Preset" section below).
+
+**Other gotcha**: If you create `jest.preset.js` manually but skip `npx nx add @nx/jest`, the plugin won't be registered and `nx run PROJECT:test` will fail with "Cannot find target 'test'". You need both.
+
+---
+
+### Jest Preset
+
+The preset provides shared Jest configuration (test patterns, ts-jest transform, resolver, jsdom environment).
+
+**Root `jest.preset.js`:**
+
+```js
+const nxPreset = require('@nx/jest/preset').default;
+module.exports = { ...nxPreset };
+```
+
+**Project `jest.config.ts`:**
+
+```ts
+export default {
+    displayName: 'my-lib',
+    preset: '../../jest.preset.js',
+    // project-specific overrides
+};
+```
+
+The `preset` path is relative from the project root to the workspace root. Subdirectory imports preserve the original relative path (e.g. `../../jest.preset.js`), which resolves correctly if the import destination matches the source directory depth.
+
+---
+
+### Testing Dependencies
+
+#### Core (always needed)
+
+```
+pnpm add -wD jest ts-jest @types/jest @nx/jest
+```
+
+#### Environment-specific
+
+- **DOM testing** (React, Vue, browser libs): `jest-environment-jsdom`
+- **Node testing** (APIs, CLIs): no extra deps (Jest defaults to `node` env, but Nx preset defaults to `jsdom`)
+
+#### React testing
+
+```
+pnpm add -wD @testing-library/react @testing-library/jest-dom
+```
+
+#### React with Babel (non-ts-jest transform)
+
+Some React projects use Babel instead of ts-jest for JSX transformation:
+
+```
+pnpm add -wD babel-jest @babel/core @babel/preset-env @babel/preset-react @babel/preset-typescript
+```
+
+**When**: Project `jest.config` has `transform` using `babel-jest` instead of `ts-jest`. Common in older Nx workspaces and CRA migrations.
+
+#### Vue testing
+
+```
+pnpm add -wD @vue/test-utils
+```
+
+Vue projects typically use Vitest (not Jest) — see VITE.md.
+
+---
+
+### `tsconfig.spec.json`
+
+Jest projects need a `tsconfig.spec.json` that includes test files:
+
+```json
+{
+    "extends": "./tsconfig.json",
+    "compilerOptions": {
+        "outDir": "../../dist/out-tsc",
+        "module": "commonjs",
+        "types": ["jest", "node"]
+    },
+    "include": ["jest.config.ts", "src/**/*.test.ts", "src/**/*.spec.ts", "src/**/*.d.ts"]
+}
+```
+
+**Common issues after import:**
+
+- Missing `"types": ["jest", "node"]` — causes `describe`/`it`/`expect` to be unrecognized
+- Missing `"module": "commonjs"` — Jest doesn't support ESM by default (ts-jest transpiles to CJS)
+- `include` array missing test patterns — TypeScript won't check test files
+
+---
+
+### Jest vs Vitest Coexistence
+
+Workspaces can have both:
+
+- **Jest**: Next.js apps, older React libs, Node libraries
+- **Vitest**: Vite-based React/Vue apps and libs
+
+Both `@nx/jest/plugin` and `@nx/vite/plugin` (which infers Vitest targets) coexist without conflicts — they detect different config files (`jest.config.*` vs `vite.config.*`).
+
+**Target naming**: Both default to `test`. If a project somehow has both config files, rename one:
+
+```json
+{
+    "plugin": "@nx/jest/plugin",
+    "options": { "targetName": "jest-test" }
+}
+```
+
+---
+
+### `@testing-library/jest-dom` — Jest vs Vitest
+
+Projects migrating from Jest to Vitest (or workspaces with both) need different imports:
+
+**Jest** (in `test-setup.ts`):
+
+```ts
+import '@testing-library/jest-dom';
+```
+
+**Vitest** (in `test-setup.ts`):
+
+```ts
+import '@testing-library/jest-dom/vitest';
+```
+
+If the source used Jest but the dest workspace uses Vitest for that project type, update the import path. Also add `@testing-library/jest-dom` to tsconfig `types` array.
+
+---
+
+### Non-Nx Source: Test Script Rewriting
+
+Nx rewrites `package.json` scripts during init. Test scripts get broken:
+
+- `"test": "jest"` → `"test": "nx test"` (circular if no executor configured)
+- `"test": "vitest run"` → `"test": "nx test run"` (broken — `run` becomes an argument)
+
+**Fix**: Remove all rewritten test scripts. `@nx/jest/plugin` and `@nx/vite/plugin` infer test targets from config files.
+
+---
+
+### CI Atomization
+
+`@nx/jest/plugin` supports splitting tests per-file for CI parallelism:
+
+```json
+{
+    "plugin": "@nx/jest/plugin",
+    "options": {
+        "targetName": "test",
+        "ciTargetName": "test-ci"
+    }
+}
+```
+
+This creates `test-ci--src/lib/foo.spec.ts` targets for each test file, enabling Nx Cloud distribution. Not relevant during import, but useful for post-import CI setup.
+
+---
+
+### Common Post-Import Issues
+
+1. **"Cannot find target 'test'"**: `@nx/jest/plugin` not registered in `nx.json`. Run `npx nx add @nx/jest` or manually add the plugin entry.
+
+2. **"Cannot find module 'jest-preset'"**: `jest.preset.js` missing at workspace root. Create it (see SKILL.md).
+
+3. **"Cannot find type definition file for 'jest'"**: Missing `@types/jest` or `tsconfig.spec.json` doesn't have `"types": ["jest", "node"]`.
+
+4. **Tests fail with "Cannot use import statement outside a module"**: `ts-jest` not installed or not configured as transform. Check `jest.config.ts` transform section.
+
+5. **Snapshot path mismatches**: After import, `__snapshots__` directories may have paths baked in. Run tests once with `--updateSnapshot` to regenerate.
+
+---
+
+## Fix Order
+
+### Subdirectory Import (Nx Source)
+
+1. `npx nx add @nx/jest` — registers plugin in `nx.json` (does NOT create `jest.preset.js`)
+2. Create `jest.preset.js` manually (see "Jest Preset" section above)
+3. Install deps: `pnpm add -wD jest jest-environment-jsdom ts-jest @types/jest`
+4. Install framework test deps: `@testing-library/react @testing-library/jest-dom` (React), `@vue/test-utils` (Vue)
+5. Verify `tsconfig.spec.json` has `"types": ["jest", "node"]`
+6. `nx run-many -t test`
+
+### Whole-Repo Import (Non-Nx Source)
+
+1. Remove rewritten test scripts from `package.json`
+2. `npx nx add @nx/jest` — registers plugin (does NOT create preset)
+3. Create `jest.preset.js` manually
+4. Install deps (same as above)
+5. Verify/fix `jest.config.*` — ensure `preset` path points to root `jest.preset.js`
+6. Verify/fix `tsconfig.spec.json` — add `types`, `module`, `include` if missing
+7. `nx run-many -t test`