React v19 + AWS S3 + github actions 를 이용한 프로젝트 배포

신규 프로젝트를 진행하게 되었는데, 이번 기회에 최신 React 버전을 직접 사용해보고 싶었다.
또한 빠른 배포와 자동화된 워크플로우를 위해 AWS S3를 활용한 정적 사이트 배포와 GitHub Actions를 이용한 CI/CD 구성까지 함께 적용해보기로 했다.
최근에는 간단한 CI/CD 환경을 누구나 쉽게 구성할 수 있는 도구들이 잘 갖춰져 있어서,
이번 글에서는 React v19 버전 + AWS S3 + GitHub Actions 조합으로 프로젝트를 어떻게 세팅했는지
따라하기 쉽게 정리해보려 한다.
진행하는 프로젝트는 간단한 Admin 페이지로, SEO 최적화가 필요 없는 SPA(single-page application) 형태이기 때문에 React로 구성하는 데 부담이 없었다.

사용기술

우선 본격적인 진행에 앞서, 이번 프로젝트에서 사용한 주요 기술 스택은 React v19와 Chakra UI다.
디자인 작업이 별도로 필요 없는 프로젝트였기 때문에, 정형화된 컴포넌트와 간편한 스타일링을 제공하는 Chakra UI를 선택하게 되었다. 

구조

CCM 이라는 내부적으로 만들어둔 폴더 아키텍처를 사용하였고, 해당부분은 React 구조에 맞게 수정하였습니다.
CCM 은 Context-Clustered Module 에 약자로, 현 회사에서 만든 라우팅 폴더 아키텍쳐 입니다.
각 컨텍스트별로 컴포넌트, 훅을 클러스트링하여 관리하는 방식으로, 각 맥락에 기능, 페이지, 데이터, 도메인 컨텍스트를 지정해서 나누는 방식이라고 알고 있으면 됩니다.
그렇기 때문에 Next, React 두 프로젝트에 공통 구조를 지닐 수 있으며, 프로젝트에 구조가 통일성있게 만들어집니다.

프로젝트 폴더 구조

S3 에 배포

React는 빌드 시 정적 파일로 번들되기 때문에, 별도의 서버 인스턴스를 구성하지 않아도 S3에 정적 사이트 형태로 바로 배포할 수 있습니다.

React 프로젝트를 S3에 자동 배포하기 (with GitHub Actions + pnpm)

GitHub Actions를 이용해 master 브랜치에 push할 때마다 React 프로젝트가 S3에 자동으로 배포되도록 설정하는 방법을 정리한 글입니다.

S3 버킷 만들기

1. AWS 콘솔 → S3 → 버킷 만들기
2. 이름: test-note-admin (원하는 이름으로 설정 가능)
3. 리전: ap-northeast-2 (서울)
4. 퍼블릭 접근 허용 (정적 웹 호스팅 용도면 퍼블릭 읽기 가능하게 설정) - https://docs.aws.amazon.com/ko_kr/IAM/latest/UserGuide/reference_policies_examples_s3_rw-bucket.html
5. “정적 웹사이트 호스팅” 설정 켜기:
   • 인덱스 문서: index.html
   • 오류 문서: index.html

오류 문서를 index.html로 설정하는 이유는, React가 SPA라서 직접 경로로 접근했을 때 404를 방지하기 위함입니다. (매우 중요)

IAM 사용자 만들기

이미 설정되어 있는 경우가 대부분일테니, 없는 경우 추가해주시면 됩니다.

1. AWS 콘솔 → IAM → 사용자 추가
2. 접근 유형: 프로그래밍 방식
3. 권한: 기존 정책 직접 연결 → AmazonS3FullAccess (or 필요한 최소 권한 커스터마이징)
4. 액세스 키 / 시크릿 키 복사

근데, 만들어져있으면 그대로 사용하면 됨. → 나는 그대로 있는거 사용.

GitHub Actions Workflow 작성

.github/workflows/deploy.yaml 파일을 생성하고 아래 내용을 추가합니다

name: Deploy to S3

on:
  push:
    branches: [master]

jobs:
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 10

    steps:
      - name: Checkout source code
        uses: actions/checkout@v4

      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID_TESTBED }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY_TESTBED }}
          aws-region: 'ap-northeast-2'

      - name: Install pnpm
        run: npm install -g pnpm

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Build project
        run: pnpm run build

      - name: Deploy to S3
        uses: jakejarvis/s3-sync-action@v0.5.1
        with:
          args: --delete
        env:
          AWS_S3_BUCKET: test-admin
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID_TESTBED }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY_TESTBED }}
          AWS_REGION: 'ap-northeast-2'
          SOURCE_DIR: 'dist'

 

주의사항 및 팁

• args: --delete 는 S3 버킷에서 빌드 결과에 없는 파일을 삭제해줍니다.
• 만약 S3 버킷이 ACL을 허용하지 않는다면, --acl public-read 옵션은 제거해야 합니다. (AccessControlListNotSupported 에러 방지)
• 정적 웹사이트 호스팅은 꼭 index.html을 에러 문서로 설정해야 라우팅 문제 없이 작동합니다.
• 빌드 결과 폴더가 dist가 아니라면 SOURCE_DIR 경로를 수정해주세요.

이제 master 브랜치에 코드가 push될 때마다 GitHub Actions가 자동으로 빌드 & S3에 배포해줍니다!
이제 github actions 가 아래와 같이 도는지 확인해주세요.