Implement project structure and documentation for Fog Expedition, including .mcp.json configuration, agent guidelines in AGENTS.md, and detailed project context in PROJECT_CONTEXT.md. Update .gitignore and pnpm-workspace.yaml for new dependencies and workspace management. Introduce CI monitoring skills and scripts for enhanced CI pipeline management.
This commit is contained in:
Maurycy
214
.agents/skills/nx-import/references/NEXT.md
Normal file
214
.agents/skills/nx-import/references/NEXT.md
Normal file
@@ -0,0 +1,214 @@
|
||||
## Next.js
|
||||
|
||||
Next.js-specific guidance for `nx import`. For generic import issues (pnpm globs, root deps, project references, name collisions, ESLint, frontend tsconfig base settings, `@nx/react` typings, Jest preset, target name prefixing, non-Nx source handling), see `SKILL.md`.
|
||||
|
||||
---
|
||||
|
||||
### `@nx/next/plugin` Inferred Targets
|
||||
|
||||
`@nx/next/plugin` detects `next.config.{ts,js,cjs,mjs}` and creates these targets:
|
||||
|
||||
- `build` → `next build` (with `dependsOn: ['^build']`)
|
||||
- `dev` → `next dev`
|
||||
- `start` → `next start` (depends on `build`)
|
||||
- `serve-static` → same as `start`
|
||||
- `build-deps` / `watch-deps` — for TS solution setup
|
||||
|
||||
**No separate typecheck target** — Next.js runs TypeScript checking as part of `next build`. The `@nx/js/typescript` plugin provides a standalone `typecheck` target for non-Next libraries in the workspace.
|
||||
|
||||
**Build target conflict**: Both `@nx/next/plugin` and `@nx/js/typescript` define a `build` target. `@nx/next/plugin` wins for Next.js projects (it detects `next.config.*`), while `@nx/js/typescript` handles libraries with `tsconfig.lib.json`. No rename needed — they coexist.
|
||||
|
||||
### `withNx` in `next.config.js`
|
||||
|
||||
Nx-generated Next.js projects use `composePlugins(withNx)` from `@nx/next`. This wrapper is optional for `next build` via the inferred plugin (which just runs `next build`), but it provides Nx-specific configuration. Keep it if present.
|
||||
|
||||
### Root Dependencies for Next.js
|
||||
|
||||
Beyond the generic root deps issue (see SKILL.md), Next.js projects typically need:
|
||||
|
||||
**Core**: `react`, `react-dom`, `@types/react`, `@types/react-dom`, `@types/node`, `@nx/react` (see SKILL.md for `@nx/react` typings)
|
||||
**Nx plugins**: `@nx/next` (auto-installed by import), `@nx/eslint`, `@nx/jest`
|
||||
**Testing**: see SKILL.md "Jest Preset Missing" section
|
||||
**ESLint**: `@next/eslint-plugin-next` (in addition to generic ESLint deps from SKILL.md)
|
||||
|
||||
### Next.js Auto-Installing Dependencies via Wrong Package Manager
|
||||
|
||||
Next.js detects missing `@types/react` during `next build` and tries to install it using `yarn add` regardless of the actual package manager. In a pnpm workspace, this fails with a "nearest package directory isn't part of the project" error.
|
||||
|
||||
**Root cause**: `@types/react` is missing from root devDependencies.
|
||||
**Fix**: Install deps at the root before building: `pnpm add -wD @types/react @types/react-dom`
|
||||
|
||||
### Next.js TypeScript Config Specifics
|
||||
|
||||
Next.js app tsconfigs have unique patterns compared to Vite:
|
||||
|
||||
- **`noEmit: true`** with `emitDeclarationOnly: false` — Next.js handles emit, TS just checks types. This conflicts with `composite: true` from the TS solution setup.
|
||||
- **`"types": ["jest", "node"]`** — includes test types in the main tsconfig (no separate `tsconfig.app.json`)
|
||||
- **`"plugins": [{ "name": "next" }]`** — for IDE integration
|
||||
- **`include`** references `.next/types/**/*.ts` for Next.js auto-generated types
|
||||
- **`"jsx": "preserve"`** — Next.js uses its own JSX transform, not React's
|
||||
|
||||
**Gotcha**: The Next.js tsconfig sets `"noEmit": true` which disables `composite` mode. This is fine because Next.js projects use `next build` for building, not `tsc`. The `@nx/js/typescript` plugin's `typecheck` target is not needed for Next.js apps.
|
||||
|
||||
### `next.config.js` Lint Warning
|
||||
|
||||
Imported Next.js configs may have `// eslint-disable-next-line @typescript-eslint/no-var-requires` but the project ESLint config enables different rule sets. This produces `Unused eslint-disable directive` warnings. Harmless — remove the comment or ignore.
|
||||
|
||||
### `@nx/next:init` Rewrites All npm Scripts (Whole-Repo Import)
|
||||
|
||||
When `@nx/next:init` runs during a whole-repo import, it rewrites the project's `package.json` scripts to prefixed `nx` calls:
|
||||
|
||||
```json
|
||||
{
|
||||
"dev": "nx next:dev",
|
||||
"build": "nx next:build",
|
||||
"start": "nx next:start"
|
||||
}
|
||||
```
|
||||
|
||||
This is the standard "npm Script Rewriting" issue from SKILL.md, but triggered by `@nx/next:init` rather than Nx init. **Fix**: Remove all rewritten scripts from `package.json` — `@nx/next/plugin` infers all targets from `next.config.*`.
|
||||
|
||||
---
|
||||
|
||||
## Non-Nx Source (create-next-app)
|
||||
|
||||
### Whole-Repo Import Recommended
|
||||
|
||||
For single-project `create-next-app` repos, use whole-repo import into a subdirectory:
|
||||
|
||||
```bash
|
||||
nx import /path/to/source apps/web --ref=main --source=. --no-interactive
|
||||
```
|
||||
|
||||
### `next-env.d.ts`
|
||||
|
||||
`next build` auto-generates `next-env.d.ts` at the project root. Add `next-env.d.ts` to the dest root `.gitignore` — it is framework-generated and should not be committed.
|
||||
|
||||
### ESLint: Self-Contained `eslint-config-next`
|
||||
|
||||
`create-next-app` generates a flat ESLint config using `eslint-config-next` (which bundles its own plugins). This is **self-contained** — no root `eslint.config.mjs` needed, no `@nx/eslint-plugin` dependency. The `@nx/eslint/plugin` detects it and creates a lint target.
|
||||
|
||||
### TypeScript: No Changes Needed
|
||||
|
||||
Non-Nx Next.js projects have self-contained tsconfigs with `noEmit: true`, their own `lib`, `module`, `moduleResolution`, and `jsx` settings. Since `next build` handles type checking internally, no tsconfig modifications are needed. The project does NOT need to extend `tsconfig.base.json`.
|
||||
|
||||
**Gotcha**: The `@nx/js/typescript` plugin won't create a `typecheck` target because there's no `tsconfig.lib.json`. This is fine — use `next:build` for type checking.
|
||||
|
||||
### `noEmit: true` and TS Solution Setup
|
||||
|
||||
Non-Nx Next.js projects use `noEmit: true`, which conflicts with Nx's TS solution setup (`composite: true`). If the dest workspace uses project references and you want the Next.js app to participate:
|
||||
|
||||
1. Remove `noEmit: true`, add `composite: true`, `emitDeclarationOnly: true`
|
||||
2. Add `extends: "../../tsconfig.base.json"`
|
||||
3. Add `outDir` and `tsBuildInfoFile`
|
||||
|
||||
**However**, this is optional for standalone Next.js apps that don't export types consumed by other workspace projects.
|
||||
|
||||
### Tailwind / PostCSS
|
||||
|
||||
`create-next-app` with Tailwind generates `postcss.config.mjs`. This works as-is after import — no path changes needed since PostCSS resolves relative to the project root.
|
||||
|
||||
---
|
||||
|
||||
## Mixed Next.js + Vite Coexistence
|
||||
|
||||
When both Next.js and Vite projects exist in the same workspace.
|
||||
|
||||
### Plugin Coexistence
|
||||
|
||||
Both `@nx/next/plugin` and `@nx/vite/plugin` can coexist in `nx.json`. They detect different config files (`next.config.*` vs `vite.config.*`) so there are no conflicts. The `@nx/js/typescript` plugin handles libraries.
|
||||
|
||||
### Vite Standalone Project tsconfig Fixes
|
||||
|
||||
Vite standalone projects (imported as whole-repo) have self-contained tsconfigs without `composite: true`. The `@nx/js/typescript` plugin's typecheck target runs `tsc --build --emitDeclarationOnly` which requires `composite`.
|
||||
|
||||
**Fix**:
|
||||
|
||||
1. Add `extends: "../../tsconfig.base.json"` to the root project tsconfig
|
||||
2. Add `composite: true`, `declaration: true`, `declarationMap: true`, `tsBuildInfoFile` to `tsconfig.app.json` and `tsconfig.spec.json`
|
||||
3. Set `moduleResolution: "bundler"` (replace `"node"`)
|
||||
4. Add source files to `tsconfig.spec.json` `include` — specs import app code, and `composite` mode requires all files to be listed
|
||||
|
||||
### Typecheck Target Names
|
||||
|
||||
- `@nx/vite/plugin` defaults `typecheckTargetName` to `"vite:typecheck"`
|
||||
- `@nx/js/typescript` uses `"typecheck"`
|
||||
- Next.js projects have NO standalone typecheck target — Next.js runs type checking during `next build`
|
||||
|
||||
No naming conflicts between frameworks.
|
||||
|
||||
---
|
||||
|
||||
## Fix Order — Nx Source (Subdirectory Import)
|
||||
|
||||
1. Import Next.js apps into `apps/<name>` (see SKILL.md: "Application vs Library Detection")
|
||||
2. Generic fixes from SKILL.md (pnpm globs, root deps, `.gitkeep` removal, frontend tsconfig base settings, `@nx/react` typings)
|
||||
3. Install Next.js-specific deps: `pnpm add -wD @next/eslint-plugin-next`
|
||||
4. ESLint setup (see SKILL.md: "Root ESLint Config Missing")
|
||||
5. Jest setup (see SKILL.md: "Jest Preset Missing")
|
||||
6. `nx reset && nx sync --yes && nx run-many -t typecheck,build,test,lint`
|
||||
|
||||
## Fix Order — Non-Nx Source (create-next-app)
|
||||
|
||||
1. Import into `apps/<name>` (see SKILL.md: "Application vs Library Detection")
|
||||
2. Generic fixes from SKILL.md (pnpm globs, stale files cleanup, script rewriting, target name prefixing)
|
||||
3. (Optional) If app needs to export types for other workspace projects: fix `noEmit` → `composite` (see SKILL.md)
|
||||
4. `nx reset && nx run-many -t next:build,eslint:lint` (or unprefixed names if renamed)
|
||||
|
||||
---
|
||||
|
||||
## Iteration Log
|
||||
|
||||
### Scenario 1: Basic Nx Next.js App Router + Shared Lib → TS preset (PASS)
|
||||
|
||||
- Source: CNW next preset (Next.js 16, App Router) + `@nx/react:library` shared-ui
|
||||
- Dest: CNW ts preset (Nx 23)
|
||||
- Import: subdirectory-at-a-time (apps, libs separately)
|
||||
- Errors found & fixed:
|
||||
1. pnpm-workspace.yaml: `apps`/`libs` → `apps/*`/`libs/*`
|
||||
2. Root tsconfig: `nodenext` → `bundler`, add `dom`/`dom.iterable` to `lib`, add `jsx: react-jsx`
|
||||
3. Missing `@nx/react` (for CSS module/image type defs in lib)
|
||||
4. Missing `@types/react`, `@types/react-dom`, `@types/node`
|
||||
5. Next.js trying `yarn add @types/react` — fixed by installing at root
|
||||
6. Missing `@nx/eslint`, root `eslint.config.mjs`, ESLint plugins
|
||||
7. Missing `@nx/jest`, `jest.preset.js`, `jest-environment-jsdom`, `ts-jest`
|
||||
- All targets green: typecheck, build, test, lint
|
||||
|
||||
### Scenario 3: Non-Nx create-next-app (App Router + Tailwind) → TS preset (PASS)
|
||||
|
||||
- Source: `create-next-app@latest` (Next.js 16.1.6, App Router, Tailwind v4, flat ESLint config)
|
||||
- Dest: CNW ts preset (Nx 23)
|
||||
- Import: whole-repo into `apps/web`
|
||||
- Errors found & fixed:
|
||||
1. pnpm-workspace.yaml: `apps/web` → `apps/*`
|
||||
2. Stale files: `node_modules/`, `pnpm-lock.yaml`, `pnpm-workspace.yaml`, `.gitignore` — deleted
|
||||
3. Nx-rewritten npm scripts (`"build": "nx next:build"`, etc.) — removed
|
||||
- No tsconfig changes needed — self-contained config with `noEmit: true`
|
||||
- ESLint self-contained via `eslint-config-next` — no root config needed
|
||||
- No test setup (create-next-app doesn't include tests)
|
||||
- All targets green: next:build, eslint:lint
|
||||
|
||||
### Scenario 4: Non-Nx create-next-app (alongside Vite, React Router 7, TanStack, CRA) → TS preset (PASS)
|
||||
|
||||
- See VITE.md Scenario 6 for the full multi-import scenario
|
||||
- Next.js-specific findings:
|
||||
1. `@nx/next:init` rewrote all scripts to `nx next:*` format — removed all rewritten scripts
|
||||
2. Stale files: `node_modules/`, `package-lock.json`, `.gitignore` — deleted (npm workspace, no pnpm files)
|
||||
3. ESLint self-contained via `eslint-config-next` — no root config needed
|
||||
4. No tsconfig changes needed — `noEmit: true` stays; `next build` handles type checking
|
||||
- Targets: `next:build`, `next:dev`, `next:start`, `eslint:lint`
|
||||
|
||||
### Scenario 5: Mixed Next.js (Nx) + Vite React (standalone) → TS preset (PASS)
|
||||
|
||||
- Source A: CNW next preset (Next.js 16, App Router) — subdirectory import of `apps/`
|
||||
- Source B: CNW react-standalone preset (Vite 7, React 19) — whole-repo import into `apps/vite-app`
|
||||
- Dest: CNW ts preset (Nx 23)
|
||||
- Errors found & fixed:
|
||||
1. All Scenario 1 fixes for the Next.js app
|
||||
2. Stale files from Vite source: `node_modules/`, `pnpm-lock.yaml`, `pnpm-workspace.yaml`, `.gitignore`, `nx.json`
|
||||
3. Removed rewritten scripts from Vite app's `package.json`
|
||||
4. ESLint 8 vs 9 conflict — `@nx/eslint` peer on ESLint 8 resolved wrong version. Fixed with `pnpm.overrides`
|
||||
5. Vite tsconfigs missing `composite: true`, `declaration: true` — needed for `tsc --build --emitDeclarationOnly`
|
||||
6. Vite `tsconfig.spec.json` `include` missing source files — specs import app code
|
||||
7. Vite tsconfig `moduleResolution: "node"` → `"bundler"`, added `extends: "../../tsconfig.base.json"`
|
||||
- All targets green: typecheck, build, test, lint for both projects
|
||||
Reference in New Issue
Block a user