빠른 시작 가이드

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

사전 요구 사항

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

필수

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

권장

• PNPM >= 11 (원하는 경우 Yarn >= 4, Bun >= 1, 또는 NPM >= 11을 사용할 수도 있습니다)
  • 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 설치를 권장합니다.

1단계: 워크스페이스 생성

원하는 패키지 매니저로 Nx 워크스페이스를 생성하고, 생성된 디렉터리를 엽니다:

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

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

명령 구성하기3

workspace필수

iac

cdkterraform

containers

inferdockerfinch

cd my-project

코드형 인프라 제공자로 CDK 또는 Terraform 중 하나를 선택하라는 메시지가 표시됩니다.

2단계: 애플리케이션 빌드

풀스택 애플리케이션을 빌드합니다: tRPC API, React 웹사이트, Cognito 인증, 그리고 CDK 또는 Terraform 인프라. AI 어시스턴트에게 스캐폴딩을 요청하거나 제너레이터를 직접 실행하세요 — 두 방법 모두 동일한 워크스페이스에 도달합니다.

AI 사용

1. AI 코딩 어시스턴트에서 워크스페이스를 엽니다.

   새 워크스페이스에는 플러그인의 MCP server가 Kiro, Claude Code, Cursor, Gemini CLI, GitHub Copilot 및 OpenAI Codex에 대해 이미 구성되어 있으므로, 어시스턴트가 별도의 설정 없이 플러그인의 제너레이터를 조회하고 실행할 수 있습니다.

2. 애플리케이션을 요청합니다:

   Prompt

   Create a tRPC API called demo-api, and a React website called demo-website. Add Cognito authentication to the website, connect the website to the API, and add an infrastructure project called infra. Then instantiate the generated infrastructure components so the website and API deploy, granting authenticated users access to the API.

   어시스턴트는 MCP 서버를 통해 제너레이터를 발견하고 종속성이 필요한 순서대로 실행합니다. 변경 사항을 검토한 다음 3단계로 계속 진행하세요.

CLI 사용

애플리케이션을 스캐폴딩하는 제너레이터를 실행합니다. 아래 버튼을 사용하여 모두 복사하거나, 다이어그램 아래에 설명된 대로 각각을 직접 실행하세요.

CDK

Loading the diagram…

Terraform

Loading the diagram…

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

tRPC API 추가

이 제너레이터 실행@aws/nx-plugin:ts#api

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:ts#api --no-interactive

yarn

$ yarn nx g @aws/nx-plugin:ts#api --no-interactive

npm

$ npx nx g @aws/nx-plugin:ts#api --no-interactive

bun

$ bunx nx g @aws/nx-plugin:ts#api --no-interactive

VSCode

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

이 단계의 옵션2

name필수

framework

trpc

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

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

React 웹사이트 추가

이 제너레이터 실행@aws/nx-plugin:ts#website

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:ts#website --no-interactive

yarn

$ yarn nx g @aws/nx-plugin:ts#website --no-interactive

npm

$ npx nx g @aws/nx-plugin:ts#website --no-interactive

bun

$ bunx nx g @aws/nx-plugin:ts#website --no-interactive

VSCode

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

이 단계의 옵션1

name필수

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

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

Cognito 인증 추가

이 제너레이터 실행@aws/nx-plugin:ts#website#auth

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:ts#website#auth --no-interactive

yarn

$ yarn nx g @aws/nx-plugin:ts#website#auth --no-interactive

npm

$ npx nx g @aws/nx-plugin:ts#website#auth --no-interactive

bun

$ bunx nx g @aws/nx-plugin:ts#website#auth --no-interactive

VSCode

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

이 단계의 옵션1

project필수

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

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

프론트엔드와 백엔드 연결

이 제너레이터 실행@aws/nx-plugin:connection

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:connection --no-interactive

yarn

$ yarn nx g @aws/nx-plugin:connection --no-interactive

npm

$ npx nx g @aws/nx-plugin:connection --no-interactive

bun

$ bunx nx g @aws/nx-plugin:connection --no-interactive

VSCode

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

이 단계의 옵션2

sourceProject필수

targetProject필수

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

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

인프라 추가

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

CDK

이 제너레이터 실행@aws/nx-plugin:ts#infra

CLI

pnpm

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

yarn

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

npm

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

bun

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

VSCode

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

이 단계의 옵션1

name필수

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

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

Terraform

이 제너레이터 실행@aws/nx-plugin:terraform#project

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:terraform#project --no-interactive

yarn

$ yarn nx g @aws/nx-plugin:terraform#project --no-interactive

npm

$ npx nx g @aws/nx-plugin:terraform#project --no-interactive

bun

$ bunx nx g @aws/nx-plugin:terraform#project --no-interactive

VSCode

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

이 단계의 옵션1

name필수

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

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

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

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

pnpm

pnpm dev

yarn

yarn dev

npm

npm run dev

bun

bun dev

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

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

시도해보기: 웹사이트에서 API 호출하기

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

CDK

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

import {
  DemoApi,
  DemoWebsite,
  UserIdentity,
} from '@my-project/common-constructs';
import { Stack, StackProps } from 'aws-cdk-lib';
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를 열고 다음 코드를 추가합니다:

# 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]
}

# Print the website URL and user pool id when the deployment finishes
output "website_url" {
  value = module.demo_website.website_url
}

output "user_pool_id" {
  value = module.user_identity.user_pool_id
}

이것이 풀스택 애플리케이션을 배포하기 위해 작성해야 하는 모든 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

워크스페이스가 동기화되지 않음

빌드에서 The workspace is out of sync라고 보고하면, 워크스페이스를 동기화하라는 프롬프트를 수락하거나 빌드를 다시 시도하기 전에 다음 동기화 명령을 직접 실행하세요:

pnpm

pnpm nx sync

yarn

yarn nx sync

npm

npx nx sync

bun

bunx nx sync

이렇게 하면 임포트에 필요한 TypeScript 프로젝트 참조와 package.json 종속성 항목이 작성됩니다.

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

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 모두에 필요합니다. 다른 곳에 배포하는 경우 us-east-1도 부트스트랩하세요:

pnpm

pnpm nx run infra:bootstrap --args="aws://<account-id>/us-east-1"

yarn

yarn nx run infra:bootstrap --args="aws://<account-id>/us-east-1"

npm

npx nx run infra:bootstrap --args="aws://<account-id>/us-east-1"

bun

bunx nx run infra:bootstrap --args="aws://<account-id>/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 및 인증을 위해 배포한 리소스를 가리킵니다.

로그인하려면 Cognito 사용자 풀에서 사용자를 생성해야 합니다.

AWS CLI를 사용한 지침을 보려면 여기를 클릭하세요

웹사이트는 CloudFront에서도 제공됩니다. 배포 후 터미널에 출력되는 배포 도메인 이름을 열어 AWS에서 완전히 실행되는 버전을 사용하세요.

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

6단계: 정리

완료되면 지속적인 비용을 피하기 위해 배포한 리소스를 삭제합니다:

CDK

pnpm

pnpm nx destroy-sandbox infra

yarn

yarn nx destroy-sandbox infra

npm

npx nx destroy-sandbox infra

bun

bunx nx destroy-sandbox infra

보존된 리소스

Cognito 사용자 풀은 삭제 보호가 활성화된 상태로 생성되므로 자동으로 제거되지 않습니다. 더 이상 필요하지 않으면 사용자 풀과 Cognito가 SMS 메시지를 보내는 데 사용하는 IAM 역할을 수동으로 삭제하세요.

Terraform

pnpm

pnpm nx destroy infra

yarn

yarn nx destroy infra

npm

npx nx destroy infra

bun

bunx nx destroy infra

보존된 리소스

Cognito 사용자 풀은 삭제 보호가 활성화된 상태로 생성되므로 자동으로 제거되지 않습니다(destroy 명령이 실패를 보고합니다). 더 이상 필요하지 않으면 사용자 풀과 Cognito가 SMS 메시지를 보내는 데 사용하는 IAM 역할을 수동으로 삭제하세요.

부트스트랩 리소스를 제거하려면 아래를 따르세요:

CDK

us-east-1을 포함하여 부트스트랩한 모든 리전에서 부트스트랩 스택을 삭제합니다. 이렇게 하면 부트스트랩 역할과 컨테이너 이미지 리포지토리가 제거됩니다:

aws cloudformation delete-stack --stack-name CDKToolkit --region <region>

자산 버킷

자산 버킷은 의도적으로 보존되므로 별도로 삭제하세요.

Terraform

pnpm

pnpm nx bootstrap-destroy infra

yarn

yarn nx bootstrap-destroy infra

npm

npx nx bootstrap-destroy infra

bun

bunx nx bootstrap-destroy infra

Terraform 상태도 삭제됩니다

이 명령은 Terraform 상태를 보관하는 S3 버킷을 비우고 삭제하므로, 배포된 모든 인프라를 해체한 후에만 실행하세요.

---

다음 단계

• Dungeon Adventure Tutorial — 이 가이드보다 더 심화된 연습을 위해 풀스택 AI 던전 어드벤처 게임을 빌드합니다.
• Workspaces — 워크스페이스가 어떻게 배치되어 있는지, 그리고 제너레이터가 공유하는 구성에 대해 알아봅니다.
• Add to an Existing Project — 기존 코드베이스에 플러그인을 도입합니다.