create-web-0to1 0.1.0

package/templates/react/src/pages/login/page.tsx

@@ -0,0 +1,18 @@
+/**
+ * 인증 흐름 예시를 위한 로그인 플레이스홀더 화면입니다.
+ * 프로젝트의 실제 로그인 페이지로 교체해서 사용하세요.
+ */
+export default function LoginPage() {
+  return (
+    <main className="mx-auto flex min-h-screen w-full max-w-xl items-center px-6 py-16">
+      <section className="w-full rounded-3xl border border-zinc-200 bg-white p-8 shadow-sm">
+        <p className="text-sm font-medium uppercase tracking-[0.2em] text-zinc-500">로그인</p>
+        <h1 className="mt-3 text-3xl font-semibold text-zinc-950">로그인이 필요합니다</h1>
+        <p className="mt-3 text-sm leading-6 text-zinc-600">
+          기본 템플릿은 인증 오류가 발생하면 이 경로로 이동할 수 있습니다. 프로젝트 로그인 화면으로
+          교체하세요.
+        </p>
+      </section>
+    </main>
+  );
+}

package/templates/react/tsconfig.app.json

@@ -0,0 +1,30 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+    "target": "ES2023",
+    "useDefineForClassFields": true,
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "types": ["vite/client"],
+    "skipLibCheck": true,
+
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    },
+
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": ["src"]
+}

package/templates/react/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "files": [],
+  "references": [{ "path": "./tsconfig.app.json" }, { "path": "./tsconfig.node.json" }]
+}

package/templates/react/tsconfig.node.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
+    "target": "ES2023",
+    "lib": ["ES2023"],
+    "module": "ESNext",
+    "types": ["node"],
+    "skipLibCheck": true,
+
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": ["vite.config.ts", "scripts/**/*.mjs"]
+}

package/templates/react/vite.config.ts

@@ -0,0 +1,14 @@
+import path from 'node:path';
+
+import tailwindcss from '@tailwindcss/vite';
+import react from '@vitejs/plugin-react';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, './src'),
+    },
+  },
+});

package/templates/shared/docs//352/260/234/353/260/234/354/233/220/354/271/231/00-/354/240/204/353/260/230/354/240/201/354/235/270-/355/217/264/353/215/224/352/265/254/354/241/260.md

@@ -0,0 +1,150 @@
+# 전반적인 폴더 구조
+
+## 원칙
+
+- 폴더 구조는 기술 기준보다 기능 기준으로 나눕니다.
+- 먼저 `feature 안에 두는 것`을 기본으로 생각합니다.
+- `shared/ui`는 앱 전반에서 재사용되는 진짜 공통 UI만 둡니다.
+- `2~3개 feature`가 같이 쓰는 준공통 컴포넌트는 `shared/components/[공유-맥락-이름]`으로 둘 수 있습니다.
+- 공통화는 단계적으로 올리고, 처음부터 너무 위로 올리지 않습니다.
+
+## Why?
+
+- 모든 걸 `shared`로 올리기 시작하면 재사용 경계가 흐려집니다.
+- 반대로 전부 feature 안에만 두면 비슷한 코드가 여러 군데서 반복됩니다.
+- 그래서 `feature 전용`, `준공통`, `진짜 공통`을 나눠서 보는 편이 가장 실무적입니다.
+
+## 권장 구조
+
+```text
+app/
+  (dashboard)/
+    layout.tsx
+    posts/page.tsx
+    comments/page.tsx
+
+features/
+  posts/
+    api/
+    components/
+    hooks/
+    lib/
+    types/
+  comments/
+    api/
+    components/
+    hooks/
+    lib/
+    types/
+  users/
+    api/
+    components/
+    hooks/
+    types/
+
+shared/
+  api/
+  config/
+  lib/
+  ui/
+    button.tsx
+    global-modal.tsx
+    text-input-field.tsx
+  components/
+    content-meta/
+      author-badge.tsx
+      content-meta.tsx
+```
+
+## 폴더별 역할
+
+### `app/`
+
+- Next.js 라우트 엔트리
+- 페이지, layout, loading, error 같은 라우팅 단위 파일
+- 가능한 한 조립과 진입 제어에 집중합니다.
+
+### `features/<domain>/`
+
+- 해당 기능의 UI, API, hooks, types, 유틸을 둡니다.
+- 기본값은 여기입니다.
+- 특정 도메인 용어와 규칙이 들어가면 우선 feature 안에 둡니다.
+
+### `shared/ui/`
+
+- 진짜 전역 공통 UI만 둡니다.
+- 도메인을 몰라도 설명 가능한 컴포넌트가 들어갑니다.
+- 예: `Button`, `TextInputField`, `GlobalModal`
+
+### `shared/components/[공유-맥락-이름]/`
+
+- 2~3개 feature가 함께 쓰는 준공통 컴포넌트를 둡니다.
+- 완전히 전역 공통은 아니지만, 한 feature 안에만 두기엔 애매할 때 사용합니다.
+- 폴더명은 여러 feature가 공유하는 맥락이나 책임을 드러내게 짓습니다.
+- 글자를 억지로 이어붙이기보다, 겹치는 개념을 하나의 이름으로 표현하는 편이 좋습니다.
+- 예: `content-meta`, `billing`, `access-control`
+
+## 어디에 둘지 빠른 기준
+
+- 한 feature에서만 쓴다: `features/<domain>/components`
+- 2~3개 feature가 함께 쓰지만 공통 맥락이 있다: `shared/components/[공유-맥락-이름]`
+- 앱 어디서든 써도 되는 도메인 중립 UI다: `shared/ui`
+
+## 예시 코드
+
+```tsx
+// src/features/posts/components/post-publish-button.tsx
+type PostPublishButtonProps = {
+  postId: string;
+  isPublished: boolean;
+  onPublish: (postId: string) => void;
+};
+
+export function PostPublishButton({
+  postId,
+  isPublished,
+  onPublish,
+}: PostPublishButtonProps) {
+  return (
+    <button disabled={isPublished} onClick={() => onPublish(postId)}>
+      {isPublished ? "발행 완료" : "발행하기"}
+    </button>
+  );
+}
+```
+
+```tsx
+// src/shared/components/content-meta/author-badge.tsx
+type AuthorBadgeProps = {
+  name: string;
+  role?: string;
+};
+
+export function AuthorBadge({ name, role }: AuthorBadgeProps) {
+  return (
+    <div>
+      <strong>{name}</strong>
+      {role ? <span>{role}</span> : null}
+    </div>
+  );
+}
+```
+
+```tsx
+// src/shared/ui/global-modal.tsx
+'use client';
+
+import { useModalStore } from '@/shared/ui/modal-store';
+
+export function GlobalModal() {
+  const { isOpen } = useModalStore();
+
+  if (!isOpen) return null;
+
+  return <div>공통 모달</div>;
+}
+```
+
+## 한 줄 요약
+
+기본은 feature 안에 두고, 2~3개 feature 공통은 `shared/components/[공유-맥락-이름]`, 진짜 전역 공통만 `shared/ui`에 둡니다.

package/templates/shared/docs//352/260/234/353/260/234/354/233/220/354/271/231/01-/352/265/254/354/241/260/354/231/200-/353/235/274/354/232/260/355/214/205.md

@@ -0,0 +1,186 @@
+# 구조와 라우팅
+
+## 원칙
+
+- 코드는 기술 기준보다 기능 기준으로 나눕니다.
+- 기본 구조는 `features/<domain>` + `shared`를 우선합니다.
+- `shared/ui`는 앱 전반에서 재사용되는 진짜 공통 UI만 둡니다.
+- `2~3개 feature`가 함께 쓰는 준공통 컴포넌트는 `shared/components/[공유-맥락-이름]`으로 둘 수 있습니다.
+- `layout`은 공통 화면 틀, 인증/권한 체크, provider 주입을 담당합니다.
+- `layout`에는 페이지 전용 비즈니스 로직을 넣지 않습니다.
+- 컴포넌트는 크기보다 책임 경계로 나눕니다.
+- 너무 이른 공통화는 피합니다.
+
+## Why?
+
+- 기능 단위로 묶어두면 수정 범위가 좁아지고 찾기 쉬워집니다.
+- 공통 UI와 기능 전용 UI를 섞어두면 재사용 경계가 흐려집니다.
+- 전역 공통과 준공통을 같은 폴더에 몰아넣으면 `shared`가 금방 비대해집니다.
+- `layout`이 인증, provider, 공통 화면 틀을 맡으면 페이지 코드가 가벼워집니다.
+
+## 공통 계층을 나누는 기준
+
+### `features/<domain>/components`
+
+- 한 feature 안에서만 쓰는 컴포넌트
+- 해당 도메인 용어와 규칙이 그대로 남아 있는 컴포넌트
+
+### `shared/components/[공유-맥락-이름]`
+
+- 2~3개 feature가 함께 쓰는 준공통 컴포넌트
+- 전역 공통이라고 보긴 어렵지만, 특정 feature 하나에 두기 애매한 컴포넌트
+- 폴더명은 여러 feature를 억지로 이어붙이기보다, 겹치는 책임과 맥락을 한 개념으로 표현합니다.
+- 예: `shared/components/content-meta`, `shared/components/billing`
+
+### `shared/ui`
+
+- 앱 어디서든 재사용 가능한 진짜 공통 UI
+- 도메인 중립적인 primitive 또는 base component
+- 예: `Button`, `TextInputField`, `GlobalModal`
+
+## 공통 컴포넌트 판단 기준
+
+- 한 feature에서만 쓰면 `features/<domain>/components`에 둡니다.
+- `2~3개 독립 feature`가 비슷한 구조와 동작으로 쓰고, 공통 맥락이 남아 있으면 `shared/components/[공유-맥락-이름]`으로 올립니다.
+- 앱 어디서든 쓸 수 있는 도메인 중립 UI면 `shared/ui`로 올립니다.
+- 공통화는 마크업만이 아니라 동작과 props까지 비슷할 때 합니다.
+- 공통화 때문에 `variant`, `mode`, `type` 같은 예외 props가 계속 늘면 멈추고 feature에 둡니다.
+- `Button`, `TextInputField`, `GlobalModal` 같은 base UI는 `2개 feature`만 보여도 `shared/ui` 후보가 될 수 있습니다.
+
+여기서 feature는 `posts`, `comments`, `users`처럼 도메인이 다른 단위를 뜻합니다.  
+같은 feature 안의 여러 페이지는 보통 "여러 화면"으로 봅니다.
+
+## 예시 구조
+
+```text
+app/
+  (dashboard)/
+    layout.tsx
+    posts/page.tsx
+features/
+  posts/
+    api/
+      get-post-list.server.ts
+      get-post-list.client.ts
+    components/
+      post-list.tsx
+      post-list-client.tsx
+    hooks/
+      query-keys.ts
+      use-post-list-query.ts
+      use-create-post-mutation.ts
+    types/
+      post.ts
+shared/
+  components/
+    content-meta/
+      author-badge.tsx
+  ui/
+    button.tsx
+    global-modal.tsx
+    text-input-field.tsx
+```
+
+## 예시 코드
+
+```tsx
+// src/features/posts/components/post-publish-button.tsx
+type PostPublishButtonProps = {
+  postId: string;
+  isPublished: boolean;
+  onPublish: (postId: string) => void;
+};
+
+export function PostPublishButton({
+  postId,
+  isPublished,
+  onPublish,
+}: PostPublishButtonProps) {
+  return (
+    <button disabled={isPublished} onClick={() => onPublish(postId)}>
+      {isPublished ? "발행 완료" : "발행하기"}
+    </button>
+  );
+}
+```
+
+위 컴포넌트는 `postId`, `isPublished`, `onPublish`처럼 게시글 도메인에 강하게 묶여 있으므로 `shared`보다 `features/posts`에 두는 편이 자연스럽습니다.
+
+```tsx
+// src/shared/components/content-meta/author-badge.tsx
+type AuthorBadgeProps = {
+  name: string;
+  role?: string;
+};
+
+export function AuthorBadge({ name, role }: AuthorBadgeProps) {
+  return (
+    <div>
+      <strong>{name}</strong>
+      {role ? <span>{role}</span> : null}
+    </div>
+  );
+}
+```
+
+위 컴포넌트는 게시글과 댓글처럼 몇 개 feature에서 함께 쓸 수 있지만, 완전히 전역 공통 primitive라고 보긴 어려워서 `shared/components/content-meta` 같은 위치가 더 자연스럽습니다.
+
+여기서 이름은 `post-comment`처럼 글자를 이어붙이는 방식보다, 두 feature가 공유하는 맥락을 표현하는 `content-meta` 같은 이름이 더 좋습니다.
+
+```tsx
+// src/shared/ui/text-input-field.tsx
+import type { InputHTMLAttributes } from 'react';
+
+type TextInputFieldProps = {
+  label: string;
+  error?: string;
+} & InputHTMLAttributes<HTMLInputElement>;
+
+export function TextInputField({ label, error, id, ...props }: TextInputFieldProps) {
+  const inputId = id ?? props.name;
+
+  return (
+    <div>
+      <label htmlFor={inputId}>{label}</label>
+      <input id={inputId} {...props} />
+      {error ? <p className="text-sm text-rose-600">{error}</p> : null}
+    </div>
+  );
+}
+```
+
+위 컴포넌트는 특정 도메인을 모르고, 여러 feature에서 같은 방식으로 쓸 수 있어서 `shared/ui`로 올리기 좋습니다.
+
+```tsx
+// src/app/layout.tsx
+import './globals.css';
+
+import { AppProviders } from '@/app/providers';
+
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return (
+    <html lang="ko">
+      <body>
+        <AppProviders>{children}</AppProviders>
+      </body>
+    </html>
+  );
+}
+```
+
+## 체크 포인트
+
+- 이 코드가 특정 기능에만 쓰이는가: feature 안에 둡니다.
+- 2~3개 feature가 같이 쓰지만 공유되는 맥락을 한 이름으로 설명할 수 있는가: `shared/components/[공유-맥락-이름]` 후보입니다.
+- 앱 어디서든 쓸 수 있을 정도로 도메인 중립적인가: `shared/ui` 후보입니다.
+- 공통화하려면 예외 props가 계속 늘어나는가: 그렇다면 아직 feature에 둡니다.
+- 이 컴포넌트가 도메인 용어 없이도 설명 가능한가: 가능하면 `shared` 후보입니다.
+- 페이지 여러 곳이 같은 화면 틀을 쓰는가: `layout`으로 올립니다.
+
+## 한 줄 요약
+
+구조는 기능 기준으로 나누고, 공통 계층은 정말 공통인 것만 올립니다.

package/templates/shared/docs//352/260/234/353/260/234/354/233/220/354/271/231/02-/354/204/234/353/262/204/354/231/200-/355/201/264/353/235/274/354/235/264/354/226/270/355/212/270.md

@@ -0,0 +1,86 @@
+# 서버와 클라이언트
+
+## 원칙
+
+- Next.js에서는 서버 컴포넌트를 기본값으로 생각합니다.
+- 서버 컴포넌트는 초기 데이터 조회, 접근 제어, `redirect`, `notFound` 같은 라우팅 판단을 맡습니다.
+- 클라이언트 컴포넌트는 인터랙션, 브라우저 상태, 이벤트 처리를 맡습니다.
+- `use client`는 꼭 필요한 경우에만 붙입니다.
+
+## Why?
+
+- 서버에서 끝낼 수 있는 일을 클라이언트로 내리면 번들 크기와 복잡도가 커집니다.
+- 초기 데이터와 권한 체크를 서버에서 처리하면 화면 진입 흐름이 더 단순해집니다.
+- 반대로 입력, 드래그, 브라우저 API처럼 사용자 상호작용이 중심인 것은 클라이언트가 더 자연스럽습니다.
+
+## 서버에서 처리하기 좋은 것
+
+- 초기 데이터 조회
+- 인증/권한 체크
+- 페이지 진입 시 분기
+- 서버에서 끝낼 수 있는 가공
+
+## 클라이언트에서 처리하기 좋은 것
+
+- 클릭, 입력, 드래그 같은 상호작용
+- 브라우저 API 사용
+- 로컬 UI 상태 관리
+- 폼 제어
+
+## 판단 기준
+
+- 브라우저 API가 필요한가
+- 사용자 이벤트에 따라 즉시 반응해야 하는가
+- local state가 필요한가
+- 아니면 서버에서 미리 처리 가능한가
+
+위 질문에 대부분 `아니오`라면 서버에 두는 쪽이 기본입니다.
+
+## 예시 코드
+
+```tsx
+// src/app/posts/page.tsx
+import { getPostListServer } from '@/features/posts/api/get-post-list.server';
+import { PostFilter } from '@/features/posts/components/post-filter';
+import { PostList } from '@/features/posts/components/post-list';
+
+export default async function PostsPage() {
+  const posts = await getPostListServer();
+
+  return (
+    <section>
+      <h1>게시글</h1>
+      <PostFilter />
+      <PostList posts={posts} />
+    </section>
+  );
+}
+```
+
+```tsx
+// src/features/posts/components/post-filter.tsx
+'use client';
+
+import { useState } from 'react';
+
+import { TextInputField } from '@/shared/ui/text-input-field';
+
+export function PostFilter() {
+  const [keyword, setKeyword] = useState('');
+
+  return (
+    <TextInputField
+      label="검색"
+      value={keyword}
+      onChange={(event) => setKeyword(event.target.value)}
+      placeholder="검색어를 입력하세요"
+    />
+  );
+}
+```
+
+위 예시에서는 목록 데이터는 서버에서 가져오고, 입력 상호작용만 클라이언트로 분리했습니다.
+
+## 한 줄 요약
+
+서버는 초기 데이터와 접근 제어를 맡고, 클라이언트는 인터랙션과 브라우저 상태를 맡습니다.

package/templates/shared/docs//352/260/234/353/260/234/354/233/220/354/271/231/03-/354/203/201/355/203/234/352/264/200/353/246/254.md

@@ -0,0 +1,84 @@
+# 상태관리
+
+## 원칙
+
+- 상태는 한 군데 store에 몰아넣지 않습니다.
+- 상태의 성격에 맞는 계층에 둡니다.
+
+## Why?
+
+- 상태를 성격별로 나누면 중복 저장과 책임 충돌이 줄어듭니다.
+- 서버 데이터와 로컬 UI 상태를 같은 곳에 섞어두면 갱신 기준이 흐려집니다.
+- URL로 표현 가능한 상태를 URL에 두면 공유, 새로고침, 뒤로가기 동작이 자연스러워집니다.
+
+## 어디에 둘지 기준
+
+- URL로 표현 가능하고 공유/새로고침이 필요한 상태: URL
+- 서버에서 가져온 데이터: `TanStack Query`
+- 입력 중인 폼 값: `React Hook Form`
+- 특정 컴포넌트 안에서만 쓰는 UI 상태: local state
+- 앱 여러 곳이 동시에 알아야 하는 상태: global store
+
+## 전역 store 원칙
+
+- 인증 상태
+- 전역 모달
+- 앱 전역 UI 상태
+
+위처럼 정말 전역 공유가 필요한 것만 넣습니다.
+
+## 피할 것
+
+- 서버 데이터를 전역 store에 복제하기
+- URL에 둘 수 있는 상태를 store에만 두기
+- 폼 값을 전역 상태로 관리하기
+
+## 예시 코드
+
+```tsx
+// src/app/posts/page.tsx
+const params = useSearchParams();
+const page = Number(params.get('page') ?? '1');
+```
+
+```tsx
+// src/features/posts/components/post-list-client.tsx
+const { data: posts = [], isPending } = usePostListQuery();
+```
+
+```tsx
+// src/features/posts/components/create-post-form.tsx
+const form = useForm<CreatePostFormValues>({
+  resolver: zodResolver(createPostSchema),
+});
+```
+
+```tsx
+// src/features/posts/components/post-filter.tsx
+const [keyword, setKeyword] = useState('');
+```
+
+```ts
+// src/shared/ui/modal-store.ts
+export const useModalStore = create<ModalState>((set) => ({
+  isOpen: false,
+  title: '',
+  description: '',
+  openModal: ({ title, description }) =>
+    set({
+      isOpen: true,
+      title,
+      description,
+    }),
+  closeModal: () =>
+    set({
+      isOpen: false,
+      title: '',
+      description: '',
+    }),
+}));
+```
+
+## 한 줄 요약
+
+URL은 URL에, 서버 데이터는 Query에, 폼은 Form에, 지역 UI는 local state에 둡니다.