빠른 시작 가이드

이 가이드는 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

팁

인프라스트럭처 코드(IaC) 제공자로 CDK 또는 Terraform을 선택할 수 있습니다. --iacProvider 플래그를 사용하면 프롬프트를 건너뛸 수 있습니다:

CDK

pnpm

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

yarn

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

npm

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

bun

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

Terraform

pnpm

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

yarn

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

npm

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

bun

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

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

cd my-project

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

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

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를 호출할 수 있도록 필요한 프로바이더를 구성합니다.

인프라 추가

선택한 IaC 제공자에 따라 인프라 프로젝트를 추가합니다.

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 앱을 구성합니다.

Terraform

VSCode

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

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

이 명령은 AWS에 인프라를 배포하는 데 사용할 Terraform 프로젝트를 구성합니다.

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 배포

CDK

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 구성을 포함합니다.

Terraform

packages/infra/src/main.tf를 열고 다음 코드를 추가하세요:

# @aws/nx-plugin 사용 메트릭 추적 포함
module "metrics" {
  source = "../../common/terraform/src/metrics"
}

# 사용자 신원 배포
module "user_identity" {
  source = "../../common/terraform/src/core/user-identity"
}

# API 배포
module "demo_api" {
  source = "../../common/terraform/src/app/apis/demo-api"
}

# 인증된 사용자의 API 호출 권한 부여
resource "aws_iam_policy" "api_invoke_policy" {
  name        = "DemoApiInvokePolicy"
  description = "인증된 사용자가 API를 호출할 수 있도록 하는 정책"

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect = "Allow"
        Action = "execute-api:Invoke"
        Resource = "${module.demo_api.api_execution_arn}/*/*"
      }
    ]
  })
}

resource "aws_iam_role_policy_attachment" "authenticated_api_access" {
  role       = module.user_identity.authenticated_role_name
  policy_arn = aws_iam_policy.api_invoke_policy.arn
}

# 웹사이트 배포
provider "aws" {
  alias  = "us_east_1"
  region = "us-east-1"
}

module "demo_website" {
  source = "../../common/terraform/src/app/static-websites/demo-website"

  providers = {
    aws.us_east_1 = aws.us_east_1
  }

  depends_on = [module.user_identity, module.demo_api]
}

이 코드는 풀스택 애플리케이션 배포에 필요한 모든 Terraform 구성을 포함합니다.

인프라 빌드 및 배포

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

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

인프라를 부트스트랩합니다:

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

팁

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

Terraform

pnpm

pnpm nx run infra:bootstrap

yarn

yarn nx run infra:bootstrap

npm

npx nx run infra:bootstrap

bun

bunx nx run infra:bootstrap

팁

Terraform 부트스트랩은 Terraform 상태 파일을 저장할 S3 버킷을 생성합니다. 이 작업은 AWS 계정/리전 조합당 한 번만 수행하면 됩니다.

프로젝트를 배포합니다:

CDK

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/*

Terraform

pnpm

pnpm nx run infra:apply

yarn

yarn nx run infra:apply

npm

npx nx run infra:apply

bun

bunx nx run infra:apply

팁

이 명령은 먼저 terraform plan으로 변경 사항을 확인한 후 인프라에 변경 사항을 적용합니다.

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을 사용하여 풀스택 애플리케이션을 성공적으로 구축하고 배포했습니다!