[개발 포트폴리오 github.io 만들기] 1일차 – Next.js 구조 셋팅과 GitHub Actions로 자동 배포(CI/CD)까지

handa·2025년 7월 30일

🎬 들어가며
직접 개발한 여러 프로젝트를 체계적으로 보여주는 포트폴리오 웹사이트를 만들기로 했습니다.
평소 주력으로 쓰던 기술은 아니지만, React와 Next.js를 선택해 최신 웹 생태계 경험을 쌓고자 도전했습니다.

1일차 기록은

왜 익숙하지 않은 React(Next.js)를 선택했는지
프로젝트 구조와 환경 셋팅 방법
코드 푸시 시 자동으로 배포되는 GitHub Actions CI/CD 설정 과정

을 자세히 정리합니다.

1. ⚡ 왜 React(Next.js)를 선택했나? — 익숙하지 않은 기술이었지만 도전한 이유

사실 React와 Next.js는 평소 주력으로 쓰던 기술이 아니었습니다.
하지만 이번 포트폴리오 작업을 계기로 다음과 같은 이유로 과감히 선택했습니다.

새로운 기술 학습 기회
최신 프론트엔드 트렌드와 타입스크립트 기반 UI 개발 능력을 높이고자 했습니다.
현업 협업과 이직 준비에 실질적 도움
React/Next.js 관련 역량을 증명하는 포트폴리오가 경쟁력을 키웁니다.
컴포넌트 기반 재사용성과 유지보수성 확보
UI를 효율적으로 관리하고 데이터 구조를 체계적으로 설계할 수 있습니다.
정적 사이트 생성(SSG)과 빠른 배포 환경 활용
Next.js의 SSG 기능을 통해 손쉽게 GitHub Pages에 배포할 수 있습니다.
직접 주도하는 UI/UX 구현 가능
외부 템플릿이 아닌 내 색깔을 입히는 자유도가 큽니다.

낯선 기술 선택이었지만, 결과물 제작뿐 아니라 과정 자체가 성장과 현업 적응력을 키우는 데 큰 도움이 되었습니다.

2. 📦 프로젝트 구조와 환경 준비

1) 저장소 및 개발환경 세팅

GitHub 저장소 생성: my-portfolio.github.io
Next.js + 타입스크립트 프로젝트 세팅

npx create-next-app my-portfolio --typescript
cd my-portfolio

2) 스타일링과 폴더 구조

styled-components 설치 및 사용

npm install styled-components @types/styled-components

주요 폴더 구조 예시

/app
  /portfolio
    /components
      profile.tsx
      ProjectAccordion.tsx
      ...
/public
  (이미지 등 정적 자원)
/src/data
  projects.ts       # 프로젝트 데이터 분리
  troubleshootingList.ts  # 트러블슈팅 데이터 분리

3) 데이터 중심 설계

프로젝트 카드, 상세, 트러블슈팅, 회고 등을 객체 데이터로 분리해 관리
TypeScript interface로 엄격한 타입 선언을 통해 코드 안정성과 자동완성 확보

3. 🔄 GitHub Actions로 완전자동화(CI/CD) 구현하기

📝 1) github actions을 쓰는 이유

빌드와 배포를 매번 수동으로 처리하는 번거로움 없이
깃허브 메인 브랜치에 코드만 푸시하면 자동으로 정적 사이트가 빌드되고 배포됨

⚙️ 2) 실제 workflow 파일(.github/workflows/deploy.yml)

빌드-배포 자동화를 위해 아래처럼 workflow를 작성했다.

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]  # main에 push할 때 배포

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

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

      - name: Use Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'

      - name: Install dependencies
        run: npm install

      - name: Build & Export Next.js
        run: |
          npm run build
          npm run export

      - name: Fix .nojekyll (정적 파일 변환 시 필요)
        run: touch out/.nojekyll

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./out

📌 설명