React 웹사이트

이 생성기는 기본적으로 shadcn/ui가 구성된 새로운 React 웹사이트와 S3에 호스팅된 정적 웹사이트를 CloudFront로 서비스하고 WAF로 보호하는 클라우드 배포 인프라를 AWS CDK 또는 Terraform으로 생성합니다.

생성된 애플리케이션은 빌드 도구 및 번들러로 Vite를 사용하며, 타입 안전 라우팅을 위해 TanStack Router를 사용합니다.

UX Provider

기본 uxProvider는 shadcn/ui입니다. Cloudscape 또는 None(자체 컴포넌트 라이브러리 사용)을 선택할 수도 있습니다.

사용 방법

React 웹사이트 생성

새로운 React 웹사이트를 두 가지 방법으로 생성할 수 있습니다:

VSCode

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

pnpm nx g @aws/nx-plugin:ts#website --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#website --dry-run

npm

npx nx g @aws/nx-plugin:ts#website --dry-run

bun

bunx nx g @aws/nx-plugin:ts#website --dry-run

옵션

매개변수	타입	기본값	설명
name 필수	string	-	애플리케이션의 이름입니다.
framework	react	react	사용할 프론트엔드 프레임워크입니다.
directory	string	packages	새 애플리케이션의 디렉토리입니다.
subDirectory	string	-	프로젝트가 배치되는 하위 디렉토리입니다. 기본값은 프로젝트 이름입니다.
ux	none | cloudscape | shadcn	shadcn	선호하는 UX 제공자입니다.
tailwind	boolean	true	유틸리티 우선 스타일링을 위해 TailwindCSS를 활성화합니다.
tanstackRouter	boolean	true	타입 안전 라우팅을 위해 Tanstack router를 활성화합니다.
infra	cloudfront-s3 | none	cloudfront-s3	웹사이트를 배포할 인프라 유형입니다.
iac	inherit | cdk | terraform	inherit	선호하는 IaC 제공자입니다. 기본적으로 초기 선택에서 상속됩니다.
preferInstallDependencies	boolean	true	생성기 실행 후 의존성 설치를 선호할지 여부입니다. 여러 생성기를 일괄 처리할 때 설치를 연기하려면 false로 설정하세요(후속 생성기가 Nx 프로젝트 그래프를 계산할 수 있도록 필요한 경우 설치는 여전히 실행됩니다). 마지막에 한 번만 설치하세요.

생성기 출력 결과

생성기는 <directory>/<name> 디렉토리에 다음 프로젝트 구조를 생성합니다:

• index.html HTML 진입점
• public 정적 에셋
• 디렉터리src

  • main.tsx React 설정이 포함된 애플리케이션 진입점
  • config.ts 애플리케이션 구성 (예: 로고)
  • 디렉터리components

    • AppLayout 전체 레이아웃 및 네비게이션 바를 위한 컴포넌트
  • 디렉터리hooks

    • useAppLayout.tsx 중첩 컴포넌트에서 AppLayout 조정을 위한 훅 (Cloudscape 전용)
  • 디렉터리routes

    • index.tsx TanStack Router용 예제 라우트(페이지)
  • styles.css 전역 스타일
• vite.config.mts Vite 및 Vitest 구성
• tsconfig.json 소스 및 테스트용 기본 TypeScript 구성
• tsconfig.app.json 소스 코드용 TypeScript 구성
• tsconfig.spec.json 테스트용 TypeScript 구성

TanStack Router 미사용

TanStack Router 사용을 선택하지 않은 경우, routes 디렉토리 대신 간단한 src/app.tsx 파일이 애플리케이션 진입점으로 제공됩니다.

인프라

이 생성기는 선택한 iacProvider 기반으로 인프라를 코드 형태로 제공하므로, packages/common 디렉터리에 관련 CDK 구축 요소 또는 Terraform 모듈을 포함하는 프로젝트를 생성합니다.

공통 인프라스트럭처 코드 프로젝트의 구조는 다음과 같습니다:

CDK

• 디렉터리packages/common/constructs

  • 디렉터리src

    • 디렉터리app/ 특정 프로젝트/생성기에 종속적인 인프라를 위한 구축 요소

      • …
    • 디렉터리core/ app 내 구축 요소에서 재사용되는 일반적 구축 요소

      • …
    • index.ts app의 구축 요소를 익스포트하는 진입점
  • project.json 프로젝트 빌드 대상 및 구성

생성된 프로젝트

이 프로젝트는 ts#project 생성기를 사용하여 생성되었으므로 동일한 빌드 대상이 구성됩니다.

Terraform

• 디렉터리packages/common/terraform

  • 디렉터리src

    • 디렉터리app/ 특정 프로젝트/생성기 전용 Terraform 모듈

      • …
    • 디렉터리core/ app 내 모듈에서 재사용되는 일반적 모듈

      • …
  • project.json 프로젝트 빌드 대상 및 구성

생성된 프로젝트

이 프로젝트는 terraform#project 생성기를 사용하여 생성되었으므로 동일한 빌드 대상이 구성됩니다.

생성기는 선택한 iacProvider 기반으로 웹사이트 배포를 위한 인프라 코드를 생성합니다:

CDK

• 디렉터리packages/common/constructs/src

  • 디렉터리app

    • 디렉터리static-websites

      • <name>.ts 웹사이트 전용 인프라
  • 디렉터리core

    • static-website.ts 일반 StaticWebsite construct

Terraform

• 디렉터리packages/common/terraform/src

  • 디렉터리app

    • 디렉터리static-websites

      • 디렉터리<name>

        • <name>.tf 웹사이트 전용 모듈
  • 디렉터리core

    • 디렉터리static-website

      • static-website.tf 일반 정적 웹사이트 모듈

아키텍처

배포된 웹사이트는 다음과 같은 아키텍처를 가집니다:

보안 헤더

CloudFront 배포는 모든 응답에 Strict-Transport-Security, X-Content-Type-Options, X-Frame-Options: DENY, Referrer-Policy 및 Content-Security-Policy를 설정하는 응답 헤더 정책을 적용합니다.

기본 Content-Security-Policy가 적용됩니다. 이는 XSS 및 클릭재킹을 완화하기 위해 스크립트와 프레이밍을 제한하면서, 배포 시점에만 알 수 있는 URL을 가진 AWS 서비스 엔드포인트(API Gateway, Cognito, Bedrock AgentCore 등)를 웹사이트가 호출할 수 있도록 HTTPS 및 WSS 연결을 허용합니다. 정책을 조정하려면(예: connect-src를 특정 출처로 제한) 생성된 static-website.ts(CDK) 또는 static-website.tf(Terraform)의 content_security_policy 값을 편집하세요.

runtime-config.json은 Cache-Control: no-cache로 제공되어 브라우저가 재배포 후 캐시된 오래된 복사본 대신 항상 최신 구성을 가져오도록 합니다.

React 웹사이트 구현

React 문서는 React 개발 기초를 배우기에 좋은 시작점입니다.

ux = cloudscape

Cloudscape 문서에서 사용 가능한 컴포넌트와 사용 방법을 확인할 수 있습니다.

ux = shadcn

shadcn/ui 문서에서 사용 가능한 컴포넌트와 사용 방법을 확인할 수 있습니다.

라우트

라우트/페이지 생성

웹사이트는 기본적으로 TanStack Router가 구성되어 있습니다. 새로운 라우트 추가가 간편합니다:

1. 로컬 개발 서버 실행
2. src/routes에 새 <page-name>.tsx 파일 생성 (파일 트리 위치가 경로를 나타냄)
3. 자동 생성된 Route 및 RouteComponent를 확인하고 페이지 개발 시작!

페이지 간 네비게이션

페이지 간 이동에는 Link 컴포넌트나 useNavigate 훅을 사용할 수 있습니다:

import { Link, useNavigate } from '@tanstack/react-router';

export const MyComponent = () => {
  const navigate = useNavigate();

  const submit = async () => {
    const id = await ...
    // 비동기 액션 후 리다이렉트 시 `navigate` 사용
    navigate({ to: '/products/$id', { params: { id }} });
  };

  return (
    <>
      <Link to="/products">취소</Link>
      <Button onClick={submit}>제출</Button>
    </>
  )
};

자세한 내용은 TanStack Router 문서를 참조하세요.

런타임 구성

인프라의 구성 정보는 런타임 구성을 통해 웹사이트에 제공됩니다. 이를 통해 배포 시점에만 알 수 있는 API URL 등의 정보에 접근할 수 있습니다.

인프라

CDK

RuntimeConfig CDK construct를 사용하여 CDK 인프라에 구성 값을 추가하고 조회할 수 있습니다. @aws/nx-plugin 생성기(ts#api, py#api 등)로 생성된 CDK construct는 자동으로 RuntimeConfig에 적절한 값을 추가합니다.

웹사이트 CDK construct는 런타임 구성의 connection 네임스페이스를 S3 버킷 루트에 runtime-config.json 파일로 배포합니다.

packages/infra/src/stacks/application-stack.ts

import { Stack } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { MyWebsite, MyApi } from ':my-scope/common-constructs';

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string) {
    super(scope, id);

    // 웹사이트는 어느 시점에나 선언 가능 — 런타임 구성은 지연 평가됨
    new MyWebsite(this, 'MyWebsite');

    // RuntimeConfig에 값 자동 추가
    new MyApi(this, 'MyApi', {
      integrations: MyApi.defaultIntegrations(this).build(),
    });
  }
}

CDK 웹사이트 컨스트럭트

CDK에서는 웹사이트 construct를 스택의 어느 시점에나 선언할 수 있습니다. 런타임 구성은 synth 시점에 지연 평가되므로 선언 순서와 관계없이 모든 값이 포함됩니다.

Terraform

Terraform의 경우 런타임 구성은 runtime-config 모듈을 통해 관리됩니다. @aws/nx-plugin 생성기(ts#trpc-api, py#fast-api 등)로 생성된 Terraform 모듈은 런타임 구성에 적절한 값을 자동으로 추가합니다.

웹사이트 Terraform 모듈은 런타임 구성의 connection 네임스페이스를 S3 버킷 루트에 runtime-config.json 파일로 배포합니다.

packages/infra/src/main.tf

module "asset_bucket" {
  source = "../../common/terraform/src/core/asset-bucket"
}

# 런타임 구성에 값 자동 추가
module "my_api" {
  source = "../../common/terraform/src/app/apis/my-api"

  asset_bucket_name = module.asset_bucket.bucket_name
}

# runtime-config.json으로 런타임 구성 자동 배포
module "my_website" {
  source = "../../common/terraform/src/app/static-websites/my-website"

  providers = {
    aws.us_east_1 = aws.us_east_1
  }

  # API가 런타임 구성 추가를 먼저 완료하도록 보장
  depends_on = [module.my_api]
}

모듈 순서

runtime-config.json 파일 누락을 방지하려면 런타임 구성을 추가하는 모듈을 웹사이트 모듈보다 먼저 선언하고 적절한 depends_on을 설정해야 합니다.

웹사이트 코드

웹사이트에서는 useRuntimeConfig 훅을 사용해 런타임 구성 값을 조회할 수 있습니다:

import { useRuntimeConfig } from '../hooks/useRuntimeConfig';

const MyComponent = () => {
  const runtimeConfig = useRuntimeConfig();

  // 런타임 구성 값 접근 예시
  const apiUrl = runtimeConfig.apis.MyApi;
};

런타임 구성

런타임 구성이 AWS AppConfig에 어떻게 저장되고 서버 측 소비자(Lambda 함수, 에이전트)가 어떻게 조회할 수 있는지에 대한 자세한 내용은 런타임 구성 가이드를 참조하세요.

로컬 런타임 구성

로컬 개발 서버 실행 시 백엔드 URL, 인증 구성 등을 위해 public 디렉토리에 runtime-config.json 파일이 필요합니다.

웹사이트 프로젝트는 배포된 애플리케이션에서 runtime-config.json 파일을 가져오는 load:runtime-config 타겟을 포함하고 있습니다:

pnpm

pnpm nx run <my-website>:"load:runtime-config"

yarn

yarn nx run <my-website>:"load:runtime-config"

npm

npx nx run <my-website>:"load:runtime-config"

bun

bunx nx run <my-website>:"load:runtime-config"

사용자 정의 스테이지 이름

CDK

인프라 프로젝트의 src/main.ts에서 스테이지 이름 접두사를 변경한 경우 웹사이트의 project.json 파일에서 load:runtime-config 타겟을 수정해야 합니다.

또한 load:runtime-config 타겟은 단일 스테이지가 AWS 자격 증명 환경에 배포되었다고 가정합니다. 동일 계정/리전에 여러 스테이지를 배포한 경우 명령어를 조정해야 합니다.

Terraform

Terraform 프로젝트의 경우 load:runtime-config 타겟은 최근 로컬 terraform apply로 생성된 runtime-config.json 파일을 복사합니다.

로컬 개발 서버

로컬 개발을 위한 표준 명령어는 dev로, 웹사이트와 연결된 API의 로컬 서버를 하나의 명령어로 시작합니다:

pnpm

pnpm nx dev <my-website>

yarn

yarn nx dev <my-website>

npm

npx nx dev <my-website>

bun

bunx nx dev <my-website>

serve 타겟은 애플리케이션의 어느 부분을 로컬에서 실행하고 어느 부분을 배포된 AWS 인프라를 가리킬지 제어해야 할 때 사용할 수 있습니다. 여러 컴포넌트가 있는 프로젝트에서 dev가 어떻게 동작하는지를 포함하여 연결된 프로젝트 간 로컬 개발에 대한 전반적인 개요는 로컬 개발 가이드를 참조하세요.

Serve 타겟

serve 타겟은 웹사이트의 로컬 개발 서버를 시작합니다. 이 타겟은 웹사이트가 상호작용하는 지원 인프라의 배포와 로컬 런타임 구성 로드가 필요합니다.

다음 명령어로 실행할 수 있습니다:

pnpm

pnpm nx serve <my-website>

yarn

yarn nx serve <my-website>

npm

npx nx serve <my-website>

bun

bunx nx serve <my-website>

이 타겟은 “실제” 배포된 API 및 인프라를 사용하면서 웹사이트 변경 작업 시 유용합니다.

Dev 타겟

dev 타겟은 Vite MODE를 local-dev로 설정한 로컬 개발 서버를 시작하며, Connection 생성기로 연결된 API의 로컬 서버도 함께 실행합니다.

이 타겟으로 서버를 실행하면 runtime-config.json이 자동으로 로컬 API URL을 가리키도록 재정의됩니다.

다음 명령어로 실행할 수 있습니다:

pnpm

pnpm nx dev <my-website>

yarn

yarn nx dev <my-website>

npm

npx nx dev <my-website>

bun

bunx nx dev <my-website>

이 타겟은 웹사이트와 API를 동시에 작업하며 인프라 배포 없이 빠른 반복을 원할 때 유용합니다.

워크스페이스 dev 스크립트

워크스페이스의 루트 package.json에는 dev 타겟이 있는 모든 프로젝트에 대해 dev 타겟을 실행하는 dev 스크립트가 포함되어 있습니다:

pnpm

pnpm dev

yarn

yarn dev

npm

npm run dev

bun

bun dev

이 명령은 웹사이트(및 dev 타겟이 있는 다른 프로젝트)의 로컬 개발 서버를 한 번에 시작합니다. 이 웹사이트만 실행하려면 해당 웹사이트의 dev 타겟을 사용하세요(예: nx dev <my-website>).

모의 인증

이 모드에서 실행 시 runtime-config.json이 없고 ts#website#auth 생성기로 Cognito 인증을 구성한 경우, 로그인이 생략되며 로컬 서버 요청에 인증 헤더가 포함되지 않습니다.

dev에서 로그인 및 인증을 사용하려면 인프라를 배포하고 런타임 구성을 로드해야 합니다.

Dev 동작

dev 실행 시 API가 다른 배포된 AWS 리소스를 가리키도록 필요한 환경 변수를 지정할 수 있습니다. 예를 들어:

pnpm

DYNAMODB_TABLE_NAME=xxxxx pnpm nx dev <my-website>

yarn

DYNAMODB_TABLE_NAME=xxxxx yarn nx dev <my-website>

npm

DYNAMODB_TABLE_NAME=xxxxx npx nx dev <my-website>

bun

DYNAMODB_TABLE_NAME=xxxxx bunx nx dev <my-website>

로컬 API 서버는 로컬에 구성된 AWS 자격 증명으로 실행됩니다.

빌드

build 타겟을 사용해 웹사이트를 빌드할 수 있습니다. 이는 bundle, compile, test, lint 타겟을 실행하여 타입 검사, 번들링, 테스트, 린팅을 수행합니다.

pnpm

pnpm nx build <my-website>

yarn

yarn nx build <my-website>

npm

npx nx build <my-website>

bun

bunx nx build <my-website>

bundle 타겟은 Vite를 사용해 루트 dist/packages/<my-website>/bundle 디렉토리에 프로덕션 번들을 생성합니다. 이는 웹사이트 인프라에서 사용하는 배포 가능한 아티팩트입니다. 단독으로 실행할 수 있습니다:

pnpm

pnpm nx bundle <my-website>

yarn

yarn nx bundle <my-website>

npm

npx nx bundle <my-website>

bun

bunx nx bundle <my-website>

테스트

웹사이트 테스트는 일반 TypeScript 프로젝트 테스트 작성과 유사하므로 자세한 내용은 TypeScript 프로젝트 가이드를 참조하세요.

React 전용 테스트를 위해 React Testing Library가 설치되어 있습니다. 사용법은 React Testing Library 문서를 참조하세요.

test 타겟으로 테스트를 실행할 수 있습니다:

pnpm

pnpm nx test <my-website>

yarn

yarn nx test <my-website>

npm

npx nx test <my-website>

bun

bunx nx test <my-website>

웹사이트 배포

React 웹사이트 생성기는 선택한 iacProvider 기반으로 CDK 또는 Terraform 인프라 코드를 생성합니다. 이를 통해 웹사이트를 배포할 수 있습니다.

CDK

웹사이트 배포를 위해 CDK 애플리케이션 생성 시 ts#infra 생성기 사용을 권장합니다.

packages/common/constructs에 생성된 CDK construct를 사용해 웹사이트를 배포할 수 있습니다.

packages/infra/src/stacks/application-stack.ts

import { Stack } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { MyWebsite } from ':my-scope/common-constructs';

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string) {
    super(scope, id);

    new MyWebsite(this, 'MyWebsite');
  }
}

이 설정은 다음을 구성합니다:

1. 정적 웹사이트 파일 호스팅을 위한 S3 버킷
2. 글로벌 콘텐츠 전송을 위한 CloudFront 배포
3. 보안 보호를 위한 WAF Web ACL
4. 안전한 S3 접근을 위한 Origin Access Control
5. 웹사이트 파일 및 런타임 구성 자동 배포

Terraform

웹사이트 배포를 위해 Terraform 프로젝트 생성 시 terraform#project 생성기 사용을 권장합니다.

packages/common/terraform에 생성된 Terraform 모듈을 사용해 웹사이트를 배포할 수 있습니다.

packages/infra/src/main.tf

# 웹사이트 배포
module "my_website" {
  source = "../../common/terraform/src/app/static-websites/my-website"

  providers = {
    aws.us_east_1 = aws.us_east_1
  }
}

이 설정은 다음을 구성합니다:

1. 정적 웹사이트 파일 호스팅을 위한 S3 버킷
2. 글로벌 콘텐츠 전송을 위한 CloudFront 배포
3. 보안 보호를 위한 WAF Web ACL (us-east-1에 배포)
4. 안전한 S3 접근을 위한 Origin Access Control
5. 웹사이트 파일 및 런타임 구성 자동 배포

WAF 프로바이더 리전

CloudFront 및 WAF 리소스는 us-east-1 리전에 배포되어야 하므로 aws.us_east_1 provider가 필요합니다. Terraform 구성에 다음 provider가 포함되었는지 확인하세요:

packages/infra/src/providers.tf

provider "aws" {
  alias  = "us_east_1"
  region = "us-east-1"
}

연결

connection 생성기를 사용하여 이 프로젝트를 워크스페이스의 다른 프로젝트와 통합할 수 있습니다. 다음은 이 프로젝트와 관련된 연결입니다:

React to tRPCReact 웹사이트에서 tRPC API 호출하기

React to FastAPIReact 웹사이트에서 Python FastAPI 호출하기

React to Smithy APIReact 웹사이트에서 Smithy API 호출하기

React to Python AgentReact 웹사이트에서 Python Agent 호출하기

React to TypeScript AgentReact 웹사이트에서 TypeScript Agent 호출하기

React to AG-UI AgentCopilotKit를 통해 React 웹사이트에서 AG-UI 프로토콜을 노출하는 Agent 호출하기