자세한 설명
Nx Import는 기존 Nx 워크스페이스에 프로젝트나 선택한 원본 디렉터리를 Git 이력과 함께 가져오는 작업을 위한 Skill입니다. 대상 저장소에서 작업하며 원본 위치, 최종 경로, 범위를 먼저 정해야 합니다. 파일이 옮겨졌다는 사실만으로 새 환경에서 앱이 빌드된다고 판단할 수는 없습니다.
원문은 저장소 전체 가져오기와 monorepo의 개별 프로젝트 가져오기를 구분합니다. 디렉터리 충돌, 워크스페이스 패턴, 중복 패키지 이름과 외부 공유 파일을 다룹니다. 대상의 구조를 존중하면서 루트 ESLint·Jest 설정, 스크립트, 공유 라이브러리를 별도로 조정해야 합니다.
전체 패키지에는 ESLint, Gradle, Jest, Next.js, Turborepo, Vite 참고 파일 여섯 개가 있습니다. 프로젝트에 해당하는 자료를 읽어 후속 작업을 판단합니다. 특정 버전의 조언을 모든 현재 도구에 적용하거나 ESLint 버전과 TypeScript 설정을 일괄 강제하는 근거로 삼아서는 안 됩니다.
준비할 사항
- 접근 가능한 원본 저장소 또는 경로, 브랜치·리비전, 가져올 프로젝트.
- 대상 Nx 워크스페이스, 경로, 패키지 관리자, 기존 빌드·테스트 명령.
예상 결과
- 예정한 위치와 필요한 Git 이력을 갖춘 프로젝트 파일.
- 검토한 의존성·설정 차이와 프로젝트 인식, 빌드, 테스트 결과.
사용 순서
- 대상 프로젝트, 외부 공유 파일, 목적지 규칙을 확인합니다.
- 설치된 Nx 도움말과 충돌을 확인하고 대상 저장소에서 가져옵니다.
- 워크스페이스 범위, 의존성, 이름, 공유 설정을 관련 참고 자료와 조정합니다.
- 프로젝트 그래프, Git 이력, 실제 빌드와 테스트를 확인합니다.
제한 및 확인 사항
- 하위 폴더 가져오기가 모든 루트 의존성·설정 병합을 뜻하지는 않습니다.
- 상속받는 tsconfig와 lint·테스트 설정을 무조건 삭제하지 않습니다.
- 패키지·프로젝트·작업 이름 충돌을 명확히 해결합니다.
- 원문의 버전별 해결책을 보편적인 규칙으로 취급하지 않습니다.
자주 묻는 질문
monorepo의 일부만 가져올 수 있나요?
네. 원문은 원본 디렉터리별 가져오기를 다루며 중첩된 워크스페이스 설정을 피하는 데 도움이 될 수 있습니다. 경로 대응과 빠진 공유 파일은 여전히 확인해야 합니다.
로컬 패키지 연결과 어떻게 다른가요?
가져오기는 코드와 이력이 있는 위치를 바꿉니다. link-workspace-packages는 이미 워크스페이스에 있는 패키지 간 의존성 선언을 처리합니다.
nrwl/nx 배포는 다른 이전 엔진인가요?
이 검토에서는 그런 차이가 확인되지 않았습니다. 여섯 참고 파일을 포함한 두 고정 패키지는 동일하며 저장소·배포 식별자는 별도로 유지합니다.
이 Skill 설치
Skills CLI로 검증된 GitHub 출처에서 이 Skill을 추가합니다.
npx skills add https://github.com/nrwl/nx-ai-agents-config --skill nx-import출처 정보
- github.com/nrwl/nx-ai-agents-config/blob/13282936b5f6aa53e3d41ba589a4a2dc0d6f5786/skills/nx-import/SKILL.md
- github.com/nrwl/nx-ai-agents-config/blob/13282936b5f6aa53e3d41ba589a4a2dc0d6f5786/README.md
- github.com/nrwl/nx/tree/d976a693f12e81402bcbd53d4b04f91974650c04/.agents/skills/nx-import
- nx.dev/docs/kb/import-project
원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.
Quick Start
nx importbrings code from a source repository or folder into the current workspace, preserving commit history.- After nx
22.6.0,nx importresponds with .ndjson outputs and follow-up questions. For earlier versions, always run with--no-interactiveand specify all flags directly. - Run
nx import --helpfor 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 usespackages/? Import intopackages/(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 inpackage.json - JVM: Maven
pom.xmlwith<packaging>jar</packaging>or<packaging>war</packaging>and amainclass; Gradleapplicationplugin ormainClasssetting - .NET:
.csproj/.fsprojwith<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"inpackage.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,workspacesin rootpackage.json) for an existingapps/*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/devDependenciesfrompackage.jsontargetDefaultsfromnx.json(e.g."@nx/esbuild:esbuild": { "dependsOn": ["^build"] }— critical for build ordering)namedInputsfromnx.json(e.g.productionexclusion 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 importdetects and offers to install plugins. Accept them. - Subdirectory import: Plugins NOT auto-detected. Manually add with
npx nx add @nx/PLUGIN. Checkinclude/excludepatterns — defaults won't match alternate directories (e.g.apps-beta/). - Run
npx nx resetafter 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 lockfilepnpm-workspace.yaml— source workspace config; conflicts with destnode_modules/— stale symlinks pointing to source filesystem.gitignore— redundant with dest root.gitignorenx.json— source Nx config; dest has its ownREADME.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-pluginbase rules) - Then
npx nx add @nx/eslintto register the plugin innx.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`:
"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:
- Run
npx nx add @nx/jest— registers@nx/jest/plugininnx.jsonand updatesnamedInputs - Create
jest.preset.jsat workspace root (seereferences/JEST.mdfor content) —nx addonly creates this when a generator runs, not on barenx 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.jsonto 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": falseexplicitly. - 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 flateslint.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: duplicatelint/eslint:linttargets, legacy.eslintrc.*linting generated files, flat config.cjsself-linting,typescript-eslintv7/v9 peer dep conflict, mixed ESLint v8+v9 in one workspace.references/GRADLE.mdreferences/JEST.md— Jest testing:@nx/jest/pluginsetup, 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/plugintargets,withNx, Next.js TS config (noEmit,jsx: "preserve"), auto-installing deps via wrong PM, non-Nxcreate-next-appimports, mixed Next.js+Vite coexistence.references/TURBOREPO.mdreferences/VITE.md— Vite projects (React, Vue, or both):@nx/vite/plugintypecheck target,resolve.alias/__dirnamefixes, framework deps, Vue-specific setup, mixed React+Vue coexistence.


