컨텐츠로 건너뛰기
@aws/nx-plugin
Blog

클라우드스케이프 웹사이트

이 생성기는 React 웹사이트를 새로 생성하며 CloudScape가 구성된 상태와 AWS CDK 인프라를 함께 제공합니다. 이를 통해 정적 웹사이트를 S3에 호스팅하고 CloudFront로 서비스하며 WAF로 보호하는 클라우드 배포가 가능합니다.

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

사용 방법

CloudScape 웹사이트 생성

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

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

    옵션

    매개변수 타입 기본값 설명
    name 필수 string - The name of the application.
    directory string packages The directory of the new application.

    생성기 출력 결과

    생성기는 <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 설정

    또한 생성기는 packages/common/constructs 디렉토리에 웹사이트 배포를 위한 CDK 인프라 코드를 생성합니다:

    • 디렉터리src
      • 디렉터리app
        • 디렉터리static-websites
          • <name>.ts 웹사이트 전용 인프라 코드
      • 디렉터리core
        • static-website.ts 일반 StaticWebsite Construct

    CloudScape 웹사이트 구현

    React 문서에서 React 기초 학습을 시작할 수 있습니다. CloudScape 문서에서 사용 가능한 컴포넌트와 사용 방법을 확인할 수 있습니다.

    라우트

    라우트/페이지 생성

    생성된 CloudScape 웹사이트는 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 문서 참조.

    런타임 설정

    AWS CDK 인프라의 설정값은 런타임 설정을 통해 웹사이트에 제공됩니다. 이를 통해 배포 시점에야 알 수 있는 API URL 등의 정보에 접근 가능합니다.

    인프라

    RuntimeConfig CDK Construct를 사용하여 인프라 코드에서 설정값을 추가/조회할 수 있습니다. @aws/nx-plugin으로 생성된 CDK Construct(예: tRPC API 및 FastAPI)는 자동으로 적절한 값을 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');
    

        // runtime-config.json에 런타임 설정 자동 배포
        new MyWebsite(this, 'MyWebsite');
      }
    }

    runtime-config.json 파일에서 설정값이 누락되지 않도록 웹사이트를 다른 Construct들 _이후_에 선언해야 합니다.

    웹사이트 코드

    웹사이트 코드에서는 useRuntimeConfig 훅을 사용하여 런타임 설정값을 조회할 수 있습니다:

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

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

      // 런타임 설정값 접근 예시
      const apiUrl = runtimeConfig.httpApis.MyApi;
    };

    로컬 런타임 설정

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

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

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

    인프라 프로젝트의 src/main.ts에서 스택 이름을 변경한 경우, 웹사이트의 project.json 파일 내 load:runtime-config 타겟을 해당 스택 이름으로 업데이트해야 합니다.

    로컬 개발 서버

    로컬 개발 서버 실행 전 인프라 배포 완료 및 로컬 런타임 설정 로드가 필요합니다.

    다음 명령어로 serve 타겟 실행:

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

    빌드

    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

    웹사이트 배포

    TypeScript 인프라 생성기를 사용하여 CDK 애플리케이션 생성 권장.

    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');
      }
    }