create-web-0to1 0.1.0

package/templates/shared/docs//352/260/234/353/260/234/354/233/220/354/271/231/12-/354/213/244/353/254/264-/353/215/260/354/235/264/355/204/260-/355/214/250/355/204/264.md

@@ -0,0 +1,302 @@
+# 실무 데이터 패턴
+
+## 검색 파라미터 원칙
+
+### 원칙
+
+- 공유, 새로고침, 뒤로가기와 연결되어야 하는 상태는 검색 파라미터에 둡니다.
+- `page`, `sort`, `search`, `filter`처럼 목록 조회 조건은 URL에 두는 쪽이 기본입니다.
+- 입력 중 임시값이나 열림/닫힘 같은 UI 상태는 검색 파라미터보다 local state에 둡니다.
+- 검색 조건이 바뀌면 `page`를 같이 초기화할지 먼저 정합니다.
+
+### Why?
+
+- URL에 있는 상태는 링크 공유와 새로고침에 자연스럽게 이어집니다.
+- 목록 조건이 local state에만 있으면 뒤로가기와 화면 복원이 어색해지기 쉽습니다.
+- 반대로 모든 UI 상태를 URL에 올리면 주소가 불필요하게 복잡해집니다.
+
+### 예시 코드
+
+```tsx
+// src/features/posts/components/post-filter.tsx
+'use client';
+
+import { usePathname, useRouter, useSearchParams } from 'next/navigation';
+
+export function PostFilter() {
+  const pathname = usePathname();
+  const router = useRouter();
+  const searchParams = useSearchParams();
+
+  const keyword = searchParams.get('search') ?? '';
+
+  function updateSearch(value: string) {
+    const params = new URLSearchParams(searchParams.toString());
+
+    if (value) {
+      params.set('search', value);
+    } else {
+      params.delete('search');
+    }
+
+    params.delete('page');
+
+    const queryString = params.toString();
+    router.replace(queryString ? `${pathname}?${queryString}` : pathname);
+  }
+
+  return (
+    <input
+      value={keyword}
+      onChange={(event) => updateSearch(event.target.value)}
+      placeholder="검색어를 입력하세요"
+    />
+  );
+}
+```
+
+### 흐름 예시: `searchParams -> query key -> 목록 조회`
+
+```ts
+// src/features/posts/lib/post-list-params.ts
+export type PostListParams = {
+  search: string;
+  page: number;
+  sort: 'latest' | 'popular';
+};
+
+export function parsePostListParams(searchParams: URLSearchParams): PostListParams {
+  const rawPage = Number(searchParams.get('page') ?? '1');
+  const rawSort = searchParams.get('sort');
+
+  return {
+    search: searchParams.get('search')?.trim() ?? '',
+    page: Number.isNaN(rawPage) || rawPage < 1 ? 1 : rawPage,
+    sort: rawSort === 'popular' ? 'popular' : 'latest',
+  };
+}
+
+export function buildPostListSearchParams(
+  current: URLSearchParams,
+  next: Partial<PostListParams>,
+) {
+  const params = new URLSearchParams(current.toString());
+
+  if (next.search !== undefined) {
+    if (next.search) {
+      params.set('search', next.search);
+    } else {
+      params.delete('search');
+    }
+
+    params.delete('page');
+  }
+
+  if (next.page !== undefined) {
+    params.set('page', String(next.page));
+  }
+
+  if (next.sort !== undefined) {
+    params.set('sort', next.sort);
+  }
+
+  return params;
+}
+```
+
+```ts
+// src/features/posts/hooks/query-keys.ts
+import type { PostListParams } from '@/features/posts/lib/post-list-params';
+
+export const postQueryKeys = {
+  all: ['posts'] as const,
+  list: (params: PostListParams) =>
+    [...postQueryKeys.all, 'list', params] as const,
+};
+```
+
+```tsx
+// src/features/posts/hooks/use-post-list-query.ts
+'use client';
+
+import { useSearchParams } from 'next/navigation';
+import { useQuery } from '@tanstack/react-query';
+
+import { getPostListClient } from '@/features/posts/api/get-post-list.client';
+import { postQueryKeys } from '@/features/posts/hooks/query-keys';
+import { parsePostListParams } from '@/features/posts/lib/post-list-params';
+
+export function usePostListQuery() {
+  const searchParams = useSearchParams();
+  const params = parsePostListParams(new URLSearchParams(searchParams.toString()));
+
+  return useQuery({
+    queryKey: postQueryKeys.list(params),
+    queryFn: () => getPostListClient(params),
+  });
+}
+```
+
+```ts
+// src/features/posts/lib/post-list-params.test.ts
+import { describe, expect, it } from 'vitest';
+
+import {
+  buildPostListSearchParams,
+  parsePostListParams,
+} from '@/features/posts/lib/post-list-params';
+
+describe('parsePostListParams', () => {
+  it('잘못된 page 값이면 1로 보정합니다', () => {
+    const result = parsePostListParams(
+      new URLSearchParams('search=react&page=-3&sort=popular'),
+    );
+
+    expect(result).toEqual({
+      search: 'react',
+      page: 1,
+      sort: 'popular',
+    });
+  });
+});
+
+describe('buildPostListSearchParams', () => {
+  it('search가 바뀌면 page를 제거합니다', () => {
+    const result = buildPostListSearchParams(
+      new URLSearchParams('search=next&page=3&sort=latest'),
+      { search: 'react' },
+    );
+
+    expect(result.toString()).toBe('search=react&sort=latest');
+  });
+});
+```
+
+## 낙관적 업데이트 원칙
+
+### 원칙
+
+- 결과를 쉽게 예측할 수 있고 롤백이 단순할 때만 낙관적 업데이트를 검토합니다.
+- 좋아요 토글, 체크 상태 변경처럼 작은 상호작용에 더 잘 맞습니다.
+- 복잡한 폼 저장이나 서버 응답이 중요한 작업은 성공 후 invalidate를 기본으로 둡니다.
+- 낙관적 업데이트를 쓰면 실패 시 되돌리는 흐름까지 같이 설계합니다.
+
+### Why?
+
+- 낙관적 업데이트는 체감 속도를 크게 올릴 수 있습니다.
+- 하지만 실패 처리와 롤백이 애매하면 화면과 서버 상태가 쉽게 어긋납니다.
+- 모든 mutation에 일괄 적용하기보다, 예측 가능한 작업에만 쓰는 편이 안전합니다.
+
+### 예시 코드
+
+```tsx
+// src/features/posts/hooks/use-toggle-post-like-mutation.ts
+'use client';
+
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+
+import { togglePostLikeClient } from '@/features/posts/api/toggle-post-like.client';
+import { postQueryKeys } from '@/features/posts/hooks/query-keys';
+import type { Post } from '@/features/posts/types/post';
+
+export function useTogglePostLikeMutation(postId: string) {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: () => togglePostLikeClient(postId),
+    onMutate: async () => {
+      await queryClient.cancelQueries({
+        queryKey: postQueryKeys.detail(postId),
+      });
+
+      const previousPost = queryClient.getQueryData<Post>(postQueryKeys.detail(postId));
+
+      if (previousPost) {
+        queryClient.setQueryData<Post>(postQueryKeys.detail(postId), {
+          ...previousPost,
+          liked: !previousPost.liked,
+        });
+      }
+
+      return { previousPost };
+    },
+    onError: (_error, _variables, context) => {
+      if (context?.previousPost) {
+        queryClient.setQueryData(postQueryKeys.detail(postId), context.previousPost);
+      }
+    },
+    onSettled: () => {
+      queryClient.invalidateQueries({
+        queryKey: postQueryKeys.detail(postId),
+      });
+    },
+  });
+}
+```
+
+## DTO / 도메인 타입 분리 원칙
+
+### 원칙
+
+- 서버 응답 형식은 DTO로 두고, 화면에서 쓰는 타입은 도메인 타입으로 분리할 수 있습니다.
+- 응답 필드명이 UI에서 바로 쓰기 불편하거나 서버 스키마 변경 가능성이 크면 분리를 우선 검토합니다.
+- DTO를 그대로 컴포넌트 전반에 퍼뜨리기보다 feature API 계층에서 도메인 타입으로 매핑합니다.
+- 단순한 프로젝트에서는 무조건 분리하지 말고, 필요할 때만 도입합니다.
+
+### Why?
+
+- 서버 응답 형식은 종종 UI가 원하는 이름과 다릅니다.
+- DTO와 도메인 타입을 나누면 API 변경 영향이 feature API 계층에 더 잘 머뭅니다.
+- 반대로 항상 두 타입을 만드는 건 과할 수 있어서, 분리 기준을 같이 가져가는 편이 좋습니다.
+
+### 예시 코드
+
+```ts
+// src/features/posts/types/post.ts
+export type Post = {
+  id: string;
+  title: string;
+  authorName: string;
+  publishedAt: string | null;
+};
+```
+
+```ts
+// src/features/posts/api/get-post-list.client.ts
+import { requestClient } from '@/shared/api/request.client';
+
+import type { Post } from '@/features/posts/types/post';
+
+type PostDto = {
+  id: string;
+  title: string;
+  author_name: string;
+  published_at: string | null;
+};
+
+type GetPostListResponseDto = {
+  items: PostDto[];
+};
+
+function toPost(dto: PostDto): Post {
+  return {
+    id: dto.id,
+    title: dto.title,
+    authorName: dto.author_name,
+    publishedAt: dto.published_at,
+  };
+}
+
+export async function getPostListClient() {
+  const response = await requestClient<GetPostListResponseDto>({
+    method: 'GET',
+    url: '/posts',
+  });
+
+  return response.items.map(toPost);
+}
+```
+
+## 한 줄 요약
+
+검색 파라미터는 공유 가능한 상태에, 낙관적 업데이트는 예측 가능한 변경에, DTO 분리는 필요할 때만 도입하는 쪽이 실무적으로 안정적입니다.

package/templates/shared/docs//352/260/234/353/260/234/354/233/220/354/271/231/13-/354/204/261/353/212/245-/354/233/220/354/271/231.md

@@ -0,0 +1,175 @@
+# 성능 원칙
+
+## 코드 스플리팅 원칙
+
+### 원칙
+
+- 먼저 라우트 단위로 나눕니다.
+- 초기 화면에 꼭 필요하지 않은 무거운 컴포넌트만 추가로 분리합니다.
+- 에디터, 차트, 지도, 큰 모달처럼 번들 비용이 큰 UI에 우선 적용합니다.
+- 작은 공통 UI나 항상 같이 렌더되는 컴포넌트는 과하게 나누지 않습니다.
+
+### Why?
+
+- 코드 스플리팅은 초기 번들을 줄이는 데 도움이 됩니다.
+- 반대로 너무 잘게 나누면 로딩 경계와 관리 포인트가 늘어납니다.
+- 그래서 모든 컴포넌트를 나누기보다, 늦게 필요한 무거운 기능에 먼저 적용하는 편이 실용적입니다.
+
+### 예시 코드
+
+```tsx
+// src/app/router.tsx
+import { Suspense, lazy } from 'react';
+import { createBrowserRouter, RouterProvider } from 'react-router-dom';
+
+const PostListPage = lazy(() => import('@/pages/post-list-page'));
+const PostDetailPage = lazy(() => import('@/pages/post-detail-page'));
+
+const router = createBrowserRouter([
+  {
+    path: '/posts',
+    element: <PostListPage />,
+  },
+  {
+    path: '/posts/:id',
+    element: <PostDetailPage />,
+  },
+]);
+
+export function AppRouter() {
+  return (
+    <Suspense fallback={<div>페이지를 불러오는 중...</div>}>
+      <RouterProvider router={router} />
+    </Suspense>
+  );
+}
+```
+
+```tsx
+// src/features/posts/components/create-post-page.tsx
+import { Suspense, lazy } from 'react';
+
+const PostEditor = lazy(() => import('@/features/posts/components/post-editor'));
+
+export function CreatePostPage() {
+  return (
+    <Suspense fallback={<div>에디터를 불러오는 중...</div>}>
+      <PostEditor />
+    </Suspense>
+  );
+}
+```
+
+## 재렌더링 최적화 원칙
+
+### 원칙
+
+- `memo`, `useMemo`, `useCallback`을 기본값처럼 쓰지 않습니다.
+- 새로운 프로젝트에서는 React Compiler 도입을 적극 검토합니다.
+- 기존 프로젝트는 React 버전, 빌드 환경, 팀 사용 패턴을 같이 보고 점진적으로 도입합니다.
+- 실제로 느리거나, 계산 비용이 크거나, 리스트가 큰 경우에만 검토합니다.
+- 최적화는 상태 위치, props 구조, 컴포넌트 분리로 먼저 해결하고, 그다음 memoization을 봅니다.
+- 입력 중 UI가 무거우면 `useDeferredValue`나 `startTransition` 같은 React 기능을 검토합니다.
+
+### Why?
+
+- 과한 memoization은 코드만 복잡하게 만들고 효과는 거의 없을 수 있습니다.
+- React Compiler는 반복적인 수동 memoization 부담을 줄이는 데 도움이 될 수 있습니다.
+- 많은 경우 문제는 훅 하나가 아니라 상태 범위와 컴포넌트 구조에 있습니다.
+- 다만 도입 여부는 프로젝트 환경과 운영 비용까지 같이 보고 정하는 편이 안전합니다.
+- React가 이미 충분히 빠른 부분까지 미리 최적화하면 유지보수 비용만 커집니다.
+
+### 예시 코드
+
+```tsx
+// src/features/posts/components/post-search.tsx
+import { useDeferredValue, useMemo, useState } from 'react';
+
+type Post = {
+  id: string;
+  title: string;
+};
+
+export function PostSearch({
+  posts,
+}: {
+  posts: Post[];
+}) {
+  const [keyword, setKeyword] = useState('');
+  const deferredKeyword = useDeferredValue(keyword);
+
+  const filteredPosts = useMemo(() => {
+    return posts.filter((post) =>
+      post.title.toLowerCase().includes(deferredKeyword.toLowerCase()),
+    );
+  }, [posts, deferredKeyword]);
+
+  return (
+    <div>
+      <input
+        value={keyword}
+        onChange={(event) => setKeyword(event.target.value)}
+        placeholder="검색어를 입력하세요"
+      />
+
+      <ul>
+        {filteredPosts.map((post) => (
+          <li key={post.id}>{post.title}</li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+## 큰 리스트 렌더링 원칙
+
+### 원칙
+
+- 데이터가 많을수록 먼저 페이지네이션이나 무한 스크롤을 검토합니다.
+- 한 번에 많은 행을 렌더해야 하면 가상화를 검토합니다.
+- 리스트 아이템은 가능한 한 가볍게 유지합니다.
+- 필터, 정렬, 선택 상태가 많아질수록 어떤 연산이 매 렌더마다 반복되는지 같이 봅니다.
+
+### Why?
+
+- 리스트 성능 문제는 보통 한두 개 컴포넌트보다, 렌더되는 개수와 반복 연산에서 크게 발생합니다.
+- 보이는 것만 렌더하면 DOM 수와 렌더 비용을 크게 줄일 수 있습니다.
+- 리스트 아이템이 무거우면 가상화를 해도 체감 성능이 충분히 좋아지지 않을 수 있습니다.
+
+### 예시 코드
+
+```tsx
+// src/features/posts/components/post-list.tsx
+import { FixedSizeList as List } from 'react-window';
+
+type Post = {
+  id: string;
+  title: string;
+};
+
+export function PostList({
+  posts,
+}: {
+  posts: Post[];
+}) {
+  return (
+    <List
+      height={560}
+      itemCount={posts.length}
+      itemSize={56}
+      width="100%"
+    >
+      {({ index, style }) => (
+        <div style={style}>
+          {posts[index].title}
+        </div>
+      )}
+    </List>
+  );
+}
+```
+
+## 한 줄 요약
+
+성능 최적화는 모든 곳에 미리 적용하지 않고, 초기 번들 비용이 큰 영역, 재렌더링이 잦은 흐름, 큰 리스트처럼 실제로 비용이 큰 곳부터 다루는 편이 가장 실용적입니다.

package/templates/shared/docs//352/260/234/353/260/234/354/233/220/354/271/231/README.md

@@ -0,0 +1,39 @@
+# 프론트엔드 원칙, 패턴, 컨벤션 모음
+
+프론트엔드 개발에서 반복해서 마주치는 구조, 데이터, UI, 상태 관련 기준을 정리한 문서입니다.
+
+> 한 곳에서 정하고, 책임에 따라 나누고, 전역 상태는 최소화합니다.
+
+## 문서 목록
+
+- [00-전반적인-폴더구조.md](./00-전반적인-폴더구조.md): 전체 폴더 구조와 `feature`, `shared/components`, `shared/ui` 기준
+- [01-구조와-라우팅.md](./01-구조와-라우팅.md): feature-first, layout, route, 컴포넌트 분리
+- [02-서버와-클라이언트.md](./02-서버와-클라이언트.md): server/client 경계와 `use client` 기준
+- [03-상태관리.md](./03-상태관리.md): URL, Query, Form, local/global state 기준
+- [04-API와-데이터.md](./04-API와-데이터.md): request 계층, API layer, Query 규칙
+- [05-에러와-UI-상태.md](./05-에러와-UI-상태.md): 전역/로컬 에러, 로딩, empty, 모달, 인증 에러
+- [06-폼.md](./06-폼.md): `zod`, `react-hook-form`, 제출 UX
+- [07-스타일링과-접근성.md](./07-스타일링과-접근성.md): 스타일 기준과 접근성
+- [08-네이밍-설정-포맷팅.md](./08-네이밍-설정-포맷팅.md): 네이밍, 상수, 환경변수, 날짜/숫자 포맷팅
+- [09-라우트-정의.md](./09-라우트-정의.md): route, menu, breadcrumb를 한 파일에서 관리하는 기준
+- [10-커밋-컨벤션.md](./10-커밋-컨벤션.md): 커밋 메시지 타입과 작성 기준
+- [11-기타-원칙.md](./11-기타-원칙.md): layout 반응형, layout state 범위, 영역별 provider 기준
+- [12-실무-데이터-패턴.md](./12-실무-데이터-패턴.md): 검색 파라미터, 낙관적 업데이트, DTO / 도메인 타입 분리 기준
+- [13-성능-원칙.md](./13-성능-원칙.md): 코드 스플리팅, 재렌더링, 큰 리스트 렌더링 기준
+
+## 읽는 순서
+
+- 각 문서는 `원칙 -> Why? -> 예시 코드` 순서로 정리했습니다.
+- 먼저 `00`, `01`, `02`, `03`을 읽으면 전체 구조를 잡기 좋습니다.
+- 구현 기준이 필요할 때는 `04`, `05`, `06`, `12`, `13`을 같이 보면 연결이 잘 됩니다.
+- 공통 규칙은 `07`, `08`, `09`, `10`, `11`, `13`에서 빠르게 확인할 수 있습니다.
+
+## 빠른 요약
+
+- 구조는 기능 기준으로 나눕니다.
+- `shared/ui`는 진짜 공통만 둡니다.
+- `2~3개 feature` 공통은 `shared/components/[공유-맥락-이름]`도 사용할 수 있습니다.
+- 상태는 성격에 맞는 계층에 둡니다.
+- 공통 계층은 최대한 단순하게 유지합니다.
+- low-level 계층이 UI를 직접 제어하지 않게 합니다.
+- 이름만 봐도 역할이 보이게 짓습니다.