@wooojin/forgen 0.4.8 → 0.4.9

package/assets/dev-guide/fe/sources/react/react-compiler.md

@@ -0,0 +1,182 @@
+---
+title: React Compiler (자동 메모이제이션)
+source: https://react.dev/learn/react-compiler
+fetched: 2026-05-18
+category: compiler
+react_version: 19
+---
+
+## 개요
+
+React Compiler는 `useMemo`, `useCallback`, `React.memo`를 수동으로 작성할 필요 없이 자동으로 메모이제이션을 처리하는 빌드타임 최적화 도구.
+
+**핵심 기능:**
+- 컴포넌트와 계산값 자동 메모이제이션
+- 수동 `useMemo` / `useCallback` 대체
+- 설정 없이 기본적으로 React 앱 최적화
+- React 19 권장, React 17/18도 지원
+
+---
+
+## 설치
+
+```bash
+npm install -D babel-plugin-react-compiler@latest
+# 또는
+yarn add -D babel-plugin-react-compiler@latest
+# 또는
+pnpm install -D babel-plugin-react-compiler@latest
+```
+
+---
+
+## 빌드 도구별 설정
+
+### Babel
+
+```js
+// babel.config.js
+module.exports = {
+  plugins: [
+    'babel-plugin-react-compiler', // 반드시 첫 번째로!
+    // ... 다른 플러그인
+  ],
+};
+```
+
+> **중요**: React Compiler는 Babel 플러그인 파이프라인에서 **첫 번째**로 실행되어야 함.
+
+### Vite (v6.0.0+)
+
+```bash
+npm install -D @rolldown/plugin-babel
+```
+
+```js
+// vite.config.js
+import { defineConfig } from 'vite';
+import react, { reactCompilerPreset } from '@vitejs/plugin-react';
+import babel from '@rolldown/plugin-babel';
+
+export default defineConfig({
+  plugins: [
+    react(),
+    babel({
+      presets: [reactCompilerPreset()],
+    }),
+  ],
+});
+```
+
+Vite 구버전 (6.0.0 미만):
+```js
+// vite.config.js
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [
+    react({
+      babel: {
+        plugins: ['babel-plugin-react-compiler'],
+      },
+    }),
+  ],
+});
+```
+
+### React Router (Vite)
+
+```bash
+npm install vite-plugin-babel
+```
+
+```js
+// vite.config.js
+import { defineConfig } from "vite";
+import babel from "vite-plugin-babel";
+import { reactRouter } from "@react-router/dev/vite";
+
+const ReactCompilerConfig = { /* ... */ };
+
+export default defineConfig({
+  plugins: [
+    reactRouter(),
+    babel({
+      filter: /\.[jt]sx?$/,
+      babelConfig: {
+        presets: ["@babel/preset-typescript"], // TypeScript 사용 시
+        plugins: [
+          ["babel-plugin-react-compiler", ReactCompilerConfig],
+        ],
+      },
+    }),
+  ],
+});
+```
+
+### Next.js
+[Next.js 공식 문서](https://nextjs.org/docs/app/api-reference/next-config-js/reactCompiler) 참조.
+
+---
+
+## ESLint 플러그인
+
+```bash
+npm install -D eslint-plugin-react-hooks@latest
+```
+
+`recommended-latest` 프리셋에 컴파일러 규칙 포함:
+- Rules of React 위반 식별
+- 최적화 불가 컴포넌트 표시
+- 수정 방법 에러 메시지 제공
+
+---
+
+## 적용 확인
+
+### React DevTools
+1. React Developer Tools 브라우저 확장 설치
+2. 개발 모드로 앱 실행
+3. React DevTools 열기
+4. 컴포넌트 이름 옆 ✨ 이모지 확인 → "Memo ✨" 뱃지
+
+### 빌드 출력 확인
+
+컴파일된 코드에 자동 메모이제이션 로직 포함:
+```js
+import { c as _c } from "react/compiler-runtime";
+
+export default function MyApp() {
+  const $ = _c(1);
+  let t0;
+  if ($[0] === Symbol.for("react.memo_cache_sentinel")) {
+    t0 = <div>Hello World</div>;
+    $[0] = t0;
+  } else {
+    t0 = $[0];
+  }
+  return t0;
+}
+```
+
+---
+
+## 특정 컴포넌트 최적화 제외
+
+```js
+function ProblematicComponent() {
+  "use no memo"; // 이 컴포넌트만 컴파일러 건너뜀
+  // ...
+}
+```
+
+---
+
+## 요약: 이전 vs 이후
+
+| 이전 (수동) | 이후 (컴파일러) |
+|------------|----------------|
+| `const memoVal = useMemo(() => compute(a, b), [a, b])` | 자동 처리 |
+| `const cb = useCallback(() => fn(x), [x])` | 자동 처리 |
+| `export default React.memo(MyComponent)` | 자동 처리 |

package/assets/dev-guide/fe/sources/react/server-components.md

@@ -0,0 +1,194 @@
+---
+title: Server Components
+source: https://react.dev/reference/rsc/server-components
+fetched: 2026-05-18
+category: rsc
+react_version: 19
+---
+
+## 개요
+
+Server Components는 번들링 전, 클라이언트 앱/SSR 서버와 분리된 환경에서 렌더링되는 새로운 React 컴포넌트 유형.
+
+**핵심 특징:**
+- 빌드 타임 또는 요청마다 서버에서 렌더링
+- `useState` 등 인터랙티브 API 사용 불가
+- `async/await` 직접 사용 가능
+- 브라우저에 전송되지 않음 (번들에 포함 안 됨)
+- **`"use server"` 디렉티브 없음** — Server Component는 기본값; `"use client"` / `"use server"`만 존재
+
+---
+
+## 사용 사례 1: 서버 없는 빌드타임 렌더링
+
+무거운 라이브러리를 번들에 포함하지 않고 빌드 시 처리:
+
+❌ 기존 방식 (클라이언트 번들에 35.9K + 206K 추가):
+```js
+import marked from 'marked';           // 35.9K (11.2K gzipped)
+import sanitizeHtml from 'sanitize-html'; // 206K (63.3K gzipped)
+
+function Page({ page }) {
+  const [content, setContent] = useState('');
+  useEffect(() => {
+    fetch(`/api/content/${page}`).then((data) => {
+      setContent(data.content);
+    });
+  }, [page]);
+  return <div>{sanitizeHtml(marked(content))}</div>;
+}
+```
+
+✅ Server Component (번들 크기 0):
+```js
+import marked from 'marked';           // 번들에 포함되지 않음
+import sanitizeHtml from 'sanitize-html'; // 번들에 포함되지 않음
+
+async function Page({ page }) {
+  const content = await file.readFile(`${page}.md`);
+  return <div>{sanitizeHtml(marked(content))}</div>;
+}
+```
+
+클라이언트 출력:
+```js
+<div><!-- html for markdown --></div>
+```
+
+---
+
+## 사용 사례 2: 요청마다 서버 데이터 페칭
+
+클라이언트 waterfall 없이 서버에서 직접 DB 쿼리:
+
+❌ 기존 방식 (N+1 waterfall):
+```js
+function Note({ id }) {
+  const [note, setNote] = useState('');
+  useEffect(() => {
+    fetch(`/api/notes/${id}`).then(data => setNote(data.note));
+  }, [id]);
+
+  return (
+    <div>
+      <Author id={note.authorId} />
+      <p>{note}</p>
+    </div>
+  );
+}
+
+function Author({ id }) {
+  const [author, setAuthor] = useState('');
+  useEffect(() => {
+    fetch(`/api/authors/${id}`).then(data => setAuthor(data.author));
+  }, [id]);
+  return <span>By: {author.name}</span>;
+}
+```
+
+✅ Server Component (병렬 DB 쿼리):
+```js
+import db from './database';
+
+async function Note({ id }) {
+  const note = await db.notes.get(id);
+  return (
+    <div>
+      <Author id={note.authorId} />
+      <p>{note}</p>
+    </div>
+  );
+}
+
+async function Author({ id }) {
+  const author = await db.authors.get(id);
+  return <span>By: {author.name}</span>;
+}
+```
+
+클라이언트 출력:
+```js
+<div>
+  <span>By: The React Team</span>
+  <p>React 19 is...</p>
+</div>
+```
+
+---
+
+## 인터랙티비티 추가: Server + Client 조합
+
+`"use client"` 디렉티브로 Client Component와 합성:
+
+```js
+// Server Component
+import Expandable from './Expandable';
+
+async function Notes() {
+  const notes = await db.notes.getAll();
+  return (
+    <div>
+      {notes.map(note => (
+        <Expandable key={note.id}>
+          <p note={note} />
+        </Expandable>
+      ))}
+    </div>
+  );
+}
+```
+
+```js
+// Client Component
+"use client"
+
+export default function Expandable({ children }) {
+  const [expanded, setExpanded] = useState(false);
+  return (
+    <div>
+      <button onClick={() => setExpanded(!expanded)}>Toggle</button>
+      {expanded && children}
+    </div>
+  );
+}
+```
+
+---
+
+## Promise를 서버→클라이언트로 전달
+
+```js
+// Server Component
+import db from './database';
+
+async function Page({ id }) {
+  const note = await db.notes.get(id);           // 서버에서 await
+  const commentsPromise = db.comments.get(note.id); // 시작만, 클라이언트에서 await
+
+  return (
+    <div>
+      {note}
+      <Suspense fallback={<p>Loading Comments...</p>}>
+        <Comments commentsPromise={commentsPromise} />
+      </Suspense>
+    </div>
+  );
+}
+```
+
+```js
+// Client Component
+"use client";
+import { use } from 'react';
+
+function Comments({ commentsPromise }) {
+  const comments = use(commentsPromise); // 서버에서 시작된 Promise 이어서 처리
+  return comments.map(comment => <p>{comment}</p>);
+}
+```
+
+---
+
+## API 안정성 주의
+
+> Server Component 구현을 위한 번들러/프레임워크 API는 semver를 따르지 않으며 React 19.x 마이너 버전 간 breaking change 가능. 특정 React 버전에 pin하거나 Canary 릴리스 사용 권장.

package/assets/dev-guide/fe/sources/react/server-functions.md

@@ -0,0 +1,192 @@
+---
+title: Server Functions ('use server' / 'use client')
+source: https://react.dev/reference/rsc/server-functions
+fetched: 2026-05-18
+category: rsc
+react_version: 19
+---
+
+## 개요
+
+Server Functions는 `"use server"` 디렉티브로 정의된 서버에서 실행되는 비동기 함수. Client Component에서 호출 가능.
+
+> **Note**: 2024년 9월 이전에는 "Server Actions"라고 불렸음. Server Actions는 action props에 전달되거나 action 내부에서 호출되는 Server Functions이지만, 모든 Server Functions가 Server Actions는 아님.
+
+**동작 원리**: 프레임워크가 자동으로 함수 참조를 생성하고, 클라이언트에서 호출 시 서버로 요청을 전송하고 결과를 반환.
+
+---
+
+## 'use server' vs 'use client'
+
+| 디렉티브 | 위치 | 의미 |
+|----------|------|------|
+| `"use server"` | 파일 상단 또는 함수 첫 줄 | 이 함수/모듈은 서버에서만 실행 |
+| `"use client"` | 파일 상단 | 이 컴포넌트는 클라이언트에서 실행 |
+| (없음) | — | Server Component (기본값) |
+
+---
+
+## 사용 패턴
+
+### 1. Server Component 내부에서 Server Function 정의
+
+```js
+// Server Component
+import Button from './Button';
+
+function EmptyNote() {
+  async function createNoteAction() {
+    'use server'; // 함수 레벨 디렉티브
+
+    await db.notes.create();
+  }
+
+  return <Button onClick={createNoteAction} />;
+}
+```
+
+Client Component에서 참조 확인:
+```js
+"use client";
+
+export default function Button({ onClick }) {
+  console.log(onClick);
+  // { $$typeof: Symbol.for("react.server.reference"), $$id: 'createNoteAction' }
+  return <button onClick={() => onClick()}>Create Empty Note</button>;
+}
+```
+
+### 2. 별도 파일에서 Server Functions 내보내기
+
+```js
+// actions.js
+"use server"; // 파일 레벨 디렉티브
+
+export async function createNote() {
+  await db.notes.create();
+}
+```
+
+```js
+// Client Component
+"use client";
+import { createNote } from './actions';
+
+function EmptyNote() {
+  return <button onClick={() => createNote()} />;
+}
+```
+
+### 3. useTransition과 함께 (Actions)
+
+```js
+// actions.js
+"use server";
+
+export async function updateName(name) {
+  if (!name) {
+    return { error: 'Name is required' };
+  }
+  await db.users.updateName(name);
+}
+```
+
+```js
+// Client Component
+"use client";
+import { updateName } from './actions';
+import { useTransition, useState } from 'react';
+
+function UpdateName() {
+  const [name, setName] = useState('');
+  const [error, setError] = useState(null);
+  const [isPending, startTransition] = useTransition();
+
+  const submitAction = async () => {
+    startTransition(async () => {
+      const { error } = await updateName(name);
+      if (error) {
+        setError(error);
+      } else {
+        setName('');
+      }
+    });
+  };
+
+  return (
+    <form action={submitAction}>
+      <input type="text" name="name" disabled={isPending} />
+      {error && <span>Failed: {error}</span>}
+    </form>
+  );
+}
+```
+
+### 4. Form Action으로 직접 사용
+
+```js
+"use client";
+import { updateName } from './actions';
+
+function UpdateName() {
+  return (
+    <form action={updateName}>
+      <input type="text" name="name" />
+    </form>
+  );
+}
+```
+
+> 성공 시 React가 자동으로 폼 리셋.
+
+### 5. useActionState와 조합
+
+```js
+"use client";
+import { updateName } from './actions';
+import { useActionState } from 'react';
+
+function UpdateName() {
+  const [state, submitAction, isPending] = useActionState(updateName, { error: null });
+
+  return (
+    <form action={submitAction}>
+      <input type="text" name="name" disabled={isPending} />
+      {state.error && <span>Failed: {state.error}</span>}
+    </form>
+  );
+}
+```
+
+**이점:**
+- pending state 접근
+- 마지막 반환 응답 접근
+- hydration 전 폼 자동 재실행
+- 점진적 향상 지원
+
+### 6. 점진적 향상 (Progressive Enhancement)
+
+```js
+"use client";
+import { updateName } from './actions';
+import { useActionState } from 'react';
+
+function UpdateName() {
+  const [, submitAction] = useActionState(updateName, null, `/name/update`);
+
+  return (
+    <form action={submitAction}>
+      {/* form fields */}
+    </form>
+  );
+}
+```
+
+> 세 번째 인자(permalink)를 전달하면 JavaScript 로드 전 폼 제출 시 해당 URL로 리다이렉트.
+
+---
+
+## API 안정성
+
+- React 19의 Server Functions 자체: stable
+- 번들러/프레임워크 구현 API: semver 미준수, 마이너 버전 간 breaking change 가능