콘텐츠로 이동

React 웹사이트

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

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

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

  1. 설치 Nx Console VSCode Plugin 아직 설치하지 않았다면
  2. VSCode에서 Nx 콘솔 열기
  3. 클릭 Generate (UI) "Common Nx Commands" 섹션에서
  4. 검색 @aws/nx-plugin - ts#react-website
  5. 필수 매개변수 입력
    • 클릭 Generate
    매개변수 타입 기본값 설명
    name 필수 string - The name of the application.
    directory string packages The directory of the new application.
    enableTailwind boolean true Enable TailwindCSS for utility-first styling.
    enableTanstackRouter boolean true Enable Tanstack router for type-safe routing.
    iacProvider string Inherit The preferred IaC provider. By default this is inherited from your initial selection.

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

    • index.html HTML 진입점
    • public 정적 에셋
    • 디렉터리src
      • main.tsx React 설정이 포함된 애플리케이션 진입점
      • config.ts 애플리케이션 구성 (예: 로고)
      • 디렉터리components
        • AppLayout CloudScape 레이아웃 및 네비게이션 바를 위한 컴포넌트
      • 디렉터리hooks
        • useAppLayout.tsx 중첩 컴포넌트에서 AppLayout 조정을 위한 훅
      • 디렉터리routes
        • 디렉터리welcome
          • index.tsx @tanstack/react-router용 예제 라우트(페이지)
      • styles.css 전역 스타일
    • vite.config.ts Vite 및 Vitest 구성
    • tsconfig.json 소스 및 테스트용 기본 TypeScript 구성
    • tsconfig.app.json 소스 코드용 TypeScript 구성
    • tsconfig.spec.json 테스트용 TypeScript 구성

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

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

    • 디렉터리packages/common/constructs
      • 디렉터리src
        • 디렉터리app/ 특정 프로젝트/생성기에 종속적인 인프라를 위한 구축 요소
        • 디렉터리core/ app 내 구축 요소에서 재사용되는 일반적 구축 요소
        • index.ts app의 구축 요소를 익스포트하는 진입점
      • project.json 프로젝트 빌드 대상 및 구성

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

    • 디렉터리packages/common/constructs/src
      • 디렉터리app
        • 디렉터리static-websites
          • <name>.ts 웹사이트 전용 인프라
      • 디렉터리core
        • static-website.ts 일반 StaticWebsite construct

    React 문서는 React 개발 기초를 배우기에 좋은 시작점입니다. CloudScape 문서에서 사용 가능한 컴포넌트와 사용 방법을 확인할 수 있습니다.

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

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

    페이지 간 이동에는 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 등의 정보에 접근할 수 있습니다.

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

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

    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);
    // RuntimeConfig에 값 자동 추가
    new MyApi(this, 'MyApi', {
    integrations: MyApi.defaultIntegrations(this).build(),
    });
    // runtime-config.json으로 런타임 구성 자동 배포
    new MyWebsite(this, 'MyWebsite');
    }
    }

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

    import { useRuntimeConfig } from '../hooks/useRuntimeConfig';
    const MyComponent = () => {
    const runtimeConfig = useRuntimeConfig();
    // 런타임 구성 값 접근 예시
    const apiUrl = runtimeConfig.apis.MyApi;
    };

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

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

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

    serve 또는 serve-local 타겟을 사용해 로컬 개발 서버를 실행할 수 있습니다.

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

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

    Terminal window
    pnpm nx run <my-website>:serve

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

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

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

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

    Terminal window
    pnpm nx run <my-website>:serve-local

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

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

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

    build 타겟을 사용해 웹사이트를 빌드할 수 있습니다. 이는 Vite를 사용해 루트 dist/packages/<my-website>/bundle 디렉토리에 프로덕션 번들을 생성하며 타입 검사, 컴파일, 린팅을 수행합니다.

    Terminal window
    pnpm nx run <my-website>:build

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

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

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

    Terminal window
    pnpm nx run <my-website>:test

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

    웹사이트 배포를 위해 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. 웹사이트 파일 및 런타임 구성 자동 배포