📌 처음 시작

📝 계획

⚡ 실행 (강도 순)

🔍 분석 & 리뷰

🤖 멀티 AI

🛠️ 유틸리티

📊 참고

실행 강도

대화 < plan < autopilot < ralph < team ralph

비용

haiku < sonnet << opus

GitHub

github.com/Yeachan-Heo/oh-my-claudecode

새프로젝트에 들어가면 항상 이것부터 해라

/deepinit

OMC가 프로젝트 구조를 분서갛고 AGENTS.md 계층 문서를 자동 생성한다.

모델 라우팅

OMC는 작업 복잡도에 따라 자동으로 모델을 선택한다.

haiku  (저비용, 빠름)
  → 파일 탐색, 구조 분석, 문서 작성, 간단한 검색
  → 예: explore, writer 에이전트

sonnet (중간 비용, 균형)
  → 일반 구현, 테스트, 디버깅, 리팩토링
  → 예: executor, test-engineer, debugger 에이전트

opus   (고비용, 최고 성능)
  → 아키텍처 설계, 복잡한 분석, 종합 리뷰, 비판적 검토
  → 예: architect, code-reviewer, critic 에이전트

실제로 이렇게 동작한다. 사용자: "autopilot: 인증 시스템 만들어줘"

OMC 내부:

  1. explore    (haiku)  → 현재 코드 구조 파악
  2. planner    (opus)   → 구현 계획 수립
  3. architect  (opus)   → 인터페이스 설계
  4. executor   (sonnet) × 3 → 병렬 구현
  5. test-engineer (sonnet) → 테스트 작성
  6. verifier   (sonnet) → 완료 검증

Autopilot - 완전 자율 실행

복잡한 단일 기능 구현에 최적, 계획부터 검증까지 자동

트리거 키워드: autopilot:, build me, I want a

Phase 1 — 확장 (Expansion)
  "할일 목록"을 구체적 요구사항으로 확장
  → 할일 추가/삭제/완료 토글, 로컬 상태 관리, 반응형 UI

Phase 2 — 계획 (Planning)
  planner 에이전트가 작업 분해
  → Todo 타입 정의 → TodoItem 컴포넌트 → TodoList → 페이지 통합

Phase 3 — 실행 (Execution)
  executor 에이전트들 병렬 구현
  → src/types/todo.ts 생성
  → src/components/TodoItem.tsx 생성
  → src/components/TodoList.tsx 생성
  → src/app/todos/page.tsx 수정

Phase 4 — QA
  qa-tester 가 빌드/린트/테스트 실행
  → npm run build → 통과
  → npm run lint  → 통과

Phase 5 — 검증 (Verification)
  verifier 에이전트가 요구사항 체크리스트 확인
  → ✓ 할일 추가 기능
  → ✓ 삭제 기능
  → ✓ 완료 토글
  → "완료 확인됨"

ralph: 끝까지 멈추지 않는 모드

v4.6.0부터 Ralph는 자동으로 prd.json을 생성합니다. 모든 수용 기준이 통과할 때까지 반복합니다.

트리거 키워드: ralph:, don't stop, must complete

사용자: "ralph: 이 앱에 JWT 인증 시스템 전체 구현해줘"

자동 생성: .omc/prd.json
  {
    "title": "JWT 인증 시스템",
    "acceptance_criteria": [
      "회원가입 API (/api/auth/register) 동작",
      "로그인 API (/api/auth/login) JWT 발급",
      "보호된 라우트에서 토큰 검증",
      "리프레시 토큰 갱신",
      "모든 에러 케이스 핸들링"
    ]
  }

Iteration 1: 기본 구조 + 회원가입 구현
Iteration 2: 로그인 + JWT 발급 구현
Iteration 3: 미들웨어 + 토큰 검증 구현
Iteration 4: 리프레시 토큰 구현
Iteration 5: verifier 검증 → "에러 핸들링 미흡"
Iteration 6: 에러 핸들링 전체 보강
Iteration 7: verifier 검증 → "모든 기준 통과" → 완료

PRD 없이 시작하려면: "ralph --no-prd: 로그인 기능 만들어줘"

Ultrawork — 최대 병렬 실행

5개 이상의 에이전트를 동시에 투입. 독립적인 작업 대량 처리에 최적.

트리거 키워드: ultrawork, ulw

사용자: "ulw: 이 5개 API 엔드포인트 전부 구현해줘
        (users, posts, comments, likes, notifications)"

동시 실행:
  executor #1 → /api/users 구현    ─┐
  executor #2 → /api/posts 구현    ─┤
  executor #3 → /api/comments 구현 ─┤ 병렬
  executor #4 → /api/likes 구현    ─┤
  executor #5 → /api/notifications ─┘

총 소요 시간 ≈ 단일 작업 시간 × 1.2 (병렬 오버헤드 포함)

Ecomode — 토큰 효율 최대화

비용이 중요할 때. 가능한 한 저렴한 모델 우선 사용.

트리거 키워드: eco

사용자: "eco: 린트 에러 전부 수정해줘"

→ haiku 모델로 먼저 시도
→ haiku가 해결 못하면 sonnet으로 에스컬레이션
→ opus는 절대적으로 필요한 경우에만 사용
→ 예상 비용 절감: 30~50%

Team — 네이티브 팀 협업

Claude Code 네이티브 팀 기능을 활용한 조율 방식.

트리거 키워드: team

사용자: "team 3:executor 모든 컴포넌트 테스트 코드 작성"

→ executor 에이전트 3개가 팀으로 조율하며 작업
→ 실시간 메시지로 작업 상태 공유
→ 공유 태스크 리스트에서 각자 작업 픽업

파이프라인:
  team-plan → team-prd → team-exec → team-verify → team-fix

Deep Interview — 막연한 아이디어 명확화

v4.6.0 신기능. 실행 전 소크라테스식 질문으로 모호함을 제거합니다.

트리거 키워드: /deep-interview

사용자: "/deep-interview '대시보드 만들어줘'"

OMC가 수학적 모호성 점수를 계산하고 질문 생성:

Q1: "어떤 종류의 데이터를 보여주는 대시보드인가요?
    (a) 사용자 분석  (b) 매출 현황  (c) 시스템 모니터링  (d) 기타"

Q2: "실시간 업데이트가 필요한가요?"

Q3: "대상 사용자는 누구인가요? 기술적 지식 수준은?"

→ 명확성 점수가 임계값 이상이 되면 실행 시작
→ 애매한 요구사항으로 인한 재작업 방지

사용 시점: 요구사항이 추상적이거나 규모가 큰 작업 전

Plan — 전략적 계획 수립

실행 전 계획을 먼저 세우고 승인을 받는 방식.

트리거 키워드: plan this:, plan the

사용자: "plan this: 결제 시스템 연동"

→ 현재 코드 분석 (explore)
→ 구현 계획 상세 작성
→ 계획을 사용자에게 제시 → 승인 요청

출력 예시:
  구현 계획: 결제 시스템 연동

  Step 1: 환경 변수 설정 (5분)
    - .env에 STRIPE_SECRET_KEY, STRIPE_PUBLISHABLE_KEY 추가

  Step 2: Stripe SDK 설치 및 클라이언트 설정 (10분)
    - npm install @stripe/stripe-js stripe
    - src/lib/stripe.ts 생성

  Step 3: 결제 API 라우트 구현 (20분)
    - POST /api/checkout → Stripe 세션 생성
    - GET /api/checkout/success → 결제 확인

  Step 4: 프론트엔드 결제 버튼 구현 (15분)
    - src/components/CheckoutButton.tsx 생성

  Step 5: 웹훅 처리 (15분)
    - POST /api/webhooks/stripe → 결제 완료 처리

  이 계획으로 진행할까요?

Ralplan — 합의 기반 계획

Planner, Architect, Critic 세 에이전트가 합의에 이를 때까지 반복 검토.

트리거 키워드: ralplan, consensus plan

사용자: "ralplan: 멀티테넌트 SaaS 아키텍처 설계해줘"

Round 1:
  planner   → 초안 작성 (마이크로서비스 제안)
  architect → 검토: "데이터 격리 방식 명시 필요"
  critic    → 비판: "배포 복잡성 과소평가됨"

Round 2:
  planner   → 수정안 (모놀리스 + 모듈식)
  architect → 수정: "테넌트별 스키마 격리 추가"
  critic    → "허용 가능, 스케일링 계획 보강 필요"

Round 3:
  합의 도달 → 최종 아키텍처 문서 생성

옵션: "ralplan --deliberate: ..." 
  → 사전 위험 분석 + 확장된 테스트 계획 포함

Claude Code 모드 & 에이전트 완전 정리

Claude Code는 단순히 코드 생성만 하는 것이 아니라, 작업 규모와 목적에 따라 다양한 실행 모드와 전문 에이전트를 활용할 수 있다.

1. 작업 규모별 추천 모드

2. 빌드 & 분석 에이전트

프로젝트를 이해하고 구현하기 위한 핵심 에이전트들이다.

3. 리뷰 에이전트

코드 품질과 안정성을 검토하는 역할을 담당한다.

사용 예시

review code

→ code-reviewer 실행

security review

→ security-reviewer 실행

4. 도메인 전문가 에이전트

특정 분야에 특화된 전문가 역할을 수행한다.

5. 조율 에이전트

다른 에이전트가 만든 결과를 비판적으로 검토한다.

추천 활용 패턴

• 기능 개발

analyst
 → planner
 → architect
 → executor
 → verifier

요구사항 분석 → 설계 → 구현 → 검증

• 버그 수정

explore
 → debugger
 → executor
 → verifier

원인 파악 → 수정 → 검증

• 코드 리뷰

quality-reviewer
 → security-reviewer
 → code-reviewer

품질 → 보안 → 최종 리뷰

• 대규모 프로젝트

team
 + ralph
 + architect
 + deep-executor
 + verifier

설계부터 구현, 검증까지 자동화된 워크플로우 구성 가능

한 줄 요약

• 작은 작업 → 일반 대화
• 기능 개발 → autopilot
• 대규모 개발 → ralph
• 설계 → architect / ralplan
• 리뷰 → code-reviewer
• 보안 → security-reviewer
• 테스트 → test-engineer
• Git 작업 → git-master

작업 규모가 커질수록 "계획 → 구현 → 검증"을 자동으로 반복하는 모드가 효율적이다.

6. 매직 키워드 & 슬래시 명령어 레퍼런스

Claude Code는 특정 키워드나 슬래시 명령어를 입력하면 자동으로 적절한 실행 모드와 에이전트를 활성화할 수 있다.

매직 키워드(Magic Keywords)

프롬프트에 특정 키워드를 포함하면 자동으로 해당 모드가 활성화된다.

자율 실행 계열

언제 사용할까?

• 여러 파일 수정이 필요한 기능 개발
• 구현 → 테스트 → 수정 과정을 자동으로 돌리고 싶을 때
• 중간 승인 없이 끝까지 진행시키고 싶을 때

병렬 작업 계열

언제 사용할까?

• 많은 파일을 동시에 수정해야 할 때
• 독립적인 작업을 병렬로 처리할 수 있을 때
• 대규모 리팩토링 작업

계획 수립 계열

언제 사용할까?

• 구현 전에 설계를 검토하고 싶을 때
• 시스템 구조를 먼저 정의해야 할 때
• 대규모 기능 개발 전

분석 및 디버깅 계열

언제 사용할까?

• 에러의 근본 원인을 찾고 싶을 때
• 성능 저하나 메모리 문제 분석
• 복잡한 버그 조사

리뷰 및 품질 관리 계열

언제 사용할까?

• PR 생성 전
• 배포 직전 점검
• TypeScript 마이그레이션
• 테스트 코드 작성

슬래시 명령어(Slash Commands)

직접 입력하여 사용할 수 있는 명령어들이다.

핵심 워크플로우

코드 품질 관리

멀티 AI 협업

유틸리티

추천 사용 흐름

기능 개발

/deep-interview
→ /plan
→ /autopilot
→ /code-review

버그 수정

/analyze
→ debug
→ fix build
→ review code

대규모 프로젝트

/team
→ /ralplan
→ /ralph
→ /code-review

배포 전 점검

/security-review
→ review code
→ verifier

한 줄 요약

Claude Code를 제대로 활용하려면 단순히 "코드 작성"을 요청하는 것이 아니라,

• 설계는 plan, ralplan
• 구현은 autopilot, ralph
• 병렬 작업은 ultrawork
• 리뷰는 review code
• 보안은 security review

처럼 작업 목적에 맞는 모드와 에이전트를 선택하는 것이 핵심이다.

가성비

강력한 AI 를 단순 작업에 쓰는 것은 낭비 저렴한 AI를 복잡한 AI 에 쓰는 것은 품질 저하

OMC 에이전트 소개

작업에 맞는 올바른 도구

• Haiku: 저렴하고 빠름,
• Sonnet : 균형
• Opus: 성능이 좋은대신, 느리고 비쌈

Haiku * 60 = Opus 비용 차이는 60배 이다.

OMC에서 단순 반복 작업은 Haiku, 깊은 사고가 필요하면 Opus를 투입하는 것이다

작업은 어떻게 할당되는가

그것을 하는것이 "멀티 에이전트 오케스트레이션"이다.

PM처럼 딱 맞는 담당자에게 일을 맡겨주는 것을 의미한다.

실제 작동하는 AI 팀

예를 들어 결제 시스템 환불 기능 추가에선

1. planner가 요청 분석
2. explore 가 코드를 찾고 architect가 통합 전략 구현
3. excutor 가 환불, api 데이터 모델 등 새 코드를 작성
4. build-fixer 가 오류를 해결하고 code-reviewer가 품질 검사
5. writer가 새 기능을 반영하여 API 문서 업데이트

AI팀 리딩하기

1. 명확한 개요 작성: 모호한 요청 대신 구체적으로 지시하라
2. 적절한 톤 사용: 복잡한 문제에는 "신중하게 검토해줘" 라는 힌트를 추가
3. 구축 전 계획: 대규모 작업은 planner를 먼저 사용하여 낭비 줄이기

테스트 주도 개발(TDD) 같은 특정 워크 플로우전체를 직접 호출하여 실행하는 강력한 명령어

/autopilot

: 뼈대완성 아무것도 없는 빈화면에서 실행 화면으로 단숨에 끌어올릴 수 있다. PM이 일하는 방법과 같다. 우리의 목표를 이해하려고 하는 질문들을 한 후에 코드를 한다. 이후 스스로 수정한다. 이후 완벽히 돌아가는지 확인한다.

/code-review

: 가상팀. 단순한 문법 오류를 잡아주는 팀이 아니다. 시니어 개발자가 코드 품질, 가독성, 잠재적 버그를 검토해주며 피드백을 준다. 팀 구성

1. 코드리뷰어
2. 보안 전문가
3. 오류검출 테스터

/security-review

: 품질, 보안검사해주는 프로젝트 경호원

1. 보안의 허점을 미리 잡아준다.

/tdd

: 테트스 주도 개발, 테스트 만듦 -> 테스트 통과 코드 -> 코드 다듬기 이걸 ai가 대신 해주어 튼튼한 코드 작성 가능

온디맨드 AI 팀

: 디지털 군단으로 확장하기 작업이 너무 커서 ai 하나로 안되면 어떡하지? => /swarm

/swarm

: 프로젝트 매니저가 에이전트에게 분할하여 독립적으로 처리하고 협력하게 함으로써 큰 프로젝트를 더 빨리 완료

순서

1. /autopilot 으로 큰 그림을 그린다
2. /code-review 로 멘토의 조언을 듣고
3. /tdd 로 코드를 보장하고
4. 문제가 생기면 /swarm으로 해결한다

ralph

: 완료 될때까지 자동 반복 실행 - 분석 > 수정 > 테스트 > 반복

ralph: 회원가입/로그인/프로필 수정 기능 전부 만들어줘

uwl

: 멀티태스킹 용도. 최대 병렬 처리로 속도 향상, ex) api 를 한번에 5개를 리팩토링 해야 할때

plan

: 코딩 전 기획 인터뷰 모드 - 애초에 실수 막고 계획하도록 함

ralpan

: 멀티에이전트와 반복 기획 - 기획 아이디어가 계속 제련됨

정리

조합

조합을 하면 더 잘 쓸 수 있다. 최강조합 uwl + ralph 각각의 테스트들을 통과할때까지 계속 반복된다.

실전팁

1. 키워드를 너무 남발하지 말아라.
2. 애매하면 plan으로 시작하라
3. ulw 을 쓸땐 서로 의존성 없는지 확인하고 작업하라

OMC 이용해서 개발해보기 전 왜 써야 하는가?

Claude Code의 한계

1. 단일 agent라는 점 : 설계, 테스트, 리뷰까지 혼자하는건 벅차다

2. 콘텍스트 손실

3. 작업 실패시 반복적으로 다시 시도하게 명령하는 것

OMC가 해결한 것

1. 여러 전문 agent가 함께 일하는 multi agent Orchestration 을 적용

2. 영구적인 메모리로 해결로 대화의 길을 잃을 일이 없다

3. 자동 반복 실행 기능으로, 알아서 여러번 재시도

OMC 3계층 구조

1. 매직 키워드 : ralph, plan 같은 키워드로 특별 실행모드 활성화(계획을 짬)

2. 슬래시 스킬 : /oh-my-claudecode 처럼 직접 호출하는 전문 기능

3. 플러그인 에이전트 : 굳이 시키지 않아도, 전문 ai(리서치 전문가, 아키텍처 설계 전문가)를 데려와서 작업한다

설치방법

Claude Code에서 다음 명령어를 실행합니다:

/plugin marketplace add https://github.com/Yeachan-Heo/oh-my-claudecode
/plugin install oh-my-claudecode

GPT생겨서 공부하기 참 쉬워졌쥬..

1️⃣ 공식문서 초기 세팅 (이건 꼭 해라)

✔️ 프로젝트 생성 npx create-react-router@latest

Remix v2는 이제 React Router에 흡수됐어. 👉 Remix = React Router + 서버 기능 이라고 생각해.

2️⃣ 생성 후 구조부터 이해 (중요 ⭐⭐⭐)

처음 보면 이게 제일 멘붕이야.

app/
 ├─ routes/
 │   ├─ _index.tsx
 │   ├─ login.tsx
 │   └─ posts.$id.tsx
 ├─ root.tsx
 └─ entry.server.tsx

핵심만 딱 정리해줄게

• routes/ = 페이지
• 파일 이름 = URL

이거 하나만 기억해도 반은 이해함

• routes/login.tsx → /login
• routes/posts.$id.tsx → /posts/123

👉 React Router의 안 써도 됨 👉 파일이 라우터다

3️⃣ Remix에서 제일 중요한 개념 TOP 4

🧠 ① loader (서버에서 데이터 가져오기)

export const loader = async () => {
  return { message: 'hello' };
};

✔️ 이 함수는 브라우저에서 실행 안 됨 ✔️ 서버에서만 실행

const data = useLoaderData<typeof loader>();

👉 API 호출 + 상태관리 + 로딩을 한 번에 해결

🧠 ② action (폼 submit 처리)

export const action = async ({ request }) => {
  const formData = await request.formData();
  return null;
};

✔️ POST / PUT / DELETE 전용 ✔️ 서버에서 실행됨

👉 axios.post() + onSubmit 안 써도 됨

🧠 ③ Form (Remix 전용)

<Form method="post">
  <input name="email" />
  <button type="submit" />
</Form>

👉 submit 하면 자동으로 action() 실행 👉 새로고침 ❌ 👉 상태관리 ❌

🧠 ④ useNavigation (로딩 상태)

const navigation = useNavigation();

navigation.state === 'loading'
navigation.state === 'submitting'

👉 버튼 로딩 처리, 스피너 여기서 함

4️⃣ “아 그래서 뭐가 좋은데?” (리액트랑 비교)

시작 전 환경 세팅

1️⃣ 필수 도구

Insomnia → API 테스트용 (Postman 대체)

2️⃣ NestJS CLI 설치 및 프로젝트 생성

npm i -g @nestjs/cli nest new project-name

nest new 명령어를 사용하면 기본적인 폴더 구조와 설정이 자동으로 구성된다.

Single Responsibility Principle (SRP)

NestJS는 단일 책임 원칙(SRP) 을 굉장히 강하게 따른다.

하나의 module / class / function 은 하나의 책임만 가져야 한다

기본 구조 예시

AppModule ├── AppController └── AppService

역할 분리

1. Controller

• HTTP 요청/응답 처리
• URL, Method 정의

2. Service

• 실제 비즈니스 로직 담당

3. Module

• 관련 Controller와 Provider를 묶는 단위

👉 Controller에서 로직을 처리하지 않고 Service로 위임하는 구조가 기본이다.

ValidationPipe (요청 데이터 검증)

NestJS는 class 기반 유효성 검사를 공식적으로 지원한다.

1️⃣ 패키지 설치 npm i class-validator class-transformer

class-validator : 유효성 검사

class-transformer : plain object → class 변환

2️⃣ DTO를 위한 패키지 npm i @nestjs/mapped-types

DTO 상속 및 변환을 도와주는 유틸 패키지

3️⃣ DTO 예시

export class CreateMovieDto {
  @IsString()
  title: string;

  @IsNumber()
  year: number;
}

👉 ValidationPipe를 사용하면

컨트롤러 진입 전에 자동으로 유효성 검증이 이루어진다.

Dependency Injection (DI)

NestJS의 가장 핵심 개념 중 하나.

NestJS의 DI 기본 구조 – 핵심 3요소

역할 - 의미 Provider - 주입 가능한 클래스 Consumer - 주입받는 쪽 Module - Provider를 등록하는 장소

예시

@Injectable()
export class MoviesService {}

@Module({
  providers: [MoviesService],
})
export class MoviesModule {}

@Controller('movies')
export class MoviesController {
  constructor(private readonly moviesService: MoviesService) {}
}

👉 객체를 직접 생성하지 않고 NestJS가 DI 컨테이너를 통해 자동으로 주입해준다.

Fastify vs Express

NestJS는 기본적으로 Express 위에서 동작한다

하지만 Fastify를 사용하면 Express 대비 약 2배 빠른 성능을 낼 수 있다.

Req / Res 직접 접근 getAll(@Req() req, @Res() res): GetMovieDto[] { return this.movies; }

NestJS에서는 @Req(), @Res() 데코레이터를 통해 플랫폼(Express / Fastify)의 객체에 직접 접근할 수 있다.

❗ 하지만 권장되지 않는 이유

NestJS의 추상화 레이어를 깨게 됨

플랫폼 종속 코드가 됨

테스트 및 유지보수 어려움 증가

👉 가능하면 NestJS 방식(@Body, @Param, @Query 등)을 사용하는 것이 좋다.

정리하며 느낀 점

NestJS는 구조와 규칙을 강하게 강제하는 프레임워크

처음엔 번거롭지만 규모가 커질수록 장점이 커진다

특히 DI + Module 구조는 테스트, 유지보수, 협업에 굉장히 유리하다

React 개발자 입장에서는 “왜 이렇게 나눠?” 싶지만 커질수록 이 구조가 왜 필요한지 체감하게 되겠지

이유는,

• 프로젝트에 파일을 포함하지 않아도 됨

• 캐싱 활용 가능 (다른 사이트에서도 같은 CDN 사용 시)
• 초기 설정이 간단 ... 가장 큰 이유는 회사에서 빨리 HTML <-> 에디터 읽기쓰기 호환 기능을 가진 에디터를 도입해달라고 했기 때문.

하지만 React에서 CDN으로 불러오면 아래와 같은 단점이 있어서 npm방식으로 바꾸려 한다.

• CDN 서버 장애 시 사용 불가

• 버전 관리가 명확하지 않음 (URL에 버전이 있어도 관리가 어려움)
• 보안 이슈 가능성 (외부 스크립트 실행)
• 번들러 최적화 불가

아지만 이렇게 하다보니 예전에 써서 문제가 없던 Quill에디터는 모노리식 번들(단일번들) 이라 css만 import하면 동작하고, 모든것을 webpack이 처리해서 문제가 없었다고 한다. TinyMCE 라는 라이브러리는 모듈러 아키텍처라 필요한 리소스를 런타임에 로드하기 때문에 React 에서 사용시 문제가 생겼다. 이 라이브러리의 유연성과 확장성 때문에 리소스 경로설정 이라는 것이 필요했다.

추가로 번들 크기가 증가할것이다 라는 문제점이 또 보였고..

결국 CRACO/webpack 설정을 하기로 했다.

TinyMCE webpack 최적화 구현 계획 (하이브리드 방식) 개요

목표

• TinyMCE를 npm 패키지로 사용 (CDN 제거)
• 공통 webpack 설정 + 앱별 오버라이드 구조
• webpack으로 리소스 최적화 및 번들 크기 감소
• seller-admin에 먼저 적용 (테스트 후 system-admin 확장) 구현 단계

1. CRACO 설치 및 공통 설정

• apps/seller-admin/package.json에 @craco/craco 의존성 추가
• 루트에 공통 설정 생성: craco.base.js
• TinyMCE 리소스 복사 설정 (CopyWebpackPlugin)
• 공통 번들 최적화 설정 (압축, 트리쉐이킹, 코드 스플리팅)
• apps/seller-admin/craco.config.js 생성
• 공통 설정 import 및 seller-admin 특화 오버라이드 (필요시)
• apps/seller-admin/package.json의 scripts를 react-scripts → craco로 변경

  2. Node.js 버전 고정

• 루트에 .nvmrc 파일 생성 (Node.js 24.6.0)
• Jenkins 배포 시 버전 일관성 보장

  3. TinyMCE 컴포넌트 수정

• packages/ui-components/src/organisms/TinyMCEEditor.tsx 수정
• base_url 설정 제거 (webpack이 처리)
• tinymceScriptSrc prop 제거 (npm 패키지 사용)
• 필요한 플러그인만 import하여 트리쉐이킹 최적화

  4. 빌드 스크립트 검증

• pnpm install 실행
• pnpm --filter seller-admin start로 개발 서버 테스트
• pnpm --filter seller-admin build로 프로덕션 빌드 테스트

주요 파일 변경

1. apps/seller-admin/package.json

• @craco/craco 의존성 추가
• scripts 수정: react-scripts → craco

  2. craco.base.js (신규, 루트)

• 공통 webpack 설정
• TinyMCE 리소스 복사 (CopyWebpackPlugin)
• 공통 번들 최적화 설정

  3. apps/seller-admin/craco.config.js (신규)

• 공통 설정 import
• seller-admin 특화 설정 오버라이드 (필요시)

  4. .nvmrc (신규)

• Node.js 24.6.0 고정

  5. packages/ui-components/src/organisms/TinyMCEEditor.tsx

• base_url 제거
• tinymceScriptSrc 제거

아키텍처

루트/
├── craco.base.js          # 공통 webpack 설정
├── .nvmrc                  # Node.js 버전 고정
└── apps/
    └── seller-admin/
        └── craco.config.js # 공통 설정 import + 오버라이드

예상 효과

• 번들 크기: 약 20-30% 감소 (트리쉐이킹 및 최적화)
• 로딩 속도: 개선 (로컬 파일, 번들 최적화)
• 안정성: 향상 (외부 CDN 의존성 제거)
• 유지보수성: 향상 (공통 설정 중앙 관리)

  주의사항

  Jenkins 배포 시 Node.js 24.6.0 이상 필요 빌드 메모리 사용량 증가 가능 (webpack 최적화) seller-admin 테스트 완료 후 system-admin에도 동일 적용

코드

1. apps/system-admin/package.json 수정

script 에서 'start':'react-script start' 와 같은 것들을 아래처럼 바꾸고

• "prestart": "node ../../scripts/copy-tinymce.js seller-admin",
• "start": "craco start",
• "build": "craco build",
• "test": "craco test",

devDependencies에서 아래와 같은 것들을 설치

• "@craco/craco": "^7.1.0",
• "copy-webpack-plugin": "^12.0.2",

2. apps/system-admin/craco.config.js 생성

const baseConfig = require('../../craco.base.js');

module.exports = {
  ...baseConfig,
  // system-admin 특화 설정이 필요한 경우 여기에 추가
  // 예: 특정 플러그인, 로더 설정 등
};

3. 루트 스크립트에 copy-tinymce.js 생성

const fs = require('fs');
const path = require('path');

// 루트 디렉토리 찾기 (craco.base.js와 동일한 기준)
const rootDir = path.resolve(__dirname, '../../..');

// 여러 가능한 경로 시도
const possibleSources = [
  // 1. 루트의 node_modules (craco.base.js와 동일한 방식)
  path.resolve(rootDir, 'node_modules/tinymce'),
  // 2. pnpm의 .pnpm 디렉토리에서 찾기
  (() => {
    try {
      const pnpmStore = path.resolve(rootDir, 'node_modules/.pnpm');
      if (fs.existsSync(pnpmStore)) {
        // tinymce@로 시작하는 디렉토리 찾기
        const entries = fs.readdirSync(pnpmStore);
        for (const entry of entries) {
          if (entry.startsWith('tinymce@')) {
            const entryPath = path.join(pnpmStore, entry);
            if (fs.statSync(entryPath).isDirectory()) {
              const tinymcePath = path.join(entryPath, 'node_modules/tinymce');
              if (fs.existsSync(tinymcePath)) {
                return tinymcePath;
              }
            }
          }
        }
      }
      return null;
    } catch (e) {
      return null;
    }
  })(),
  // 3. ui-components의 node_modules
  path.resolve(rootDir, 'packages/ui-components/node_modules/tinymce'),
  // 4. system-admin의 node_modules
  path.resolve(__dirname, '../node_modules/tinymce'),
];

// 존재하는 소스 경로 찾기
let source = null;
for (const possibleSource of possibleSources) {
  if (possibleSource && fs.existsSync(possibleSource)) {
    source = possibleSource;
    break;
  }
}

if (!source) {
  console.error('❌ TinyMCE not found in node_modules');
  console.error('   Tried paths:');
  possibleSources.forEach((p, i) => {
    if (p) {
      const exists = fs.existsSync(p) ? '✓' : '✗';
      console.error(`   ${i + 1}. ${exists} ${p}`);
    } else {
      console.error(`   ${i + 1}. (skipped)`);
    }
  });
  console.error('\n   Please ensure TinyMCE is installed:');
  console.error('   pnpm install');
  console.error('\n   Or check if TinyMCE is in packages/ui-components:');
  console.error('   ls packages/ui-components/node_modules/tinymce');
  process.exit(1);
}

const dest = path.resolve(__dirname, '../public/tinymce');
const checkFile = path.resolve(dest, 'plugins/help/js/i18n/keynav/en.js');

// 파일이 없을 때만 복사 (빠름)
if (!fs.existsSync(checkFile)) {
  console.log('📦 Copying TinyMCE files (first time only)...');
  console.log(`   From: ${source}`);
  console.log(`   To: ${dest}`);

  const { execSync } = require('child_process');

  if (fs.existsSync(dest)) {
    fs.rmSync(dest, { recursive: true, force: true });
  }

  const isWindows = process.platform === 'win32';
  if (isWindows) {
    execSync(`xcopy /E /I /Y "${source}" "${dest}"`, { stdio: 'inherit' });
  } else {
    execSync(`cp -R "${source}" "${dest}"`, { stdio: 'inherit' });
  }
  console.log('✅ Done');
} else {
  console.log('⚡ TinyMCE files already exist');
}

파일별 용도 설명

1. craco.base.js - Webpack 설정 파일

• 용도: CRACO를 통한 webpack 설정
• 역할: 개발/프로덕션 모드에서 webpack이 실행될 때 동작 CopyWebpackPlugin으로 TinyMCE 리소스를 빌드 출력에 복사 프로덕션 빌드 최적화 (코드 스플리팅, 트리쉐이킹, 압축)
• 작동 시점:
• craco start 실행 시 (개발 모드)
• craco build 실행 시 (프로덕션 빌드)
• 🔴 문제점: 개발 모드에서 CopyWebpackPlugin이 초기 복사를 보장하지 않을 수 있음 개발 서버 시작 시 파일이 없으면 에러 발생 가능!!!

  2. scripts/copy-tinymce.js - 파일 복사 스크립트

• 용도: 개발 서버/빌드 시작 전에 TinyMCE 파일을 수동 복사
• 역할: prestart, prebuild 훅에서 실행 TinyMCE 파일이 없을 때만 복사 (조건부) 개발 모드에서 리소스 누락 방지
• 작동 시점: pnpm start 실행 전 (prestart 훅) pnpm build 실행 전 (prebuild 훅)
• 장점: 개발 서버 시작 전에 파일 존재 보장 파일이 있으면 스킵하여 빠른 시작 에러 메시지로 문제 진단 용이

Deployment

git에 push 를 마쳤다면, Vercel이 호출할 수 있도록 package.json 에 명령어를 수정한다

  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start":"next start"
  },

vercel 은 그냥 deploy 버튼만 누르고 기다리면 된다. 그리고 나타나는 오류들을 해결하면 dashboard에 보인다.

추가) <Link prefetch href={/movies/${id}}>{title}</Link>

배포 시에 prefetch 라는 props 통해 통해 사용자가 클릭하기 전부터 fetch를 진행한다. 스크롤을 내리고 아래쪽에 있는 링크가 보여지면, NextJS는 자동적으로 요청을 보내게 된다. movie페이지를 자동으로 fetch 하고 있는 것이다. 클릭하지 않았지만 마치 페이지에 들어간 것처럼 요청하는 것이다!!

1. application 전체에 적용할 global style 을 만든다. 전체 웹사디트의 bg color 나 폰트를 적용하도록 한다.

2. app/layout 에서 import global css를 한다.

3. 공통 디자인을 적용해준다.

   html,
   body,
   div,
   span,
   applet,
   object,
   iframe,
   h1,
   h2,
   h3,
   h4,
   h5,
   h6,
   p,
   blockquote,
   pre,
   a,
   abbr,
   acronym,
   address,
   big,
   cite,
   code,
   del,
   dfn,
   em,
   img,
   ins,
   kbd,
   q,
   s,
   samp,
   small,
   strike,
   strong,
   sub,
   sup,
   tt,
   var,
   b,
   u,
   i,
   center,
   dl,
   dt,
   dd,
   ol,
   ul,
   li,
   fieldset,
   form,
   label,
   legend,
   table,
   caption,
   tbody,
   tfoot,
   thead,
   tr,
   th,
   td,
   article,
   aside,
   canvas,
   details,
   embed,
   figure,
   figcaption,
   footer,
   header,
   hgroup,
   menu,
   nav,
   output,
   ruby,
   section,
   summary,
   time,
   mark,
   audio,
   video {
   margin: 0;
   padding: 0;
   border: 0;
   font-size: 100%;
   font: inherit;
   vertical-align: baseline;
   }
   /* HTML5 display-role reset for older browsers */
   article,
   aside,
   details,
   figcaption,
   figure,
   footer,
   header,
   hgroup,
   menu,
   nav,
   section {
   display: block;
   }
   body {
   line-height: 1;
   }
   ol,
   ul {
   list-style: none;
   }
   blockquote,
   q {
   quotes: none;
   }
   blockquote:before,
   blockquote:after,
   q:before,
   q:after {
   content: "";
   content: none;
   }
   table {
   border-collapse: collapse;
   border-spacing: 0;
   }
   

body { font-family: Cambria, Cochin, Georgia, Times, "Times New Roman", serif; background-color: black; color: white; font-size: 18px; }

a { color: inhefit;

text-decoration: none; }

a:hover { text-decoration: underline; }

4. 특정 디자인에 적용하고 싶다면 이름에 `.module.css`를 넣도록 한다.
![](https://velog.velcdn.com/images/angel_eugnen/post/0bbb9e61-c53d-4b38-860e-eb0e403d3359/image.png)

폴더 위치는 /styles 폴더에 있어도 무관하다.

그리고 오로지 className만 작성할 것이다.

5. 그리고 사용하고 싶은 tsx 파일에서 css 파일을 마치 자바스크립트 처럼 import 해온다.
`import styles from '../style/navigation.module.css'`

Error Handling

1. API 요청이 안되거나
2. 네트워크가 끊기는 등 에러가 생긴 경우의 핸들링은 error.tsx 파일을 만들면 된다.

프레임워크 특성상 파일 위치는 페이지 대상이 되는 폴더 안에 넣어야 한다.

"use client";
export default function ErrorOMG() {
  return <h1>Error OMG</h1>;
}

Parallel Request

import { API_URL } from "../../../(home)/page";
async function getMovie(id: string) {
  console.log(`getMovie: ${Date.now()}`);
  await new Promise((resolve) => setTimeout(resolve, 5000));
  const response = await fetch(`${API_URL}/${id}`);
  const json = await response.json();
  return json;
}
async function getVideo(id: string) {
  console.log(`getVideo: ${Date.now()}`);
  await new Promise((resolve) => setTimeout(resolve, 5000));
  const response = await fetch(`${API_URL}/${id}/videos`);
  const json = await response.json();
  return json;
}
export default async function Text({ params }) {
  const { id } = await params;
  console.log("startfetching");
  const movie = await getMovie(id); // 이 함수 응답이 오래걸리면
  const video = await getVideo(id); // 첫줄 함수를 기다리다가 응답이 늦는다. 병렬로 실행해야 한다.
  console.log("endfetching");

  return (
    <div>
      testestest
      <h1>{movie.title}</h1>
    </div>
  );
}

이렇게 하면 start fetching 이 출력되고 end fetching이 순차적으로 출력되며 총 10초 넘게 걸리게 된다.

startfetching
getMovie: 1752386606417
getVideo: 1752386607056
endfetching

병렬 요청으로 바꿔줘야 한다.

promise.all을 사용하면 결과값이 동시에 나올 것이다.

const [movie, videos]=  await Promise.all([getMovie(id), getVideos(id)])

이렇게 요청을 보내면

startfetching
getMovie: 1752386815316
getVideo: 1752386815316 
endfetching

동시에 시작하게 된다. 순차적인 작업이 아니기 때문이다. 이것이 병렬 fetch 이다.

하지만 지금은 둘이 끝나야 보이므로, 둘을 분리하는 것이 좋다. 둘중 어느 한쪽도 기다릴 필요가 없게! 그것이 suspense이다.

Suspense

getMovie와 getVideos 만 렌더링 하는 컴포넌트를 만든다. /components/movie-video.tsx /components/movie-info.tsx

// 1. components.movie-video.tsx
import { API_URL } from "../app/(home)/page";
async function getVideos(id: string) {
  console.log(`getVideo: ${Date.now()}`);
  await new Promise((resolve) => setTimeout(resolve, 5000));
  const response = await fetch(`${API_URL}/${id}/videos`);
  const json = await response.json();
  return json;
}

export default async function MovieVideos({ id }: { id: string }) {
  const videos = await getVideos(id);
  return <h6>{JSON.stringify(videos)}</h6>;
}

//2. components/movie-video.tsx
import { API_URL } from "../app/(home)/page";
async function getMovie(id: string) {
  console.log(`getMovie: ${Date.now()}`);
  await new Promise((resolve) => setTimeout(resolve, 3000));
  const response = await fetch(`${API_URL}/${id}`);
  const json = await response.json();
  return json;
}

export default async function MovieInfo({ id }: { id: string }) {
  const movie = await getMovie(id);
  return <h6>{JSON.stringify(movie)}</h6>;
}

를 만들고 개별적으로 기다리게 한다. 그리고 page.tsx에서 MovieInfo 와 MovieVideos를 렌더링한다.

import { Suspense } from "react";
import MovieDetail from "../../../../components/movie-info";
import MovieVideos from "../../../../components/movie-video";
export default async function Text({ params }) {
  const { id } = await params;



  return (
    <div>
      <Suspense fallback={<h1>Loading Movie Info</h1>}>
        <MovieDetail id={id} />
      </Suspense>
      <Suspense fallback={<h1>Loading Movie Video</h1>}>
        <MovieVideos id={id} />
      </Suspense>
    </div>
  );
}

그럼 순차적으로 데이터가 준비되는 순간 사용자는 렌더링된 데이터를 볼 수 있다. 그리고 page.tsx 와 같은 위치에 있는 loading.tsx 는 최적화 한 덕분에 await 하는게 없으므로 전체 로딩하는 일이 없게 된다.

page 단위 로딩: loading.tsx 서버컴포넌트 단위 로딩: Suspense

Next15) 15버전 부터는 기본 캐싱이 안되기 때문에 캐싱을 확인하려면 fetch의 두번째 인자 cache옵션을 force-cache 로 바꿔줘야 한다고 한다.

Data Fetching

fetch, streaming, suspense, boundary 등을 배울것이다. 쉽고 멋지다고 한다.

NextJS 의 fetching을 위해 영화 상세보기 API를 이용하자.

[출처-노마드코더] : https://nomad-movies.nomadcoders.workers.dev/

/: This page /movies: List popular movies /movies/:id: Get movie by :id /movies/:id/credits: Get credits for a movie by :id /movies/:id/videos: Get videos for a movie by :id /movies/:id/providers: Get providers for a movie by :id /movies/:id/similar: Get similar movies for a movie by :id

url 종류는 위와 같다.

React Client Fetching

"use client";
// 과거에 리액트에서 하던 방식의 클라이언트 fetch는 아래와 같다.
import { useEffect, useState } from "react";

export default function HOME() {
  const [isLoading, setIsLoading] = useState(true);
  const [movies, setMovies] = useState([]);
  const getMovies = async () => {
    const response = await fetch(
      "https://nomad-movies.nomadcoders.workers.dev/movies"
    );
    const json = await response.json();
    setMovies(json);
    setIsLoading(false);
  };
  useEffect(() => {
    getMovies();
  }, []);
  return (
    <div>
      <h1>HOME</h1>
      <p>{isLoading ? "...isLoading" : JSON.stringify(movies)}</p>
    </div>
  );
}

기존방식: React API <===> API <===> DB 이렇게 하면 네트워크 탭을 열면 누구나 api를 보고 쿼리를 통해 정보를 찾을 수 있어서 보안적으로 안전하지 않은 경우가 있다.

모든것을 client 에서 fetching을 하면 API에서 보안을 위해 DB요청하는 중간의 API이 필요했다. 하지만 NextJS 는 중간의 백엔드 API 없이 DB에서 바로 데이터를 가져올 수 있다.

또한 React앱에서는 로딩 상태를 항상 신경써서 직접 만들어야 하고, useState를 사용해서 데이터를 관리해야 한다.

하지만 server component 에서 fetching을 하면, useEffect와 useState, Loding을 사용하지 않아도 된다.

그리고 프론트엔드 개발자는 백엔드가 만든 API가 필요하지 않게 된다.

//next.js
// 브라우저에서는 아무것도 fetch하지 않는다.
export const metadata = {
  title: "Home",
};
const MoviesURL = "https://nomad-movies.nomadcoders.workers.dev/movies";

async function getMovies() {
  const response = await fetch(MoviesURL);
  const json = await response.json();
  return json;
}
// 한번만 서버에서 fetch 하면 캐시된다. server component 에서 Next JS 가 fetch한 것을 기억하고 있기 때문이다.
// 새로고침해도 이미 응답이 캐시되었기 때문에 로딩이 필요 없다
// 하지만 만약 서버 끄고 재 실행된다면 로딩이 필요하다. 즉 첫번째 fetch한 데이터가 존재하면 API에 요청하지 않고 캐싱된 데이터를 보여준다.
export default async function HomePage() {
  const movies = await getMovies();
  return <div>{JSON.stringify(movies)}</div>;
}

최신 데이터가 필요할때는 캐싱이나 revalidation을 해야한다.

Loding

백엔드의 응답까지 첫 초기 렌더링이 UI 가 표기되지 않는 멈춤상태로 있는 설정이 싫고 최소한의 정적 UI를(네비게이션) 보고있게 하고 싶다면 loading파일을 하나 만들어서 해결할 수 있다. loading.tsx 파일을 만들어주자

export default function Loading() {
  return <h2>Loading...</h2>;
}

loading 파일만 제공 해줘도 된다. 이것은 백엔드가 페이지를 streaming 하기 때문에 가능하다. 백엔드에서 fetch함수가 완료되면 결과값을 브라우저에 보낸다. 그래서 layout과 navigation을 먼저 보내고 loading이 끝난 결과값을 보여주면 된다.

네트워크 탭을 열면 로딩중이라면 localhost가 로딩중임을 확인 할 수 있다. 이때 NextJS는 브라우저의 일부를 보여주며 기다려 달라고 하고, loading컴포넌트가 교체되는 것이다. 그리고 HomePage가 async인 이유는 준비된 Html 부분을 브라우저에 전달하기 위함이다.

변수가 라우터에 들어갈 때 사용한다. 파일시스템으로 동작한다.

[id] 이런 식으로 동작한다.

export default function MovieDetail(props){
    console.log(props)
    return <div>Movie</div>
}

콘솔로 찍어보면

이렇게 나온다.

id, sesarchParams을 얻게 되는데, searchParams는 url 뒤에 ? 데 대한 내용이다..

15 버전 이상 부터는 params 와 searchParams가 비동기로 작동해서, async await를 사용해야 한다.

const Page = async ({
  params,
  searchParams,
}: {
  params: Promise<{ id: string }>
  searchParams: Promise<{ [key: string]: string }>
}) => {
  const { id } = await params
  const search = await searchParams

  console.log(id, search)

  return <h1>My Post: {id}</h1>
}

export default Page

그러면 이렇게 출력된다.

layout, not-found 는 꼭 루트 폴더에 있어야 한다.

그룹을 만들고 싶으면 (home) 처럼 폴더 이름을 괄호로 묶어줘야 한다. 폴더 이름을 지정해주면 url이 바뀌지 않고, 프레임 워크에서만 보인다.

그래서 루트에 있던 홈 컴포넌트를 (home) 폴더로 옮길 수 있다.

Metadata

꼭 내보내야 하는 object 이고, 이것을 Metadata라고 부른다. 그리고 이것은 헤더에 표시된다.

export const metadata = {
  title: 'Home',
  description: '집에 보내줘 빨리, 바이 짜이쩬~',
}
export default function HOME(){
   return  <div> HOME</div>
}

metadata는 병합된다. title을 상위에 적고 하위에 description을 적으면 title은 상위에 있는 내용으로, description은 하위에 있는 내용으로 메타데이터가 병합된다. 또한 metadata는 서버 컴포넌트에만 있을 수 있다.

메타데이터에 대한 템플릿 또한 만들 수 있다.

루트에서 템플릿 메타데이터를 만들었다.

import { Metadata } from "next"

export const metadata :Metadata = {
  title: {template:"%s | Next Movies",
  default: "Loading...",
  },
  description: '집에 보내줘 빨리, 바이 짜이쩬~',
}

export default function Layout({childeren}:{childeren:React.ReactNode}){
   return ( <div>
    {childeren}
&copy; Next JS is great!    </div>)
}

헤더에 반영되고, head 태그에 반영된 것을 알 수 있다.

추가) 동적 메타데이터 정보가 api에 있을때? generateMetadata에서 호출해도 된다

export async function generateMetadata({ params: { id } }: IParamas) {
  const movie = await getMovie(id); // 영화 정보를 불러오기 위해 API 를 부르면 안좋은가? -> 최신버전은 fetch한번하면 캐싱된 응답을 받아서 괜찮다 ㅎㅎ
  return {
    title: movie.title,
  };
}

layout.tsx 라는 파일을 만들면 그 하위에 적용된다.

이렇게 있는 경우 루트의 layout 에서 컴포넌트를 임포트 하여 그것이 제일 상단으로, 그리고 아채 children이 추가된다.

그리고 about-us라는 루트 하위의 폴더에서 layout을 만들고 하위 url로 접속하면

app/about-us/jobs/sales 라는 폴더에서 레이아웃이 렌더링 되는 것을 알 수 있다.

레이아웃은 서로 상쇄되는 것이 아닌 중첩되고 있다.

Next JS 동작 방식

<RootLayout/> 확인 -> /about-us 경로 확인 -> <Layout/> 확인 -> 하위의 children인 <Sales/> 렌더링

즉 2개의 layout을 중첩하여 렌더링 하고 있다.

프레임 워크는 page의 가장 가까운 layout을 찾으려고 한다. 그래서 가까운 layout을 찾으면, 그 위 상위 항목을 확인하고 또 layout을 찾는다.

0

Hydration

단순 HTML을 React applaction으로 초기화 하는 작업이다.(HTML 위에서 React Application을 실행한다는 의미)

예를 들어 React 를 Initialize하여 onClick를 부착해 여기서 작성 가능 한 기능을 수행하도록 하는 것이다.

/aout-us 접근 => <button>0</button> => 사용자 확인 이후 => <button onClick={()=>이벤트수행}></button>

마치 위의 상태로 있는 것이다. 그리고 먼저 렌더링 한 후에 뒷단에서 next.js를 로딩하고 framework 를 초기화 하고 React application을 생성하는 것이다.

그러면 버튼이 interactive해지고 eventListener가 생기는 것이다.

🤔 render()

ReactDOM.render(element, container, [callback])

• element: 화면에 그려진 React element (집어넣어 줄 요소)
• container: React element를 해당 container DOM에 렌더링 (구체적인 위치)
• callback: 렌더링 후 반환되는 값을 돌려주는 콜백 함수 CRA하게 되면 index.js에 다음 코드를 쉽게 볼 수 있습니다.

import App from './App';

ReactDOM.render(<App />, document.getElementById('root'));

즉, <App/> 컴포넌트를 root라는 id를 가지고 있는 엘리먼트 내부로 넣어주어 페이지를 렌더링 해주고 있습니다.

🤔 hyrate()

ReactDOM.hydrate(element, container, [callback]) 기본적으로 render()와 동일하지만, ReactDOMServer로 렌더링된 HTML에 이벤트 리스터(자바스크립트 코드)를 연결해주기 위해 사용됩니다.

서버 사이드를 통해 이미 HTML에는 엘리먼트들이 채워져 있죠? 따라서 다시 render 해줄 필요 없이 hydrate를 통해 기존 마크업에 이벤트 리스너를 붙여주는 과정입니다.

위 과정들을 정리해봅시다.

Next.js는 서버에서 HTML을 문자열로 가져온 후에, 클라이언트에서 서버로부터 보내준 HTML을 render(), hydrate()하여 브라우저에 렌더링 했습니다. 이 일련의 과정을 Hydration이라고 합니다!

Hydration 사전적 정의 [명사] 수분 공급

서버의 데이터가 클라이언트의 DOM과 결합하는 과정을 빗대어 hydrate라는 단어로 정의된 것 같습니다.

React는 클라이언트 렌더링만 있어, 유저에게 보여줄 HTML, CSS 그리고 자바스크립트 모두 render() 함수를 이용해 생성하여, 모든 리소스를 한번에 렌더링합니다.

반면, Next.js는 서버에서 보여줄 HTML 컨텐츠를 미리 렌더링(내용을 채워서)하여 가져오기 때문에 render() 함수로 HTML 뼈대만 렌더하고, hydrate()를 통해 서버에서 받아온 HTML에 유저가 상호작용할 수 있는 이벤트 리스너(JS파일)을 연결하는 것입니다.

HTML에 JS파일(수분💦)을 주입한다고 해서 hydrate라고 이해할 수 있겠습니다!

client

client 에서 hydrdate 되어 interactive 하게 만들어질 components는 오직 use client 지시어를 최 상단에 갖고있는 컴포넌트만 가능하다.

따라서 Navigation 만 hydration 되는 것이다.

백엔드에서 render되고 프론트엔드에서 hydrate된다는 것이다.

이는 data fetch 되는 방식에서 중요한 개념이다. useQuery, useEffect ... 등등은 이제 안 쓸것이다.

hydrate장점

: Javascript를 선택적으로 작은파일만 다운로드 하게 할 수 있다. 그래서 백엔드에서 HTML을 먼저 preRender할 수 있다. 그리고 use client를 작성하면 그 child는 모두 client component가 된다. 그리고 server component 에서 fetch를 진행하면, 보안을 신경쓰지 않아도 된다. client에서 render 되기 때문! 그래서 API키를 넣거나 DB에 접근해도 된다.

Recap

Routing, Navigation, Layout, client, server components 등에 대해 배울 예정이다.

client, server 는 NextJS에서 나온 개념이라고 한다.

NextJS는 프레임워크라서, 올바른 폴더에 정확한 이름의 파일이 들어가 있으면 NextJS는 우리 코드를 이용해서 만들어 준다.

app 폴더 안에 page 파일을 찾는것 처럼. 그리고 꼭 export를 해야한다. 그리고 동시에 layout을 찾는다. 그래서 자동 생성된다. meta data라는 객체와 RootLauout는 html 바디 안에 body 태그를 갖는다.

Routing

• react 라우팅 방식

  / -> <Home />
  /about-us -> <AboutUs />

• NextJS 방식

  app 폴더 -> / (roote segment)
  app폴더/about-us 폴더 -> /about-us

  

• 주의

이렇게 된 경우 url 에서 /about-us/company에 접근하면 404 와 같다. page.tsx파일이 할당되지 않았기 때문이다.

Navigation Bar

"use client"
import Link from "next/link"
import { usePathname } from "next/navigation"

export default function Navigation(){
    const path = usePathname();
    return <nav>
        <ul>
            <li>
                <Link href='/'>HOME</Link>
                {path === '/' ? '💕':''}
            </li>
            <li>
                <Link href='/about-us'>AboutUS</Link>
                {path === '/about-us' ? '💕':''}

            </li>
        </ul>
    </nav>
}

Link 라는 태그를 이용해 네비게이션을 구현한다. 현재 경로를 알기 위해선 usePathname을 이용한다. 이때 최상단에 use client 를 작성하지 않으면 에러가 난다.

왜그럴까? client component가 뭘까

평범한 react 가 렌더링 되는 방식은 client side application이다. 유저가 페이지에 도착한 시점에는 javascript를 모두 실행한 후 페이지를 렌더링 한다. html에 UI가 없는 시점에서 Javascript를 기다릴 때 빈화면이 보이게 된다. App을 실행하려면 JavaScript가 실행되어야만 한다.

client side rendering 단점

• 만약 사용자가 데이터 연결 상태가 안좋은 상태에서 이 페이지에 접근하게 된다면, 아무 UI가 없는 빈 화면을 더 오래보게 될 것이다.
• Google에서도 빈 HTML을 보게 된다.

server side rendering 장점

• 페이지의 내용들이 (html) 이미 브라우저에 있다. html 을 보여주는데 Javascript가 필요하지 않기 때문이다. 그래서 빈 화면을 보지 않게 된다.
• 가장 먼저 back end 에서 렌더링 되는 것이다.=> 렌더링이란, JavaScript function을 가져와서 브라우저가 이해할 수 있는 html로 변환하는 작업니다.

1. Introduction

이 Framework 는 풀스택 웹앱을 개발하기 위한 최선의 Framework 라고 한다. 이 코스가 끝날 때에는 모든 프로그램을 NextJS로 만들고 싶어질거라 한다.

React Framework 중에 1등이라 하는 NextJS 최신 업데이트로 많이 발전했다고 한다.(14기준) 자동화로 개발자 경험 1위 라는데.. 기대가 된다.

2. Requirements

React.js 다룰줄 알아야 한다. (state, props, fetch, routing 등을 알아야 하니..)

3. Library(React) vs Framework(NextJS)

• Library: 라이브러리는 코드 내에서 사용하는 것이다. 원하는 아키텍를 원하는 방식으로 짠다. 함수 지향, 객체지향 프로그래밍이 가능하다. 코드 내에서 사용하고 사용의 주체는, 사용자이다. 파일이름, 폴더 구조 등. 라이브러리는 우리가 사용할 때 쓸 수 있다는 것이다.라이브러리의 도움이 필요할 때만 가져와서 사용할 수 있다. 다운받아서 사용하는 것. React는 UI 인터페이스를 build하는데 사용하는 라이브러리 이다.반응형 인터페이스를 구축하는데 도움이 된다. CSS 에 Styled Components 를 사용하거나 tailwind를 사용하거나, expo 를 사용하거나 routing을 사용하거나.. 등등의 모든 자유를 개발자가 가지는 것이다.

• Framework: 개발자에게 주도권은 없다. 프레임워크가 주도하고 담당한다. 프레임워크가 대신 자동화 하고 결정을 담당한다. 그래서 NextJS는 많은 Feature을 가지고 있다. 그래서 규칙을 따라야 한다. 이것이 프레임 워크다. 개발자가 규칙을 지켜야 한다는 것이다. 적당한 폴더에 파일을 만들어야 한다는 것. 그것이 지켜지지 않는다면 동작하지 않는다. import의 개념을 잊어라. 올바른 변수의 모양으로 넣어야 한다는 것이다. 올바른 위치에 넣으면 그것을 실행해 줄것이다.

라이브러리는 개발자가 사용하고, 프레임워크는 코드를 사용한다.

4. Old vs New Version

• Page Router : app 폴더에서 찾는다
• App Router : pages폴더에서 찾는다.

app에서 라우팅 하는 방식과 data fetching하는 법은 많이 바뀌었다. getStaticProps같은 것은 잊어라. page Router를 사용했다면, 최신 버전을 사용하기 위해선 migration 해야 한다.

5. Installation

npm init -y

// 이후  package.json 생김. author 수정
{
  "name": "next-practice",
  "version": "1.0.0",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/Eugenius1st/next-practice.git"
  },
  "keywords": [],
  "author": "",
  "license": "MIT", // 여기 수정
  "bugs": {
    "url": "https://github.com/Eugenius1st/next-practice/issues"
  },
  "homepage": "https://github.com/Eugenius1st/next-practice#readme",
  "description": ""
}

npm install react@latest next@latest react-dom@latest

• react: UI 와 여타 많은 것들을 구성하는 부분
• reactdom: 브라우저에서 렌더링 하는 도구

// 이후 스크립트 수정
  "scripts": {
    "dev": "next dev"

  },

실행하면 NextJS는 pages라는 폴더를 찾으로 할 것이다. 그리고 그 폴더는 app 폴더 안에 있을 것이다.

다음 app/page.tsx 혹은 .jsx를 만들어라.

그리고 npm run dev로 실행

그리고 실행하면 local:3000 에서 실행중임을 알 수 있다. 그리고 자연히 layout.tsx 가 생겨남을 알 수 있다.

export const metadata = {
  title: 'Next.js',
  description: 'Generated by Next.js',
}

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  )
}