Nx Import 使用指南：从源仓库导入代码并保留Git历史

nx-import by nrwl/nx-ai-agents-config

250 周安装量

13 GitHub Stars

GitHub

安装命令

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

开发自动化代码规范

🇨🇳中文介绍

快速开始

nx import 将代码从源仓库或文件夹导入当前工作区，并保留提交历史。
在 nx 22.6.0 之后，nx import 会响应 .ndjson 输出和后续问题。对于更早的版本，请始终使用 --no-interactive 运行并直接指定所有标志。
运行 nx import --help 查看可用选项。
导入前请确保目标目录为空。示例：目标有 libs/utils 和 libs/models；源有 libs/ui 和 libs/data-access —— 你不能直接将 libs/ 导入到。需要单独导入每个源库。

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

应用程序与库的识别

导入前，识别源是应用程序还是库：

应用程序：可部署的最终产品。常见指标：
- 前端：next.config.*、vite.config.* 带有构建入口点，特定框架的应用脚手架（CRA、Angular CLI 应用等）
- 后端（Node.js）：Express/Fastify/NestJS 服务器入口点，package.json 中没有 "exports" 字段
- JVM：Maven pom.xml 带有 <packaging>jar</packaging> 或 <packaging>war</packaging> 和一个 main 类；Gradle application 插件或 mainClass 设置
- .NET：.csproj/.fsproj 带有 <OutputType>Exe</OutputType> 或 <OutputType>WinExe</OutputType>
- 通用：Dockerfile，可运行的入口点，不打算被其他项目导入的公共 API 接口
库：供其他项目使用的可复用包。常见指标：package.json 中的 "main"/"exports"，Maven/Gradle 打包为库 jar，.NET 的 <OutputType>Library</OutputType>，旨在被其他包导入的命名导出。

目标目录规则：

应用程序 → apps/<name>。检查工作区全局模式（例如 pnpm-workspace.yaml、根 package.json 中的 workspaces）是否存在现有的 apps/* 条目。
- 如果 apps/* 不存在，在导入前添加它：更新工作区全局模式配置并提交（或暂存）更改。
- 示例：nx import <source> apps/my-app --source=packages/my-app
库 → 遵循目标的现有约定（packages/、libs/ 等）。

pnpm 工作区全局模式（关键）

nx import 会将导入的目录本身（例如 apps）添加到 pnpm-workspace.yaml，而不是其中的包的全局模式。跨包导入将失败并提示 Cannot find module。

修复：用源配置中的正确全局模式替换（例如 apps/*、libs/shared/*），然后运行 pnpm install。

根依赖项和配置未被导入（关键）

nx import 不会从源仓库的根目录合并以下内容：

package.json 中的 dependencies/devDependencies
nx.json 中的 targetDefaults（例如 "@nx/esbuild:esbuild": { "dependsOn": ["^build"] } —— 对构建顺序至关重要）
nx.json 中的 namedInputs（例如用于测试文件的 production 排除模式）
nx.json 中的插件配置

修复：对比源和目标工作区的 package.json 和 nx.json。添加缺失的依赖项，合并相关的 targetDefaults 和 namedInputs。

TypeScript 项目引用

导入后，运行 nx sync --yes。如果它报告没有问题但类型检查仍然失败，先运行 nx reset，然后再运行 nx sync --yes。

显式执行器路径修复

推断出的目标（通过 Nx 插件）会相对于项目根目录解析配置 —— 无需更改。显式执行器目标（例如 @nx/esbuild:esbuild）具有相对于工作区根目录的路径（main、outputPath、tsConfig、assets、sourceRoot），这些路径必须加上导入目标目录的前缀。

整个仓库导入：nx import 会检测并提示安装插件。接受它们。
子目录导入：插件不会自动检测。使用 npx nx add @nx/PLUGIN 手动添加。检查 include/exclude 模式 —— 默认值不会匹配替代目录（例如 apps-beta/）。
在任何插件配置更改后运行 npx nx reset。

冗余的根文件（仅限整个仓库导入）

整个仓库导入会将源仓库的所有根文件带到目标子目录中。清理以下文件：

pnpm-lock.yaml —— 已过时；目标工作区有自己的 lockfile
pnpm-workspace.yaml —— 源工作区配置；与目标工作区冲突
node_modules/ —— 指向源文件系统的过时符号链接
.gitignore —— 与目标根目录的 .gitignore 冗余
nx.json —— 源 Nx 配置；目标工作区有自己的配置
README.md —— 可选；保留或删除

不要盲目删除 tsconfig.base.json —— 导入的项目可能通过相对路径扩展它。

根 ESLint 配置缺失（子目录导入）

子目录导入不会带来源仓库的根 eslint.config.mjs，但项目配置引用了 ../../eslint.config.mjs。

首先安装 ESLint 依赖：pnpm add -wD eslint@^9 @nx/eslint-plugin typescript-eslint（加上特定框架的插件）
创建根 eslint.config.mjs（从源仓库复制或使用 @nx/eslint-plugin 基础规则创建）
然后运行 npx nx add @nx/eslint 以在 nx.json 中注册插件

显式安装 typescript-eslint —— pnpm 的严格提升不会自动解析这个 @nx/eslint-plugin 的传递依赖。

ESLint 版本锁定（关键）

将 ESLint 锁定到 v9（eslint@^9.0.0）。ESLint 10 会破坏 @nx/eslint 和许多插件，并出现诸如 Cannot read properties of undefined (reading 'version') 的隐晦错误。

@nx/eslint 可能对等依赖于 ESLint 8，导致解析到错误的版本。如果 lint 失败并提示 Cannot read properties of undefined (reading 'allow')，添加 pnpm.overrides：

{ "pnpm": { "overrides": { "eslint": "^9.0.0" } } }

导入后，比较关键依赖项（typescript、eslint、特定框架的依赖）。如果目标工作区使用较新的版本，将导入的包升级以匹配（通常是安全的）。如果源仓库的版本较新，可能需要先升级目标工作区。如果需要，使用 pnpm.overrides 来强制执行单一版本策略。

导入的项目可能缺少 tags。添加标签或更新 @nx/enforce-module-boundaries 规则。

项目名称冲突（多次导入）

源仓库和目标工作区中 package.json 的 name 相同会导致 MultipleProjectsWithSameNameError。修复：重命名冲突的名称（例如 @org/api → @org/teama-api），更新所有依赖引用和导入语句，运行 pnpm install。每个导入仓库的根 package.json 也会成为一个项目 —— 也要重命名它们。

工作区依赖导入顺序

如果在 nx import 期间，一个 "workspace:*" 依赖项尚未被导入，pnpm install 会失败。文件操作仍然成功。修复：先导入所有项目，然后运行 pnpm install --no-frozen-lockfile。

`.gitkeep` 阻止子目录导入

TS 预设会创建 packages/.gitkeep。在导入前删除它并提交。

前端 tsconfig 基础设置（关键）

TS 预设的默认值（module: "nodenext"、moduleResolution: "nodenext"、lib: ["es2022"]）与前端框架（React、Next.js、Vue、Vite）不兼容。导入前端项目后，验证目标根目录的 tsconfig.base.json：

moduleResolution：必须是 "bundler"（不是 "nodenext"）
module：必须是 "esnext"（不是 "nodenext"）
lib：必须包含 "dom" 和 "dom.iterable"（前端项目需要这些）
jsx：对于纯 React 工作区使用 "react-jsx"，对于混合框架则按项目配置

对于子目录导入，目标根目录的 tsconfig 是权威的 —— 更新它。对于整个仓库导入，导入的项目可能扩展它们自己嵌套的 tsconfig.base.json，这使得这一点不那么关键。

如果目标工作区也有需要 nodenext 的后端项目，请使用按项目的覆盖，而不是更改根配置。

陷阱：TypeScript 不会合并 lib 数组 —— 项目级别的覆盖会完全替换基础数组。在任何项目级别的 lib 中始终包含所有需要的条目（例如 es2022、dom、dom.iterable）。

`@nx/react` 库的类型定义

使用 @nx/react:library 生成的 React 库在其 tsconfig 的 types 中引用了 @nx/react/typings/cssmodule.d.ts 和 @nx/react/typings/image.d.ts。除非在目标工作区安装了 @nx/react，否则这些引用会失败并提示 Cannot find type definition file。

修复：pnpm add -wD @nx/react

Jest 预设缺失（子目录导入）

Nx 预设会在工作区根目录创建 jest.preset.js，项目的 jest 配置会引用它（例如 ../../jest.preset.js）。子目录导入不会带来这个文件。

运行 npx nx add @nx/jest —— 在 nx.json 中注册 @nx/jest/plugin 并更新 namedInputs
在工作区根目录创建 jest.preset.js（内容参见 references/JEST.md）—— nx add 只在生成器运行时创建此文件，而不是在裸的 nx add 上
安装测试运行器依赖：pnpm add -wD jest jest-environment-jsdom ts-jest @types/jest
根据需要安装特定框架的测试依赖（参见 references/JEST.md）

对于更深入的 Jest 问题（tsconfig.spec.json、Babel 转换、CI 原子化、Jest 与 Vitest 共存），请参阅 references/JEST.md。

目标名称前缀（整个仓库导入）

当导入一个具有现有 npm 脚本（build、dev、start、lint）的项目时，Nx 插件会自动为推断出的目标名称添加前缀以避免冲突：例如 next:build、vite:build、eslint:lint。

修复：从导入的 package.json 中删除 Nx 重写的 npm 脚本，然后选择以下任一方式：

接受带前缀的名称（例如 nx run app:next:build）
在 nx.json 中重命名插件目标名称以使用无前缀的名称

非 Nx 源仓库问题

当源仓库是一个没有 nx.json 的普通 pnpm/npm 工作区时。

npm 脚本重写（关键）

Nx 在初始化期间重写 package.json 脚本，创建损坏的命令（例如 vitest run → nx test run）。修复：删除所有重写的脚本 —— Nx 插件从配置文件推断目标。

`noEmit` → `composite` + `emitDeclarationOnly`（关键）

普通的 TS 项目使用 "noEmit": true，这与 Nx 项目引用不兼容。

症状："typecheck target is disabled because one or more project references set 'noEmit: true'" 或 TS6310。

在所有导入的 tsconfig 中修复：

移除 "noEmit": true。如果通过 extends 链继承，则显式设置 "noEmit": false。
添加 "composite": true、"emitDeclarationOnly": true、"declarationMap": true
添加 "outDir": "dist" 和 "tsBuildInfoFile": "dist/tsconfig.tsbuildinfo"
如果缺少，添加 "extends": "../../tsconfig.base.json"。移除现在从基础配置继承的设置。

过时的 node_modules 和 Lockfiles

nx import 可能会带来源仓库的 node_modules/（指向源文件系统的 pnpm 符号链接）和 pnpm-lock.yaml。两者都已过时。

修复：rm -rf imported/node_modules imported/pnpm-lock.yaml imported/pnpm-workspace.yaml imported/.gitignore，然后运行 pnpm install。

旧版 .eslintrc.json（ESLint 8）：删除所有 .eslintrc.*，移除 v8 依赖，创建扁平的 eslint.config.mjs。
扁平配置（eslint.config.js）：自包含的配置通常可以保持不变。
没有 ESLint：从头创建根目录和项目级别的配置。

TypeScript `paths` 别名

Nx 使用 package.json 的 "exports" 和 pnpm 工作区链接，而不是 tsconfig 的 "paths"。如果包有正确的 "exports"，paths 就是冗余的。否则，为新目录结构更新 paths。

识别源仓库中的技术，然后阅读并应用匹配的参考文件。

可用的参考文件：

references/ESLINT.md —— ESLint 项目：重复的 lint/eslint:lint 目标，旧版 .eslintrc.* 对生成文件的 linting，扁平配置 .cjs 自检，typescript-eslint v7/v9 对等依赖冲突，一个工作区中混合 ESLint v8+v9。
references/GRADLE.md
references/JEST.md —— Jest 测试：@nx/jest/plugin 设置，jest.preset.js，按框架的测试依赖，tsconfig.spec.json，Jest 与 Vitest 共存，Babel 转换，CI 原子化。
references/NEXT.md —— Next.js 项目：@nx/next/plugin 目标，withNx，Next.js TS 配置（noEmit、jsx: "preserve"），通过错误的包管理器自动安装依赖，非 Nx create-next-app 导入，混合 Next.js+Vite 共存。
references/TURBOREPO.md
references/VITE.md —— Vite 项目（React、Vue 或两者）：@nx/vite/plugin 类型检查目标，resolve.alias/__dirname 修复，框架依赖，Vue 特定设置，混合 React+Vue 共存。

🇺🇸English

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:

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 setting

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 :

Install ESLint deps first: pnpm add -wD eslint@^9 @nx/eslint-plugin typescript-eslint (plus framework-specific plugins)
Create root eslint.config.mjs (copy from source or create with @nx/eslint-plugin base rules)
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:

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

Run npx nx add @nx/jest — registers @nx/jest/plugin in nx.json and updates namedInputs
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
Install test runner deps: pnpm add -wD jest jest-environment-jsdom ts-jest @types/jest
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:

Remove "noEmit": true. If inherited via extends chain, set "noEmit": false explicitly.
Add "composite": true, "emitDeclarationOnly": true, "declarationMap": true
Add "outDir": "dist" and "tsBuildInfoFile": "dist/tsconfig.tsbuildinfo"
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: targets, , Next.js TS config (, ), auto-installing deps via wrong PM, non-Nx imports, mixed Next.js+Vite coexistence.

Weekly Installs

250

Repository

nrwl/nx-ai-agents-config

GitHub Stars

First Seen

Mar 5, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

cursor245

gemini-cli244

codex244

kimi-cli244

github-copilot244

amp244

agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试

140,500 周安装

.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.

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.