React 컴포넌트 구조 설계와 폴더 배치

왜 폴더 구조가 중요한가

프로젝트가 커질수록 컴포넌트와 기능이 늘어난다. 폴더 구조가 명확하면 협업과 유지보수가 쉬워진다. 반대로 구조가 뒤죽박죽이면 파일을 찾는 데 시간이 낭비되고 리팩터링이 어렵다. 따라서 초기 설계에서 컴포넌트 아키텍처 react 관점을 반영한 폴더 배치를 결정하는 것이 중요하다.

설계 원칙

• 관심사의 분리: UI, 비즈니스 로직, 상태 관리, 스타일을 분리한다.
• 기능 중심: 기능 단위로 묶어 변경 범위를 좁힌다.
• 일관된 명명: 파일과 폴더 명을 규칙적으로 유지한다.
• 재사용성: 공통 컴포넌트는 별도 폴더로 분리한다.
• 간결한 인덱스: Barrel 파일(index.ts)을 활용해 임포트 경로를 단순화한다.

두 가지 주요 접근법

1. 폴더별(Feature-first) 접근

기능 단위로 파일을 그룹화한다. 페이지나 도메인 단위로 폴더를 구성하면 팀이 특정 기능을 수정할 때 관련 파일을 한 곳에서 찾을 수 있다. 중대형 애플리케이션에서 권장되는 방식이다.

2. 레이어별(Atomic 또는 Layered) 접근

컴포넌트, 서비스, 훅, 유틸 등 역할 단위로 분리한다. 작은 프로젝트나 라이브러리 개발에 적합하다. 컴포넌트 아키텍처 react 원칙을 적용해 명확한 책임 경계를 만든다.

권장 폴더 구조 예시

아래는 기능 중심(Feature-first)을 기반으로 한 리액트 프로젝트 구조 설계 예시다. 실무에서 자주 사용되는 패턴을 반영했다.

src/
  app/
    store.ts
    routes.tsx
  features/
    auth/
      components/
        LoginForm.tsx
      hooks/
        useAuth.ts
      api.ts
      index.ts
    dashboard/
      components/
        DashboardHeader.tsx
        Widgets/
          WidgetCard.tsx
      styles.module.css
      index.ts
  components/
    ui/
      Button.tsx
      Modal.tsx
      index.ts
  hooks/
    useFetch.ts
  services/
    apiClient.ts
  utils/
    formatDate.ts
  types/
    index.d.ts
  assets/
    logo.svg
  pages/
    HomePage.tsx
    NotFound.tsx
  App.tsx
  index.tsx

파일/폴더 규칙과 권장 관행

• 컴포넌트는 폴더로 묶고, 관련 스타일·테스트·서브컴포넌트를 함께 둔다.
• 파일명은 파스칼케이스(컴포넌트)와 카멜케이스(유틸) 혼용을 명확히 한다.
• index.ts를 사용해 외부에서는 폴더 단위로 임포트하게 한다.
• hooks는 접두사 use로 시작하고 독립 폴더에 보관한다.
• 서비스(api)와 상태(store)는 앱 루트에서 분리해 테스트와 교체를 용이하게 한다.

컴포넌트 설계 세부 전략

프레젠테이셔널 vs 컨테이너

UI 렌더링만 담당하는 프레젠테이셔널 컴포넌트와 데이터 로딩·상태를 처리하는 컨테이너를 분리하면 테스트와 재사용성이 높아진다. 예를 들어 List 컴포넌트는 아이템을 렌더링만 하고, ListContainer는 데이터 호출과 상태를 담당한다.

컴포넌트 경량화

하나의 컴포넌트가 너무 많은 책임을 갖지 않도록 기능을 분해한다. 복잡한 로직은 커스텀 훅으로 분리해 재사용한다.

실제 컴포넌트 예시

아래는 단순한 버튼 컴포넌트 예시다. JSX의 <와 >는 HTML 이스케이프 처리한다.

// src/components/ui/Button.tsx
import React from 'react';

type Props = {
  children: React.ReactNode;
  onClick?: () => void;
};

export function Button({ children, onClick }: Props) {
  return <button className="btn" onClick={onClick}>{children}</button>;
}

마이그레이션과 유지보수 팁

• 초기 구조를 너무 상세하게 만들기보다 필요한 시점에 폴더를 분리한다.
• 리팩터링 시 일괄 이동을 위해 에디터의 리네임/이동 기능과 테스트를 활용한다.
• 바벨 경로(alias)를 설정하면 장기적으로 임포트 문이 간결해진다.
• 문서화는 README와 간단한 다이어그램으로 남긴다.

정리

react 폴더 구조 추천은 프로젝트 성격과 팀 규모에 따라 달라진다. 중대형 앱은 기능 중심(feature-first)으로 구성하고, 라이브러리나 소규모는 레이어별 구조가 더 효율적일 수 있다. 컴포넌트 아키텍처 react 원칙을 반영해 관심사를 분리하고, 일관된 규칙을 유지하면 장기적으로 유지보수와 협업 생산성이 향상된다. 위 예시들을 참고해 리액트 프로젝트 구조 설계에 맞는 구조를 선택하면 구조