npm - create-web-0to1 - Versions diffs - 0.1.0 - Mend

create-web-0to1 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (193) hide show

package/templates/monorepo/README.md ADDED Viewed

@@ -0,0 +1,292 @@
+# AI CMS Monorepo
+단일 Next.js 앱을 기준으로 CMS 프론트엔드와 공통 패키지를 관리하는 모노레포입니다.
+현재 구조는 다음 전제를 기준으로 정리되어 있습니다.
+- 앱 코드는 named export만 사용합니다.
+- API 함수는 `@repo/core/api/*`에서 직접 import 합니다.
+- `@repo/core-react`는 React 클라이언트 공통 기능을 제공합니다.
+- `@repo/core-next`는 Next.js 전용 기능과 `@repo/core-react` 재export를 제공합니다.
+- `ui` 패키지는 별도 디자인 시스템으로 보고, fetch/error/core-next/eslint 정리와 분리해서 유지합니다.
+## 전제
+- 현재 `initCore()`는 module-scoped state를 사용합니다.
+- 그래서 `siteId`와 `baseUrl`이 앱 단위로 고정되는 구조를 전제로 합니다.
+- 고객사별로 앱이 아예 분리 배포되거나, 앱 하나가 사실상 고정 설정으로 운영되는 경우에는 지금 구조로 충분합니다.
+- 현재 이 레포는 그 전제를 따르고 있으므로, `initCore()`는 가장 단순하고 유지비가 낮은 선택으로 봅니다.
+- 하나의 서버 프로세스가 요청마다 다른 `siteId`를 처리하는 진짜 멀티테넌트 구조로 가면, 이 초기화 방식은 나중에 바꿔야 합니다.
+## 폴더 구조
+- `apps/web`: Next.js App Router 기준 앱
+- `apps/project`: Vite 예제 앱
+- `packages/core`: 프레임워크 비의존 fetch, request, error, core API
+- `packages/core-react`: React Query provider, query client, client auth wrapper
+- `packages/core-next`: Next.js 전용 bootstrap, server auth wrapper, `core-react` facade
+- `packages/ui`: 공용 UI 패키지
+- `packages/eslint-config`: 공용 ESLint 설정
+- `packages/typescript-config`: 공용 TypeScript 설정
+## 실행
+```bash
+pnpm install
+pnpm dev
+```
+자주 쓰는 명령:
+```bash
+pnpm build
+pnpm lint
+pnpm check-types
+```
+## 앱 생성
+이 monorepo에는 `turbo/generators/config.js` 기준의 custom generator가 같이 들어 있습니다.
+새 앱을 추가할 때는 레포 루트에서 아래 명령을 실행합니다.
+```bash
+pnpm turbo gen create-next
+pnpm turbo gen create-vite
+```
+자주 쓰게 되면 아래 shortcut script로 실행해도 됩니다.
+```bash
+pnpm gen:next
+pnpm gen:vite
+```
+현재 generator가 묻는 대표 질문:
+- 앱 이름
+- `siteId`
+- API base URL
+- 추가할 workspace dependency / devDependency
+역할 분리:
+- `turbo/generators/config.js`: monorepo 전용 generator 동작
+- `turbo/generators/templates/**/*.tpl`: generator가 복사하는 정적 scaffold
+- `packages/core*`: generator가 연결하는 공통 runtime 패키지
+이 generator 자산은 standalone `create-app` 흐름과 달리 monorepo preset 안에서 그대로 유지하는 static template 경계로 봅니다.
+## 패키지 규칙
+### `@repo/core`
+역할:
+- 순수 request 실행기
+- 공용 에러 타입과 정규화
+- API 함수 구현
+공개 경로:
+- `@repo/core`
+- `@repo/core/api/*`
+루트 export에는 다음 성격의 것만 둡니다.
+- `initCore`
+- request 타입
+- error 타입/유틸
+API 함수는 루트에 다시 모으지 않습니다.
+이유:
+- 파일 하나 만들고 바로 import 가능해야 합니다.
+- 중앙 barrel 파일을 계속 수정하지 않기 위해서입니다.
+- 클라이언트 번들에서 tree-shaking이 잘 되게 하기 위해서입니다.
+예시:
+```ts
+import { initCore } from "@repo/core";
+import { testFetch } from "@repo/core/api/test";
+```
+### `@repo/core-next`
+역할:
+- Next.js 환경에서 필요한 부가 기능 제공
+- `@repo/core-react`를 재export해서 Next 앱에서 한 패키지로 쓰기 쉽게 구성
+- `@repo/core` API를 다시 pass-through 하지는 않음
+공개 경로:
+- `@repo/core-next`
+- `@repo/core-next/bootstrap`
+- `@repo/core-next/server-auth`
+- `@repo/core-next/client-auth`
+이 패키지에는 API 함수 자체를 두지 않습니다. API 함수는 항상 `@repo/core/api/*`에서 직접 가져옵니다.
+### `@repo/core-react`
+역할:
+- React Query `QueryClient` 생성
+- 공용 React provider
+- 조합형 app providers
+- query hydration helper
+- 클라이언트 auth wrapper
+- query key factory
+- 클라이언트 query 에러 핸들러
+공개 경로:
+- `@repo/core-react`
+## 사용법
+### 1. 앱 초기화
+Next.js에서는 루트 레이아웃에 `CoreBootstrap`을 한 번만 둡니다.
+클라이언트 provider에서 함수 prop을 다뤄야 하면 `app/providers.tsx` 같은 client component로 분리합니다.
+```tsx
+import "./globals.css";
+import { CoreBootstrap } from "@repo/core-next/bootstrap";
+import { Providers } from "./providers";
+const SITE_ID = "a";
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return (
+    <html lang="ko">
+      <body>
+        <CoreBootstrap siteId={SITE_ID} />
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  );
+}
+```
+```tsx
+"use client";
+import type { ReactNode } from "react";
+import {
+  AppProviders,
+  createClientQueryErrorHandler,
+} from "@repo/core-next";
+const handleClientQueryError = createClientQueryErrorHandler({
+  onUnauthorized: () => {
+    window.location.href = "/login";
+  },
+});
+export function Providers({ children }: { children: ReactNode }) {
+  return (
+    <AppProviders onGlobalError={handleClientQueryError}>
+      {children}
+    </AppProviders>
+  );
+}
+```
+동작:
+- 서버 렌더 시 한 번 초기화
+- 클라이언트 하이드레이션 시 한 번 초기화
+주의:
+- 이 방식은 `siteId`/`baseUrl`이 앱에서 사실상 고정일 때를 전제로 합니다.
+### 2. API 함수 작성
+API 함수는 `packages/core/src/api/*` 아래 파일별로 작성합니다.
+예시:
+```ts
+// packages/core/src/api/test.ts
+import { coreFetch, type CoreFetchOptions } from "../api";
+export function testFetch(options?: CoreFetchOptions) {
+  return coreFetch("https://jsonplaceholder.typicode.com/posts", options);
+}
+```
+사용:
+```ts
+import { testFetch } from "@repo/core/api/test";
+```
+규칙:
+- 각 파일에서 named export
+- 루트 `@repo/core`로 다시 모으지 않음
+- 새 API를 추가할 때 `package.json`이나 중앙 export 파일을 건드리지 않음
+### 3. 서버에서 인증 쿠키와 함께 호출
+서버에서는 `withServerAuth()`로 API 함수를 감쌉니다.
+```ts
+import { testFetch } from "@repo/core/api/test";
+import { withServerAuth } from "@repo/core-next/server-auth";
+const authTestFetch = withServerAuth(testFetch);
+const data = await authTestFetch();
+```
+현재 동작:
+- `next/headers`의 `cookies()` 사용
+- allowlist 쿠키만 `Cookie` 헤더에 붙임
+현재 allowlist:
+- `session`
+- `access_token`
+- `refresh_token`
+### 4. 클라이언트에서 인증 포함 호출
+클라이언트에서는 `withClientAuth()`로 API 함수를 감쌉니다.
+```ts
+import { testFetch } from "@repo/core/api/test";
+import { withClientAuth } from "@repo/core-next/client-auth";
+const authTestFetch = withClientAuth(testFetch);
+const data = await authTestFetch();
+```
+현재 동작:
+- 마지막 인자를 request options로 보고 `credentials: "include"`를 주입합니다.
+전제:
+- API 함수 시그니처는 마지막 인자가 request options인 형태여야 합니다.
+예:
+- `fn(options?)`
+- `fn(id, options?)`
+- `fn(endpoint, options?)`
+### 5. React Query provider와 hydration
+`@repo/core-react`는 템플릿 기준으로 query infra를 패키지로 올려둔 구조입니다.

package/templates/monorepo/_gitignore ADDED Viewed

@@ -0,0 +1,38 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+# Dependencies
+node_modules
+.pnp
+.pnp.js
+# Local env files
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+# Testing
+coverage
+# Turbo
+.turbo
+# Vercel
+.vercel
+# Build Outputs
+.next/
+out/
+build
+dist
+# Debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+# Misc
+.DS_Store
+*.pem

package/templates/monorepo/_npmrc ADDED Viewed

	@@ -0,0 +1 @@
1	+

package/templates/monorepo/apps/project/Dockerfile ADDED Viewed

@@ -0,0 +1,32 @@
+# 1. Base 이미지
+FROM node:lts-alpine AS base
+RUN npm install -g pnpm turbo
+WORKDIR /app
+# 2. Prune 단계 (루트의 모든 파일을 보고 필요한 것만 추출)
+FROM base AS pruner
+COPY . .
+# 여기서 @repo/web은 실제 package.json의 name입니다.
+RUN turbo prune project --out-dir=out --docker
+# 3. Build 단계
+FROM base AS builder
+WORKDIR /app
+# 의존성 설치를 위해 json 파일들 먼저 복사
+COPY --from=pruner /app/out/json/ .
+COPY --from=pruner /app/out/pnpm-lock.yaml ./pnpm-lock.yaml
+RUN pnpm install --frozen-lockfile
+# 실제 소스 코드 복사 (여기에 turbo.json이 포함되어 있음)
+COPY --from=pruner /app/out/full/ .
+# 별도의 COPY turbo.json turbo.json 줄은 삭제하세요. 이미 위 줄에서 복사되었습니다.
+RUN pnpm turbo build --filter=project
+# 4. Runner 단계 (생략 - 이전과 동일)
+FROM nginx:stable-alpine AS runner
+# 빌드된 dist 경로를 확인하여 복사 (보통 apps/앱이름/dist)
+COPY --from=builder /app/apps/project/dist /usr/share/nginx/html
+EXPOSE 80
+CMD ["nginx", "-g", "daemon off;"]

package/templates/monorepo/apps/project/eslint.config.mjs ADDED Viewed

@@ -0,0 +1,4 @@
+import { config } from "@repo/eslint-config/base";
+/** @type {import("eslint").Linter.Config} */
+export default config;

package/templates/monorepo/apps/project/index.html ADDED Viewed

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport"
+          content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
+    <meta http-equiv="X-UA-Compatible" content="ie=edge">
+    <title>Document</title>
+    <script src="./index.ts" type="module"></script>
+</head>
+<body>
+asdfㅁㄴㅇㄹㅁㄴㅇㄹㅁㄴㅇㄹ asdfasdfasdfasdf
+</body>
+</html>

package/templates/monorepo/apps/project/index.ts ADDED Viewed

@@ -0,0 +1,15 @@
+import { type AppError, initCore } from "@repo/core";
+import { testFetch } from "@repo/core/api/test";
+initCore("a");
+(async () => {
+  try {
+    const data = await testFetch();
+    document.body.innerText = JSON.stringify(data);
+  } catch (error) {
+    const appError = error as AppError;
+    alert(appError.message);
+  }
+})();

package/templates/monorepo/apps/project/package.json ADDED Viewed

@@ -0,0 +1,21 @@
+{
+  "name": "project",
+  "type": "module",
+  "dependencies": {
+    "@repo/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@repo/eslint-config": "workspace:*",
+    "@repo/typescript-config": "workspace:*",
+    "@types/node": "^22.15.3",
+    "eslint": "^9.39.1",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.1",
+    "vite-tsconfig-paths": "^6.0.5"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  }
+}

package/templates/monorepo/apps/project/tsconfig.json ADDED Viewed

@@ -0,0 +1,9 @@
+{
+  "extends": "@repo/typescript-config/base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "moduleResolution": "nodenext"
+  },
+  "include": ["src", "./index.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/templates/monorepo/apps/project/vite.config.ts ADDED Viewed

@@ -0,0 +1,6 @@
+import { defineConfig } from "vite";
+import tsConfigPaths from "vite-tsconfig-paths";
+export default defineConfig({
+  plugins: [tsConfigPaths()],
+});

package/templates/monorepo/apps/web/Dockerfile ADDED Viewed

@@ -0,0 +1,43 @@
+# 1단계: Base 설정
+FROM node:lts-alpine AS base
+RUN npm install -g pnpm turbo
+WORKDIR /app
+# 2단계: Prune - 필요한 패키지만 추출
+FROM base AS pruner
+COPY . .
+# 💡 @repo/web은 apps/web/package.json의 "name" 필드값입니다.
+RUN turbo prune web --docker
+# 3단계: Build - 의존성 설치 및 빌드
+FROM base AS builder
+WORKDIR /app
+# 캐시 효율을 위해 json 파일만 먼저 복사하여 설치
+COPY --from=pruner /app/out/json/ .
+COPY --from=pruner /app/out/pnpm-lock.yaml ./pnpm-lock.yaml
+RUN pnpm install --no-frozen-lockfile
+# 전체 소스 코드 복사 (out/full에 이미 turbo.json이 포함됨)
+COPY --from=pruner /app/out/full/ .
+RUN pnpm turbo build --filter=web
+# 4단계: Runner - 실행 전용 이미지
+FROM node:lts-alpine AS runner
+WORKDIR /app
+ENV NODE_ENV production
+# Cloud Run 등에서 사용할 포트 (기본 3000)
+ENV PORT 3000
+ENV HOSTNAME "0.0.0.0"
+# standalone 실행에 필요한 최소 파일만 복사
+# 💡 경로 주의: apps/web 부분은 실제 본인의 폴더 구조를 따라갑니다.
+COPY --from=builder /app/apps/web/public ./apps/web/public
+COPY --from=builder /app/apps/web/.next/standalone ./
+COPY --from=builder /app/apps/web/.next/static ./apps/web/.next/static
+EXPOSE 3000
+# standalone 모드에서는 서버를 node로 직접 실행합니다.
+CMD ["node", "apps/web/server.js"]

package/templates/monorepo/apps/web/README.md ADDED Viewed

@@ -0,0 +1,111 @@
+# web
+`apps/web`은 monorepo generator로 만든 Next.js 앱입니다. `create-next-app` 기본 scaffold 위에 공용 설정과 core wiring이 이미 연결되어 있습니다.
+## 빠른 시작
+레포 루트에서 실행하세요.
+```bash
+pnpm install
+pnpm --filter "./apps/web" dev
+```
+자주 쓰는 명령:
+```bash
+pnpm --filter "./apps/web" lint
+pnpm --filter "./apps/web" check-types
+pnpm --filter "./apps/web" build
+```
+## 기본 연결
+- `apps/web/app/layout.tsx`: `CoreBootstrap`와 `Providers`를 연결합니다.
+- `apps/web/app/providers.tsx`: `AppProviders`와 전역 query 에러 핸들러를 연결합니다.
+- `apps/web/app/page.tsx`: 첫 페이지 예시입니다.
+- `apps/web/app/global-error.tsx`: 전역 에러 UI입니다.
+상대 경로 API를 공통으로 쓰실 계획이면 `CoreBootstrap`에 `baseUrl`도 같이 넘겨주세요.
+```tsx
+<CoreBootstrap siteId="a" baseUrl="https://api.example.com" />
+```
+## API 사용 규칙
+API 함수는 항상 `@repo/core/api/*`에서 직접 import합니다.
+```tsx
+import { testFetch } from "@repo/core/api/test";
+export default async function Page() {
+  const data = await testFetch();
+  return <pre>{JSON.stringify(data, null, 2)}</pre>;
+}
+```
+다음 패턴은 피해주세요.
+- `@repo/core` 루트에 API를 다시 모으기
+- `@repo/core-next`에서 API를 가져오기
+## 새 API 추가하기
+새 API는 `packages/core/src/api/*.ts`에 파일 단위로 추가합니다.
+```ts
+import { z } from "zod";
+import { coreFetch, type CoreFetchOptions } from "../api";
+import { parseWithSchema } from "../schema-utils";
+const articleSchema = z.object({
+  id: z.number(),
+  title: z.string(),
+});
+const articleListSchema = z.array(articleSchema);
+export async function listArticles(options?: CoreFetchOptions) {
+  const payload = await coreFetch<unknown>("/articles", {
+    ...options,
+    baseUrl: "https://api.example.com",
+  });
+  return parseWithSchema(articleListSchema, payload);
+}
+```
+앱에서는 바로 이렇게 가져다 쓰시면 됩니다.
+```ts
+import { listArticles } from "@repo/core/api/article";
+```
+## 인증 포함 호출
+서버 컴포넌트나 route handler에서는 `withServerAuth()`를 붙이면 됩니다.
+```tsx
+import { testFetch } from "@repo/core/api/test";
+import { withServerAuth } from "@repo/core-next/server-auth";
+const authTestFetch = withServerAuth(testFetch);
+const data = await authTestFetch();
+```
+클라이언트 호출에서 쿠키를 같이 보내려면 `withClientAuth()`를 사용하세요.
+```tsx
+import { testFetch } from "@repo/core/api/test";
+import { withClientAuth } from "@repo/core-next/client-auth";
+const authTestFetch = withClientAuth(testFetch);
+const data = await authTestFetch();
+```
+## 더 보기
+공통 규칙과 패키지 구조는 [루트 README](../../README.md)를 참고해주세요.

package/templates/monorepo/apps/web/_gitignore ADDED Viewed

@@ -0,0 +1,36 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+.yarn/install-state.gz
+# testing
+/coverage
+# next.js
+/.next/
+/out/
+# production
+/build
+# misc
+.DS_Store
+*.pem
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+# env files (can opt-in for commiting if needed)
+.env*
+# vercel
+.vercel
+# typescript
+*.tsbuildinfo
+next-env.d.ts

package/templates/monorepo/apps/web/app/favicon.ico ADDED Viewed

Binary file

package/templates/monorepo/apps/web/app/global-error.tsx ADDED Viewed

@@ -0,0 +1,12 @@
+"use client";
+export default function GlobalError({ error }: { error: Error }) {
+  return (
+    <html>
+      <body>
+        <h2>에러 발생</h2>
+        <pre>{error.message}</pre>
+      </body>
+    </html>
+  );
+}

package/templates/monorepo/apps/web/app/globals.css ADDED Viewed

File without changes

package/templates/monorepo/apps/web/app/layout.tsx ADDED Viewed

@@ -0,0 +1,28 @@
+import "./globals.css";
+import { CoreBootstrap } from "@repo/core-next/bootstrap";
+import type { Metadata } from "next";
+import { Providers } from "./providers";
+export const metadata: Metadata = {
+  title: "Create Next App",
+  description: "Generated by create next app",
+};
+const SITE_ID = "a";
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return (
+    <html lang="ko">
+      <body>
+        <CoreBootstrap siteId={SITE_ID} />
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  );
+}

package/templates/monorepo/apps/web/app/page.tsx ADDED Viewed

@@ -0,0 +1,7 @@
+import { testFetch } from "@repo/core/api/test";
+export default async function Home() {
+  const data = await testFetch();
+  return <div className={""}>{JSON.stringify(data)}</div>;
+}