클라우드스케이프 웹사이트
이 생성기는 React 웹사이트를 생성하며 CloudScape가 구성되어 있고, 정적 웹사이트를 클라우드에 배포하기 위한 AWS CDK 인프라 코드를 함께 제공합니다. 생성된 웹사이트는 S3에 호스팅되며 CloudFront를 통해 서비스되고 WAF로 보호됩니다.
생성된 애플리케이션은 빌드 도구 및 번들러로 Vite를 사용합니다. 타입 안전 라우팅을 위해 TanStack Router를 사용합니다.
사용 방법
CloudScape 웹사이트 생성
새 CloudScape 웹사이트를 두 가지 방법으로 생성할 수 있습니다:
- 설치 Nx Console VSCode Plugin 아직 설치하지 않았다면
- VSCode에서 Nx 콘솔 열기
- 클릭
Generate (UI)
"Common Nx Commands" 섹션에서 - 검색
@aws/nx-plugin - ts#cloudscape-website
- 필수 매개변수 입력
- 클릭
Generate
pnpm nx g @aws/nx-plugin:ts#cloudscape-website
yarn nx g @aws/nx-plugin:ts#cloudscape-website
npx nx g @aws/nx-plugin:ts#cloudscape-website
bunx nx g @aws/nx-plugin:ts#cloudscape-website
어떤 파일이 변경될지 확인하기 위해 드라이 런을 수행할 수도 있습니다
pnpm nx g @aws/nx-plugin:ts#cloudscape-website --dry-run
yarn nx g @aws/nx-plugin:ts#cloudscape-website --dry-run
npx nx g @aws/nx-plugin:ts#cloudscape-website --dry-run
bunx nx g @aws/nx-plugin:ts#cloudscape-website --dry-run
옵션
매개변수 | 타입 | 기본값 | 설명 |
---|---|---|---|
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 구문
CloudScape 웹사이트 구현
React 문서는 React 기반 구축의 기초를 배우기 좋은 시작점입니다. 사용 가능한 컴포넌트와 사용 방법에 대한 자세한 내용은 CloudScape 문서를 참조하세요.
라우트
라우트/페이지 생성
CloudScape 웹사이트는 TanStack Router가 미리 구성되어 있습니다. 새 라우트 추가가 간편합니다:
- 로컬 개발 서버 실행
src/routes
에 새<page-name>.tsx
파일 생성 (파일 트리 위치가 경로를 나타냄)- 자동 생성된
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 구문을 사용해 CDK 인프라에서 구성 값을 추가/조회할 수 있습니다. @aws/nx-plugin
으로 생성된 CDK 구문(예: tRPC API 및 FastAPI)은 자동으로 RuntimeConfig
에 적절한 값을 추가합니다.
웹사이트 CDK 구문은 런타임 구성을 S3 버킷 루트에 runtime-config.json
파일로 배포합니다.
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'); }}
runtime-config.json
파일에 누락되지 않도록 웹사이트를 RuntimeConfig
에 값을 추가하는 다른 구문들 _이후_에 선언해야 합니다.
웹사이트 코드
웹사이트에서는 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
타겟으로 구성되어 있습니다:
pnpm nx run <my-website>:"load:runtime-config"
yarn nx run <my-website>:"load:runtime-config"
npx nx run <my-website>:"load:runtime-config"
bunx nx run <my-website>:"load:runtime-config"
인프라 프로젝트의 src/main.ts
에서 스택 이름을 변경한 경우, 웹사이트의 project.json
파일 내 load:runtime-config
타겟을 해당 스택 이름으로 업데이트해야 합니다.
로컬 개발 서버
serve
또는 serve-local
타겟을 사용해 로컬 개발 서버를 실행할 수 있습니다.
Serve 타겟
serve
타겟은 웹사이트의 로컬 개발 서버를 시작합니다. 이 타겟은 웹사이트가 상호작용하는 지원 인프라가 배포되어 있고 로컬 런타임 구성이 로드된 상태여야 합니다.
다음 명령어로 실행 가능:
pnpm nx run <my-website>:serve
yarn nx run <my-website>:serve
npx nx run <my-website>:serve
bunx nx run <my-website>:serve
이 타겟은 “실제” 배포된 API 및 기타 인프라를 가리키는 상태에서 웹사이트 변경 작업 시 유용합니다.
Serve-local 타겟
serve-local
타겟은 웹사이트의 로컬 개발 서버를 시작하며(Vite MODE
가 serve-local
로 설정), API 연결 생성기를 통해 연결된 API의 로컬 서버도 함께 시작합니다.
이 타겟으로 실행 시 runtime-config.json
이 자동으로 로컬 실행 중인 API URL을 가리키도록 재정의됩니다.
다음 명령어로 실행 가능:
pnpm nx run <my-website>:serve-local
yarn nx run <my-website>:serve-local
npx nx run <my-website>:serve-local
bunx nx run <my-website>:serve-local
이 타겟은 웹사이트와 API를 동시에 작업하며 빠르게 반복하고 싶을 때 유용합니다.
이 모드 실행 시 runtime-config.json
이 없고 Cognito 인증(CloudScape 웹사이트 인증 생성기 통해 구성된 경우)이 구성된 경우, 로그인이 생략되며 로컬 서버 요청에 인증 헤더가 포함되지 않습니다.
serve-local
에서 로그인 및 인증을 활성화하려면 인프라를 배포하고 런타임 구성을 로드해야 합니다.
빌드
build
타겟으로 웹사이트 빌드 가능. 이는 Vite를 사용해 루트 dist/packages/<my-website>/bundle
디렉토리에 프로덕션 번들을 생성하며, 타입 체크, 컴파일, 린팅을 수행합니다.
pnpm nx run <my-website>:build
yarn nx run <my-website>:build
npx nx run <my-website>:build
bunx nx run <my-website>:build
테스트
웹사이트 테스트는 일반 TypeScript 프로젝트 테스트 작성과 유사하므로 자세한 내용은 TypeScript 프로젝트 가이드를 참조하세요.
React 전용 테스트를 위해 React Testing Library가 미리 설치되어 있습니다. 사용법은 React Testing Library 문서를 참조하세요.
test
타겟으로 테스트 실행 가능:
pnpm nx run <my-website>:test
yarn nx run <my-website>:test
npx nx run <my-website>:test
bunx nx run <my-website>:test
웹사이트 배포
웹사이트 배포에는 TypeScript 인프라 생성기를 사용해 CDK 애플리케이션 생성하는 것을 권장합니다.
packages/common/constructs
에 생성된 CDK 구문을 사용해 웹사이트를 배포할 수 있습니다.
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'); }}