create-web-0to1 0.1.0

package/templates/react/README.md

@@ -0,0 +1,250 @@
+# Vite React Frontend Template
+
+실무에서 반복되는 구조를 바로 가져다 쓸 수 있도록 만든 `Vite + React + TypeScript` 템플릿이다.
+
+## Defaults
+
+- `feature-first` 구조
+- `react-router-dom` 기본 포함
+- `src/pages/**/page.tsx` 기반 자동 라우팅
+- 공통 `request` 코어 + 클라이언트 wrapper 분리
+- `TanStack Query` 중심 서버 상태 관리
+- `Zustand`는 전역 UI 상태에만 사용
+- `React Hook Form + Zod` 예제는 CRUD feature 생성 시 추가
+- 날짜, 포맷팅, query string, 에러 처리 같은 공통 로직 분리
+
+## Quick Start
+
+```bash
+npm install
+cp .env.example .env.local
+npm run dev
+```
+
+필수 환경 변수:
+
+```bash
+VITE_API_BASE_URL=http://localhost:4000
+```
+
+- 클라이언트 요청은 기본적으로 `VITE_API_BASE_URL`을 사용한다.
+- feature API 함수는 `features/<name>/api` 아래에 둔다.
+
+## Structure
+
+```txt
+src/
+  app/
+  pages/
+  features/
+  shared/
+    api/
+    auth/
+    config/
+    error/
+    lib/
+    query/
+    routes/
+    ui/
+    utils/
+```
+
+- `app`
+  - 앱 엔트리, router, provider, 공통 frame을 둔다.
+- `pages`
+  - route component를 둔다. `src/pages/**/page.tsx`는 자동으로 React Router 경로가 된다.
+- `features`
+  - 특정 도메인에서만 쓰는 API, hook, component, lib를 둔다.
+- `shared`
+  - 두 개 이상 feature 또는 앱 전역에서 재사용하는 공통 코드만 둔다.
+
+라우트 예시:
+
+- `src/pages/index/page.tsx` -> `/`
+- `src/pages/login/page.tsx` -> `/login`
+- `src/pages/products/page.tsx` -> `/products`
+- `src/pages/products/new/page.tsx` -> `/products/new`
+
+## Request And Error Flow
+
+요청 함수 선택 기준:
+
+- 일반 요청: `requestClient`
+- 인증 쿠키 포함 요청: `requestClientAuth`
+
+기준:
+
+- `request.ts`는 공통 타입과 실행 함수 정의를 두고, 실제 사용은 wrapper를 통해 한다.
+- 상대 경로 요청은 `VITE_API_BASE_URL`을 기준으로 실행된다.
+- `request`는 정규화된 `AppError`를 throw한다.
+
+예시:
+
+```ts
+import { requestClient } from '@/shared/api/request.client';
+
+export function getProducts(search?: string) {
+  return requestClient<Product[]>({
+    method: 'GET',
+    url: '/products',
+    params: { search },
+  });
+}
+```
+
+옵션 예제:
+
+- `src/shared/error/handle-app-error.client.ts`
+- `src/shared/auth/auth-error-listener.tsx`
+- `src/shared/ui/global-modal.tsx`
+- 기본 템플릿에서는 연결하지 않으며, 필요하면 `src/app/providers.tsx`, `src/app/frame.tsx`에서 수동으로 연결한다.
+
+## Scripts
+
+```bash
+npm run dev
+npm run build
+npm run preview
+npm run lint
+npm run lint:fix
+npm run format
+npm run format:check
+npm run pack:dry-run
+npm run release:check
+npm run create:feature -- products
+npm run create:feature:crud -- products
+```
+
+## Create Feature
+
+```bash
+npm run create:feature -- products
+```
+
+생성 대상:
+
+- `src/features/<name>/api/`
+- `src/features/<name>/components/`
+- `src/features/<name>/hooks/`
+- `src/features/<name>/lib/`
+- `src/pages/<name>/page.tsx`
+
+주의:
+
+- 최소 폴더 구조와 route page만 만든다.
+- route는 `src/pages/**/page.tsx` 규칙으로 자동 연결된다.
+- CRUD 예제가 필요하면 아래 명령을 사용한다.
+
+```bash
+npm run create:feature:crud -- products
+```
+
+CRUD 예시 생성 대상:
+
+- `src/features/<name>/api`
+- `src/features/<name>/components`
+- `src/features/<name>/hooks`
+- `src/features/<name>/lib`
+- `src/pages/<name>/page.tsx`
+- `src/pages/<name>/new/page.tsx`
+
+주의:
+
+- 생성된 API 함수는 외부 백엔드 연동을 전제로 한다.
+- same-origin mock route는 생성하지 않는다.
+- `routePaths`는 자동 병합하지 않는다.
+- 필요하면 생성 후 `src/shared/routes/route-paths.ts`에 직접 추가한다.
+
+관련 스크립트:
+
+- `scripts/create-app.mjs`
+- `scripts/create-feature.mjs`
+- `scripts/create-feature-crud.mjs`
+
+## Coding Defaults
+
+- 앱 내부 타입 선언은 기본적으로 `.ts` / `.tsx`에서 `type`을 우선 사용한다.
+- `interface`는 declaration merging이나 외부 타입 확장처럼 확장 계약이 필요할 때만 사용한다.
+- query key는 feature별 파일에서 관리하고, `GET`은 query, `POST/PUT/PATCH/DELETE`는 mutation으로 분리한다.
+- URL로 표현 가능한 상태는 URL에 두고, 전역 store는 여러 컴포넌트가 함께 알아야 하는 UI 상태에만 사용한다.
+- 날짜와 숫자 포맷팅은 공통 함수로 관리한다.
+- 클릭 가능한 요소는 `button`, 이동은 `Link`를 사용하고, input은 `label`과 연결한다.
+
+## Create App
+
+배포 전에 템플릿 로컬 검증이 필요하면 이 저장소에서 바로 실행할 수 있다.
+
+```bash
+node ./scripts/create-app.mjs my-app
+```
+
+`commitlint`까지 같이 확인하고 싶으면:
+
+```bash
+node ./scripts/create-app.mjs my-app --with-commitlint
+```
+
+스타일 없이 시작하는 버전으로 확인하고 싶으면:
+
+```bash
+node ./scripts/create-app.mjs my-app --no-style
+```
+
+패키지를 npm에 배포한 뒤에는 아래처럼 사용할 수 있다.
+
+```bash
+npm create react-0to1@latest my-app
+```
+
+또는:
+
+```bash
+bun create react-0to1 my-app
+```
+
+기본 실행 시에는 `create-vite`의 원래 인터랙션이 그대로 열린다.
+
+이 템플릿은 React 계열 Vite 템플릿만 지원한다.
+- 예: `react-ts`, `react-compiler-ts`
+- `vue`, `svelte`, `solid` 같은 비-React 템플릿을 고르면 생성 결과를 정리한 뒤 안내 메시지와 함께 중단한다.
+
+인터랙션 없이 바로 만들고 싶으면:
+
+```bash
+npm create react-0to1@latest my-app -- --template react-ts
+```
+
+React Compiler 템플릿을 바로 쓰고 싶으면:
+
+```bash
+npm create react-0to1@latest my-app -- --template react-compiler-ts
+```
+
+배포 후 `commitlint`까지 같이 넣고 싶으면:
+
+```bash
+npm create react-0to1@latest my-app -- --with-commitlint
+```
+
+스타일 파일 없이 시작하고 싶으면:
+
+```bash
+npm create react-0to1@latest my-app -- --no-style
+```
+
+`--with-commitlint`를 켜면 `commit-msg` hook과 `commitlint` 설정이 추가되고, `feat: 내용` 같은 Conventional Commits 형식을 검사한다.
+`--no-style`을 켜면 `@tailwindcss/vite`, `tailwindcss`, 전역 CSS import를 제외하고 기본 화면과 feature 스캐폴드도 스타일 없이 생성한다.
+
+## Release Flow
+
+첫 공개 릴리스 전에는 아래 순서를 권장한다.
+
+1. `npm run release:check`
+2. `npm publish`
+3. `npm view create-react-0to1 version`
+4. 배포 확인 후 README의 `npm create react-0to1@latest my-app` 예시를 사용한다.
+
+버전을 올려서 배포할 때는 필요 시 먼저 `package.json`과 `package-lock.json`의 버전을 함께 갱신한다.
+
+이 템플릿은 `TypeScript + React Router + ESLint + Vite` 전제를 가진다.
+Husky는 기본 설치하며, `pre-commit`에서 `lint`만 실행한다.

package/templates/react/_gitignore

@@ -0,0 +1,31 @@
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# build
+/dist
+/coverage
+
+# misc
+.DS_Store
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files
+.env*
+!.env.example
+
+# typescript
+*.tsbuildinfo
+
+.idea

package/templates/react/eslint.config.mjs

@@ -0,0 +1,64 @@
+import js from '@eslint/js';
+import { defineConfig, globalIgnores } from 'eslint/config';
+import prettier from 'eslint-config-prettier/flat';
+import globals from 'globals';
+import reactHooks from 'eslint-plugin-react-hooks';
+import reactRefresh from 'eslint-plugin-react-refresh';
+import simpleImportSort from 'eslint-plugin-simple-import-sort';
+import unusedImports from 'eslint-plugin-unused-imports';
+import tseslint from 'typescript-eslint';
+
+export default defineConfig([
+  globalIgnores(['dist/**', 'coverage/**']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      js.configs.recommended,
+      ...tseslint.configs.recommended,
+      reactHooks.configs.flat.recommended,
+      reactRefresh.configs.vite,
+    ],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: {
+        ...globals.browser,
+        ...globals.node,
+      },
+    },
+    plugins: {
+      'simple-import-sort': simpleImportSort,
+      'unused-imports': unusedImports,
+    },
+    rules: {
+      'no-var': 'error',
+      'prefer-const': 'error',
+      curly: ['error', 'all'],
+      eqeqeq: ['error', 'always'],
+      'object-shorthand': ['error', 'always'],
+      'no-unused-vars': 'off',
+      '@typescript-eslint/no-unused-vars': 'off',
+      'unused-imports/no-unused-imports': 'error',
+      'unused-imports/no-unused-vars': [
+        'warn',
+        {
+          args: 'after-used',
+          argsIgnorePattern: '^_',
+          ignoreRestSiblings: true,
+          vars: 'all',
+          varsIgnorePattern: '^_',
+        },
+      ],
+      '@typescript-eslint/consistent-type-imports': [
+        'error',
+        {
+          disallowTypeAnnotations: false,
+          fixStyle: 'inline-type-imports',
+          prefer: 'type-imports',
+        },
+      ],
+      'simple-import-sort/imports': 'error',
+      'simple-import-sort/exports': 'error',
+    },
+  },
+  prettier,
+]);

package/templates/react/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "__PROJECT_NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "lint": "eslint .",
+    "lint:fix": "eslint --fix .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "pack:dry-run": "npm pack --dry-run",
+    "release:check": "npm run lint && npm run build && npm run pack:dry-run",
+    "preview": "vite preview",
+    "create:feature": "node ./scripts/create-feature.mjs",
+    "create:feature:crud": "node ./scripts/create-feature-crud.mjs"
+  }
+}

package/templates/react/scripts/create-feature-crud.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+console.error('이 파일은 generator 템플릿 placeholder입니다.');
+console.error('실제 생성 결과물에서는 engine이 공통 create-feature-crud 스크립트로 대체합니다.');
+process.exit(1);

package/templates/react/scripts/create-feature.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+console.error('이 파일은 generator 템플릿 placeholder입니다.');
+console.error('실제 생성 결과물에서는 engine이 공통 create-feature 스크립트로 대체합니다.');
+process.exit(1);

package/templates/react/src/app/app.tsx

@@ -0,0 +1,15 @@
+import { RouterProvider } from 'react-router-dom';
+
+import { AppErrorBoundary } from '@/app/error-boundary';
+import { AppProviders } from '@/app/providers';
+import { router } from '@/app/router';
+
+export default function App() {
+  return (
+    <AppErrorBoundary>
+      <AppProviders>
+        <RouterProvider router={router} />
+      </AppProviders>
+    </AppErrorBoundary>
+  );
+}

package/templates/react/src/app/error-boundary.tsx

@@ -0,0 +1,59 @@
+import { Component, type ErrorInfo, type ReactNode } from 'react';
+
+type AppErrorBoundaryProps = {
+  children: ReactNode;
+};
+
+type AppErrorBoundaryState = {
+  error: Error | null;
+  retryKey: number;
+};
+
+export class AppErrorBoundary extends Component<AppErrorBoundaryProps, AppErrorBoundaryState> {
+  state: AppErrorBoundaryState = {
+    error: null,
+    retryKey: 0,
+  };
+
+  static getDerivedStateFromError(error: Error): Partial<AppErrorBoundaryState> {
+    return {
+      error,
+    };
+  }
+
+  componentDidCatch(error: Error, errorInfo: ErrorInfo) {
+    console.error(error, errorInfo);
+  }
+
+  handleRetry = () => {
+    this.setState((prevState) => ({
+      error: null,
+      retryKey: prevState.retryKey + 1,
+    }));
+  };
+
+  render() {
+    if (this.state.error) {
+      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>
+            <button
+              type="button"
+              onClick={this.handleRetry}
+              className="mt-6 rounded-lg bg-zinc-950 px-4 py-2 text-sm font-medium text-white"
+            >
+              다시 시도
+            </button>
+          </section>
+        </main>
+      );
+    }
+
+    return <div key={this.state.retryKey}>{this.props.children}</div>;
+  }
+}

package/templates/react/src/app/frame.tsx

@@ -0,0 +1,32 @@
+import { Outlet, useNavigation } from 'react-router-dom';
+
+/**
+ * 앱 공통 레이아웃 예시입니다.
+ * 공통 헤더, 인증 리스너, 전역 모달 연결이 필요하면 여기서 추가해서 사용하세요.
+ */
+export function AppFrame() {
+  const navigation = useNavigation();
+  const isRoutePending = navigation.state !== 'idle';
+
+  return (
+    <div className="min-h-screen bg-zinc-50 text-zinc-950">
+      {isRoutePending ? (
+        <>
+          <div className="fixed inset-x-0 top-0 z-50 h-1 overflow-hidden bg-zinc-200/80">
+            <div className="h-full w-1/3 animate-pulse rounded-full bg-zinc-950" />
+          </div>
+          <div className="pointer-events-none fixed inset-x-0 top-5 z-50 flex justify-center px-4">
+            <div
+              role="status"
+              aria-live="polite"
+              className="rounded-full border border-zinc-200 bg-white/95 px-3 py-1 text-xs font-medium tracking-[0.12em] text-zinc-600 shadow-sm backdrop-blur"
+            >
+              페이지를 불러오는 중입니다
+            </div>
+          </div>
+        </>
+      ) : null}
+      <Outlet />
+    </div>
+  );
+}

package/templates/react/src/app/globals.css

@@ -0,0 +1,43 @@
+@import 'tailwindcss';
+
+:root {
+  --background: #fafaf9;
+  --foreground: #18181b;
+}
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --font-sans:
+    'Pretendard Variable', 'Pretendard', 'Apple SD Gothic Neo', 'Malgun Gothic', sans-serif;
+  --font-mono: 'SFMono-Regular', ui-monospace, monospace;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html,
+body,
+#root {
+  min-height: 100%;
+}
+
+body {
+  margin: 0;
+  background: var(--background);
+  color: var(--foreground);
+  font-family: var(--font-sans);
+}
+
+button,
+input,
+textarea,
+select {
+  font: inherit;
+}
+
+a {
+  color: inherit;
+  text-decoration: none;
+}

package/templates/react/src/app/not-found-page.tsx

@@ -0,0 +1,23 @@
+import { Link } from 'react-router-dom';
+
+import { routePaths } from '@/shared/routes/route-paths';
+
+export function NotFoundPage() {
+  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">404</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>
+        <Link
+          to={routePaths.home}
+          className="mt-6 inline-flex rounded-lg bg-zinc-950 px-4 py-2 text-sm font-medium text-white"
+        >
+          홈으로 이동
+        </Link>
+      </section>
+    </main>
+  );
+}

package/templates/react/src/app/providers.tsx

@@ -0,0 +1,16 @@
+import type { ReactNode } from 'react';
+
+import { QueryProviders } from '@/shared/query/providers';
+
+type AppProvidersProps = {
+  children: ReactNode;
+};
+
+/**
+ * 앱 전역 provider 연결 지점입니다.
+ * 전역 query 에러 처리가 필요하면
+ * <QueryProviders onGlobalError={handleClientAppError}> 처럼 연결해서 사용하세요.
+ */
+export function AppProviders({ children }: AppProvidersProps) {
+  return <QueryProviders>{children}</QueryProviders>;
+}

package/templates/react/src/app/router.tsx

@@ -0,0 +1,62 @@
+import type { ComponentType } from 'react';
+import { createBrowserRouter, type RouteObject } from 'react-router-dom';
+
+import { AppFrame } from '@/app/frame';
+import { NotFoundPage } from '@/app/not-found-page';
+
+type PageModule = {
+  default: ComponentType;
+};
+
+const pageModules = import.meta.glob<PageModule>('../pages/**/page.tsx', {
+  eager: false,
+});
+
+function toRoutePath(filePath: string) {
+  const relativePath = filePath.replace('../pages/', '').replace('/page.tsx', '');
+  const segments = relativePath
+    .split('/')
+    .filter(Boolean)
+    .filter((segment) => segment !== 'index');
+
+  return segments.join('/');
+}
+
+function createPageRoutes(): RouteObject[] {
+  return Object.entries(pageModules).map(([filePath, loadPageModule]) => {
+    const routePath = toRoutePath(filePath);
+    const lazy = async () => {
+      const module = await loadPageModule();
+
+      return {
+        Component: module.default,
+      };
+    };
+
+    if (!routePath) {
+      return {
+        index: true,
+        lazy,
+      };
+    }
+
+    return {
+      path: routePath,
+      lazy,
+    };
+  });
+}
+
+export const router = createBrowserRouter([
+  {
+    path: '/',
+    element: <AppFrame />,
+    children: [
+      ...createPageRoutes(),
+      {
+        path: '*',
+        element: <NotFoundPage />,
+      },
+    ],
+  },
+]);

package/templates/react/src/main.tsx

@@ -0,0 +1,12 @@
+import '@/app/globals.css';
+
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+
+import App from '@/app/app';
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);

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

@@ -0,0 +1,36 @@
+/**
+ * 템플릿 첫 화면 예시입니다.
+ * 프로젝트 소개나 대시보드 시작 화면으로 교체해서 사용하세요.
+ */
+export default function HomePage() {
+  return (
+    <main className="mx-auto flex min-h-screen w-full max-w-5xl flex-col gap-8 px-6 py-16">
+      <section className="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-4xl font-semibold tracking-tight text-zinc-950">
+          필요한 기본값과 필수 전역 처리를 갖춘 Vite React 프론트엔드 스타터
+        </h1>
+        <p className="mt-4 max-w-3xl text-base leading-7 text-zinc-600">
+          이 템플릿은 feature-first 구조, React Router, TanStack Query, request helper, shared
+          utilities처럼 초기에 바로 필요한 것만 포함합니다.
+        </p>
+      </section>
+
+      <section className="rounded-3xl border border-dashed border-zinc-300 bg-zinc-50 p-8">
+        <h2 className="text-lg font-semibold text-zinc-950">기본 라우팅 흐름까지 바로 시작</h2>
+        <ul className="mt-3 grid gap-2 text-sm leading-6 text-zinc-600">
+          <li>
+            <code>src/pages/**/page.tsx</code> 파일은 자동으로 React Router 경로가 됩니다.
+          </li>
+          <li>
+            <code>react-router-dom</code>, Query, request helper를 기본으로 포함했습니다.
+          </li>
+          <li>
+            폼/목록 예제가 필요하면 <code>npm run create:feature -- products</code>로 생성할 수
+            있습니다.
+          </li>
+        </ul>
+      </section>
+    </main>
+  );
+}