빠른 시작 가이드

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

풀스택 튜토리얼

풀스택 애플리케이션 구축을 위한 더 심화된 튜토리얼은 Dungeon Adventure Tutorial을 확인하세요.

사전 요구 사항

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

필수

• Git
• Node >= 22 (NVM과 같은 도구를 사용하여 node 버전을 관리하는 것을 권장합니다)
  • node --version을 실행하여 확인하세요
• UV >= 0.5.29
  1. uv python install 3.14.0을 실행하여 Python 3.14를 설치하세요
  2. uv python list --only-installed로 확인하세요

권장

• PNPM >= 11 (원하는 경우 Yarn >= 4, Bun >= 1, 또는 NPM >= 10을 사용할 수도 있습니다)
  • pnpm --version, yarn --version, bun --version 또는 npm --version을 실행하여 확인하세요
• 애플리케이션을 배포하려면 (일부 로컬 개발 워크플로에도 필요) 대상 AWS 계정에 구성된 AWS Credentials가 필요합니다.
• 일부 생성기에는 Docker 또는 Finch >= 1.6.0이 필요합니다. Docker의 경우 멀티 플랫폼 빌드가 설정되어 있어야 하며, Finch는 기본적으로 멀티 플랫폼 빌드를 지원합니다.
• CDK 대신 인프라를 코드로 관리하기 위해 이것을 사용하려면 Terraform >= 1.12가 필요합니다
  • terraform --version을 실행하여 확인하세요
• VSCode를 사용하는 경우 Nx Console VSCode Plugin 설치를 권장합니다.

AI 어시스턴트 설정

Kiro, Kiro CLI, Cursor, Claude Code 또는 Cline과 같은 AI 어시스턴트를 사용하는 경우, Nx Plugin for AWS MCP 서버를 설치하는 것도 고려해 볼 수 있습니다.

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

다음 명령을 실행하여 원하는 패키지 매니저로 Nx 워크스페이스를 생성합니다:

pnpm

pnpm create @aws/nx-workspace my-project

yarn

yarn create @aws/nx-workspace my-project

npm

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

bun

bun create @aws/nx-workspace my-project

IaC 제공자 선택

선호하는 코드형 인프라(IaC) 제공자로 CDK 또는 Terraform 중 하나를 선택하라는 메시지가 표시됩니다. --iac 옵션과 함께 명령을 실행하여 프롬프트를 건너뛸 수 있습니다:

CDK

pnpm

pnpm create @aws/nx-workspace my-project --iac=cdk

yarn

yarn create @aws/nx-workspace my-project --iac=cdk

npm

npm create @aws/nx-workspace -- my-project --iac=cdk

bun

bun create @aws/nx-workspace my-project --iac=cdk

Terraform

pnpm

pnpm create @aws/nx-workspace my-project --iac=terraform

yarn

yarn create @aws/nx-workspace my-project --iac=terraform

npm

npm create @aws/nx-workspace -- my-project --iac=terraform

bun

bun create @aws/nx-workspace my-project --iac=terraform

완료되면 프로젝트 디렉터리로 이동합니다:

cd my-project

2단계: 제너레이터를 사용하여 프로젝트 스캐폴딩

이 빠른 시작 가이드에서는 tRPC API, React 웹사이트, Cognito 인증, 그리고 CDK 또는 Terraform 인프라를 추가합니다. 구축하는 프로젝트 유형에 따라 제너레이터의 조합을 선택하여 프로젝트를 빠르게 부트스트랩할 수 있습니다. 왼쪽 탐색 바의 __Generators__를 확인하여 전체 옵션 목록을 보거나, 그래프 빌더를 사용하여 워크스페이스를 시각적으로 구성해 보세요.

단축키로 아래 버튼을 사용하여 전체 애플리케이션을 스캐폴딩하는 명령을 복사할 수 있습니다.

Loading the diagram…

AI로 빌드하기

Nx Plugin for AWS MCP Server가 이미 워크스페이스에 구성되어 있으므로, CLI 명령을 직접 입력하는 대신 Kiro나 Claude와 같은 좋아하는 AI 코딩 에이전트에게 이러한 프로젝트를 빌드하도록 요청할 수 있습니다.

그렇지 않으면 아래 단계를 따라 각 제너레이터를 직접 실행하세요.

tRPC API 추가

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive

yarn

yarn nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive

npm

npx nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive

bun

bunx nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive

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

pnpm

pnpm nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive --dry-run

npm

npx nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive --dry-run

bun

bunx nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive --dry-run

VSCode

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

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

React 웹사이트 추가

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

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

VSCode

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

이렇게 하면 packages/demo-website에 새 React 웹사이트가 스캐폴딩됩니다.

Cognito 인증 추가

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

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

VSCode

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

이렇게 하면 웹사이트에 Cognito 인증을 추가하는 데 필요한 인프라와 React 코드가 설정됩니다.

프론트엔드와 백엔드 연결

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

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

VSCode

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

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

인프라 추가

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

CDK

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

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

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

이렇게 하면 AWS에 인프라를 배포하는 데 사용할 수 있는 CDK 앱이 구성됩니다.

Terraform

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

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

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

이렇게 하면 AWS에 인프라를 배포하는 데 사용할 수 있는 Terraform 프로젝트가 구성됩니다.

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

다음 명령을 사용하여 웹사이트와 연결된 API에 대한 로컬 개발 서버를 시작합니다:

pnpm

pnpm dev

yarn

yarn dev

npm

npm run dev

bun

bun dev

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

로컬 웹사이트와 API 서버가 모두 핫 리로드되므로 웹사이트와 API 모두의 변경 사항이 실시간으로 반영됩니다.

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

CDK

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

import { Stack, StackProps } from 'aws-cdk-lib';
import { DemoApi, DemoWebsite, UserIdentity } from '@my-project/common-constructs';
import { Construct } from 'constructs';

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string, props?: 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를 열고 다음 코드를 추가합니다:

# Include metrics tracking for @aws/nx-plugin usage
module "metrics" {
  source = "../../common/terraform/src/metrics"
}

# Deploy user identity
module "user_identity" {
  source = "../../common/terraform/src/core/user-identity"
}

# Shared asset bucket — stages Lambda deployment zips for every lambda / API module
module "asset_bucket" {
  source = "../../common/terraform/src/core/asset-bucket"
}

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

  asset_bucket_name = module.asset_bucket.bucket_name
}

# Grant authenticated users access to invoke the API
resource "aws_iam_policy" "api_invoke_policy" {
  name        = "DemoApiInvokePolicy"
  description = "Policy to allow authenticated users to invoke the 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
}

# Deploy website
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 build

yarn

yarn build

npm

npm run build

bun

bun build

린트 오류 수정

린트 오류가 발생하면 다음 명령을 실행하여 자동으로 수정할 수 있습니다.

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

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

CDK

pnpm

pnpm nx bootstrap infra

yarn

yarn nx bootstrap infra

npm

npx nx bootstrap infra

bun

bunx nx bootstrap infra

부트스트랩 리전

CDK 부트스트래핑은 대상 배포 AWS 리전과 웹사이트용 AWS WAF WebACL 배포를 허용하기 위한 us-east-1 모두에 필요합니다.

Terraform

pnpm

pnpm nx bootstrap infra

yarn

yarn nx bootstrap infra

npm

npx nx bootstrap infra

bun

bunx nx bootstrap infra

일회성 설정

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

프로젝트를 배포합니다:

CDK

pnpm

pnpm nx deploy-sandbox infra

yarn

yarn nx deploy-sandbox infra

npm

npx nx deploy-sandbox infra

bun

bunx nx deploy-sandbox infra

Terraform

pnpm

pnpm nx apply infra

yarn

yarn nx apply infra

npm

npx nx apply infra

bun

bunx nx apply infra

적용 전 계획

이 명령은 먼저 terraform plan을 실행하여 어떤 변경 사항이 적용될지 보여준 다음, 해당 변경 사항을 적용하여 인프라를 배포합니다.

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

1. runtime-config.json 파일을 가져옵니다:

   pnpm

   pnpm nx load-runtime-config demo-website

   yarn

   yarn nx load-runtime-config demo-website

   npm

   npx nx load-runtime-config demo-website

   bun

   bunx nx load-runtime-config demo-website

2. 로컬 웹사이트 서버를 시작합니다

   pnpm

   pnpm nx serve demo-website

   yarn

   yarn nx serve demo-website

   npm

   npx nx serve demo-website

   bun

   bunx nx serve demo-website

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

---

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