Production-Ready 포트폴리오 구축: Phase-2 — Frontend Bootstrapping & Architecture Setup

Source: Dev.to

인프라가 준비되고 요구사항이 명확히 정의된 후, 드디어 코드를 작성할 시간이었다. 하지만 UI 컴포넌트로 바로 뛰어들기보다는, 이 단계에서는 확장 가능하고 진화하며 유지 보수가 가능한 프런트엔드 기반을 구축하는 데 초점을 맞췄다.

🔗 프로젝트 저장소
https://github.com/imsushant12/sushantgaurav-portfolio

프론트엔드 설정이 별도의 단계가 필요한 이유

완료 후:

• Phase‑0 – 인프라 및 워크플로우
• Phase‑1 – 요구사항 수집 및 PRD

대부분의 사이드 프로젝트가 갖지 못한 것이 있었습니다:

• 범위에 대한 명확성
• 명확한 사용자 흐름
• 정의된 책임

그래서 Phase‑2가 시작될 때 목표는 ‘UI 구축’이 아니었습니다.

목표

• 프론트엔드 아키텍처 구축
• 도구 선택을 초기에 확정
• 일관성 강제
• 향후 리팩토링 감소
• 코드베이스를 기여자 친화적으로 만들기

이 단계는 프로젝트의 Day‑3에 해당하지만, 일일 로그가 아니라 정식 엔지니어링 단계로 간주됩니다.

Phase‑2 Objective

이 단계의 목표는 의도적으로 제한되었습니다:

• 최신 도구를 사용하여 프런트엔드 부트스트랩
• 기능 개발 전에 폴더 구조 설정
• 스타일링, 린팅, 포맷팅 구성
• 전체 페이지를 구현하지 않고 라우팅 계획
• 재작성 없이 앱을 확장할 수 있도록 준비

아직 UI 다듬기 없음.
아직 기능 완성 없음.
오직 기반만 구축.

Step 1 – Vite로 React 앱 부트스트래핑

프론트엔드에서는 기존 번들러 대신 Vite + React를 선택했습니다.

왜 Vite인가?

• 매우 빠른 개발 서버
• 최신 ESM 기반 툴링
• 최소한의 설정
• React 프로젝트에 최적화된 뛰어난 개발자 경험

빠르게 시작하고, 빠르게 유지하며, 불필요한 복잡성을 피하세요.
이 결정은 CI/CD 및 향후 빌드 파이프라인과도 잘 맞습니다.

Step 2 – 프론트엔드 작업 공간 설정

기본 구조가 자연스럽게 성장하도록 두는 대신, 나는 즉시 프론트엔드를 전용 frontend/ 폴더로 정리했습니다.

장점

• 프론트엔드와 백엔드가 독립적으로 진화합니다
• CI 파이프라인이 깔끔하게 유지됩니다
• 배포 대상이 명확합니다
• 소유권 경계가 존중됩니다

제품 및 엔지니어링 관점에서 보면, 이는 실제 팀들이 레포지토리를 구성하는 방식과 일치합니다.

3단계 – 핵심 의존성 설치 (우연이 아니라 의도적으로)

컴포넌트를 작성하기 전에 장기적인 품질을 지원하기 위한 최소 필수 도구를 설치했습니다.

스타일링

Tailwind CSS – 선택 이유:

• 일관성
• 빠른 반복
• 유틸리티‑우선 접근 방식
• 이후 디자인 리팩토링이 용이

라우팅

React Router DOM – 초기에 설치한 이유:

• 네비게이션 계획
• Phase‑1에서 정의된 사용자 여정에 맞추기
• 이후 라우팅 재작성 방지

코드 품질

• ESLint
• Prettier

초기 설정 목적:

• 일관된 코드 스타일 강제
• 리뷰 마찰 감소
• 포맷팅 논쟁 방지
• PR을 깔끔하고 읽기 쉽게 유지

단계 4 – 페이지 구축 전에 라우팅 계획하기

왜?

• 라우팅은 사용자 여정을 정의합니다
• 페이지는 네비게이션을 따르고, 이를 결정하지 않아야 합니다
• 불필요한 재작성 방지

라우트는 다음을 기반으로 매핑했습니다:

• PRD
• Phase‑1의 사용자 흐름 다이어그램
• 이전에 식별된 포트폴리오 섹션

이 단계에서:

• 라우트가 계획되었습니다
• 구조가 준비되었습니다
• 실제 콘텐츠는 의도적으로 최소화되었습니다

Step 5 – Designing the Frontend Folder Structure (Before Writing Features)

이 단계에서 가장 중요한 결정 중 하나는 프론트엔드 아키텍처였습니다.
모든 것을 components/에 몰아넣는 대신, 구조를 의도적으로 계층화했습니다.

High‑Level View

src/
├── components
├── pages
├── hooks
├── data
├── services
├── styles
├── contexts

이 구조는 초기 단계에서 핵심 질문에 답합니다:

• UI는 어디에 위치하나요?
• 로직은 어디에 위치하나요?
• 데이터는 어디서 오나요?
• API 호출은 어디에 배치하나요?

또한 코드베이스를 다음과 같은 사람들에게 더 이해하기 쉽게 만듭니다:

• 미래의 기여자들
• 리뷰어들
• 당신의 미래의 자신

왜 이 단계가 중요한가 (아직 눈에 보이는 것이 없더라도)

이 시점에서는:

• 다듬어진 UI가 없음
• 애니메이션이 없음
• 완성된 페이지가 없음

하지만 프론트엔드는 이미:

• 확장 가능함
• 예측 가능함
• 구조화됨
• 유지 보수 가능함

많은 프로젝트가 구조를 생략하고 나중에 비용을 치르면서 조용히 실패한다.

컴포넌트 아키텍처 – “단순 컴포넌트”를 넘어 생각하기

프론트엔드 프로젝트에서 가장 큰 실수 중 하나는 모든 파일을 단순히 또 다른 컴포넌트로 취급하는 것입니다.
대신 저는 책임에 따라 컴포넌트를 분류했습니다.

components/common

비즈니스 로직이 전혀 없는, 레이아웃에 구애받지 않는 재사용 가능한 빌딩 블록을 포함합니다.

예시

• Section.jsx
• SectionHeader.jsx

이 컴포넌트들은:

• 어디서 사용되는지 모른다
• 라우팅에 의존하지 않는다
• 페이지 간에 쉽게 재사용할 수 있다

components/layout

레이아웃 컴포넌트는 구조를 정의하고, 내용은 정의하지 않습니다.

예시

• NavBar
• Footer
• Layouts

이 컴포넌트들은:

• 페이지를 감싼다
• 공유 UI를 관리한다
• 스켈레톤과 여백을 정의한다

components/sections

섹션은 도메인‑특화 UI를 나타냅니다.

예시

• Hero
• About
• Projects
• OpenSource

이들은:

• 콘텐츠를 인식한다
• 페이지에 특화되어 있다
• 독립적으로 진화할 수 있다

디자인 시스템은 구조화됩니다

페이지와 섹션 (의도적인 구분)

라우팅과 UI 로직을 혼합하는 흔한 안티패턴이 있습니다.
이를 피하기 위해 나는 명확한 구분을 만들었습니다:

pages/

• 라우트‑레벨 컴포넌트
• URL에 직접 매핑
• 섹션을 조합
• 최소한의 로직

sections/

• 페이지 간 재사용 가능
• 논리적 콘텐츠 블록을 표현
• 라우팅에 무관

이렇게 하면:

• 라우트가 얇게 유지
• UI가 조합 가능
• 리팩터링이 쉬워짐

또한 다음을 가능하게 합니다:

• UI를 다시 작성하지 않고 페이지 구조 재배치
• 일관된 레이아웃 재사용

Hooks: 로직을 UI와 분리

컴포넌트 내부에 로직을 직접 넣는 대신, 나는 초기에 hooks/ 레이어를 도입했습니다.

목적:

• 데이터‑패칭 로직 격리
• 부수 효과 캡슐화
• 테스트 용이성 향상
• 컴포넌트 복잡도 감소

예시:

• useProjects
• useAchievements
• useAbout

이렇게 하면 컴포넌트가:

• 선언적
• 읽기 쉬움
• 디버깅 쉬움

API가 변하면 UI가 아니라 훅만 수정하면 됩니다.

데이터 레이어: UI와 콘텐츠 분리

이 단계에서는 대부분의 콘텐츠가 data/ 안의 JSON 파일에 저장됩니다.

이유:

• 콘텐츠 변경이 UI보다 빈번함
• 빠른 반복 가능
• API‑주도 개발 시뮬레이션
• 초기 테스트 간소화

예시 파일:

• projects.json
• experiences.json
• hero.json

이들은 임시 백엔드 역할을 합니다. 실제 API를 연결하면 전환이 원활합니다.

Services 레이어: 백엔드 통합 준비

백엔드가 아직 완전히 구현되지 않았지만, 나는 services/ 레이어를 만들었습니다.

이 레이어:

• API 호출을 중앙 집중화
• HTTP 로직을 격리
• 컴포넌트에 API 사용이 퍼지는 것을 방지

예시: api.js

이점:

• 강한 결합 방지
• 목킹 지원
• 나중에 CI 테스트가 쉬워짐

스타일 & 에셋: 초기 단계부터 정리

스타일

모든 전역 스타일을 다음 위치에 두었습니다:

styles/
├── globals.css
├── animations.css

이렇게 하면:

• CSS가 흩어지는 현상 방지
• 인라인 혼란 방지
• 애니메이션 일관성 유지

에셋

에셋을 도메인별로 그룹화했습니다:

• hero
• about
• projects
• logos

이렇게 하면:

• 가독성 향상
• 에셋 재사용 용이
• 유지보수성 향상

ESLint & Prettier: 초기 단계부터 규율 적용

기능을 작성하기 전에 린팅과 포맷팅을 설정했습니다.

이렇게 하면:

• 스타일 일관성 확보
• 차이점 예측 가능
• PR 리뷰가 쉬워짐
• 주관적 논쟁 감소

리드나 리뷰어 입장에서 나중에 엄청난 시간을 절약할 수 있습니다.

Phase‑2에서 달성한 것

이 단계가 끝날 때:

• 최신 도구로 프런트엔드 부트스트랩 완료
• 확장 가능한 폴더 구조 구축
• 라우팅 계획 수립 (서두르지 않음)
• 코드 품질 도구 설정
• UI, 로직, 데이터 명확히 분리
• 백엔드 통합 준비

아직 “화려한 UI”는 없지만 강력하고 실전적인 프런트엔드 기반.

왜 이 단계가 중요한가 (특히 포트폴리오에 대해)

대부분의 포트폴리오는 무엇을 만들었는지를 보여줍니다.
이 단계에서는 다음을 보여줍니다:

• 결정이 어떻게 이루어졌는지
• 아키텍처가 어떻게 계획되었는지
• 유지보수가 어떻게 우선시되었는지
• 실제 팀이 어떻게 생각하는지

이것이 차이를 만들습니다:

“포트폴리오를 만들었습니다”

from

“제품을 설계했습니다.”

What’s Next?

Phase‑3 will focus on backend setup and API foundations.

Now that the frontend can consume APIs cleanly, it’s time to build them properly.