기존 프로젝트에 추가하기

모든 프로젝트가 pnpm create @aws/nx-workspace로 시작하는 것은 아닙니다. 이미 Nx 워크스페이스가 있거나 Nx를 추가할 수 있는 모노레포가 있다면, 프로젝트를 재생성하지 않고도 @aws/nx-plugin을 점진적으로 도입할 수 있습니다.

사전 요구사항

필수

Git
Node >= 22 (NVM 같은 도구로 Node 버전 관리 권장)
- node --version 실행하여 버전 확인
PNPM >= 11 (선호한다면 Yarn >= 4, Bun >= 1, NPM >= 10 사용 가능)
- pnpm --version, yarn --version, bun --version 또는 npm --version 실행하여 버전 확인
UV >= 0.5.29
1. uv python install 3.14.0 실행하여 Python 3.14 설치
2. uv python list --only-installed 실행하여 확인

권장 사항

대상 AWS 계정에 구성된 AWS Credentials는 애플리케이션 배포(및 일부 로컬 개발 워크플로)에 필요합니다.
일부 생성기에는 Docker 또는 Finch >= 1.6.0가 필요합니다. Docker의 경우 멀티 플랫폼 빌드가 설정되어 있어야 하며, Finch는 멀티 플랫폼 빌드를 기본적으로 지원합니다.
CDK 대신 인프라스트럭처 코드로 Terraform을 사용할 경우 Terraform >= 1.12 설치 필요
- terraform --version 명령어로 버전 확인
VSCode 사용 시 Nx Console VSCode Plugin 설치 권장

비-Nx 프로젝트에 Nx 추가하기

프로젝트가 아직 Nx를 사용하지 않는 경우, 먼저 nx init으로 추가하세요. 이것은 Nx 자체가 담당하는 단계이며, 플러그인은 작동하는 Nx 워크스페이스 위에 구축됩니다. 일반 패키지, npm/pnpm/yarn/bun 워크스페이스, Turborepo 또는 Lerna 모노레포에서 작동합니다:

pnpm dlx nx@23.1.1 init

yarn dlx nx@23.1.1 init

npx nx@23.1.1 init

bunx nx@23.1.1 init

프롬프트를 따라 워크스페이스에 Nx를 추가하세요. 자세한 내용은 Nx 문서를 참조하세요.

pnpm은 허용 목록에 있는 패키지에 대해서만 설치 스크립트를 실행하며, nx는 설치 스크립트가 필요합니다 — 이것이 없으면 nx init이 수행하는 설치가 실패하여 pnpm-workspace.yaml에 set this to true or false 플레이스홀더가 남을 수 있습니다. nx init을 실행하기 전에 허용 목록에 추가하세요:

allowBuilds:
  - nx

비-Node 프로젝트 (Python, Go, Java, Rust, …)

Nx와 플러그인은 npm 패키지로 배포되므로, Node.js 도구가 없는 프로젝트는 nx init이 유용한 작업을 수행하기 전에 최소한의 루트 package.json이 필요합니다:

{
  "name": "my-project",
  "private": true,
  "type": "module"
}

해당 파일을 생성한 다음 nx init을 실행하고 평소처럼 플러그인을 추가하세요. 기존 언어 도구는 그대로 유지됩니다 — 플러그인이 생성한 Nx 프로젝트(Python 프로젝트 포함)는 기존 코드와 함께 존재하며, 기존 빌드를 점진적으로 Nx에 연결할 수 있습니다.

기존 프로젝트를 Nx로 가져오려면 언어에 따라 몇 가지 옵션이 있습니다:

공식 Nx 플러그인이 있는 언어 — Java (Gradle 또는 Maven) 및 .NET에는 프로젝트의 작업을 자동으로 추론하는 전용 플러그인이 있습니다. 관련 플러그인을 추가하세요. 예: nx add @nx/gradle, nx add @nx/maven 또는 nx add @nx/dotnet.
커뮤니티 플러그인이 있는 언어 — 예를 들어 Go (@nx-go/nx-go) 또는 Rust (@monodon/rust). 다른 플러그인은 Nx Plugin Registry를 참조하세요.
기타 언어 — 각 프로젝트에 project.json을 추가하고 기존 빌드 명령을 실행하도록 타겟을 정의하여 nx build <project> (및 nx run-many)가 이를 구동하도록 합니다. project.json 및 타겟 설정 방법은 워크스페이스 가이드를 참조하세요.

단일 패키지 프로젝트

플러그인은 모노레포용으로 설계되었습니다 — 각 프로젝트를 packages/ 아래의 자체 디렉토리에 생성합니다. 단일 패키지 프로젝트(루트에 하나의 package.json이 있고 소스가 바로 아래에 있으며 워크스페이스가 없는 경우)에서 시작하는 경우, 플러그인을 도입하기 전에 기존 패키지를 packages/로 이동하여 프로젝트가 플러그인이 생성하는 프로젝트와 나란히 위치하도록 하세요:

packages/<your-package>/ 디렉토리를 생성하고 소스, package.json 및 tsconfig.json을 그 안으로 이동하세요.
프로젝트 자체가 아닌 워크스페이스 매니페스트 역할을 하는 새로운 루트 package.json을 생성하세요:
package.json
```
{
  "name": "<your-workspace>",
  "private": true,
  "type": "module"
}
```
패키지 매니저가 packages/ 아래의 프로젝트를 발견할 수 있도록 워크스페이스를 선언하세요. pnpm의 경우 pnpm-workspace.yaml을 추가하세요:
pnpm-workspace.yaml
```
packages:
  - packages/*
```
npm/yarn/bun의 경우 대신 루트 package.json에 workspaces 필드를 추가하세요:
package.json
```
{
  "workspaces": ["packages/*"]
}
```
nx init을 실행한 다음(아직 실행하지 않았다면), 플러그인을 추가하세요.

플러그인 추가하기

nx add를 사용하세요. 이는 Nx 설치와 호환되는 버전으로 플러그인을 설치한 다음 init 생성기를 실행하여 워크스페이스를 구성합니다:

pnpm nx add @aws/nx-plugin

yarn nx add @aws/nx-plugin

npx nx add @aws/nx-plugin

bunx nx add @aws/nx-plugin

완료되면 워크스페이스가 준비됩니다 — 필요한 생성기를 선택하고 프로젝트 생성을 시작하세요.

이 생성기가 구성하는 것

플러그인을 추가하면 워크스페이스가 플러그인의 생성기를 실행하는 데 필요한 결정론적 변경이 수행됩니다. 워크스페이스의 모듈 형식을 보존합니다: 루트 package.json에 type: "module"이 있는 워크스페이스는 ESM으로 유지되고, 그 외의 경우는 CommonJS로 유지되며, 생성된 코드도 이에 따릅니다. 기존 파일을 덮어쓰지 않으며, 기존 구성에 따라 이 단계 이후 일부 수동 변경이 필요할 수 있습니다.

다음 파일을 생성하거나 업데이트합니다:

aws-nx-plugin.config.mts 선택한 IaC 제공자(CDK 또는 Terraform)와 컨테이너 엔진을 기록합니다. 생성기는 여기에서 iac.provider를 읽습니다
nx.json compile 타겟에 동기화 생성기(@nx/js:typescript-sync 및 @aws/nx-plugin:ts#sync)를 등록하여 TypeScript 프로젝트 참조가 동기화 상태를 유지하도록 합니다
tsconfig.json 워크스페이스의 프로젝트를 참조하는 루트 TypeScript 구성으로, Nx의 TypeScript 동기화가 최신 상태로 유지합니다
tsconfig.base.json 플러그인의 TypeScript 프로젝트가 확장하는 공유 컴파일러 옵션(포함하는 내용은 아래 참조)
pnpm-workspace.yaml (pnpm만 해당) 플러그인의 종속성이 필요로 하는 빌드 스크립트(@swc/core, esbuild, nx, sharp)를 허용 목록에 추가합니다
package.json 일반적인 작업을 위한 편의 스크립트와 @aws/nx-plugin, @aws/nx-plugin-mcp, nx, @nx/js, @nx/workspace, typescript 및 Biome 개발 종속성을 추가합니다
biome.json 기본 Biome 포매터 및 린터 구성
.mcp.json 비활성화되지 않는 한 지원되는 코딩 에이전트를 위한 MCP 서버를 구성합니다(.cursor/, .kiro/, .gemini/, .vscode/ 및 .codex/ 동등물도 포함). 워크스페이스 자체의 @aws/nx-plugin-mcp를 실행하므로 서버는 항상 워크스페이스에 설치된 버전과 일치합니다

MCP 서버 구성은 --mcp=false로 비활성화할 수 있습니다.

생성된 tsconfig.base.json이 포함하는 컴파일러 옵션을 보려면 여기를 클릭하세요.

옵션

매개변수	타입	기본값	설명
iac	cdk \| terraform	cdk	선호하는 IaC 제공자입니다.
mcp	boolean	true	코딩 에이전트가 사용할 수 있도록 AWS MCP 서버용 Nx Plugin을 구성할지 여부입니다.
containers	infer \| docker \| finch	infer	빌드/푸시/로그인에 사용할 컨테이너 엔진입니다. 'infer'는 설치된 경우 docker를 선택하고, 그렇지 않으면 finch를 선택합니다(둘 다 설치되지 않은 경우 docker로 폴백).
preferInstallDependencies	boolean	true	제너레이터 실행 후 의존성 설치를 선호할지 여부입니다. 여러 제너레이터를 일괄 처리할 때 설치를 연기하려면 false로 설정하세요(후속 제너레이터가 Nx 프로젝트 그래프를 계산할 수 있도록 필요한 경우 설치는 여전히 실행됩니다). 마지막에 한 번 설치하세요.

문제 해결

기존 TypeScript 라이브러리에서 `nx build <project>`가 더 이상 작동하지 않음

첫 번째 ts#project 실행은 @nx/js/typescript 플러그인이 TypeScript 빌드 타겟을 compile로 추론하도록 구성합니다(플러그인은 lint, compile 및 test를 조율하기 위해 build를 예약합니다). 추론된 build 타겟에 의존하는 기존 라이브러리도 compile로 추론됩니다 — nx run <project>:compile을 실행하거나 nx run-many --target build,compile을 사용하세요. project.json에 명시적인 build 타겟이 있는 라이브러리는 영향을 받지 않습니다.

`The workspace is out of sync`

TypeScript 프로젝트 참조를 동기화해야 합니다. init은 동기화 생성기를 등록합니다. 실행하세요:

pnpm nx sync

yarn nx sync

npx nx sync

bunx nx sync

설치 중 `ERR_PNPM_IGNORED_BUILDS`

pnpm은 허용 목록에 없는 패키지의 설치 스크립트를 건너뜁니다. init은 플러그인의 도구가 필요로 하는 것(@swc/core, esbuild, nx, sharp)을 pnpm-workspace.yaml에서 허용 목록에 추가하지만, nx add @aws/nx-plugin 자체 중에 — init이 실행되기 전에 — 차단이 발생할 수 있습니다. pnpm approve-builds를 실행하고 나열된 패키지를 승인하거나(allowBuilds: 아래에 추가), 설치를 다시 실행하세요.

`nx sync`가 멈추거나 `plugin worker ... exited before the connection was established`

두 개의 다른 nx 버전이 동일한 node_modules 트리에 있으면(npm ls nx를 실행하여 확인), 플러그인-워커 IPC가 교착 상태에 빠집니다. init 생성기는 루트 nx devDependency를 플러그인 자체의 @nx/* 패키지가 해결하는 버전으로 고정하지만, 다른 패치 버전의 다른 @nx/* 패키지를 나중에 설치하면 불일치가 다시 발생할 수 있습니다. 루트 package.json의 모든 nx 및 @nx/* 항목을 단일 버전으로 정렬하고 재설치하세요.

`ts.readConfigFile is not a function`

워크스페이스에 TypeScript 7이 설치되어 있으며, Nx는 아직 이를 지원하지 않습니다 — Nx의 플러그인은 TypeScript의 인프로세스 컴파일러 API에 의존하는데, TypeScript 7은 더 이상 이를 제공하지 않습니다. 루트 package.json에서 typescript를 플러그인이 사용하는 버전으로 고정하고(init 생성기가 호환되는 버전을 설치함) 재설치하세요.

`Recursive task invocation detected`

루트 package.json이 Nx 프로젝트로 등록되어 있고("nx" 키가 있으며, nx init이 단일 패키지 레포에 추가함) nx run-many --target build의 build 스크립트를 가지고 있습니다. 그러면 Nx는 자신을 호출하는 루트에 build 타겟을 추론합니다. 소스를 packages/<your-package>/로 이동하여 루트가 프로젝트가 아닌 워크스페이스 매니페스트가 되도록 하세요 — 단일 패키지 프로젝트를 참조하세요. (Nx 자체의 독립형 프리셋은 루트 패키지에 "nx": { "includedScripts": [] }를 설정하여 이를 방지합니다. 더 빠른 대안으로 동일하게 수행할 수 있습니다.)

플러그인 추가 후 기존 프로젝트의 TypeScript 오류 (`TS6059`, `TS7016`, `TS5011`, `NG4006`)

플러그인 자체가 생성한 프로젝트는 프로젝트별 tsconfig.lib.json에 필요한 TypeScript 설정을 가지고 있으므로 tsconfig.base.json과 관계없이 빌드됩니다. 이러한 오류는 대신 init이 생성한 tsconfig.base.json(composite/emitDeclarationOnly/nodenext 포함)을 상속하지만 해당 설정과 호환되지 않는 기존 프로젝트에 나타납니다 — 예를 들어, Angular 컴파일러는 emitDeclarationOnly를 거부하거나(NG4006), rootDir 없이 outDir을 설정하는 프로젝트는 이제 하나가 필요합니다(TS5011). 해당 프로젝트에 대해 충돌하는 옵션을 다시 선언하는 프로젝트별 tsconfig 재정의를 추가하거나(예: "rootDir": "src"), 플러그인의 프로젝트와 프로젝트를 별도의 기본 구성으로 지정하세요.

init은 기존 tsconfig.base.json을 다시 작성하지 않습니다. 정확히 이를 상속하는 프로젝트를 조용히 깨뜨릴 수 없도록 하기 위함입니다 — 이러한 불일치를 해결하는 것은 코드베이스에 대해 귀하만이 내릴 수 있는 결정입니다.