fog/.agents/skills/nx-import/references/NEXT.md

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:

{
  "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:

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