콘텐츠로 이동

코드 구조

web/src는 역할에 따라 app · pages · features · entities · shared 다섯 층으로 나눠요. Feature-Sliced Design을 바탕으로, 쓰지 않는 층(widgets 등)은 두지 않아요. 이 장은 층을 나누는 규칙과, pages 폴더가 주소를 정하는 규칙을 설명해요.

flowchart TD
  app["app<br/>앱 시작 · 라우터 · 전역 설정"]
  pages["pages<br/>주소 하나에 화면 하나"]
  features["features<br/>사용자 동작 하나<br/>(목록 보기, 상세 열기)"]
  entities["entities<br/>업무 대상<br/>(업무, 문서, 프로젝트)"]
  shared["shared<br/>업무를 모르는 도구<br/>(UI 키트, API, 설정)"]
  app --> pages --> features --> entities --> shared
  pages -.-> entities
  pages -.-> shared
  features -.-> shared

화살표는 가져올 수 있는 방향이에요. 위층은 아래층을 가져올 수 있고, 아래층은 위층을 모릅니다. 점선처럼 중간 층을 건너뛰어도 돼요.

cowork의 web/src는 이렇게 생겼어요.

  • 디렉터리web/src/
    • 디렉터리app/ 앱 시작, 라우터, 테마, 앱 틀
      • …
    • 디렉터리pages/
      • 디렉터리login/
        • …
      • 디렉터리onboarding/
        • …
      • 디렉터리print/
        • …
      • 디렉터리_app/ 로그인한 사람의 화면
        • …
    • 디렉터리features/
      • 디렉터리work-item-list/
        • …
      • 디렉터리work-item-detail/
        • …
      • 디렉터리picture-change/
        • …
      • …
    • 디렉터리entities/
      • 디렉터리work-item/
        • …
      • 디렉터리project/
        • …
      • 디렉터리document/
        • …
      • …
    • 디렉터리shared/
      • 디렉터리api/ HTTP 도우미와 생성한 API 타입
        • …
      • 디렉터리auth/
        • …
      • 디렉터리config/
        • …
      • 디렉터리lib/
        • …
      • 디렉터리ui/ cowork가 만든 공용 부품
        • 디렉터리kit/ Webcraft 키트에서 받은 부품
          • …

TanStack Router의 파일 라우팅이 src/pages를 읽어요. 폴더 하나가 주소 한 단계이고, 슬라이스 하나예요. 라우트 목록을 따로 관리하지 않고, 폴더를 만들면 주소가 생겨요.

web/vite.config.ts
// 파일 라우팅: src/pages의 폴더가 곧 주소다. page.tsx가 그 주소의 화면, route.tsx가 그 아래에 걸리는 틀이다.
// 슬라이스 안의 세그먼트(ui · api · model · lib · config)와 공개 진입점(index.ts)은 라우트로 치지 않는다.
tanstackRouter({
target: 'react',
routesDirectory: './src/pages',
generatedRouteTree: './src/app/router/routeTree.gen.ts',
autoCodeSplitting: true, indexToken: 'page', routeFileIgnorePattern: '^(ui|api|model|lib|config|index\\.ts)$',
quoteStyle: 'single',
}),

indexToken: 'page' 때문에 page.tsx가 그 주소의 화면이 되고, routeFileIgnorePattern 때문에 ui/ · api/ · model/ · lib/ · config/ · index.ts는 주소로 치지 않아요.

  • 디렉터리pages/_app/
    • route.tsx 로그인 확인. 안 했으면 /login으로
    • page.tsx /에 오면 홈으로 보내기
    • 디렉터리inbox/
      • route.tsx /inbox 목록과 옆 칸, 먼저 읽을 알림
      • $id.tsx /inbox/123
      • 디렉터리ui/ 이 주소만 쓰는 부품
        • …
      • 디렉터리model/ 이 주소만 쓰는 상태와 로직
        • …
    • 디렉터리my-work/
      • page.tsx /my-work 화면
      • 디렉터리ui/
        • …
    • 디렉터리workspace/
      • 디렉터리projects/
        • page.tsx /workspace/projects 화면
        • new.tsx /workspace/projects/new 화면
        • index.ts 공개 진입점. 주소로 치지 않음
        • 디렉터리ui/
          • …
        • 디렉터리$key/
          • route.tsx 프로젝트를 먼저 읽어 두기
          • page.tsx
          • 디렉터리members/
            • page.tsx
          • 디렉터리work-items/
            • page.tsx
            • 디렉터리$number/
              • …
            • 디렉터리model/
              • …
            • 디렉터리ui/
              • …
          • 디렉터리ui/
            • …
          • …
      • …
파일·폴더 뜻
page.tsx 그 주소의 화면
route.tsx 그 주소와 아래 주소 전체에 걸리는 라우트. 레이아웃, 접근 확인, 먼저 읽을 데이터를 여기에 둬요
$key/, $id.tsx 주소의 한 단계가 값인 자리(/workspace/projects/ABC, /inbox/123)
_app/ 밑줄로 시작하는 폴더는 주소에 나타나지 않아요. 로그인한 사람의 화면을 앱 틀 하나로 묶어요
ui/ · model/ · api/ · lib/ · config/ · index.ts 슬라이스 안의 코드 묶음이에요. 주소로 치지 않아요
  • 컴포넌트는 ui/에 파일 하나에 하나씩 둬요. 파일 이름은 PascalCase이고, 페이지 컴포넌트에는 Page를 붙여요(ProjectMembersPage.tsx).
  • 여러 파일이 함께 쓰는 훅과 로직은 model/에 둬요. 훅 이름은 use로 시작하고, 일반 도구와 설정 파일 이름은 kebab-case예요.
  • 서버 조회는 그 조회를 소유한 슬라이스의 api/에 요청·쿼리 키·쿼리 옵션을 함께 둬요. 흐름은 데이터 흐름에 있어요.

pages의 파일은 자기 주소 폴더와 조상 주소 폴더의 코드만 가져와요. 목록과 그 아래 상세처럼 위 주소의 부품을 아래 주소가 함께 쓰는 것은 되고, 옆 주소의 코드를 가져오는 것은 안 돼요. 두 주소가 함께 쓰는 코드는 공통 조상 폴더로 올려요.

아래 members/page.tsx는 조상 주소($key/)의 ui/에 있는 화면을 가져와요.

web/src/pages/_app/workspace/projects/$key/members/page.tsx
import { createFileRoute } from '@tanstack/react-router';
import { projectMembersOptions } from '@/entities/project';
import { prepare } from '@/shared/lib/prepare';
import { useCrumbs } from '@/shared/lib/page-crumbs';
import { ProjectMembersPage } from '@/pages/_app/workspace/projects/$key/ui/ProjectMembersPage';
/** /workspace/projects/{key}/members: 프로젝트 멤버(설정의 멤버와 같은 화면). */
export const Route = createFileRoute('/_app/workspace/projects/$key/members/')({
loader: ({ context, params }) => prepare(context.queryClient, `project-members:${params.key}`, ({ prime }) => prime(projectMembersOptions(params.key))),
component: function ProjectMembersPageRoute() {
return <ProjectMembersPage crumbs={useCrumbs()} />;
},
});

층 방향, 같은 층의 다른 슬라이스, 옆 주소 가져오기는 npm run lint:ui(web/scripts/check-ui.mjs)가 검사해요. 검사 전체는 린트와 코딩 스타일에 있어요.