@farmzone/fz-template-react 0.0.1

package/README.md

@@ -0,0 +1,108 @@
+# @farmzone/fz-template-react
+
+Farmzone React 프로젝트 보일러플레이트 생성 CLI.
+
+## 사용법
+
+```bash
+npx @farmzone/fz-template-react <프로젝트명>
+```
+
+예시:
+
+```bash
+npx @farmzone/fz-template-react my-app
+cd my-app
+npm install
+npm run dev
+```
+
+프로젝트명을 생략하면 대화형으로 입력을 받습니다.
+
+```bash
+npx @farmzone/fz-template-react
+# 프로젝트 이름을 입력하세요: my-app
+```
+
+## 생성되는 프로젝트 구조
+
+```
+my-app/
+├── src/
+│   ├── app/
+│   │   ├── layout/
+│   │   │   ├── Layout.tsx       # 사이드바 + Outlet 레이아웃
+│   │   │   ├── Sidebar.tsx      # 사이드바 컴포넌트
+│   │   │   └── menu.ts          # 메뉴 설정
+│   │   ├── router/
+│   │   │   └── Router.tsx
+│   │   └── App.tsx              # QueryClientProvider 루트
+│   ├── pages/
+│   │   ├── dashboard/
+│   │   │   └── index.tsx
+│   │   └── error/
+│   │       ├── Error.tsx
+│   │       └── NotFound.tsx
+│   └── index.tsx
+├── .gitignore
+├── index.html
+├── index.css
+├── vite.config.ts
+├── tsconfig.json
+└── package.json
+```
+
+## 포함된 기술 스택
+
+| 항목 | 버전 |
+|---|---|
+| React | ^19 |
+| Vite | ^7 |
+| TypeScript | ~5.9 |
+| Tailwind CSS | v4 |
+| React Router | ^7 |
+| TanStack Query | ^5 |
+| @farmzone/fz-react-ui | latest |
+| react-hook-form + zod | 최신 |
+
+## 메뉴 추가
+
+`src/app/layout/menu.ts` 수정:
+
+```ts
+import { LayoutDashboard, Users, ScrollText } from "lucide-react";
+
+export const MENU_SECTIONS: MenuSection[] = [
+  {
+    items: [
+      { icon: LayoutDashboard, label: "대시보드", path: "/" },
+    ],
+  },
+  {
+    title: "관리",
+    items: [
+      { icon: Users, label: "사용자 관리", path: "/user" },
+      { icon: ScrollText, label: "로그", path: "/log" },
+    ],
+  },
+];
+```
+
+## 라우트 추가
+
+`src/app/router/Router.tsx`의 `children` 배열에 추가:
+
+```tsx
+children: [
+  { index: true, element: <DashboardPage /> },
+  { path: "user", element: <UserListPage /> },
+  { path: "user/:id", element: <UserDetailPage /> },
+  { path: "log", element: <LogPage /> },
+],
+```
+
+## npm 배포
+
+```bash
+npm publish --access public
+```

package/bin/create.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+
+import { createInterface } from "readline";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  statSync,
+  copyFileSync,
+  readFileSync,
+  writeFileSync,
+  renameSync,
+} from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+function prompt(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+function copyDir(src, dest) {
+  mkdirSync(dest, { recursive: true });
+  for (const entry of readdirSync(src)) {
+    const srcPath = join(src, entry);
+    const destPath = join(dest, entry);
+    if (statSync(srcPath).isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function replaceInFile(filePath, search, replacement) {
+  if (!existsSync(filePath)) return;
+  const content = readFileSync(filePath, "utf-8");
+  writeFileSync(filePath, content.replaceAll(search, replacement));
+}
+
+async function main() {
+  console.log("\n🌱 Farmzone React Template\n");
+
+  let projectName = process.argv[2];
+
+  if (!projectName) {
+    projectName = await prompt("프로젝트 이름을 입력하세요: ");
+  }
+
+  if (!projectName) {
+    console.error("❌ 프로젝트 이름을 입력해야 합니다.");
+    process.exit(1);
+  }
+
+  if (!/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/.test(projectName)) {
+    console.error("❌ 프로젝트 이름은 소문자, 숫자, 하이픈(-)만 사용 가능하며 하이픈으로 시작하거나 끝날 수 없습니다.");
+    process.exit(1);
+  }
+
+  const targetDir = join(process.cwd(), projectName);
+
+  if (existsSync(targetDir)) {
+    console.error(`❌ '${projectName}' 디렉터리가 이미 존재합니다.`);
+    process.exit(1);
+  }
+
+  const templateDir = join(__dirname, "..", "template");
+
+  console.log(`\n🚀 '${projectName}' 프로젝트를 생성합니다...\n`);
+
+  // 템플릿 복사
+  copyDir(templateDir, targetDir);
+
+  // gitignore -> .gitignore 이름 변경 (npm publish 시 .gitignore는 자동으로 제외됨)
+  const gitignoreSrc = join(targetDir, "gitignore");
+  const gitignoreDest = join(targetDir, ".gitignore");
+  if (existsSync(gitignoreSrc)) renameSync(gitignoreSrc, gitignoreDest);
+
+  // __PROJECT_NAME__ 치환
+  replaceInFile(join(targetDir, "package.json"), "__PROJECT_NAME__", projectName);
+  replaceInFile(join(targetDir, "index.html"), "__PROJECT_NAME__", projectName);
+
+  console.log("✅ 프로젝트 생성 완료!\n");
+  console.log("──────────────────────────────");
+  console.log("다음 명령어로 시작하세요:\n");
+  console.log(`  cd ${projectName}`);
+  console.log(`  npm install`);
+  console.log(`  npm run dev`);
+  console.log("──────────────────────────────\n");
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@farmzone/fz-template-react",
+  "version": "0.0.1",
+  "description": "Farmzone React 프로젝트 보일러플레이트 생성 CLI",
+  "type": "module",
+  "bin": {
+    "fz-template-react": "./bin/create.js"
+  },
+  "files": [
+    "bin",
+    "template"
+  ],
+  "keywords": [
+    "farmzone",
+    "react",
+    "template",
+    "boilerplate",
+    "vite"
+  ],
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/template/.prettierrc

@@ -0,0 +1,9 @@
+{
+  "printWidth": 110,
+  "tabWidth": 2,
+  "semi": true,
+  "bracketSpacing": true,
+  "singleQuote": false,
+  "jsxSingleQuote": false,
+  "trailingComma": "all"
+}

package/template/eslint.config.js

@@ -0,0 +1,23 @@
+import js from "@eslint/js";
+import globals from "globals";
+import reactHooks from "eslint-plugin-react-hooks";
+import reactRefresh from "eslint-plugin-react-refresh";
+import tseslint from "typescript-eslint";
+import { defineConfig, globalIgnores } from "eslint/config";
+
+export default defineConfig([
+  globalIgnores(["dist"]),
+  {
+    files: ["**/*.{ts,tsx}"],
+    extends: [
+      js.configs.recommended,
+      tseslint.configs.recommended,
+      reactHooks.configs.flat.recommended,
+      reactRefresh.configs.vite,
+    ],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+    },
+  },
+]);

package/template/gitignore

@@ -0,0 +1,32 @@
+# 로그
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# 의존성
+node_modules/
+.pnp
+.pnp.js
+
+# 빌드 결과물
+dist/
+dist-ssr/
+
+# 환경 변수
+.env
+.env.local
+.env.*.local
+
+# 에디터
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

package/template/index.css

@@ -0,0 +1,19 @@
+@import "tailwindcss";
+@import "tw-animate-css";
+@import "@farmzone/fz-react-ui/styles";
+
+@custom-variant dark (&:is(.dark *));
+
+@tailwind utilities;
+
+@theme inline {
+  --color-main: #3b82f6;
+  --color-sub-lightgray: #f3f4f6;
+  --color-sub-darkgray: #6b7280;
+  --color-sub-darkgray-2: #374151;
+  --color-basic-gray: #9ca3af;
+}
+
+body {
+  font-family: "Pretendard Variable", Pretendard, -apple-system, BlinkMacSystemFont, system-ui, sans-serif;
+}

package/template/index.html

@@ -0,0 +1,19 @@
+<!doctype html>
+<html lang="ko">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.ico" />
+    <link
+      rel="stylesheet"
+      as="style"
+      crossorigin
+      href="https://cdn.jsdelivr.net/gh/orioncactus/pretendard@v1.3.9/dist/web/static/pretendard-dynamic-subset.min.css"
+    />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>__PROJECT_NAME__</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/index.tsx"></script>
+  </body>
+</html>

package/template/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "__PROJECT_NAME__",
+  "private": true,
+  "version": "0.0.1",
+  "type": "module",
+  "scripts": {
+    "dev": "vite --host 0.0.0.0 --port 3000",
+    "build": "tsc -b && vite build",
+    "lint": "eslint .",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@farmzone/fz-react-ui": "latest",
+    "@hookform/resolvers": "^5.2.2",
+    "@tanstack/react-query": "^5.90.0",
+    "axios": "^1.13.0",
+    "lucide-react": "^1.16.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-hook-form": "^7.68.0",
+    "react-router": "^7.11.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "@tailwindcss/vite": "^4.1.0",
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^5.1.0",
+    "eslint": "^9.0.0",
+    "eslint-plugin-react-hooks": "^5.0.0",
+    "eslint-plugin-react-refresh": "^0.4.0",
+    "globals": "^16.0.0",
+    "tailwindcss": "^4.0.0",
+    "tw-animate-css": "^1.0.0",
+    "typescript": "~5.9.0",
+    "typescript-eslint": "^8.0.0",
+    "vite": "^7.0.0"
+  }
+}

package/template/src/app/App.tsx

@@ -0,0 +1,24 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+import Router from "@/app/router/Router";
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 0,
+      gcTime: 5 * 60 * 1000,
+      refetchOnMount: true,
+      refetchOnReconnect: false,
+      refetchOnWindowFocus: false,
+      retry: 1,
+    },
+  },
+});
+
+export default function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <Router />
+    </QueryClientProvider>
+  );
+}

package/template/src/app/layout/Layout.tsx

@@ -0,0 +1,16 @@
+import { Outlet } from "react-router";
+import { ToastProvider } from "@farmzone/fz-react-ui";
+
+import Sidebar from "./Sidebar";
+
+export default function Layout() {
+  return (
+    <div className="flex h-screen bg-gray-50">
+      <ToastProvider />
+      <Sidebar />
+      <main className="flex-1 overflow-y-auto">
+        <Outlet />
+      </main>
+    </div>
+  );
+}

package/template/src/app/layout/Sidebar.tsx

@@ -0,0 +1,53 @@
+import { NavLink, useNavigate } from "react-router";
+import { cn } from "@farmzone/fz-react-ui";
+
+import { MENU_SECTIONS } from "./menu";
+
+export default function Sidebar() {
+  const navigate = useNavigate();
+
+  return (
+    <aside className="flex h-screen w-56 shrink-0 flex-col border-r border-gray-200 bg-white">
+      {/* 로고 영역 */}
+      <div className="flex h-14 items-center border-b border-gray-200 px-5">
+        <button
+          onClick={() => navigate("/")}
+          className="text-base font-bold text-gray-900 transition-colors hover:text-blue-600"
+        >
+          PROJECT
+        </button>
+      </div>
+
+      {/* 메뉴 영역 */}
+      <nav className="flex-1 overflow-y-auto px-3 py-4">
+        {MENU_SECTIONS.map((section, i) => (
+          <div key={i} className="mb-4">
+            {section.title && (
+              <p className="mb-1 px-3 text-xs font-semibold uppercase tracking-wider text-gray-400">
+                {section.title}
+              </p>
+            )}
+            {section.items.map((item) => (
+              <NavLink
+                key={item.path}
+                to={item.path}
+                end={item.path === "/"}
+                className={({ isActive }) =>
+                  cn(
+                    "mb-0.5 flex items-center gap-3 rounded-md px-3 py-2 text-sm font-medium transition-colors",
+                    isActive
+                      ? "bg-blue-50 text-blue-600"
+                      : "text-gray-600 hover:bg-gray-100 hover:text-gray-900",
+                  )
+                }
+              >
+                <item.icon size={18} strokeWidth={1.8} />
+                {item.label}
+              </NavLink>
+            ))}
+          </div>
+        ))}
+      </nav>
+    </aside>
+  );
+}

package/template/src/app/layout/menu.ts

@@ -0,0 +1,27 @@
+import { LayoutDashboard } from "lucide-react";
+import type { LucideIcon } from "lucide-react";
+
+export interface MenuItem {
+  icon: LucideIcon;
+  label: string;
+  path: string;
+}
+
+export interface MenuSection {
+  title?: string;
+  items: MenuItem[];
+}
+
+export const MENU_SECTIONS: MenuSection[] = [
+  {
+    items: [{ icon: LayoutDashboard, label: "대시보드", path: "/" }],
+  },
+  // 메뉴 섹션 추가 예시:
+  // {
+  //   title: "관리",
+  //   items: [
+  //     { icon: Users, label: "사용자 관리", path: "/user" },
+  //     { icon: ScrollText, label: "로그", path: "/log" },
+  //   ],
+  // },
+];

package/template/src/app/router/Router.tsx

@@ -0,0 +1,28 @@
+import { useMemo } from "react";
+import { createBrowserRouter, RouterProvider } from "react-router";
+
+import Layout from "@/app/layout/Layout";
+import DashboardPage from "@/pages/dashboard";
+import ErrorPage from "@/pages/error/Error";
+import NotFoundPage from "@/pages/error/NotFound";
+
+export default function Router() {
+  const router = useMemo(
+    () =>
+      createBrowserRouter([
+        {
+          path: "/",
+          element: <Layout />,
+          errorElement: <ErrorPage />,
+          children: [
+            { index: true, element: <DashboardPage /> },
+            // 여기에 라우트를 추가하세요
+          ],
+        },
+        { path: "*", element: <NotFoundPage /> },
+      ]),
+    [],
+  );
+
+  return <RouterProvider router={router} />;
+}

package/template/src/index.tsx

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

package/template/src/pages/dashboard/index.tsx

@@ -0,0 +1,8 @@
+export default function DashboardPage() {
+  return (
+    <div className="p-8">
+      <h1 className="text-2xl font-bold text-gray-900">대시보드</h1>
+      <p className="mt-2 text-sm text-gray-500">환영합니다. 여기에 대시보드 콘텐츠를 추가하세요.</p>
+    </div>
+  );
+}

package/template/src/pages/error/Error.tsx

@@ -0,0 +1,17 @@
+import { useRouteError, useNavigate } from "react-router";
+import { Button } from "@farmzone/fz-react-ui";
+
+export default function ErrorPage() {
+  const error = useRouteError() as { statusText?: string; message?: string };
+  const navigate = useNavigate();
+
+  return (
+    <div className="flex h-screen flex-col items-center justify-center gap-4 bg-gray-50">
+      <h1 className="text-4xl font-bold text-gray-900">오류가 발생했습니다</h1>
+      <p className="text-gray-500">{error?.statusText ?? error?.message ?? "알 수 없는 오류"}</p>
+      <Button variant="outline" onClick={() => navigate("/")}>
+        홈으로 돌아가기
+      </Button>
+    </div>
+  );
+}

package/template/src/pages/error/NotFound.tsx

@@ -0,0 +1,17 @@
+import { useNavigate } from "react-router";
+import { Button } from "@farmzone/fz-react-ui";
+
+export default function NotFoundPage() {
+  const navigate = useNavigate();
+
+  return (
+    <div className="flex h-screen flex-col items-center justify-center gap-3 bg-gray-50">
+      <p className="text-8xl font-bold text-gray-200">404</p>
+      <h1 className="text-xl font-semibold text-gray-700">페이지를 찾을 수 없습니다</h1>
+      <p className="text-sm text-gray-400">요청하신 페이지가 존재하지 않거나 이동되었습니다.</p>
+      <Button className="mt-2" onClick={() => navigate("/")}>
+        홈으로 돌아가기
+      </Button>
+    </div>
+  );
+}

package/template/tsconfig.app.json

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

package/template/tsconfig.json

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

package/template/tsconfig.node.json

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

package/template/vite.config.ts

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