nrwl/nx-ai-agents-config

nx-import

Anleitung für Repository-Import und die anschließende Abstimmung von Abhängigkeiten und Konfiguration.

Quelltext ansehen

Einordnung

Nx Import unterstützt die Übernahme eines Projekts oder Quellverzeichnisses in einen bestehenden Nx-Workspace unter Erhalt der Git-Historie. Gearbeitet wird im Zielrepository; Quelle, Zielpfad und Umfang müssen vorher klar sein. Übertragene Dateien allein belegen noch keinen funktionsfähigen Build.

Die Anleitung unterscheidet ganze Repositorys von einzelnen Projekten eines Monorepos. Verzeichniskonflikte, Workspace-Muster, Paketnamen und Dateien außerhalb des gewählten Ordners sind gesondert zu behandeln. Die Zielkonventionen bleiben maßgeblich; gemeinsame ESLint-, Jest- und Skriptdateien oder Bibliotheken werden nicht automatisch vollständig zusammengeführt.

Das vollständige Paket enthält sechs Referenzen für ESLint, Gradle, Jest, Next.js, Turborepo und Vite. Nutzen Sie die zum Projekt passenden Hinweise. Versionsabhängige Empfehlungen sind am tatsächlichen Tooling zu prüfen; sie begründen weder ein allgemeines ESLint-Pinning noch pauschale Änderungen aller TypeScript-Konfigurationen.

Benötigte Eingaben

  • Lesbare Quelle, Branch oder Revision und die konkret zu übernehmenden Projekte.
  • Nx-Zielworkspace, Zielpfade, Paketmanager und vorhandene Build-/Testbefehle.

Erwartete Ergebnisse

  • Projektdateien am gewünschten Ort mit der benötigten Historie.
  • Geprüfte Abhängigkeits- und Konfigurationsänderungen sowie Build- und Testergebnisse.

Vorgehensweise

  1. Projekte, externe gemeinsame Dateien und Zielkonventionen erfassen.
  2. Nx-Hilfe und Konflikte prüfen und den Import im Zielrepository starten.
  3. Workspace-Muster, Abhängigkeiten, Namen und gemeinsame Konfiguration abstimmen.
  4. Projektgraph, Git-Historie, Builds und Tests kontrollieren.

Grenzen und Prüfungen

  • Ein Unterverzeichnisimport führt nicht alle Root-Einstellungen zusammen.
  • Benötigte tsconfig-, Lint- und Testdateien nicht blind entfernen.
  • Namens- und Taskkonflikte ausdrücklich beheben.
  • Versionsspezifische Hinweise sind keine Zusage für jede aktuelle Toolchain.

Häufige Fragen

Kann nur ein Teil eines Monorepos importiert werden?

Ja. Die Quelle beschreibt einzelne Quellverzeichnisse, wodurch eine zweite verschachtelte Workspace-Konfiguration vermieden werden kann. Pfade und ausgelassene gemeinsame Dateien bleiben zu prüfen.

Was unterscheidet dies vom Verbinden lokaler Pakete?

Ein Import verändert den Ort von Code und Historie. link-workspace-packages deklariert Abhängigkeiten zwischen bereits vorhandenen Workspace-Paketen.

Hat nrwl/nx eine andere Migrationsengine?

Das ist hier nicht belegt. Beide geprüften Pakete einschließlich der sechs Referenzen sind identisch; Repository- und Verteilungsidentitäten bleiben getrennt.

Diesen Skill installieren

Füge diesen Skill mit der Skills CLI aus seiner verifizierten GitHub-Quelle hinzu.

npx skills add https://github.com/nrwl/nx-ai-agents-config --skill nx-import

Quellenangaben

Originales Skill-Dokument

Aus dem Quell-Repository gerendert; Überschriften, Beispiele, Code, Tabellen, Links und Bilder bleiben erhalten.

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.

Verwandte Aufgaben

aus demselben Repository

Weitere Skills

Alle Skills
nrwl
Community

nx-workspace

Explore and understand Nx workspaces. USE WHEN answering questions about the workspace, projects, or tasks. ALSO USE WHEN an nx command fails or you need to check available targets/configuration before running a task. EXAMPLES: 'What projects are in this workspace?', 'How is project X configured?', 'What depends on library Y?', 'What targets can I run?', 'Cannot find configuration for task', 'debug nx task failure'.

Installationen gesamt
100.639
GitHub Stars
29
Aktualisiert
20. Nov.
nrwl
Community

link-workspace-packages

Link workspace packages in monorepos (npm, yarn, pnpm, bun). USE WHEN: (1) you just created or generated new packages and need to wire up their dependencies, (2) user imports from a sibling package and needs to add it as a dependency, (3) you get resolution errors for workspace packages (@org/) like "cannot find module", "failed to resolve import", "TS2307", or "cannot resolve". DO NOT patch around with tsconfig paths or manual package.json edits - use the package manager''s workspace commands t

Installationen / 1h
7
GitHub Stars
29
Aktualisiert
20. Nov.
nrwl
Community

nx-plugins

Find and add Nx plugins. USE WHEN user wants to discover available plugins, install a new plugin, or add support for a specific framework or technology to the workspace.

Installationen / 1h
1
GitHub Stars
29
Aktualisiert
20. Nov.
nrwl
Community

nx-generate

Generate code using nx generators. INVOKE IMMEDIATELY when user mentions scaffolding, setup, structure, creating apps/libs, or setting up project structure. Trigger words - scaffold, setup, create a new app, create a new lib, project structure, generate, add a new project. ALWAYS use this BEFORE calling nxdocs or exploring - this skill handles discovery internally.

Installationen / 1h
7
GitHub Stars
28
Aktualisiert
7. Okt.