빠른 시작 가이드

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

팁

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

사전 요구사항

진행 전 다음 전역 의존성이 필요합니다:

• Git
• Node >= 22 (NVM과 같은 도구로 Node 버전 관리 권장)
  • node --version 명령어로 버전 확인
• PNPM >= 10 (선호한다면 Yarn >= 4, Bun >= 1, NPM >= 10 사용 가능)
  • pnpm --version, yarn --version, bun --version, npm --version 명령어로 각각 버전 확인
• UV >= 0.5.29
  1. uv python install 3.12.0 명령어로 Python 3.12 설치
  2. uv python list --only-installed 명령어로 설치 확인
• 애플리케이션을 배포할 대상 AWS 계정에 설정된 AWS Credentials
• VSCode 사용 시 Nx Console VSCode Plugin 설치 권장

1단계: 새로운 Nx 워크스페이스 초기화

선택한 패키지 매니저로 Nx 워크스페이스를 생성합니다:

pnpm

npx create-nx-workspace@~20.6.3 my-project --pm=pnpm --preset=ts --ci=skip --formatter=prettier

yarn

npx create-nx-workspace@~20.6.3 my-project --pm=yarn --preset=ts --ci=skip --formatter=prettier

npm

npx create-nx-workspace@~20.6.3 my-project --pm=npm --preset=ts --ci=skip --formatter=prettier

bun

npx create-nx-workspace@~20.6.3 my-project --pm=bun --preset=ts --ci=skip --formatter=prettier

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

cd my-project

2단계: AWS용 Nx 플러그인 추가

플러그인 설치:

pnpm

pnpm add -Dw @aws/nx-plugin

yarn

yarn add -D @aws/nx-plugin

npm

npm install --legacy-peer-deps -D @aws/nx-plugin

bun

bun install -D @aws/nx-plugin

3단계: 생성기로 프로젝트 구성

이 빠른 시작에서는 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. 필수 매개변수 입력
   • apiName: demo-api
6. 클릭 Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#trpc-api --apiName=demo-api

yarn

yarn nx g @aws/nx-plugin:ts#trpc-api --apiName=demo-api

npm

npx nx g @aws/nx-plugin:ts#trpc-api --apiName=demo-api

bun

bunx nx g @aws/nx-plugin:ts#trpc-api --apiName=demo-api

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

pnpm

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

yarn

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

npm

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

bun

bunx nx g @aws/nx-plugin:ts#trpc-api --apiName=demo-api --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#cloudscape-website
5. 필수 매개변수 입력
   • name: demo-website
6. 클릭 Generate

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

bunx nx g @aws/nx-plugin:ts#cloudscape-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#cloudscape-website#auth
5. 필수 매개변수 입력
   • project: @my-project/demo-website
   • cognitoDomain: my-demo
6. 클릭 Generate

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

bunx nx g @aws/nx-plugin:ts#cloudscape-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-backend
6. 클릭 Generate

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

bunx nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api-backend --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 앱을 설정합니다.

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');
    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

5단계: 프론트엔드 로컬 실행

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

   pnpm

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

   yarn

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

   npm

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

   bun

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

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

   pnpm

   pnpm nx run @demo/demo-website:serve

   yarn

   yarn nx run @demo/demo-website:serve

   npm

   npx nx run @demo/demo-website:serve

   bun

   bunx nx run @demo/demo-website:serve

웹사이트는 http://localhost:4200에서 확인 가능합니다.

---

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