폴더 구조

• src/ : 루트 경로
  • app/ : 페이지 및 layout 경로
    • page.tsx 및 error.tsx, layout.tsx 등 next.js에 기본으로 기원하는 routing 파일들만 존재.
  • components/ : 페이지에서 사용될 컴포넌트들의 모음
    • layouts/ : 페이지의 layout에 사용될 컴포넌트 모음 (ex: Header, Footer, Sidebar 등)
      • 페이지의 layout 요소에 들어갈 컴포넌트 입니다.
      • 특정 컴포넌트의 layout 요소를 저장하지 않습니다.
    • ui/ : shadcn 에서 가져오는 공통 컴포넌트들의 모음
      • shadcn 컴포넌트만
    • commons/ : 프로젝트에서 사용할 공통 컴포넌트들의 모음
      • 프로젝트의 공통 컴포넌트라면 이 폴더에 저장
    • 각 도메인 별로 필요한 컴포넌트 모음
      • 도메인 별로 폴더를 만들고, 그 안에 컴포넌트 저장
      • challenge : 언더바() 접두사
  • config/: router, compositeProvider 등 프로젝트의 환경 설정 같은 파일을 저장
  • libs/ : 유틸리티 함수, API 호출 관련 함수, 헬퍼 등을 저장
    • utils.ts : shadcn에서 사용하는 util 함수가 자동으로 저장됨.
    • hooks/ : 커스텀 훅
    • apis/ : supabase와 통신하기 위한 캠슐화된 함수
      • 도메인 별로 파일을 분리하면 좋을 듯.
    • queries/ : tanstackquery 에서 useQuery 훅 저장
    • mutations/ : tanstackquery 에서 useMutation 훅 저장
    • utils/ : 프로젝트에 필요한 유틸 함수 저장.
      • 도메인별로 파일을 분리하면 좋을 듯.
  • constants/ : 프로젝트 전반에 걸쳐서 사용되는 상수 선언
    • 기능에 맞게 파일을 분리하면 좋을 듯
  • store/ : zustand의 스토어 목록 저장
    • 기능에 맞게 파일을 분리하면 좋을 듯
  • types/ : 서버와 통신하는데, 필요한 타입들의 모음
    • DTO/ : supabase에서 불러오는 type들을 정의한 모음
    • 일반 enum 타입의 파일들을 여기에 정의

<aside> 💡

아래 예시는 간단한 블로그를 생각하면서 만들었습니다.

폴더 및 파일이 도메인 별로 나뉘어 집니다.

블로그에는 간단하게 auth로 사용자의 권한을 관리하는 도메인과, post로 게시글을 관리하는 도메인으로 나누어집니다.

• auth : 로그인, 회원가입 가능
• post : 블로그 글 CRUD 가능 </aside>

📦 project
├─ public
└─ src
   ├─ app
   │  ├─ auth
   │  │  ├─ sign-in/ page.tsx     # 로그인 페이지
   │  │  └─ sign-up/ page.tsx     # 회원가입 페이지
   │  │
   │  ├─ post
   │  │  ├─ read/ page.tsx      # 게시글 상세 페이지
   │  │  ├─ write/ page.tsx     # 게시글 작성 페이지
   │  │  └─ page.tsx            # 게시글 목록 페이지
   │  │ 
   │  ├─ global-style.css
   │  ├─ not-found.tsx
   │  ├─ error.tsx
   │  ├─ layout.tsx
   │  └─ page.tsx
   │ 
   ├─ components
   │  ├─ **_**post
   │  │   ├─ post-card.tsx
   │  │   ├─ post-like-button.tsx
   │  │   └─ post-markdown-editor.tsx
   │  ├─ **_**auth
   │  │   ├─ auth-sign-in-form.tsx
   │  │   ├─ auth-sign-up-form.tsx
   │  │   └─ auth-tabs.tsx
   │  ├─ ui
   │  │  ├─ button.tsx
   │  │  ├─ input.tsx
   │  │  ├─ modal.tsx
   │  │  └─ combobox.tsx
   │  ├─ commons  # shadcn 컴포넌트를 이용한 공통 컴포넌트 포함
   │  └─ layouts
   │     ├─ header.tsx
   │     └─ footer.tsx
   │ 
   ├─ lib
   │  ├─ queries
   │  │  ├─ use-get-all-post-query.ts
   │  │  └─ use-get-post-by-id-suspense-query.ts
   │  ├─ mutations
   │  │  ├─ use-create-post-mutation.ts
   │  │  ├─ use-delete-post-mutation.ts
   │  │  └─ use-update-post-mutation.ts
   │  ├─ api
   │  │  ├─ post.api.ts  # supabse를 호출하는 api 함수
   │  │  └─ auth.api.ts  # supabse를 호출하는 api 함수
   │  ├─ hooks
   │  │  ├─ use-media-query.ts  # 현재 screen width이 sm, md, lg 인지 반환하는 훅
   │  │  └─ use-debounce.ts     # debounce를 적용시킨 값을 반환하는 훅
   │  ├─ utils
   │  │  ├─ auth.util.ts   
   │  │  └─ post.util.ts   
   │  └─ utils.ts    # shadcn에서 자동으로 만든 것임...! 
   │                 # 해당 경로를 수정하면 앞으로 import 할 모든 shadcn 컴포넌트들에 대해 
   │                 # `import { cn } from "@/lib/utils"` 수정해줘야 함...
   │                 # 단, `utils/index.ts` 로 수정하면 import 구문 수정 안해도 됨.
   ├─ config
   ├─ constants
   └─ types
      │  ├─ post.dto.ts   
      │  └─ auth.dto.ts  
      └─ post-category.type.ts 

폴더 & 파일 네이밍

<aside> 💡

표기법의 종류

• PascalCase (파스칼 케이스)
• camelCase (카멜 케이스)
• kebab-case (케밥 케이스)
• snake_case (스네이크 케이스) </aside>

폴더 및 파일 둘 다 케밥 케이스

• 케밥 케이스를 하고 싶은 이유

  1. 프레임워크 일관성 및 구조적 정합성

     ShadcnUI는 모듈 구조에서 케밥 케이스를 기본 규칙으로 채택하고 있음. 이 라이브러리가 src/api/components/ui/ 경로에 생성하는 파일들은 이미 케밥 케이스로 명명되어 있어, 이를 파스칼 케이스로 변경하는 것은 구조적 불일치를 불러옴. 특히 ShadcnUI 컴포넌트들이 단일 기능을 default로 export하지 않고 다중 요소를 반환하는 구조적 특성을 고려할 때, 파스칼 케이스의 사용은 구문론적으로 부적합하다고 생각함.

  2. 시각적 인지 최적화 및 코드 가독성

     케밥 케이스는 단어 사이에 하이픈을 사용하여 시각적 구분을 명확히 하고, 전체 소문자 형태로 일관성을 유지함. 이로 인해 가독성이 좋음.

  3. 인지적 오버헤드 최소화와 개발 생산성

     다양한 케이싱 규칙을 혼용할 경우(폴더는 케밥 케이스, 컴포넌트는 파스칼 케이스, 유틸/훅은 카멜 케이스) 개발자는 상황별 다른 규칙을 적용해야 하는 인지적 부담이 있음. 케밥 케이스로의 통일은 이러한 멘탈 모델 전환 비용을 줄일 수 있음.

  4. 프론트엔드 생태계 동향

     Vue, Svelte 등 프론트엔드 프레임워크에서도 케밥 케이스 채택이 증가하는 추세임.

특정 도메인에서 사용되는 폴더는 components 폴더 아래에 _(언더바) 접두사와 함께

컴포넌트 파일명 규칙

• 다른 컴포넌트와 구분할 수 있도록 도메인을 제일 앞에 붙여줌.
  • card.tsx ⇒ post-card.tsx
  • card-list.tsx ⇒ post-card-list.tsx
  • sign-in-form.tsx ⇒ auth-sign-in-form.tsx
• 컴포넌트 명과 파일명은 **동일**할 것!!
  • 표기법의 동일이 아닌 명칭을 통일
  • 예시) post-card.tsx ⇒ PostCard (O) , Card(X)

유틸 함수, api, 타입, 상수, store, dto 파일명 규칙