워크스페이스

@aws/nx-plugin으로 새 워크스페이스를 생성하면, 프리셋 제너레이터가 AWS에서 빌드하기 위한 합리적인 기본값으로 Nx 모노레포를 설정합니다.

워크스페이스 생성

워크스페이스 생성@aws/nx-workspace

$ pnpm create @aws/nx-workspace my-project

$ yarn create @aws/nx-workspace my-project

$ npm create @aws/nx-workspace -- my-project

$ bun create @aws/nx-workspace my-project

명령 구성하기8

workspace필수

iac

containers

gitSecrets

true

mcp

true

module

catalog

true

preferInstallDependencies

true

옵션

제너레이터 옵션7 옵션

iacenum기본값: cdk: 선호하는 IaC 제공자입니다.
cdkterraform
containersenum기본값: infer: 빌드/푸시/로그인에 사용할 컨테이너 엔진입니다. 'infer'는 설치된 경우 docker를 선택하고, 그렇지 않으면 finch를 선택합니다(둘 다 설치되지 않은 경우 docker로 대체).
inferdockerfinch
gitSecretsboolean기본값: true: AWS 자격 증명 커밋을 방지하기 위해 git-secrets를 구성할지 여부입니다.
mcpboolean기본값: true: 코딩 에이전트가 사용할 수 있도록 AWS MCP 서버용 Nx Plugin을 구성할지 여부입니다.
moduleenum기본값: esm: 생성된 TypeScript 코드 및 구성의 모듈 형식입니다.
esmcjs
catalogboolean기본값: true: 생성기가 패키지 매니저의 카탈로그(pnpm/yarn/bun)에 의존성 버전을 기록하여 버전에 대한 단일 진실 공급원을 유지할지 여부입니다. false인 경우 의존성은 각 프로젝트의 package.json에 직접 작성되며 버전 정렬 유지는 사용자의 책임입니다.
preferInstallDependenciesboolean기본값: true: 생성기 실행 후 의존성 설치를 선호할지 여부입니다. 여러 생성기를 일괄 처리할 때 설치를 연기하려면 false로 설정하세요 (후속 생성기가 Nx 프로젝트 그래프를 계산할 수 있도록 필요한 경우 설치는 여전히 실행됩니다); 마지막에 한 번만 설치합니다.

워크스페이스 구조

디렉터리packages/ Your projects live here
- …
package.json Root package.json for your monorepo
nx.json Nx configuration (common targets, sync generators, caching)
tsconfig.base.json Root TypeScript configuration
biome.json Biome configuration for linting and formatting
aws-nx-plugin.config.mts Nx Plugin for AWS configuration
디렉터리.git-secrets/ Vendored git-secrets bash script for credential scanning
- …
.gitallowed Patterns git-secrets treats as false positives
디렉터리.husky/ Git hooks
- …
.mcp.json Nx Plugin for AWS MCP server configuration for Claude Code
.cursor/mcp.json …and for Cursor
.kiro/settings/mcp.json …and for Kiro
.gemini/settings.json …and for Gemini CLI
.vscode/mcp.json …and for GitHub Copilot
.codex/config.toml …and for OpenAI Codex

Nx

Nx는 모노레포를 위한 언어 독립적인 빌드 시스템으로, 모든 프로그래밍 언어로 작성된 프로젝트 간의 종속성과 이를 빌드하는 작업을 관리합니다. Nx 웹사이트에서 자세히 알아볼 수 있습니다.

프로젝트

Nx 모노레포는 하나 이상의 프로젝트로 구성되며, 각 프로젝트에는 project.json 파일이 있습니다. project.json은 프로젝트의 작업(_타겟_이라고 함)을 정의하며, 이는 프로젝트가 빌드되고, 로컬에서 실행되고, 테스트되는 방법 등을 정의합니다. 또한 프로젝트 내부 또는 프로젝트 간 타겟 간의 종속성을 정의합니다.

예를 들어, project.json은 모든 업스트림 프로젝트가 먼저 빌드되어야 하는 build 타겟을 정의할 수 있습니다:

{
  "name": "@my-workspace/my-project",
  "targets": {
    "build": {
      "executor": "@nx/js:tsc",
      "dependsOn": ["^build"]
    },
    "test": {
      "command": "vitest run"
    }
  }
}

TypeScript 및 Python 프로젝트가 설정되는 방법에 대한 자세한 내용은 ts#project 및 py#project 제너레이터 가이드를 참조하세요.

캐싱

Nx는 이전에 실행된 타겟의 출력을 캐시하고 입력이 변경되지 않았을 때 이를 재생합니다. 이는 빌드, 테스트 및 린팅 속도를 크게 향상시킵니다. 오래되거나 예상치 못한 동작이 발생하면 다음 명령으로 캐시를 재설정하세요:

pnpm nx reset

yarn nx reset

npx nx reset

bunx nx reset

자세한 내용은 Nx 캐싱 문서를 참조하세요.

병렬 처리

새 워크스페이스는 nx.json에 parallel을 설정하며, 이는 Nx가 동시에 실행하는 작업 수를 제어합니다:

{
  "parallel": 8
}

코어가 적거나 메모리가 제한된 머신에서 빌드하는 경우 이를 낮추세요. 호출당 재정의할 수도 있습니다:

pnpm nx run-many --target build --parallel=4

yarn nx run-many --target build --parallel=4

npx nx run-many --target build --parallel=4

bunx nx run-many --target build --parallel=4

단일 버전 정책

기본 모노레포 설정은 Node 및 Python 기반 프로젝트 모두에 대해 단일 버전 정책을 사용합니다.

이는 모노레포 내의 모든 프로젝트가 기본적으로 동일한 버전의 종속성을 사용한다는 것을 의미하며, 동일한 모노레포의 패키지가 버전 불일치 문제에 직면하는 것과 관련된 문제를 줄입니다.

Node 관점에서 이는 루트에 단일 lockfile이 있고, 종속성이 한 번 설치되어 각 프로젝트에 링크된다는 것을 의미합니다. 각 Node 프로젝트는 소스가 가져오는 런타임 종속성을 자체 package.json에 선언하고, 공유 빌드/테스트 도구는 루트 package.json의 devDependencies에 있습니다. 프로젝트의 런타임 종속성을 추가하려면 해당 프로젝트에 설치하세요:

pnpm add some-npm-package --filter my-project

yarn workspace @my-scope/my-project add some-npm-package

npm install --legacy-peer-deps some-npm-package -w packages/my-project

bun add some-npm-package --cwd packages/my-project

카탈로그 지원이 있는 패키지 매니저(pnpm, yarn 및 bun)의 경우, 종속성 버전이 카탈로그에 기록되고 catalog: 프로토콜로 참조되어 모든 프로젝트의 package.json에서 버전에 대한 단일 진실 공급원을 유지합니다. npm 워크스페이스의 경우, 여러 package.json 파일에 선언된 버전을 정렬하기 위해 syncpack을 권장합니다.

Python 관점에서 이는 모노레포의 루트에 단일 .venv가 있고 모든 종속성이 여기에 설치된다는 것을 의미합니다. 각 Python 프로젝트에는 자체 pyproject.toml이 있지만, 이러한 종속성의 버전은 UV 워크스페이스에서 관리되고 이후 루트의 uv.lock 파일에 기록됩니다.

일반 명령

빌드

워크스페이스의 모든 프로젝트 빌드:

pnpm build

yarn build

npm run build

bun build

린트

모든 프로젝트 린트 및 자동 수정:

pnpm lint

yarn lint

npm run lint

bun lint

테스트

모든 프로젝트에서 테스트 실행:

pnpm test

yarn test

npm run test

bun test

개발

워크스페이스 전체의 모든 로컬 개발 서버 시작:

pnpm dev

yarn dev

npm run dev

bun dev

자세한 내용은 로컬 개발 가이드를 참조하세요.

동기화

동기화 제너레이터를 실행합니다. 예를 들어 TypeScript 프로젝트 참조를 동기화합니다(자세한 내용은 ts#project 제너레이터 가이드 참조):

pnpm nx sync

yarn nx sync

npx nx sync

bunx nx sync

특정 타겟 실행

다음 명령으로 특정 프로젝트에 대한 특정 타겟을 실행할 수 있습니다:

pnpm nx <target> <project>

yarn nx <target> <project>

npx nx <target> <project>

bunx nx <target> <project>

예를 들어:

pnpm nx build website

yarn nx build website

npx nx build website

bunx nx build website

이렇게 하면 선택한 타겟과 이에 종속된 타겟이 실행됩니다.

포함된 내용

린팅

새 워크스페이스는 정적 분석 및 코드 포맷팅을 위해 Biome으로 구성됩니다. lint를 실행하면 모든 프로젝트에서 문제를 확인하고, lint --configuration=fix는 이를 자동으로 수정합니다.

MCP 구성

플러그인의 MCP 서버는 Claude Code, Cursor, Kiro, Gemini CLI, GitHub Copilot 및 OpenAI Codex를 위한 프로젝트 수준 MCP 서버로 구성되어 있어, 코딩 어시스턴트가 별도의 설정 없이 플러그인의 제너레이터를 발견하고 실행할 수 있습니다. 구성은 워크스페이스와 함께 커밋되므로 팀의 모든 사람이 동일한 설정을 갖게 됩니다. 귀하와 귀하의 팀이 사용하지 않는 코딩 어시스턴트에 대한 구성은 제거하세요.

Git Secrets

워크스페이스는 각 커밋 전에 스테이징된 파일에서 AWS 자격 증명 패턴을 스캔하는 git-secrets 사전 커밋 훅으로 설정됩니다. 이는 액세스 키, 시크릿 키 및 기타 민감한 값을 실수로 커밋하는 것을 방지합니다.

스크립트는 .git-secrets/git-secrets에 워크스페이스에 포함되어 있으며 .husky/pre-commit 훅에 의해 실행되므로 설치할 것이 없습니다. 하지만 PATH에 없으므로 git secrets가 아닌 경로로 호출하세요.

거짓 양성 억제

git-secrets의 패턴은 egrep 호환 정규 표현식을 사용합니다. git-secrets가 실제 자격 증명을 포함하지 않는 커밋을 차단하는 경우:

# Allow a specific regex pattern (-a is the allowed flag)
bash .git-secrets/git-secrets --add -a -- 'my-regex-pattern'

# Allow a literal string, escaping special characters (-l is the literal flag)
bash .git-secrets/git-secrets --add -a -l -- 'my-literal+string'

# List what is currently allowed
git config --get-all secrets.allowed

이들은 로컬 git 구성에 기록되므로 자신의 클론에만 적용됩니다. 팀과 억제를 공유하려면 대신 리포지토리 루트의 .gitallowed 파일에 추가하세요. 한 줄에 하나의 egrep 호환 정규식을 작성하며, <path>:<line-number>:<line-contents>와 일치합니다:

# Allow test fixtures
tests/fixtures/.*
# Allow a specific string
EXAMPLE[A-Z]{16}

패턴 관리에 대한 전체 세부 정보는 git-secrets 문서를 참조하세요.

Nx Plugin for AWS 구성

워크스페이스는 루트에 aws-nx-plugin.config.mts 파일과 함께 제공됩니다. 제너레이터는 이 파일을 읽어 합리적인 기본값을 선택하므로 매번 동일한 플래그를 전달할 필요가 없습니다:

// aws-nx-plugin.config.mts
import { AwsNxPluginConfig } from '@aws/nx-plugin';

export default {
  iac: {
    provider: 'cdk', // or 'terraform'
  },
  containers: {
    engine: 'docker', // or 'finch'
  },
  packageManager: {
    catalogs: true, // or false
  },
} satisfies AwsNxPluginConfig;

iac.provider — 인프라를 생성하는 제너레이터(예: ts#infra, ts#api, py#api)에서 사용하는 기본 Infrastructure-as-Code 공급자(cdk 또는 terraform). --iac 플래그를 허용하는 제너레이터는 기본적으로 inherit로 설정되며, 이 값을 읽습니다.
containers.engine — 생성된 빌드/푸시/로그인 명령에 포함되는 컨테이너 CLI(docker 또는 finch). CDK 이미지 자산 빌드도 CDK_DOCKER 환경 변수를 통해 이를 선택합니다. 자세한 내용은 Docker 번들링 가이드를 참조하세요.
packageManager.catalogs — 제너레이터가 패키지 매니저의 카탈로그에 종속성 버전을 기록하고 catalog: 프로토콜로 참조할지 여부(단일 버전 정책 참조). false로 설정하면 제너레이터가 각 프로젝트의 package.json에 직접 버전 범위를 작성합니다. 카탈로그가 없는 npm에는 영향을 미치지 않습니다.

license 제너레이터는 자체 동작을 구성하기 위해 이 동일한 파일에 license 키를 추가합니다.

언제든지 모든 설정을 편집할 수 있으며, 이후 제너레이터 실행 시 새 값을 선택합니다.