빠른 시작 가이드

이 가이드는 AWS에서 프로젝트를 빠르게 구축하기 위해 @aws/nx-plugin 설치 및 사용 기본 사항을 안내합니다.

팁

전체 스택 애플리케이션 구축에 대한 심층적인 튜토리얼은 던전 어드벤처 튜토리얼을 참조하세요.

필수 조건

진행 전 다음 전역 종속성이 필요합니다:

필수 요구사항

• Git
• Node >= 22 (버전 관리를 위해 NVM 사용을 권장합니다)
  • 설치 확인: node --version
• PNPM >= 10 (Yarn >= 4, Bun >= 1, 또는 NPM >= 10 사용도 가능)
  • 설치 확인: pnpm --version, yarn --version, bun --version 또는 npm --version
• UV >= 0.5.29
  1. Python 3.12 설치: uv python install 3.12.0
  2. 설치 확인: uv python list --only-installed
• 애플리케이션 배포 대상 AWS 계정에 구성된 AWS Credentials

권장 사항

• 일부 생성기 사용 시 Docker 필요
• CDK 대신 인프라 코드로 Terraform >= 1.12 사용 시 필수
  • 설치 확인: terraform --version
• VSCode 사용 시 Nx Console VSCode Plugin 설치 권장

팁

Amazon Q Developer, Cursor, Claude Code 또는 Cline과 같은 AI 어시스턴트를 사용하는 경우 Nx Plugin for AWS MCP server 설치를 고려해 보세요.

1단계: 새 Nx 작업 공간 초기화

원하는 패키지 매니저로 Nx 작업 공간을 생성하려면 다음 명령어를 실행하세요:

pnpm

npx create-nx-workspace@~21.4.1 my-project --pm=pnpm --preset=@aws/nx-plugin --ci=skip

yarn

npx create-nx-workspace@~21.4.1 my-project --pm=yarn --preset=@aws/nx-plugin --ci=skip

npm

npx create-nx-workspace@~21.4.1 my-project --pm=npm --preset=@aws/nx-plugin --ci=skip

bun

npx create-nx-workspace@~21.4.1 my-project --pm=bun --preset=@aws/nx-plugin --ci=skip

완료 후 프로젝트 디렉토리로 이동합니다:

cd my-project

2단계: 생성기를 사용하여 프로젝트 스캐폴딩

이 빠른 시작 가이드에서는 tRPC API, React 웹사이트, Cognito 인증 및 CDK 인프라를 추가합니다. 프로젝트 유형에 따라 원하는 생성기 조합을 선택하여 프로젝트를 빠르게 부트스트랩할 수 있습니다. 왼쪽 탐색 바의 가이드 에서 전체 옵션 목록을 확인하세요.

tRPC API 추가

VSCode

1. 설치 Nx Console VSCode Plugin 아직 설치하지 않았다면
2. VSCode에서 Nx 콘솔 열기
3. 클릭 Generate (UI) "Common Nx Commands" 섹션에서
4. 검색 @aws/nx-plugin - ts#trpc-api
5. 필수 매개변수 입력
   • name: demo-api
   • auth: IAM
6. 클릭 Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM

yarn

yarn nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM

npm

npx nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM

bun

bunx nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM

어떤 파일이 변경될지 확인하기 위해 드라이 런을 수행할 수도 있습니다

pnpm

pnpm nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM --dry-run

npm

npx nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM --dry-run

bun

bunx nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM --dry-run

이렇게 하면 packages/demo-api 폴더 내에 API가 생성됩니다.

React 웹사이트 추가

VSCode

1. 설치 Nx Console VSCode Plugin 아직 설치하지 않았다면
2. VSCode에서 Nx 콘솔 열기
3. 클릭 Generate (UI) "Common Nx Commands" 섹션에서
4. 검색 @aws/nx-plugin - ts#react-website
5. 필수 매개변수 입력
   • name: demo-website
6. 클릭 Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#react-website --name=demo-website

yarn

yarn nx g @aws/nx-plugin:ts#react-website --name=demo-website

npm

npx nx g @aws/nx-plugin:ts#react-website --name=demo-website

bun

bunx nx g @aws/nx-plugin:ts#react-website --name=demo-website

어떤 파일이 변경될지 확인하기 위해 드라이 런을 수행할 수도 있습니다

pnpm

pnpm nx g @aws/nx-plugin:ts#react-website --name=demo-website --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#react-website --name=demo-website --dry-run

npm

npx nx g @aws/nx-plugin:ts#react-website --name=demo-website --dry-run

bun

bunx nx g @aws/nx-plugin:ts#react-website --name=demo-website --dry-run

packages/demo-website에 새 React 웹사이트를 스캐폴딩합니다.

Cognito 인증 추가

VSCode

1. 설치 Nx Console VSCode Plugin 아직 설치하지 않았다면
2. VSCode에서 Nx 콘솔 열기
3. 클릭 Generate (UI) "Common Nx Commands" 섹션에서
4. 검색 @aws/nx-plugin - ts#react-website#auth
5. 필수 매개변수 입력
   • project: @my-project/demo-website
   • cognitoDomain: my-demo
6. 클릭 Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#react-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo

yarn

yarn nx g @aws/nx-plugin:ts#react-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo

npm

npx nx g @aws/nx-plugin:ts#react-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo

bun

bunx nx g @aws/nx-plugin:ts#react-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo

어떤 파일이 변경될지 확인하기 위해 드라이 런을 수행할 수도 있습니다

pnpm

pnpm nx g @aws/nx-plugin:ts#react-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#react-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --dry-run

npm

npx nx g @aws/nx-plugin:ts#react-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --dry-run

bun

bunx nx g @aws/nx-plugin:ts#react-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --dry-run

웹사이트에 Cognito 인증을 추가하기 위한 인프라 및 React 코드를 설정합니다.

프론트엔드-백엔드 연결

VSCode

1. 설치 Nx Console VSCode Plugin 아직 설치하지 않았다면
2. VSCode에서 Nx 콘솔 열기
3. 클릭 Generate (UI) "Common Nx Commands" 섹션에서
4. 검색 @aws/nx-plugin - api-connection
5. 필수 매개변수 입력
   • sourceProject: @my-project/demo-website
   • targetProject: @my-project/demo-api
6. 클릭 Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api

yarn

yarn nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api

npm

npx nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api

bun

bunx nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api

어떤 파일이 변경될지 확인하기 위해 드라이 런을 수행할 수도 있습니다

pnpm

pnpm nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --dry-run

yarn

yarn nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --dry-run

npm

npx nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --dry-run

bun

bunx nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --dry-run

웹사이트가 tRPC API를 호출할 수 있도록 필요한 프로바이더를 구성합니다.

CDK 인프라 추가

VSCode

1. 설치 Nx Console VSCode Plugin 아직 설치하지 않았다면
2. VSCode에서 Nx 콘솔 열기
3. 클릭 Generate (UI) "Common Nx Commands" 섹션에서
4. 검색 @aws/nx-plugin - ts#infra
5. 필수 매개변수 입력
   • name: infra
6. 클릭 Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#infra --name=infra

yarn

yarn nx g @aws/nx-plugin:ts#infra --name=infra

npm

npx nx g @aws/nx-plugin:ts#infra --name=infra

bun

bunx nx g @aws/nx-plugin:ts#infra --name=infra

어떤 파일이 변경될지 확인하기 위해 드라이 런을 수행할 수도 있습니다

pnpm

pnpm nx g @aws/nx-plugin:ts#infra --name=infra --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#infra --name=infra --dry-run

npm

npx nx g @aws/nx-plugin:ts#infra --name=infra --dry-run

bun

bunx nx g @aws/nx-plugin:ts#infra --name=infra --dry-run

AWS에 인프라를 배포하는 데 사용할 CDK 앱을 구성합니다.

3단계: 로컬에서 웹사이트 및 API 실행

다음 명령어로 웹사이트와 연결된 API의 로컬 개발 서버를 시작하세요:

pnpm

pnpm nx run demo-website:serve-local

yarn

yarn nx run demo-website:serve-local

npm

npx nx run demo-website:serve-local

bun

bunx nx run demo-website:serve-local

웹사이트는 http://localhost:4200에서 확인할 수 있습니다.

웹사이트와 API 모두 변경 사항이 실시간으로 반영됩니다(핫 리로드 지원).

4단계: 클라우드 리소스 정의 및 AWS 배포

packages/infra/src/stacks/application-stack.ts를 열고 다음 코드를 추가하세요:

import * as cdk from 'aws-cdk-lib';
import { DemoApi, DemoWebsite, UserIdentity } from ':my-project/common-constructs';
import { Construct } from 'constructs';

export class ApplicationStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const identity = new UserIdentity(this, 'identity');
    const api = new DemoApi(this, 'api', {
      integrations: DemoApi.defaultIntegrations(this).build(),
    });
    api.grantInvokeAccess(identity.identityPool.authenticatedRole);

    new DemoWebsite(this, 'website');
  }
}

전체 스택 애플리케이션 배포에 필요한 모든 CDK 코드입니다.

인프라 빌드 및 배포

프로젝트 빌드를 위해 다음 명령어를 실행하세요:

pnpm

pnpm nx run-many --target build --all

yarn

yarn nx run-many --target build --all

npm

npx nx run-many --target build --all

bun

bunx nx run-many --target build --all

팁

린트 오류 발생 시 다음 명령어로 자동 수정 가능합니다.

pnpm

pnpm nx run-many --target lint --configuration=fix --all

yarn

yarn nx run-many --target lint --configuration=fix --all

npm

npx nx run-many --target lint --configuration=fix --all

bun

bunx nx run-many --target lint --configuration=fix --all

배포 명령어:

pnpm

pnpm nx run infra:deploy my-project-sandbox/*

yarn

yarn nx run infra:deploy my-project-sandbox/*

npm

npx nx run infra:deploy my-project-sandbox/*

bun

bunx nx run infra:deploy my-project-sandbox/*

팁

CDK 배포를 위해 AWS 환경이 적절히 부트스트랩되어 있어야 합니다.

웹사이트의 AWS WAF WebACL 배포를 위해 대상 AWS 리전과 us-east-1 모두에서 CDK 부트스트랩이 필요합니다.

pnpm

pnpm nx run infra:bootstrap

yarn

yarn nx run infra:bootstrap

npm

npx nx run infra:bootstrap

bun

bunx nx run infra:bootstrap

5단계: 배포된 클라우드 리소스로 웹사이트 테스트

1. runtime-config.json 파일 가져오기:

   pnpm

   pnpm nx run demo-website:load:runtime-config

   yarn

   yarn nx run demo-website:load:runtime-config

   npm

   npx nx run demo-website:load:runtime-config

   bun

   bunx nx run demo-website:load:runtime-config

2. 로컬 웹사이트 서버 시작

   pnpm

   pnpm nx run demo-website:serve

   yarn

   yarn nx run demo-website:serve

   npm

   npx nx run demo-website:serve

   bun

   bunx nx run demo-website:serve

웹사이트는 http://localhost:4200에서 확인할 수 있으며, 배포된 API 및 인증 리소스를 가리킵니다.

---

축하합니다! 🎉 @aws/nx-plugin을 사용하여 전체 스택 애플리케이션을 성공적으로 구축하고 배포했습니다!