코드 구조
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 키트에서 받은 부품
- …
주소는 pages 폴더가 정해요
섹션 제목: “주소는 pages 폴더가 정해요”TanStack Router의 파일 라우팅이 src/pages를 읽어요. 폴더 하나가 주소 한 단계이고, 슬라이스 하나예요. 라우트 목록을 따로 관리하지 않고, 폴더를 만들면 주소가 생겨요.
// 파일 라우팅: 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/ 이 주소만 쓰는 상태와 로직
- …
- route.tsx
디렉터리my-work/
- page.tsx
/my-work화면 디렉터리ui/
- …
- page.tsx
디렉터리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 로그인 확인. 안 했으면
| 파일·폴더 | 뜻 |
|---|---|
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/에 있는 화면을 가져와요.
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)가 검사해요. 검사 전체는 린트와 코딩 스타일에 있어요.