
> 한빛미디어 서평단 <나는리뷰어다> 활동을 위해서 책을 협찬 받아 작성된 서평입니다.

---

## 이 책을 고른 이유

![누구나 아는 나만 모르는 챗GPT 표지](/images/posts/chatgpt-beginner-guide-review/01-book-cover.webp)

챗GPT는 이제 대부분의 사람들이 쓰고 있다. 그런데 주변을 보면 사용 방식이 생각보다 한정적이다. 프롬프트를 만들어서 텍스트를 생성하거나, 검색 대용으로 질문을 던지는 정도에서 멈추는 경우가 많다. 그 외의 접근법이 있다는 걸 모르거나, 굳이 찾아보지 않는 것이다.

개발을 하면서도 코드 리뷰, 디버깅, 문서 초안 정도로 매일 쓰고 있지만, 결국 텍스트 기반의 활용에 머물러 있다. 챗GPT를 포함한 AI 도구의 활용 범위를 좀 더 넓혀보고 싶다는 생각은 이전부터 있었는데, 그 시작점이 될 만한 책이 궁금했다.

---

## 원리 대신 감각을 전달하는 구성

![카카오톡만큼 쉬운 챗GPT 설명](/images/posts/chatgpt-beginner-guide-review/02-kakaotalk-simple.webp)

![수백 번도 질문할 수 있는 똑똑한 친구](/images/posts/chatgpt-beginner-guide-review/03-smart-friend.webp)

0장의 제목이 "왕초보가 챗GPT를 배워야 하는 이유"인데, 여기서부터 책의 방향이 확실히 드러난다. "카카오톡만큼 간단하다", "타자가 느리면 음성으로 물어본다", "물어볼 사람이 없을 때 수백 번도 질문할 수 있다"처럼 LLM이 뭔지, 트랜스포머 아키텍처가 어떻게 작동하는지 같은 기술적인 설명은 일절 등장하지 않고, 철저하게 일상의 언어로만 풀어낸다.

이 접근이 맞다고 생각한다. AI를 처음 접하는 사람에게 필요한 건 원리에 대한 이해가 아니라 "나도 할 수 있겠다"는 감각이기 때문이다. 실제로 1장에서는 크롬 브라우저를 여는 것부터 시작해서 회원 가입, 첫 대화, 모바일 설치, 음성 대화까지 한 단계씩 순서대로 안내하는데, 이런 구성을 보면 초보자가 어디서 헤맬 수 있는지를 꽤 신경 쓴 저자라는 느낌이 든다.

---

## 기술 용어 없이 프롬프트 엔지니어링 소개

![개인 맞춤 설정 안내](/images/posts/chatgpt-beginner-guide-review/04-custom-settings.webp)

![역할 부여와 맞춤형 지침 예시](/images/posts/chatgpt-beginner-guide-review/05-role-prompting.webp)

2장에서 다루는 "원하는 답변을 끌어내는 다섯 가지 방법"이 인상적이었다. 개인 맞춤 설정, 역할 부여, 질문을 질문하기, 꼬리에 꼬리를 무는 질문, 예시 들기라는 다섯 가지 방법을 소개하는데, 이걸 나열해놓고 보면 사실 프롬프트 엔지니어링에서 이야기하는 핵심 기법들과 거의 겹친다.

"역할을 부여하라"는 role prompting, 즉 AI에게 특정 전문가의 관점을 부여해서 답변의 깊이와 방향을 조절하는 기법이고, "예시를 들어라"는 few-shot prompting으로 원하는 결과물의 형태를 미리 보여줘서 AI가 패턴을 파악하게 하는 방식이다. "개인 맞춤 설정"은 system prompt를 설정하는 것과 같은 맥락인데, 모든 대화에 공통으로 적용될 맥락과 톤을 미리 지정해두는 것이다.

그런데 책에서는 이런 용어를 단 하나도 꺼내지 않는다. 대신 "50대 남성을 위한 헬스 트레이너야"라고 역할을 붙여보라거나, "이 주제를 어떻게 물어보면 좋을까?"라고 챗GPT에게 질문 만드는 법을 되물어보라는 식으로 구체적인 상황과 예시만으로 설명한다. 개인 맞춤 설정도 일반인용, 가정주부용처럼 독자의 상황별로 작성 예시를 제시해서, 따라 적기만 해도 자연스럽게 system prompt가 완성되는 구조다.

개발자 입장에서 보면 이미 알고 있는 개념들일 수 있지만, 기술 용어를 전혀 쓰지 않고도 같은 내용을 전달할 수 있다는 점이 흥미로웠다. 프롬프트 엔지니어링이라는 말 자체가 진입 장벽이 될 수 있는데, 이 책은 그 장벽을 넘으면서도 핵심은 놓치지 않는다.

---

## 챗GPT 너머의 AI 도구들

![Suno로 노래 만들기](/images/posts/chatgpt-beginner-guide-review/06-suno-music.webp)

![제미나이와 나노바나나 프로](/images/posts/chatgpt-beginner-guide-review/07-gemini-nano.webp)

이 책이 챗GPT만 다루는 입문서였다면 크게 눈길이 가지 않았을 것이다. 그런데 4장부터는 Suno, Sora 2, 노트북LM, 제미나이, 나노바나나 프로 같은 도구들을 폭넓게 소개하고, 6장에서는 감마로 프레젠테이션을 만들고 냅킨으로 도해를 정리하는 업무 활용까지 다룬다. 챗GPT라는 이름을 달고 있지만, 실제로는 AI 도구 전반을 훑어보는 구성에 가깝다.

특히 Suno로 노래를 만들어 카카오톡으로 보내는 과정이나, Sora 2로 이미지 한 장에서 제품 홍보 영상을 만드는 흐름은 단순히 "이런 도구가 있다"는 소개에서 그치지 않고, 결과물을 직접 만들어보는 데까지 이어진다. 초보자 입장에서 가장 효과적인 학습은 직접 무언가를 만들어보는 것인데, 그 흐름이 잘 설계되어 있다고 느꼈다.

개발자인 나도 Suno나 나노바나나 프로는 써본 적이 없어서, 목차만 보고도 한번 시도해봐야겠다 싶은 도구가 몇 개 있었다. AI 도구의 범위가 텍스트 생성을 넘어 이미지, 영상, 음악, 프레젠테이션까지 확장되고 있다는 걸 한 권으로 경험할 수 있다는 건 이 책의 분명한 장점이다.

---

## 총평

![다양한 스타일의 콘텐츠 만들기](/images/posts/chatgpt-beginner-guide-review/08-content-styles.webp)

![QR 코드와 냅킨 도해 활용](/images/posts/chatgpt-beginner-guide-review/09-qr-napkin.webp)

이 책의 핵심은 "쉽다"는 약속을 끝까지 지킨다는 데 있다. 앞서 이야기한 것처럼 크롬 브라우저 여는 법부터 시작하는 난이도인데, 후반부에서 Suno나 감마 같은 도구를 다룰 때도 그 눈높이가 올라가지 않는다. 매 단계마다 QR 코드로 실제 대화 예시와 영상 강의를 제공하고, "조금 더 가볼까요?"나 "1분만요!" 같은 코너로 더 알고 싶은 사람만 깊이 들어갈 수 있게 구성해뒀기 때문이다. 왕초보를 위한 책이라고 하면서 중간에 갑자기 난이도가 뛰는 입문서가 많은데, 이 책은 그런 부분에서 일관성이 있었다.

다만 개발자 시점에서 솔직히 말하면, 챗GPT를 이미 활용하고 있는 사람에게는 앞부분이 익숙한 내용의 연속이다. 프롬프트 작성법을 다루는 2장도 "구체적으로 질문하라", "역할을 부여하라" 같은 기본적인 수준을 다루기 때문에, 깊이 있는 프롬프트 엔지니어링을 기대하고 펼치면 아쉬울 수 있다. 하지만 이건 애초에 이 책이 겨냥하는 독자층이 다르기 때문이니 단점이라고 보기는 어렵다.

---

## 누구에게 추천하는가

AI가 궁금하지만 어디서 시작해야 할지 모르는 분, 특히 디지털 기기 사용이 익숙하지 않은 분에게 가장 적합하다. 부모님이나 비개발자 지인에게 "챗GPT 한번 써봐"라고 말하는 대신 이 책을 건네는 게 훨씬 효과적일 것 같다.

개발자라면 4장의 AI 도구 소개 파트를 중심으로 훑어보는 것을 추천한다. 텍스트 생성 외에 어떤 AI 도구들이 나와 있는지 빠르게 파악할 수 있다.

#한빛미디어 #나는리뷰어다 #누구나아는나만모르는챗GPT


개발자가 읽은 왕초보 AI 입문서

누구나 아는 나만 모르는 챗GPT


> 한빛미디어 서평단 <나는리뷰어다> 활동을 위해서 책을 협찬 받아 작성된 서평입니다.

---

## 이 책을 고른 이유

![러스트로 갈아타기 표지](/images/posts/refactoring-to-rust/02-book-cover.webp)

솔직히 말하면 러스트를 써본 적이 없다. 주력 스택은 TypeScript/React이고, 평소에 메모리 관리나 컴파일러 같은 키워드는 나와 거리가 멀다고 생각했다. 그런데 요즘 프론트엔드 생태계를 보면 러스트가 자꾸 눈에 들어온다. Next.js에 내장된 SWC, Webpack을 대체하려는 Turbopack, 그리고 Go로 만들어진 esbuild까지. 내가 매일 쓰는 도구들의 내부가 슬슬 "자바스크립트가 아닌 언어"로 바뀌고 있었다.

그래서 궁금했다. 러스트가 대체 뭐길래, 기존에 잘 돌아가던 JS 도구들을 굳이 다른 언어로 다시 만드는 걸까? "러스트로 갈아타기"라는 제목이 그 질문에 대한 답을 줄 것 같았다.

---

## 리팩터링이라는 접근법

![1장 리팩터링이라는 접근법](/images/posts/refactoring-to-rust/03-chapter1.webp)

책을 펼치고 처음 느낀 건, 이 책이 "러스트를 배우자"가 아니라 **"기존 코드를 러스트로 조금씩 바꿔보자"**에서 출발한다는 점이었다. 1장부터 리팩터링과 재작성(rewriting)의 차이를 꽤 분명하게 나눈다.

재작성은 시스템 전체를 처음부터 다시 만드는 것이고, 리팩터링은 가장 개선이 필요한 부분만 찾아 최소한의 코드를 교체하는 것이다. 책은 후자를 권하는데, 전체를 한 번에 바꾸면 뭐가 문제인지 찾기 어렵고 기존 코드에 쌓인 수년간의 프로덕션 경험까지 잃게 되기 때문이다.

실제로 Discord는 Go로 작성된 서비스 중 지연 시간이 문제였던 부분만 러스트로 교체해 성능을 크게 개선한 사례가 있다. 이 책도 같은 맥락에서 "성능이 필요한 함수 하나만 러스트로 빼자"는 방식을 제안한다. 이 전제 덕분에 러스트를 처음 접하는 개발자도 부담 없이 읽을 수 있었다.

---

## 소유권과 대여

2장에서 러스트의 핵심인 소유권(ownership)과 대여(borrowing)를 다룬다. JS 개발자로서 이 부분이 가장 낯설었다.

자바스크립트에서는 변수를 함수에 넘기면 참조가 전달될 뿐, 원래 변수는 아무 영향 없이 계속 쓸 수 있다. 그런데 러스트에서는 값을 함수에 넘기면 **소유권 자체가 이동**한다. 원래 변수는 더 이상 그 값을 쓸 수 없다.

```rust
admire_art(art1);  // art1의 소유권이 함수로 넘어감
admire_art(art1);  // 컴파일 에러, art1은 이미 없음
```

자바스크립트에서는 볼 수 없는 에러다. JS의 가비지 컬렉터는 "아무도 안 쓰는 것 같으면 알아서 치워줌" 방식이라 개발자가 메모리를 신경 쓸 일이 없다. 반면 러스트는 가비지 컬렉터 없이 컴파일러가 소유권 규칙으로 메모리 안전성을 보장하기 때문에, 잘못된 코드는 실행 자체가 되지 않는다.

C 언어도 개발자가 메모리를 직접 관리하지만 실수해도 컴파일은 통과되고, 문제는 런타임에 가서야 터진다. 반면 러스트는 컴파일 단계에서 소유권 규칙 위반을 잡아내기 때문에 애초에 잘못된 코드가 실행되지 않는다. C가 1972년에 만들어져 이런 검증 개념 자체가 없었던 반면, 러스트는 2015년에 등장하면서 그동안 축적된 경험을 바탕으로 소유권 시스템을 언어 설계 단계에서 녹여냈다.

이 책에서 **수명 그래프(lifetime graph)**를 시각화해 보여주어 이해가 쉬웠다. 값이 언제 생성되고, 언제 유효하며, 언제 소멸하는지를 그래프로 보여주었다. 소유권이나 대여 같은 추상적인 개념을 글로만 보게 되면 머리에 잘 들어오지 않는데, 수명 그래프 덕분에 "art1이 여기서 생성되고, admire_art에 소유권이 넘어가고, 함수가 끝나면서 메모리가 해제되는구나"를 시각적으로 따라갈 수 있었다.

![수명 그래프 예시](/images/posts/refactoring-to-rust/01-lifetime-graph.webp)

또 한 가지 흥미로운 건 `mut` 키워드다. JS에서는 `const`를 써야 불변이고 `let`이 기본적으로 가변인데, 러스트는 반대로 기본이 불변이고 `mut`를 명시적으로 붙여야 변경할 수 있다. "변경은 의도적으로 하라"는 언어 설계 철학이 느껴졌다. TypeScript의 `readonly`와 방향성은 비슷하지만, 러스트는 이걸 언어 전체에 걸쳐 강제한다는 점에서 훨씬 강력하다.

---

## 프론트엔드와 WebAssembly

![9장 프론트엔드와 WebAssembly](/images/posts/refactoring-to-rust/04-chapter9.webp)

9장이 프론트엔드 개발자로서 가장 흥미로웠다. 러스트로 작성한 코드를 WebAssembly(WASM)로 컴파일해서 브라우저에서 실행하는 방법을 다룬다.

책에서는 세 가지 접근법을 보여준다.

1. **스크립트**: 웹 페이지에서 WASM 함수를 직접 호출하는 가장 단순한 방식
2. **모듈**: 러스트 WASM을 npm 패키지처럼 React 프로젝트에 import해서 사용하는 방식
3. **컴포넌트**: Yew라는 프레임워크로 UI까지 전부 러스트로 작성하는 방식

이 중 두 번째, 모듈 방식이 가장 써볼 만하다고 느꼈다. Vite + React 프로젝트를 생성하고, 데이터 처리 같은 무거운 로직만 러스트로 작성해서 WASM 모듈로 가져오는 구조다. **UI는 React(JSX)로 그대로 유지하고, 연산 함수만 러스트로 대체하는 것**이다. 전부 갈아엎는 게 아니라 부분적으로 교체한다는 점에서, 1장에서 이야기한 리팩터링의 철학이 그대로 적용된다.

Yew 프레임워크도 인상적이었다. React와 비슷한 컴포넌트 기반 프레임워크인데, 상태 관리 방식이 React의 `useReducer` 패턴과 놀라울 정도로 닮아있다. State, Action, update(reducer), view(render)의 구조가 거의 동일하다. 프레임워크가 달라도 UI 상태 관리 패턴은 결국 같은 방향으로 수렴한다는 걸 확인할 수 있었다.

---

## 총평

이 책의 가장 큰 미덕은 "전부 바꾸지 말고, 필요한 부분만 러스트로 교체하라"는 점진적 접근법에 있다. 이미 다른 언어로 일하고 있는 개발자가 러스트를 시작하기에 부담이 적고, C FFI, 파이썬(PyO3), 자바스크립트(WASM)까지 다양한 통합 시나리오를 구체적인 예제로 다룬다는 점도 좋았다. 앞서 언급한 수명 그래프처럼 추상적인 개념을 시각적으로 풀어내는 방식도 인상적이었다.

다만 예제가 주로 C와 파이썬 중심이라, 9장의 WASM 파트가 있긴 하지만 전체 분량에서 차지하는 비중은 크지 않다. 웹 생태계에서 러스트가 어떻게 작용하는지 맛볼 수 있다는 점에서 좋았지만, 이 책의 범위상 어쩔 수 없다 하더라도 좀 더 깊이 다뤄줬으면 하는 아쉬움이 있었다. 2장에서 소유권과 대여를 다루면서 스택/힙, 메모리 할당 같은 저수준 개념이 바로 등장하는 것도 가비지 컬렉션 언어만 써온 개발자에게는 가파르게 느껴질 수 있는데, 책에서도 "주로 C/C++ 경험이 있는 독자를 대상으로 한다"고 안내하고 있으니 해당 부분은 넘어가도 된다.

---

## 누구에게 추천하는가

C나 파이썬 기반 프로젝트에서 성능 병목이 있거나, 메모리 안전성이 필요한 부분을 개선하고 싶은 개발자에게 가장 적합하다.

프론트엔드 개발자라면 9장의 WASM 파트를 중심으로 읽는 것을 추천한다. 러스트를 처음 접하더라도 1-2장에서 소유권과 대여의 기본 개념을 잡고, 9장에서 "내 React 프로젝트에 러스트를 어떻게 끼워 넣을 수 있는지"를 확인할 수 있다. 당장 러스트를 실무에 쓰지 않더라도, 내가 매일 사용하는 SWC나 Turbopack 같은 도구가 왜 러스트로 만들어졌는지 이해하는 데 도움이 된다.

러스트를 전혀 모르는 상태에서 읽어도 따라갈 수 있었지만, 편하게 읽히는 책은 아니다. 소유권 같은 개념은 JS에서는 접할 일이 없는 영역이라 낯설게 느껴질 수밖에 없다. 그래도 그 낯섦 자체가 시야를 넓혀주는 경험이었다.

#한빛미디어 #나는리뷰어다 #러스트로갈아타기


레거시 코드는 살리고 성능은 높이는 단계별 리팩터링 전략

러스트로 갈아타기: 프론트엔드 개발자의 러스트 입문기


## 개요

서비스에서 실시간으로 "댓글이 추가됐다"는 이벤트를 모든 사용자가 아니라, 해당 프로젝트를 보고 있는 사용자에게만 전달해야 한다. 전체 브로드캐스트는 간단하지만, 대상을 특정하려면 약간의 추가적인 구조가 필요하다.

이 글은 Socket.IO의 Room 시스템으로 어떻게 Pub/Sub 패턴을 구현하는지, 서버가 여러 대일 때 Redis Adapter가 왜 필요한지를 정리한다.

## Room이란

![excalidraw: Room 기본 개념 — project:A Room에 속한 소켓에게만 이벤트가 전달된다](/images/posts/socket-room-pubsub-redis/01-room-concept.webp)

Socket.IO의 Room은 서버가 관리하는 구독 그룹이다. 클라이언트가 프로젝트를 확인하려고 요청하면, 서버가 해당 클라이언트를 Room에 추가한다.

```typescript
// 서버가 해당 클라이언트의 소켓을 project Room에 추가
client.join(`project:${projectId}`);

// 서버가 project Room에 속한 모든 소켓에게 이벤트를 보냄
this.server.to(`project:${projectId}`).emit("message", { op: Opcode.Update, evt: "ADD_COMMENT", d: payload });
```

Room은 서버 메모리에 존재하는 Set이다.

```typescript
// Room의 내부 구조 (개념적)
const rooms = {
  "project:a3b8f2e": Set(["socketId_A", "socketId_B"]), // Client A, B가 참여
  "project:c7d4e1a": Set(["socketId_C"]), // Client C만 참여
};
```

`client.join()`은 이 Set에 소켓 ID를 추가하고, `server.to().emit()`은 Set에 있는 모든 소켓에게 메시지를 보낸다. 클라이언트는 자신이 어떤 Room에 있는지 알 필요 없이 서버가 관리하고, 서버가 라우팅한다.

Pub/Sub 패턴을 간략하게 시각화하면 아래와 같다.

![excalidraw: Pub/Sub 패턴 — Publisher가 Channel에 발행하면, 구독한 Subscriber에게만 전달된다](/images/posts/socket-room-pubsub-redis/03-pubsub-pattern.webp)

Socket.IO에서는 Room이 Channel 역할을 하고, `join()`으로 구독하고, `to().emit()`으로 발행한다.

## Room 네이밍 전략

Room 이름을 어떻게 짓느냐에 따라 이벤트를 얼마나 정확하게 라우팅할 수 있는지가 달라진다. 여기서는 세 가지 레벨의 Room을 사용한다.

```typescript
// 인증 레벨 (토큰 만료 시 해당 사용자의 모든 연결을 끊기 위해)
client.join(`auth:${tokenId}`);

// 워크스페이스 레벨 (특정 사용자에게만 알림을 보내기 위해)
client.join(`workspace:${workspaceId}:user:${userId}`);

// 프로젝트 레벨 (해당 프로젝트를 보는 모든 사용자에게 이벤트 전달)
client.join(`project:${projectId}`);
```

`auth:` Room은 토큰 단위로 소켓을 묶기 위해 만들었다. 토큰이 무효화되면 해당 Room의 모든 소켓을 한번에 강제 종료할 수 있다.

```typescript
// 토큰 무효화 시, 해당 사용자의 모든 연결을 끊는다.
this.server.to(`auth:${tokenId}`).emit("message", { op: Opcode.Closed });
this.server.to(`auth:${tokenId}`).disconnectSockets(true);
```

`workspace:user:` Room은 특정 사용자에게 개별 알림을 보내는 데 쓴다. 프로젝트에 새 멤버가 추가되면, 해당 워크스페이스의 특정 사용자들에게만 알림을 보낸다.

```typescript
// 특정 사용자들에게만 알림을 전송한다.
this.server
  .to(userIds.map((x) => `workspace:${workspaceId}:user:${x}`))
  .emit("message", { op: Opcode.Notification, d: payload });
```

## 인증과 권한 검증

Room에 아무나 참여할 수 있으면 보안 문제가 된다. 따라서 서버는 `join()` 전에 반드시 권한을 검증해야 한다.

```typescript
async function setProject(client, payload) {
  const hasAccess = await verifyProjectAccess(client, payload);
  if (!hasAccess) throw new ForbiddenException();

  client.join(`project:${payload.projectId}`);
}
```

Socket.IO 자체는 Room 참여에 제한을 두지 않는다. `client.join()`은 아무 조건 없이 호출할 수 있다. 권한 검증은 전적으로 애플리케이션 코드의 몫이기 때문에, `join()` 호출 전에 접근 권한을 확인하는 로직을 직접 구현해야 한다.

## Redis Adapter로 서버 간 이벤트 공유

서버가 1대면 Room은 해당 서버의 메모리에서 관리되므로 문제가 없다. 하지만 사용자가 많아지면 서버 1대로는 감당이 안 되기 때문에 서버를 여러 대로 늘리게 된다. 이때 앞단에 로드밸런서가 요청을 분배하는데, 이걸 수평 확장(scale-out)이라고 한다.

문제는 사용자 A가 서버 1에, 사용자 B가 서버 2에 연결됐는데 둘 다 같은 프로젝트를 보고 있을 때다. 서버 1의 Room에는 사용자 A만 있고, 서버 2의 Room에는 사용자 B만 있다. 사용자 A가 댓글을 달면 서버 1의 Room에만 이벤트가 발생했기 때문에, 서버 2는 이 이벤트를 알 수 없다! 그렇게 되면 사용자 B는 댓글이 추가된 걸 볼 수 없다.

Redis Adapter를 통해 이 문제를 해결할 수 있다. 모든 서버가 Redis에 연결되어 있고, 한 서버에서 `to().emit()`을 호출하면 Redis를 통해 다른 서버들에게도 전달된다.

```typescript
import { Redis } from "ioredis";
import { Server } from "socket.io";

import { createAdapter } from "@socket.io/redis-streams-adapter";

const client = new Redis({ host: "localhost", port: 6379 });

const io = new Server({
  adapter: createAdapter(client, {
    maxLen: 10_000,
    streamName: "{event}",
  }),
});
```

일반 Redis Pub/Sub 대신 **Redis Streams** 기반 어댑터(`@socket.io/redis-streams-adapter`)를 사용하면 더 안정적이다. 일반 Pub/Sub은 "발행 시점에 구독하고 있는 소비자만" 메시지를 받는다. 연결이 잠깐 끊긴 사이에 발행된 메시지는 놓친다.

그 점을 보완해 Redis Streams는 메시지에 영속성(persistence)을 부여한다.

![excalidraw: Redis Adapter — 서버 1의 이벤트가 Redis Streams를 통해 서버 2로 전달된다](/images/posts/socket-room-pubsub-redis/02-redis-adapter.webp)

Pub/Sub은 메시지를 전달만 하고 바로 사라지지만, Streams는 메시지를 메모리에 보관하기 때문에 서버 간 연결이 일시적으로 끊겨도 놓친 이벤트를 나중에 가져올 수 있다.

## 정리

- Room은 서버가 관리하는 구독 그룹이다. 이벤트를 특정 대상에게만 보낼 수 있다
- Room 이름을 auth/workspace/project 레벨로 분리하면 정확한 라우팅이 가능하다
- Socket.IO는 Room 참여에 제한을 두지 않으므로, 권한 검증은 직접 구현해야 한다
- 서버가 여러 대일 때는 Redis Adapter로 서버 간 이벤트를 공유할 수 있다
- Redis Streams는 Pub/Sub과 달리 메시지를 보관하기 때문에 놓친 이벤트를 복구할 수 있다

## 참고 자료

- [Socket.IO Rooms](https://socket.io/docs/v4/rooms/)
- [Socket.IO Redis Streams Adapter](https://socket.io/docs/v4/redis-streams-adapter/)
- [Redis Streams Introduction](https://redis.io/docs/data-types/streams/)


이벤트가 사용자에게 도달하기까지

Socket.IO의 Room 기반 Pub/Sub과 Redis Adapter

싱글톤, 생명주기, React Query 캐시 동기화까지의 설계 과정

React에서 Socket.IO 연결 관리하기


## 개요

영상 플레이어를 개발하면서 타임스탬프를 비교할 일이 생겼다. 현재 재생 시점과 저장된 타임스탬프가 같은지 판별해야 했는데, `===`로 비교하면 거의 항상 불일치했다. `Math.round()`를 써도 경계에서 어긋났다.

이 글은 왜 웹 비디오에서 타임스탬프 비교가 근본적으로 어려운지, 그리고 어떻게 우회했는지를 정리한다.

## video.currentTime

HTML5 Video API에서 현재 재생 위치를 가져오는 방법은 `video.currentTime`이다. 이 값은 초 단위의 `IEEE 754` 부동소수점(double)이다.

https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/currentTime

```javascript
console.log(video.currentTime);
// 3.456789123456789
```

비디오 컨테이너(MP4 등) 내부에서는 시간을 정수 기반으로 표현한다. 소수점을 쓰면 오차가 생기니까, "1초를 N칸으로 쪼개고 몇 번째 칸인지"를 정수 쌍으로 저장하는 방식이다. MP4에서는 이걸 `TimeValue / TimeScale`이라고 부른다.

- **TimeScale**: 1초를 몇 칸으로 쪼갤지 정하는 단위다. MP4에서는 주로 90000을 사용하는데, MPEG-2 Transport Stream(방송 표준)의 90kHz 클럭에서 온 관례다. 이 값이 24fps/25fps/30fps의 공배수라서 어떤 프레임레이트(fps, 초당 프레임 수)든 나누어떨어진다.
- **TimeValue**: 그 칸에서 몇 번째 위치인지를 나타내는 정수다.

예를 들어 25fps 비디오의 13번 프레임은 `13/25 = 0.52`초에 시작한다. 이걸 MP4 내부에서는 `0.52 × 90000 = 46800`으로 변환해서 정수 쌍 `(46800, 90000)`으로 저장한다. `46800/90000 = 0.52`로 오차 없이 복원할 수 있다.

문제는 브라우저가 이 정수 기반 타임스탬프를 JavaScript에 노출할 때 초 단위 `double`로 변환한다는 점이다. 이 변환 과정에서 정밀도가 깎인다.

## 부동소수점이 프레임 비교를 망치는 과정

WebKit 버그 리포트(#52697)에 구체적인 사례가 기록되어 있다. WebKit은 Safari의 브라우저 엔진이지만, 이 문제는 WebKit에 국한되지 않고 부동소수점을 사용하는 모든 브라우저에서 동일하게 발생한다.

![WebKit Bug 52697 - Frame accurate seeking isn't always accurate](/images/posts/video-frame-precision-epsilon/01-webkit-bug-52697.webp)

25fps 비디오의 13번 프레임 시작 시간은 `46800/90000`이다. 이 값을 배정밀도(double)로 표현하면 `0.52000000000000002`가 되지만, 브라우저 내부 엔진이 이를 단정밀도(float)로 처리할 경우 `0.5199999809265137`이 된다.

이 두 값으로 프레임의 TimeValue를 역산하면

$$
\frac{13}{25} \times 90000 = 46799.999...
$$

$$
\lfloor 46799.999 \rfloor = 46799
$$

가 된다. 프레임은 연속적인 시간 범위를 차지하기 때문에, 특정 시점이 몇 번째 프레임인지 알려면 내림(floor)을 해야 한다. 프레임 13은 TimeValue 46800에서 시작하는데, 부동소수점 오차로 46799가 되면서 프레임 12의 범위에 속하게 된다. 결과적으로 봤을 때 한 프레임이 밀리게 된다.

## 정수 기반 API 부재

W3C Media & Entertainment Interest Group에서도 이 문제를 논의했다. 프레임 단위 탐색이 필요한 실제 사용 사례를 모아서 브라우저 벤더들에게 API 개선을 요구하자는 취지로 열린 이슈인데, 2018년에 열리고 아직까지 Open 상태다.

https://github.com/w3c/media-and-entertainment/issues/4

![W3C - Frame accurate seeking of HTML5 MediaElement](/images/posts/video-frame-precision-epsilon/02-w3c-frame-accurate-seeking.webp)

해당 이슈에서 지적된 이유는 여러 가지다.

첫째, 브라우저 JavaScript API에서 비디오의 실제 프레임레이트를 얻을 방법이 없다. `<video>` 요소에는 fps를 반환하는 속성이 없다. 이슈 본문에서도 "the framerate of the video, which is not exposed to Web applications"라고 지적하고 있다. VFR(Variable Frame Rate) 영상이라면 프레임마다 duration이 다르기 때문에 단일 fps 값 자체가 무의미하다.

![W3C 이슈 댓글 - currentTime만으로는 현재 프레임을 특정할 수 없다](/images/posts/video-frame-precision-epsilon/03-w3c-daiz-comment.webp)

이 이슈에서는 `currentFrameTime`이라는 새 속성을 추가해 현재 표시된 프레임의 정확한 시간을 반환하자는 제안도 있었지만, 이 속성은 추가되지 않았다.

둘째, JavaScript와 비디오 렌더링은 서로 다른 스레드에서 실행된다. `requestVideoFrameCallback` API 문서에서도

![requestVideoFrameCallback - 메인 스레드와 컴포지터 스레드 분리](/images/posts/video-frame-precision-epsilon/04-rvfc-compositor-thread.webp)

라고 설명하고 있다. `currentTime`을 읽는 시점과 실제로 화면에 그려진 프레임이 일치한다는 보장이 없다.

https://web.dev/articles/requestvideoframecallback-rvfc

## GOP(Group of Pictures) 구조가 만드는 추가 제약

YouTube IFrame API처럼 서버에서 영상을 스트리밍으로 받아 재생하는 환경에서는, 부동소수점 오차와 별개로 비디오 압축 구조 자체가 프레임 정밀 탐색을 어렵게 만든다.

GOP는 영상 프레임들을 묶는 압축 단위다. 매 프레임을 통째로 저장하면 용량이 너무 크기 때문에, 하나의 완전한 이미지(I-frame)를 기준으로 나머지 프레임은 차이만 저장하는 방식으로 압축한다. 비디오 프레임은 세 가지 유형으로 나뉜다.

| 프레임 유형 | 설명                                                                                              |
| ----------- | ------------------------------------------------------------------------------------------------- |
| I-frame     | 내부(intra)만으로 완성되는 프레임, 다른 프레임 참조 없이 독립적으로 디코딩할 수 있다.             |
| P-frame     | 이전 프레임을 예측(predicted)해서 바뀐 부분만 저장한다. 이전 I/P-frame이 있어야 디코딩할 수 있다. |
| B-frame     | 앞뒤 프레임을 양방향(bi-directional)으로 참조해서 차이만 저장한다.                                |

영상에서 특정 시점으로 탐색(seek)하면, 브라우저가 바로 그 프레임을 보여줄 수 있을 것 같지만 그렇지 않다. 해당 시점의 프레임이 P-frame이나 B-frame이라면, 차이 데이터만 있기 때문에 기준이 되는 I-frame을 먼저 찾아야 한다. 가장 가까운 I-frame까지 돌아간 뒤, 거기서부터 원하는 시점까지의 프레임을 순서대로 디코딩해야 한다.

I-frame은 보통 60-120 프레임(30fps 기준 2-4초)마다 존재한다. 스트리밍 환경에서는 용량을 줄이기 위해 I-frame 간격을 더 길게 잡는 경향이 있어서, 프레임 정확 탐색은 더욱 어려워진다.

## epsilon 비교로 우회

프레임 단위 정확한 비교가 불가능하다면, "충분히 가까우면 같다"고 판단하는 방식으로 우회할 수 있다. epsilon(ε)은 수학에서 아주 작은 양을 뜻하는데, 두 값의 차이가 이 ε보다 작으면 같다고 간주하는 비교 방식을 epsilon 비교라고 한다.

```javascript
// 정확한 비교 — 거의 항상 false
if (currentTime === targetTime) { ... }

// epsilon 비교
const EPSILON = 0.1; // 초
if (Math.abs(currentTime - targetTime) < EPSILON) {
  // 허용 오차 내면 같은 프레임으로 판단
}
```

너무 작으면 같은 프레임인데도 다르다고 판정하고, 너무 크면 다른 프레임을 같다고 판정하기 때문에 epsilon 값을 어떻게 정할 것인가가 중요하다. 여기서는 0.1초를 epsilon으로 설정했다. 60fps 기준으로 6프레임에 해당하는 넉넉한 값이다. 이 값을 선택한 근거는 다음과 같다.

```typescript
const isSameTimestamp = Math.abs(currentTimeInSeconds - timeInSeconds) < 0.1;
```

이 epsilon은 같은 타임스탬프의 중복 클릭을 판별하고, 반복 seek를 방지하는 데 사용했다. "방금 한 동작을 또 하는 건지"를 체크하는 용도이기 때문에 0.1초는 적절한 값이라 생각했다. 반면 이 값을 프레임 단위(1/60 = 0.0167초)로 줄이면 부동소수점 오차와 YouTube API의 `setInterval` 폴링 간격(250ms) 때문에 오탐이 빈번하게 발생한다.

그래서 중복 seek 방지에도 같은 epsilon을 적용했다.

```typescript
// 0.1초 이내의 seek 요청은 무시
if (lastSeekTarget !== null && Math.abs(time - lastSeekTarget) < 0.1) {
  return;
}
```

YouTube IFrame API는 `seekTo()` 호출 후 실제로 해당 시점에 도달하기까지 지연이 있다. 그 사이에 같은 위치로 반복 seek가 발생하면 플레이어가 불안정해진다. epsilon 범위 내의 요청을 무시함으로써 이 문제를 방지했다.

## 근본적 한계

epsilon 비교는 우회책이지 완벽한 해결책은 아니다. 웹 비디오에서 프레임 단위 100% 정확도는 현재 브라우저 아키텍처에서 달성할 수 없다.

`requestVideoFrameCallback` API는 비디오가 새 프레임을 그릴 때마다 콜백을 실행해주는 API다. 이 콜백에서 제공하는 `metadata.mediaTime`은 `currentTime`보다 정밀도가 높다. `currentTime`이 오디오 재생 시계를 기준으로 시간을 반환하는 반면, `mediaTime`은 실제 프레임의 원본 타임스탬프(PTS)를 직접 가져오기 때문이다.

하지만 이것도 여전히 float 기반이다. 그리고 프레임은 컴포지터 스레드에서 그려지기 때문에, JavaScript에서 콜백을 받는 시점과 실제 화면에 프레임이 나타나는 시점 사이에 1 vsync(약 16ms) 정도의 차이가 존재한다.

결국 웹 비디오 환경에서 타임스탬프를 비교해야 한다면, 정확한 일치가 아니라 "어디까지 허용할 것인가"를 용도에 맞게 결정해야 한다. 중복 클릭 판별과 반복 seek 방지라는 용도에서 0.1초는 충분히 합리적인 선택이었다.

## 참고 자료

- [WebKit Bug #52697: Frame accurate seeking isn't always accurate](https://bugs.webkit.org/show_bug.cgi?id=52697)
- [W3C Media & Entertainment Issue #4: Frame accurate seeking](https://github.com/w3c/media-and-entertainment/issues/4)
- [Dolby OptiView: Frame Accurate Seeking](https://optiview.dolby.com/docs/theoplayer/knowledge-base/playback/frame-accurate-seeking/)
- [web.dev: requestVideoFrameCallback](https://web.dev/articles/requestvideoframecallback-rvfc)
- [AWS: GOPs Explained](https://aws.amazon.com/blogs/media/part-1-back-to-basics-gops-explained/)


currentTime, 부동소수점, epsilon 비교

웹 비디오에서 프레임 단위 정밀도의 한계

시지프의 돌을 굴리며

2025년 하반기(7~12월) 회고


## 들어가며

포토부스 키오스크 행사 중 서버가 멈췄다. 참가자가 사진을 찍으면 AI 보정을 거쳐 결과물을 받는 구조였고, AI 요청이 쌓이면서 서비스 전체가 응답을 못 하게 됐다. 백엔드 담당자가 없는 상황이라 무작정 EC2를 재시작하면 같은 상황이 반복될 수 있었고, 일단 CloudWatch 로그부터 열었다.

## 로그 따라 원인 추적하기

### T+0s - 요청 폭주

가장 먼저 눈에 띈 것은 AI 서버 헬스체크 로그가 초당 여러 건씩 반복되고 있다는 점이었다.

```text
00:00.094 [http-nio-8080-exec-6] INFO
  AI Server is already running. Checking instance tags for potential scale-out.
00:00.374 [http-nio-8080-exec-2] INFO
  AI Server is already running. Checking instance tags for potential scale-out.
00:00.394 [http-nio-8080-exec-4] INFO
  AI Server is already running. Checking instance tags for potential scale-out.
```

AI 처리 요청도 계속 들어오고 있었다. 문제는 이 요청들이 처리를 완료하지 못하고 쌓이고 있었다는 것이다.

### T+1m 43s - 커넥션 누수 감지

약 2분 뒤, HikariCP(커넥션 풀 관리 라이브러리)의 하우스키퍼가 경고를 올렸다.

```text
01:43.527 [HikariPool-1 housekeeper] WARN
  Connection leak detection triggered for org.mariadb.jdbc.Connection@4a2f7c81
  on thread http-nio-8080-exec-8, stack trace follows
java.lang.Exception: Apparent connection leak detected
    ...
    at com.example.media.service.MediaService.uploadImage(MediaService.java:63)
    at com.example.media.controller.PhotoController.requestAi(PhotoController.java:107)
```

HikariCP는 커넥션을 빌려간 뒤 일정 시간이 지나도 반환되지 않으면 "Apparent connection leak detected"라는 경고를 띄운다. 스택 트레이스는 `PhotoController.requestAi`에서 시작된 호출이 `MediaService.uploadImage`에서 커넥션을 붙들고 있다는 것을 가리키고 있었다.

### T+1m 47s - NullPointerException 연쇄

몇 초 뒤, 전혀 다른 스레드에서 에러가 터지기 시작했다.

```text
01:46.922 [reactor-http-nio-3] ERROR ai image upload error
java.lang.NullPointerException: Cannot read the array length because "b" is null
    at java.base/java.io.FileOutputStream.write(FileOutputStream.java:336)
    at com.example.media.service.MediaService.uploadAiImage(MediaService.java:81)
    at com.example.media.service.AiResponseHandler.handleAiResponse(AiResponseHandler.java:39)
    at com.example.media.service.AiServerClient.lambda$sendAiRequest$2(AiServerClient.java:58)
```

그리고 바로 이어서,

```text
01:46.922 [reactor-http-nio-3] ERROR
  AI request failed: a7f3b2c9-4d1e-4856-9f02-8c5a3b1e7d42
org.springframework.web.reactive.function.client.WebClientResponseException$GatewayTimeout:
  504 Gateway Timeout from POST http://ai-server/api/process
```

AI 서버가 504(게이트웨이 타임아웃)를 반환하고 있었다. 요청이 몰리자 AI 서버가 처리를 감당하지 못하고 지연된 것이다. 이상한 건 같은 타임스탬프, 같은 스레드(`reactor-http-nio-3`)에서 504와 NPE가 동시에 찍히고 있다는 점이었다. 두 에러가 같은 요청 체인 안에서 엮여 있다는 뜻이었다.

### T+2m 28s - 커넥션 풀 완전 고갈

누수가 반복되면서 결국 풀이 바닥났다.

```text
02:27.853 [HikariPool-1 connection adder] WARN
  Error: 1040-08004: Too many connections
```

에러 코드 `1040-08004`는 DB 서버의 `max_connections` 한계에 도달했다는 의미다. HikariCP 풀이 바닥난 것에 이어 DB 서버 자체가 더 이상 새 연결을 받지 않는 단계까지 간 것이다. 이 시점부터는 AI 보정 요청뿐 아니라 같은 DB를 쓰는 모든 기능이 동시에 멈췄다.

## 코드 들여다보기

로그만으로는 504가 어떻게 NPE로 이어지는지 설명되지 않아 실제 코드를 따라가봐야 했다.

### AI 요청 흐름

이 서비스는 Spring Boot의 `DeferredResult`로 AI 서버 호출을 비동기 처리하고 있었다. `DeferredResult`는 JavaScript의 `Promise`와 비슷한 개념으로, "나중에 값이 채워질 빈 응답 객체"를 먼저 반환하고 실제 응답은 나중에 다른 스레드가 채워 넣는 패턴이다. 긴 외부 API 호출을 기다리는 동안 워커 스레드가 점유되는 걸 피하기 위한 구조다.

대략 이런 모양이다.

```java
// DeferredResult 비동기 패턴 (일반 형태)
var deferred = new DeferredResult<Response>(timeoutMs);

// 응답이 오면 실행될 콜백 등록
handler.onResponse(requestId, response -> {
    deferred.setResult(Response.ok(response));
});

// 외부 서비스에 비동기 요청
externalClient.send(request);

return deferred;
```

이 비동기 패턴 자체에는 결함이 없다. 문제는 내부 에러 처리가 **AI 서버 실패 시 `null`을 fallback 값으로 콜백에 전달하는 방식**이었는데, 그 `null`을 받는 쪽에서 체크가 없었다는 점이다. 즉 실패 시나리오가 null이라는 시그널로 표현됐지만, 이 시그널을 처리하는 방어 로직이 빠져 있었다.

### NPE로 이어지는 null 전파 경로

AI 서버가 504를 반환하면 WebClient의 `retrieve()`가 기본 동작으로 이 응답을 `WebClientResponseException$GatewayTimeout`으로 변환한다. reactor 체인의 에러 핸들러가 이를 잡은 뒤, 응답 자리에 `null`을 넣어 내부 응답 핸들러로 전달한다. 여기까지는 "실패 시 null을 시그널로 전달하는" 내부 관행대로 동작한 셈이다.

문제는 이 `null`이 아무 방어 없이 계속 아래로 흘러갔다는 점이다. 응답 핸들러는 받은 값을 그대로 이미지 업로드 메서드에 넘겼고, 업로드 메서드는 이 값을 `FileOutputStream.write(bytes)`에 그대로 전달했다. 대략 이런 흐름이다.

```java
// 단순화된 흐름
public void onResponse(String requestId, byte[] response) {
    mediaService.upload(response);  // null 체크 없이 통과
}

public void upload(byte[] bytes) {
    try (var fos = new FileOutputStream(tempFile)) {
        fos.write(bytes);  // bytes가 null이면 NPE
    }
}
```

`fos.write(null)`에서 NPE가 터진다. 상위의 `try/catch`가 이를 잡아 도메인 예외로 감싸 던지긴 했지만, 진짜 문제는 여기서부터였다.

### 커넥션 누수 발생 원인

NPE를 도메인 예외로 감싸 던지는 것 자체는 방어적으로 보인다. 그런데 왜 커넥션 누수가 발생했을까? 당시 이미지 업로드와 관련된 두 메서드(원본 업로드, AI 결과 업로드)에는 **`@Transactional` 애너테이션이 없었다**. 대략 이런 모양이었다.

```java
// @Transactional 없음
public Media uploadImage(File image) {
    String url = s3Uploader.upload(image);
    return mediaRepository.save(Media.of(url));
}

public Media uploadAiImage(byte[] bytes) {
    File tempFile = saveToTemp(bytes);
    String url = s3Uploader.upload(tempFile);
    return mediaRepository.save(Media.of(url));
}
```

JPA Repository로 DB 저장 로직을 호출하는데도 메서드 자체에는 트랜잭션 경계가 선언돼 있지 않은 상태였다.

`@Transactional`이 없으면 Spring이 이 메서드 호출을 명시적인 트랜잭션 경계로 인식하지 않는다. JPA가 내부적으로 커넥션을 획득하긴 하지만, 트랜잭션·커넥션 생명주기가 Spring의 트랜잭션 관리자에 묶이지 않기 때문에, 예외가 발생했을 때 "롤백 + 커넥션 반환"이 하나의 경계 안에서 자동으로 이뤄지지 않는다.

여기에 AI 요청 엔드포인트가 `DeferredResult`로 응답을 기다리는 비동기 구조라는 점이 겹치면서, 워커 스레드가 AI 응답 동안 물려 있는 사이 업로드 메서드에서 획득한 커넥션의 반환 시점이 불분명해진다. NPE가 터질 때마다 커넥션 하나가 깔끔하게 반환되지 못한 채 남고, 요청이 반복되면서 누수가 누적됐다.

```mermaid
sequenceDiagram
    autonumber
    participant C as Client
    participant W as Worker
    participant P as DB Pool
    participant AI as AI Server

    C->>W: AI 보정 요청
    W->>P: 커넥션 획득 (업로드)
    P-->>W: connection
    Note over W,P: @Transactional 없음<br/>반환 시점 불분명
    W->>AI: 비동기 요청
    W-->>C: DeferredResult 반환 (대기 중)
    Note over W,AI: 응답 대기 (수십 초)
    AI-->>W: 504
    Note over W: 응답 처리 중 NPE → 예외
    Note over P: 커넥션 반환 실패 → 누수
```

결과적으로 `@Transactional`이 없어서 예외가 나도 커넥션이 안 돌아오는 구조를 만들었고, AI 서버 지연이 트리거가 되어 누수가 빠르게 쌓였다. HikariCP가 감지해 경고를 던졌고, pool 사이즈 30이 빠르게 소진되면서 "Too many connections" 상태에 이르렀다.

여기까지가 현장에서 로그와 코드를 보며 추정한 범위였다. "`@Transactional`이 없어서 커넥션이 안 돌아온다"는 가정으로 수정했을 때 실제로 문제가 풀렸지만, 정확한 메커니즘까지 파고들 여유는 현장에 없었다.

## 해결 방식

### 1. null 체크 추가

응답 핸들러와 컨트롤러 콜백 두 곳에 null 체크를 넣었다. 응답 핸들러는 업로드 메서드를 호출하기 전에 null이면 즉시 리턴해서 NPE 경로를 막고, 컨트롤러 콜백은 그래도 null이 도달하면 클라이언트에 503을 반환한다.

```java
// 응답 핸들러
public void onResponse(String requestId, byte[] response) {
    Consumer<byte[]> callback = callbacks.remove(requestId);
    if (callback == null) return;

    if (response == null) {
        callback.accept(null);
        return;
    }

    try {
        mediaService.upload(response);
        callback.accept(response);
    } catch (Exception e) {
        callback.accept(null);
    }
}

// 컨트롤러 콜백
handler.onResponse(requestId, response -> {
    if (response == null) {
        deferred.setErrorResult(
            Response.status(SERVICE_UNAVAILABLE).body("AI 서버가 응답하지 않습니다.")
        );
    } else {
        deferred.setResult(Response.ok(response));
    }
});
```

### 2. 업로드 메서드에 `@Transactional` 추가

이미지 업로드 관련 두 메서드에 `@Transactional`을 붙여서, Spring이 이 호출들을 명시적인 트랜잭션 경계로 관리하도록 했다.

```java
@Transactional
public Media uploadImage(...) { ... }

@Transactional
public Media uploadAiImage(...) { ... }
```

이렇게 하면 메서드 실행 도중 예외가 발생해도 Spring의 트랜잭션 관리자가 롤백을 수행하면서 커넥션을 확실히 반환한다. 비동기 플로우에서 예외가 어떻게 튀든 커넥션 생명주기가 메서드 경계 안에 고정된다. 앞선 null 체크가 있어도 이게 없으면 비슷한 다른 예외가 터질 때 같은 누수가 재발할 수 있다.

### 3. HikariCP 풀 사이즈 증가

위 두 가지가 근본 픽스지만, 비슷한 부하가 다시 올 때를 대비해 풀 사이즈 자체도 늘렸다. 해결이라기보단 버퍼 확보에 가깝다.

```yaml
hikari:
  maximum-pool-size: 50
  minimum-idle: 20
```

수정 후 코드를 EC2에 배포하고, 서버를 재시작했다.

## OSIV가 만든 함정

이 글을 쓰면서 당시에 수정했던 부분들을 조금 더 파보았는데, 핵심은 Spring Boot의 OSIV 기본 설정에 있었다.

OSIV(Open Session In View)는 HTTP 요청 하나에 JPA 세션(`EntityManager`) 하나를 유지하는 설정이다. 요청이 끝날 때 세션이 닫히고 DB 커넥션도 풀로 돌아간다. 동기 요청에서는 문제없지만, `DeferredResult` 같은 비동기 구조에서는 **HTTP 요청이 "완료"로 처리되는 시점이 AI 응답이 올 때까지 늦춰진다**. 그 사이 DB 커넥션이 요청에 계속 묶여 있게 되는 거다. HikariCP 설정의 `leak-detection-threshold: 60000`(60초)이 이 시점을 감지해서 누수 경고를 띄웠다.

비유하자면 DB 커넥션은 렌터카와 같다. `@Transactional`이 없으면 여행(요청) 시작에 차를 빌려서 5분 운전(DB 저장) 후 식당에서 2시간(AI 응답 대기) 동안 주차장에 세워두고 여행이 끝나야 반납한다. `@Transactional`이 있으면 운전이 필요한 5분 동안만 빌렸다가 바로 반납하고, 식당에서 기다리는 동안 차는 다른 사람이 쓸 수 있다.

|                        | `@Transactional` 없음       | `@Transactional` 있음      |
| ---------------------- | --------------------------- | -------------------------- |
| 커넥션 잡는 시점       | 요청 시작                   | 업로드 메서드 시작         |
| 커넥션 반환 시점       | AI 응답 올 때까지 (수십 초) | 메서드 끝나면 즉시 (몇 ms) |
| 커넥션 점유 시간       | 수십 초                     | 몇 밀리초                  |
| 풀 30개로 버틸 수 있나 | 못 버팀 (고갈)              | 충분함                     |

`@Transactional`을 붙이면 Spring은 그 메서드가 DB 작업 구간이라는 걸 인식하고, 메서드가 시작될 때 커넥션을 잡았다가 끝나면 바로 반환한다. `@Transactional`이 없으면 이 구간이 불명확해서 커넥션이 요청이 끝날 때까지 물려 있게 된다. 결국 `@Transactional` 추가의 진짜 효과는 **커넥션을 물고 있는 시간을 수십 초에서 몇 밀리초로 줄인 것**이었다.

사실 더 근본적인 해법은 `spring.jpa.open-in-view=false`로 OSIV 자체를 끄는 것이다. 다만 당시에는 OSIV의 존재 자체를 몰랐고, `@Transactional`을 붙여서 문제가 해결되니 거기서 멈췄다. OSIV를 끄는 게 더 나은 선택이라는 것을 정리하면서 알게 되었다.

## 정리

- AI 서버가 504를 반환하자 `retrieve()`가 기본 동작으로 예외를 던졌고, reactor 에러 핸들러가 그 자리에 null을 넣어 응답 처리 함수로 전달했다. 응답 처리 함수가 null 체크 없이 업로드 메서드로 그대로 흘려보내면서 `FileOutputStream.write(null)`에서 NPE가 터졌다
- 여기에 업로드 메서드의 `@Transactional` 부재가 결합되어, 예외 시 커넥션 반환이 깔끔하게 이뤄지지 않으면서 HikariCP 풀이 고갈됐다. 현장에선 이 수준까지 추정하고 `@Transactional` 추가로 급한 불을 껐다
- 고침은 세 가지로 정리됐다. 응답 핸들러와 컨트롤러 콜백 두 곳에 null 체크, 업로드 메서드에 `@Transactional`, HikariCP 풀 30 → 50
- 후에 다시 들여다보니 Spring Boot 기본 활성화된 **OSIV**와 비동기 `DeferredResult`의 조합이 원인이었다. OSIV가 요청이 끝날 때까지 커넥션을 물고 있는데, 비동기 요청은 AI 응답이 올 때까지 "끝나지 않아서" 커넥션이 수십 초 동안 반환되지 않았다. `@Transactional`을 붙이면 메서드 단위로 커넥션을 잡았다 반환하기 때문에 점유 시간이 수십 초에서 몇 밀리초로 줄어든 것이 실제 효과였다
- 프론트엔드 개발자라도 CloudWatch 로그와 스택 트레이스를 읽을 수 있으면 백엔드 장애의 원인 체인을 추적할 수 있다. 다만 현장에서 급히 내린 결론이 항상 완전하지는 않을 수 있다


AI 요청 지연이 DB 커넥션 누수로 이어진 과정

커넥션 풀이 고갈되기까지

## 개요

드로잉 기능을 만들고 나서 뿌듯했던 시간은 짧았다. QA를 돌리는데 창 크기를 바꾸는 순간 드로잉이 전부 어긋났다. 사각형은 비디오 밖으로 튀어나가고, 펜 스트로크는 엉뚱한 위치에 떠 있었다. 여러 방식으로 고쳐봤지만 임시방편을 반복했고, 결국 좌표계를 처음부터 다시 생각해야 했다.

## 화면 좌표를 그대로 쓰면

Konva에서 Stage는 캔버스 전체를 감싸는 최상위 컨테이너다. react-konva에서는 `<Stage>` 컴포넌트를 쓰면 된다.

```tsx
<Stage width={1920} height={1080}>
  <Layer>
    <Line points={[0, 0, 100, 100]} stroke="red" />
  </Layer>
</Stage>
```

내부적으로는 `<Stage>`가 div 안에 `<canvas>` 요소를 자동으로 생성한다.

```html

<div>
  <div class="konvajs-content">
    <canvas width="1920" height="1080"></canvas>
  </div>
</div>
```

`<canvas>` 태그를 직접 만들 필요 없이, `width`와 `height`를 props로 넘기면 Konva가 알아서 캔버스를 생성하고 그 위에 올라가는 모든 도형의 렌더링을 관할한다.

이 Stage의 크기를 화면에 맞추고, 마우스 좌표를 그대로 저장했다.

```typescript
const handleMouseDown = (e: Konva.KonvaEventObject<MouseEvent>) => {
  const pos = e.target.getStage()?.getPointerPosition();
  if (!pos) return;

  const newStroke: DrawingStroke = {
    tool: selectedTool,
    points: [pos.x, pos.y], // 화면 픽셀 좌표 그대로 저장
    color: drawingToolConfig.color,
    strokeWidth: drawingToolConfig.strokeWidth,
    id: generateId(),
  };

  addStroke(newStroke);
};
```

예를 들어 1920x1080 화면에서 `(960, 540)`에 점을 찍으면, 그 좌표가 그대로 서버에 저장된다. 화면 크기와 좌표가 1:1로 대응하는 상태다. 문제는 화면 크기가 변할 때 벌어진다.

창 크기를 1280x720으로 줄이면 화면은 줄어드는데, 좌표 `(960, 540)`은 그대로다. 1280 안에 960이 들어가긴 하지만, 비디오 위에 정확히 겹쳐야 하는 드로잉이 비디오와 어긋나기 시작한다.

## 일단 scale로

우선 현재 화면 크기를 원본 크기로 나눠서 scale을 계산하고, 이 값을 `providedScale`이라는 props로 드로잉 컴포넌트에 전달하는 방식으로 고쳐봤다. 드로잉 컴포넌트는 자기가 scale을 계산하는 게 아니라, 외부에서 받은 값을 그대로 쓴다.

```typescript
if (providedScale !== undefined) {
  calculatedScale = providedScale;
}
```

1920x1080 화면에서 그린 드로잉을 1280x720 화면에서 열면, 1280 / 1920 = 0.67이 scale이 된다. 이 값을 렌더링에 적용하면 드로잉이 비율에 맞게 축소된다. 화면을 줄였다 늘렸다 해도 scale이 따라가니까, 당장은 드로잉이 비디오와 정확히 겹쳤다.

## 다시 고민

며칠 뒤 같은 버그가 다시 올라왔다. 이번에는 "창 크기를 변경한 후 페이지를 나갔다가 다시 들어오면" 드로잉이 틀어진다는 것이었다.

원인을 추적해보니, `providedScale`이 현재 화면 크기 기준으로 계산된 값이라는 게 문제였다. 1920x1080 화면에서 1280x720으로 줄인 상태에서 scale이 0.67로 계산된다. 여기까지는 맞다. 하지만 이 상태에서 페이지를 나갔다가 다시 들어오면, 1280x720이 "새로운 기준"이 된다. scale이 1.0으로 리셋되고, 원본 1920x1080 기준으로 저장된 좌표와 맞지 않게 된다.

scale의 기준은 "현재 화면"이 아니라 "드로잉이 처음 그려졌을 때의 크기"여야 한다는 걸 깨달았다.

## 화면 크기 != 좌표

한 발짝 물러서서 문제를 정리해봤다. scale로 보정하면 당장은 맞지만, 페이지를 새로 열면 기준이 바뀌어서 깨진다. 그러면 근본적으로 왜 scale이 필요한 건가? 화면 크기가 바뀌는데 좌표는 안 바뀌기 때문이다. 결국 "화면에 보이는 크기"와 "좌표가 기록되는 크기"는 원래 별개의 개념인데, 이걸 하나로 취급한 게 원인이었다.

**표시 공간(Display Space)**은 캔버스가 화면에 보이는 크기다. 브라우저 창을 줄이면 표시 공간도 줄어든다. **좌표 공간(Coordinate Space)**은 드로잉이 기록되는 내부 좌표계다. 사용자가 `(960, 540)`에 점을 찍었을 때, 이 좌표가 속하는 공간이다.

SVG에서는 이 두 공간이 처음부터 분리되어 있다.

```html
<svg width="600" height="400" viewBox="0 0 1200 800"></svg>
```

`width`/`height`가 표시 공간을, `viewBox`가 좌표 공간을 정의한다. 두 값이 다르면 SVG가 알아서 스케일링한다. 구글 맵에서 특정 지역을 줌인하면 지도의 좌표는 그대로인데 화면에 보이는 영역만 달라지는 것과 같은 원리다.

Canvas API에는 `viewBox` 같은 개념이 없다. `canvas.width`를 바꾸면 화면에 보이는 크기와 내부 좌표계가 동시에 바뀐다. 표시 공간과 좌표 공간이 항상 1:1로 묶여 있는 것이다. 그래서 직접 분리해야 했다.

![excalidraw: 표시 공간과 좌표 공간 — 화면이 줄어들면 같은 좌표가 다른 위치에 렌더링된다](/images/posts/drawing-resize-coordinate/display-vs-coordinate-space.png)

## 기준점을 고정하기

드로잉 데이터를 서버에 저장할 때 이미 `width`, `height`를 함께 저장하고 있었다. 드로잉이 그려진 시점의 캔버스 크기, 즉 좌표 공간의 크기다.

읽기 모드에서 scale을 계산할 때 이 값을 기준으로 바꿨다. 수정 전에는 외부에서 받은 `providedScale`을 우선으로 사용했다.

```typescript
if (providedScale !== undefined) {
  calculatedScale = providedScale;
} else if (containerSize && drawingData?.data) { ... }
```

수정 후에는 저장된 원본 크기를 우선으로 바꿨다.

```typescript
if (containerSize && drawingData?.data) {
  const parsedData = JSON.parse(drawingData.data);
  if (parsedData.width && parsedData.height) {
    const scaleX = containerSize.width / parsedData.width;
    const scaleY = containerSize.height / parsedData.height;
    calculatedScale = Math.min(scaleX, scaleY);
  }
} else if (providedScale !== undefined) {
  calculatedScale = providedScale; // fallback
}
```

if 문의 순서를 바꾼 것뿐이지만, "현재 표시 공간 / 원본 좌표 공간"으로 scale을 계산한다는 점에서 의미가 크다. 표시 공간이 어떻게 바뀌든, 좌표 공간(원본 크기)은 드로잉 데이터에 고정되어 있으니까 항상 정확한 비율이 나온다.

`Math.min`을 쓰는 이유는 가로세로 비율을 유지하기 위해서다. 원본이 1920x1080인데 현재 화면이 1600x720이면, scaleX는 0.83이고 scaleY는 0.67이 된다. 만약 가로는 0.83, 세로는 0.67로 따로 적용하면 동그란 원이 옆으로 늘어난 타원이 된다. `Math.min(0.83, 0.67)` = 0.67을 가로세로 둘 다에 적용하면 비율이 유지된다. 대신 가로에 약간 여백이 생기는데, SVG의 `preserveAspectRatio="meet"`가 하는 일과 동일하다.

## 아직 저장 전인 경우

서버에 저장된 데이터에 원본 크기가 있으니까 읽기 모드는 해결됐다. 하지만 편집 모드에서는 아직 저장 전이라 원본 크기를 직접 관리해야 했다.

편집 중에는 화면 크기가 수시로 바뀔 수 있는데, 그때마다 원본 크기를 기억하고 scale을 다시 계산해야 한다. 이 로직을 `useDrawingAutoScale` 훅으로 분리했다. 처음 로드된 크기를 state에 고정하고, 이후 크기가 변하면 비율만 재계산한다.

```typescript
export function useDrawingAutoScale(currentSize: Size | null) {
  const [originalSize, setOriginalSize] = useState<Size | null>(null);
  const [scale, setScale] = useState(1);

  useEffect(() => {
    if (!currentSize) return;

    if (!originalSize) {
      setOriginalSize(currentSize); // 처음 크기를 좌표 공간으로 고정
      setScale(1);
      return;
    }

    setScale(calculateScale(currentSize, originalSize));
  }, [currentSize, originalSize]);

  return { pageSize: originalSize || currentSize, scale };
}
```

## 크기 변화 감지하기

"크기가 변하는 걸" 감지하는 것도 문제였다. 처음에는 `window.resize` 이벤트를 썼는데, 이건 브라우저 창 크기만 감지한다. 사이드바를 열고 닫으면 비디오 컨테이너 크기가 바뀌는데, 브라우저 창 크기 자체는 변하지 않기 때문에 `resize` 이벤트는 발생하지 않는다. `ResizeObserver`로 바꿔서 해결했다.

`ResizeObserver`는 특정 DOM 요소의 크기 변화를 감지하는 브라우저 API다. `window.resize`가 브라우저 창 전체만 보는 반면, `ResizeObserver`는 지정한 요소의 크기가 바뀔 때마다 콜백을 실행한다. CSS 레이아웃 변화, 사이드바 여닫기, 컨테이너 크기 변동 등을 모두 감지할 수 있다.

```typescript
useEffect(() => {
  const container = containerRef.current;
  if (!container) return;

  const resizeObserver = new ResizeObserver(() => {
    calculateVideoSize();
  });

  resizeObserver.observe(container);
  return () => resizeObserver.disconnect();
}, [calculateVideoSize]);
```

유튜브 임베드에서는 한 가지 더 복잡했다. 대부분의 유튜브 영상이 16:9 비율이기 때문에, 컨테이너가 넓적해도 iframe은 16:9에 맞춰 작아진다. 드로잉 영역을 iframe에 정확히 겹치려면 컨테이너 크기에서 실제 iframe 크기를 역산해야 했다. 예를 들어 컨테이너가 1200x500이면, 가로 기준 1200 / 16 = 75, 세로 기준 500 / 9 = 55.5가 되고, 작은 쪽인 55.5를 기준으로 16 * 55.5 = 888, 9 * 55.5 = 500이 실제 iframe 크기가 된다.

```typescript
const calculateIframeSize = useCallback(() => {
  const container = containerRef.current;
  if (!container) return;

  const rect = container.getBoundingClientRect();
  const xRatio = rect.width / 16;
  const yRatio = rect.height / 9;
  const maxRatio = Math.min(xRatio, yRatio);

  setIframeSize({
    width: Math.floor(16 * maxRatio),
    height: Math.floor(9 * maxRatio),
  });
}, []);
```

## 텍스트

도형과 펜 스트로크는 Konva Layer에 `scaleX`, `scaleY`를 적용하면 일괄 처리된다. 좌표 공간 분리가 잘 되는 것이다. 그런데 텍스트에서 같은 문제가 다시 터졌다.

텍스트를 저장할 때 width/height를 기록하는 코드에서 `stage.width()`를 쓰고 있었다. 텍스트의 크기를 Stage에서 가져오는 게 자연스러워 보였기 때문이다. 하지만 `stage.width()`는 표시 공간의 크기를 반환한다.

```typescript
// As-is
const width = stage.width();
const height = stage.height();
```

좌표는 좌표 공간(원본) 기준으로 저장하고 있었는데, width/height만 표시 공간의 값을 쓰고 있었다. 두 공간이 다시 섞인 것이다.

그래서 아래와 같이 좌표 공간(원본 크기) 기준으로 저장하도록 수정했다.

```typescript
// To-be
const width = originalWidth ?? stage.width();
const height = originalHeight ?? stage.height();
```

`originalWidth`는 `useDrawingAutoScale` 훅에서 처음 로드 시 고정해둔 원본 크기다. `stage.width()`가 아닌 이 값을 쓰면 화면 크기가 바뀌어도 항상 좌표 공간 기준으로 저장된다.

텍스트 입력 시 보이는 크기도 문제였다.

```tsx
// As-is
<input style={{ fontSize: "16px", position: "absolute", left: x, top: y }} value={text} />
```

CSS input에 `fontSize: 16px`를 넣으면 표시 공간 기준의 16px가 렌더링된다. 하지만 Konva Text로 확정할 때는 좌표 공간 기준으로 그려지니까 크기가 달라졌다. CSS와 Canvas는 서로 다른 좌표 체계를 쓰고 있었던 것이다.

결국 CSS input 방식을 포기하고, hidden input으로 키보드 입력만 받고 화면에 보이는 건 Konva Text가 담당하게 바꿨다.

```tsx
// To-be
<input style={{ opacity: 0 }} value={text} />
<Text x={x} y={y} text={text} fontSize={16} />
```

하나의 렌더링 시스템 안에서 통일해 크기 불일치가 사라졌다.

## 정리

- 화면 좌표를 그대로 저장하면 화면 크기가 바뀔 때 드로잉이 어긋난다.
- 외부에서 scale을 전달하는 방식은 기준이 바뀌면 같이 깨진다.
- 표시 공간(화면에 보이는 크기)과 좌표 공간(드로잉이 기록되는 좌표계)을 분리해야 한다.
- scale 기준은 "현재 화면"이 아니라 "드로잉이 처음 그려졌을 때의 크기"로 고정한다.
- SVG는 `viewBox`로 이 분리를 언어 차원에서 지원하지만, Canvas는 직접 구현해야 한다.
- 하나의 드로잉 안에서 두 공간을 섞으면 같은 문제가 반복된다. (텍스트의 `stage.width()`, CSS와 Canvas의 좌표 체계 차이)

## 참고

- [MDN — SVG viewBox](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/viewBox)
- [MDN — SVG preserveAspectRatio](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/preserveAspectRatio)
- [MDN — ResizeObserver](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver)
- [react-konva](https://konvajs.org/docs/react/)

좌표계와 스케일링 삽질기

화면 리사이징으로 인한 드로잉 어긋남 해결하기


## React Server Component란


React Server Component(RSC)는 서버에서 렌더링되는 React 컴포넌트다. Next.js App Router는 기본적으로 모든 컴포넌트를 Server Component로 취급한다.


기존 React 앱은 모든 컴포넌트가 브라우저에서 실행되었다. Server Component는 서버에서 렌더링을 완료한 뒤 결과만 클라이언트로 보낸다. 이를 통해 JavaScript 번들 크기를 줄이고 초기 로딩 속도를 개선할 수 있다.


## 왜 필요한가


기존 React 앱에서는 데이터를 가져오기 위해 다음과 같은 과정을 거친다.

1. 브라우저가 빈 HTML을 받는다
2. JavaScript 번들을 다운로드하고 실행한다
3. 컴포넌트가 마운트되면 `useEffect`로 API를 호출한다
4. 데이터를 받아서 화면을 업데이트한다

이 과정에서 사용자는 로딩 상태를 보게 되고, JavaScript 번들 크기가 커질수록 초기 로딩이 느려진다.


Server Component는 이 문제를 해결한다. 서버에서 데이터를 가져오고 렌더링까지 완료한 뒤 결과만 보내므로, 브라우저는 즉시 컨텐츠를 표시할 수 있다.


## Server Component의 장점


Server Component는 다음과 같은 장점을 제공한다.

- 데이터 소스에 가까운 위치에서 데이터를 가져온다. 서버는 데이터베이스나 내부 API와 같은 네트워크에 있으므로 데이터 조회가 빠르다.
- **클라이언트로 전송하는 JavaScript 크기를 줄인다.** 서버에서만 실행되는 코드는 브라우저로 보내지 않는다.
- 초기 페이지 로딩이 빠르다. HTML이 서버에서 생성되어 오므로 First Contentful Paint가 개선된다.
- 보안이 강화된다. API 키나 토큰 같은 민감한 정보를 서버에만 두고 사용할 수 있다.

## Server Component의 특징


Server Component에서는 다음과 같은 작업을 할 수 있다.


```typescript
import { db } from '@/lib/database'

export default async function ProductList() {
  // 데이터베이스 직접 조회
  const products = await db.query('SELECT * FROM products')

  return (
    <ul>
      {products.map(product => (
        <li key={product.id}>{product.name}</li>
      ))}
    </ul>
  )
}
```


위 코드에서 컴포넌트를 `async` 함수로 선언하고 데이터베이스를 직접 조회한다. 이 코드는 서버에서만 실행되므로 데이터베이스 연결 정보가 클라이언트에 노출되지 않는다.


Server Component는 컴포넌트 함수 자체를 `async`로 만들 수 있다. 별도의 데이터 페칭 함수 없이 컴포넌트 내부에서 바로 비동기 작업을 수행할 수 있다.


## Server Component의 제약사항


Server Component는 서버에서만 실행되기 때문에 클라이언트 전용 기능을 사용할 수 없다. 다음과 같은 것들은 Server Component에서 사용할 수 없다.

- 상태 관리 훅: `useState`, `useReducer`
- 생명주기 훅: `useEffect`, `useLayoutEffect`
- 이벤트 핸들러: `onClick`, `onChange`
- 브라우저 전용 API: `window`, `localStorage`, `document`
- 사용자 정의 훅: 위 기능들을 사용하는 커스텀 훅
- React Context: `useContext`

예를 들어 Server Component에서 `useEffect`를 사용하려고 하면 다음과 같은 에러가 발생한다.


```plain text
Error: useEffect only works in Client Components. Add the "use client" directive at the top of the file to use it.
```


이런 기능이 필요하다면 해당 컴포넌트를 Client Component로 만들어야 한다. 파일 최상단에 `'use client'`를 추가하면 된다.


```typescript
// 에러 발생
export default function ProductList() {
  useEffect(() => {
    console.log('마운트됨')
  }, [])

  return <div>상품 목록</div>
}
```


```typescript
// ✓ 정상 작동
'use client'

export default function ProductList() {
  useEffect(() => {
    console.log('마운트됨')
  }, [])

  return <div>상품 목록</div>
}
```


Server Component는 HTML을 생성하는 데 집중하고, 인터랙션이 필요한 부분은 Client Component로 분리하는 것이 권장된다.


## Client Component란


하지만 모든 것을 Server Component로 만들 수는 없다. 사용자와의 상호작용, 상태 관리, 브라우저 API 사용 등은 클라이언트에서만 가능하다.


Client Component는 브라우저에서 실행되는 React 컴포넌트다. 다음과 같은 기능을 사용할 때는 Client Component가 필요하다.

- `useState`, `useReducer` 같은 상태 관리
- `useEffect`, `useLayoutEffect` 같은 생명주기 훅
- `onClick`, `onChange` 같은 이벤트 핸들러
- `window`, `localStorage` 같은 브라우저 전용 API
- 사용자 정의 훅

## 'use client' 디렉티브


Client Component를 만들려면 파일 최상단에 `'use client'` 디렉티브를 추가한다.


```typescript
'use client'

import { useState } from 'react'

export default function LikeButton() {
  const [likes, setLikes] = useState(0)

  return (
    <button onClick={() => setLikes(likes + 1)}>
      좋아요 {likes}
    </button>
  )
}
```


`'use client'`는 서버와 클라이언트 코드 사이의 경계를 선언한다. 이 디렉티브가 있는 파일과 그 파일이 import하는 모든 모듈은 클라이언트 번들에 포함된다.


`'use client'`를 추가하지 않으면 기본적으로 Server Component로 동작한다. Next.js App Router는 Server Component를 기본값으로 사용한다.


## 언제 무엇을 사용할지


다음 표는 어떤 상황에 어떤 컴포넌트를 사용해야 하는지 정리한 것이다.


| 작업                               | Server Component | Client Component |
| -------------------------------- | ---------------- | ---------------- |
| 데이터 가져오기                         | ✓                |                  |
| 백엔드 리소스 직접 접근                    | ✓                |                  |
| 민감한 정보를 서버에 보관                   | ✓                |                  |
| 큰 의존성을 서버에 유지                    | ✓                |                  |
| 상태 관리 (`useState`, `useReducer`) |                  | ✓                |
| 생명주기 훅 (`useEffect`)             |                  | ✓                |
| 이벤트 핸들러                          |                  | ✓                |
| 브라우저 전용 API                      |                  | ✓                |
| 사용자 정의 훅                         |                  | ✓                |


기본적으로 Server Component를 사용하고, 인터랙션이 필요한 부분만 Client Component로 분리하는 것이 권장된다.


## Server Component와 Client Component 조합하기


Server Component와 Client Component는 함께 사용할 수 있다.


### Server Component에서 Client Component로 데이터 전달하기


Server Component는 Client Component에 props로 데이터를 전달할 수 있다. 단, props는 직렬화 가능한 값이어야 한다.


```typescript
// app/page.tsx (Server Component)
import LikeButton from './like-button'

export default async function PostPage({ params }) {
  const post = await getPost(params.id)

  return (
    <article>
      <h1>{post.title}</h1>
      <p>{post.content}</p>
      <LikeButton initialLikes={post.likes} />
    </article>
  )
}
```


```typescript
// app/like-button.tsx (Client Component)
'use client'

import { useState } from 'react'

export default function LikeButton({ initialLikes }) {
  const [likes, setLikes] = useState(initialLikes)

  return (
    <button onClick={() => setLikes(likes + 1)}>
      좋아요 {likes}
    </button>
  )
}
```


위 코드에서 Server Component인 `PostPage`는 서버에서 포스트 데이터를 가져온다. 그리고 초기 좋아요 수를 `LikeButton`에 전달한다. `LikeButton`은 Client Component이므로 브라우저에서 상태를 관리하며 사용자의 클릭에 반응한다.


### Client Component 안에 Server Component 넣기


Client Component는 직접적으로 Server Component를 import할 수 없다. 하지만 `children` prop을 통해 Server Component를 받을 수 있다.


```typescript
// app/modal.tsx (Client Component)
'use client'

export default function Modal({ children }) {
  return (
    <div className="modal">
      {children}
    </div>
  )
}
```


```typescript
// app/page.tsx (Server Component)
import Modal from './modal'
import ServerContent from './server-content'

export default function Page() {
  return (
    <Modal>
      <ServerContent />
    </Modal>
  )
}
```


위 패턴에서 `Modal`은 Client Component지만 `children`으로 무엇을 받을지는 모른다. `ServerContent`는 Server Component로서 서버에서 렌더링된다. `Modal`은 단지 렌더링된 결과를 받아서 표시할 뿐이다.


이 패턴을 사용하면 Client Component와 Server Component를 독립적으로 렌더링할 수 있다. Client Component가 재렌더링되어도 Server Component는 서버에서 이미 렌더링되었기 때문에 다시 렌더링되지 않는다.


## 주의사항


### Client Component는 양쪽에서 실행된다


Server Component는 서버에서만 실행되지만, Client Component는 서버와 클라이언트 양쪽에서 실행된다.

- 서버: 초기 HTML 생성(사전 렌더링)을 위해 1번 실행
- 클라이언트: 하이드레이션을 위해 1번 실행

따라서 Client Component에는 브라우저 전용 API(`window`, `localStorage` 등)를 바로 사용하면 안 된다. 서버에서 실행될 때 에러가 발생한다. `useEffect` 안에서 사용하거나 조건부로 체크해야 한다.


```typescript
'use client'

export default function MyComponent() {
  // 에러: 서버에서 실행 시 window가 없음
  const width = window.innerWidth

  // useEffect는 클라이언트에서만 실행됨
  useEffect(() => {
    const width = window.innerWidth
  }, [])
}
```


### Client Component에서 Server Component를 import할 수 없다


Client Component는 다른 Client Component만 직접 import할 수 있다. Server Component를 사용하려면 `children`이나 props로 받아야 한다.


```typescript
// 불가능
'use client'
import ServerComponent from './server-component'

export default function ClientComponent() {
  return <ServerComponent />
}
```


```typescript
// children으로 받기
'use client'

export default function ClientComponent({ children }) {
  return <div>{children}</div>
}
```


### 직렬화 가능한 값만 전달할 수 있다


Server Component에서 Client Component로 props를 전달할 때는 직렬화 가능한 값만 보낼 수 있다. 함수, 클래스 인스턴스, Symbol 같은 값은 전달할 수 없다.


```typescript
// 불가능
<ClientComponent
  onClick={() => {}}  // 함수 전달 불가
  date={new Date()}   // Date 객체 전달 불가
/>

// 가능
<ClientComponent
  count={42}              // 숫자
  name="hello"            // 문자열
  data={{ id: 1 }}        // 객체
  items={[1, 2, 3]}       // 배열
  timestamp="2024-01-01"  // ISO 문자열
/>
```


이는 서버에서 컴포넌트를 렌더링한 결과를 JSON 형태로 클라이언트에 전송하기 때문이다. JSON으로 변환할 수 없는 값은 전달할 수 없다.


### 컴포넌트 계층 구조 설계


Client Component를 최대한 말단에 배치하는 것이 좋다. 상위에 Client Component가 있으면 그 하위의 모든 컴포넌트가 JavaScript 번들에 포함되어 용량이 커진다.


```typescript
// 비효율적인 구조
'use client'

export default function Page() {
  const [open, setOpen] = useState(false)

  return (
    <div>
      <Header />        {/* JavaScript 번들에 포함 */}
      <Content />       {/* JavaScript 번들에 포함 */}
      <Footer />        {/* JavaScript 번들에 포함 */}
      <Modal open={open} setOpen={setOpen} />
    </div>
  )
}
```


위 코드는 `Modal`의 상태 관리 때문에 전체를 Client Component로 만들었다. 이렇게 하면 `Header`, `Content`, `Footer` 같은 정적 컴포넌트까지 모두 JavaScript 번들에 포함되어 파일 크기가 커진다.


```typescript
// 효율적인 구조
export default function Page() {
  return (
    <div>
      <Header />        {/* Server Component */}
      <Content />       {/* Server Component */}
      <Footer />        {/* Server Component */}
      <ModalButton />   {/* Client Component */}
    </div>
  )
}
```


```typescript
// modal-button.tsx
'use client'

export default function ModalButton() {
  const [open, setOpen] = useState(false)

  return (
    <>
      <button onClick={() => setOpen(true)}>열기</button>
      <Modal open={open} setOpen={setOpen} />
    </>
  )
}
```


위 코드는 상태가 필요한 부분만 Client Component로 분리했다. `Header`, `Content`, `Footer`는 Server Component로 남아있어 JavaScript 번들에 포함되지 않는다. 이렇게 하면 번들 크기가 줄어들고 Time to Interactive(TTI)가 개선된다.


**핵심은 인터랙션이 필요한 최소한의 부분만 Client Component로 만드는 것이다.** 페이지 전체를 Client Component로 만들지 말고, 버튼이나 입력 폼처럼 실제로 상호작용이 필요한 부분만 분리한다.


## 참고 자료

- [Next.js 공식 문서 - Server Components](https://nextjs.org/docs/app/building-your-application/rendering/server-components)
- [Next.js 공식 문서 - Client Components](https://nextjs.org/docs/app/building-your-application/rendering/client-components)
- [Next.js 공식 문서 - Composition Patterns](https://nextjs.org/docs/app/building-your-application/rendering/composition-patterns)


서버에서 렌더링하고 JavaScript 번들 줄이기

React Server Component


## 개요

비디오 피드백 협업 도구를 만들면서 영상 위에 드로잉 기능이 필요했다. 펜, 사각형, 원, 화살표, 텍스트 5가지 도구를 지원해야 했고, Undo/Redo와 개별 스트로크 관리도 필요했다. Canvas API로 충분할 줄 알았는데, 막상 구현에 들어가니 Canvas만으로는 해결할 수 없는 근본적인 한계가 있었다.

## 비트맵과 씬 그래프

본격적으로 들어가기 전에, 이 글에서 계속 등장하는 두 개념을 먼저 짚고 가자.

![excalidraw: 비트맵과 벡터 비교](/images/posts/why-konva-over-canvas/bitmap-concept.png)

비트맵(Bitmap)은 픽셀의 격자다. 가로 1920개, 세로 1080개의 점이 모여 하나의 이미지를 구성한다. 각 점은 색상 값만 가지고 있을 뿐, "이 점이 사각형의 일부인지 원의 일부인지"는 알지 못한다. 사진 파일(PNG, JPG)이 대표적인 비트맵이다. Canvas API가 바로 이 방식으로 동작한다. 화면에 무언가를 그리면 결과는 픽셀 덩어리로 남고, 그 픽셀이 어떤 도형에서 왔는지는 기록하지 않는다.

씬 그래프(Scene Graph)는 화면에 표시할 객체들을 트리 구조로 관리하는 모델이다. "빨간 원이 좌표 (100, 150)에 반지름 40으로 존재한다"는 정보를 JavaScript 객체로 들고 있다. 렌더링할 때는 이 객체들을 순회하면서 비트맵에 그리지만, 객체 자체는 메모리에 남아있다. 그래서 "세 번째 도형을 삭제하라"는 명령이 가능하다. Konva가 Canvas 위에 씬 그래프를 얹는 방식이다.

핵심은 Konva가 비트맵을 대체하는 게 아니라는 점이다. 내부적으로는 똑같이 Canvas API로 픽셀을 찍는다. 다만 그 위에 객체 모델을 얹어서, 비트맵만으로는 할 수 없는 개별 도형 관리와 이벤트 처리를 가능하게 한다.

## Canvas API의 근본적인 한계

Canvas는 비트맵 기반이다. `context.stroke()`를 호출하는 순간 픽셀이 캔버스에 새겨지고, 그 이후로는 어떤 도형이었는지에 대한 정보가 사라진다.

실제로 구현하면서 부딪힌 문제를 보자.

### 도형 하나를 지우려면

SVG라면 해당 DOM 노드를 `removeChild()`하면 끝이다. 하지만 Canvas에는 지울 "노드"가 없다. 할 수 있는 건 전체 캔버스를 `clearRect()`로 지운 다음, 나머지 도형을 처음부터 다시 그리는 것뿐이다.

```typescript
// Canvas API로 Undo를 구현하려면,
ctx.clearRect(0, 0, canvas.width, canvas.height);

// 마지막 스트로크를 제외한 나머지를 전부 다시 그려야 한다.
remainingStrokes.forEach((stroke) => drawStroke(ctx, stroke));
```

스트로크가 100개일 때 하나를 지우려고 99개를 다시 그린다. 스트로크가 늘어날수록 Undo 한 번의 비용이 선형으로 증가한다. 거기다 Redo, 중간 스트로크 삭제, 특정 도형만 색상 변경 같은 기능까지 고려하면, 매번 전체를 다시 그리는 방식은 금방 한계에 부딪힌다.

### 특정 도형을 선택하려면

드로잉 도구에서는 특정 스트로크를 선택하거나, 마우스 커서가 도형 위에 있을 때 하이라이트를 보여줘야 할 수 있다. SVG라면 각 요소에 `addEventListener`를 달면 된다. 하지만 Canvas는 하나의 `<canvas>` 요소가 전부다. 이벤트는 캔버스 전체에 걸리고, 클릭 좌표 `(300, 200)`을 받았을 때 그 위치에 어떤 도형이 있는지 알아내는 건 전적으로 개발자 몫이다. 이걸 히트 테스팅(Hit Testing)이라 한다.

직접 구현하려면 도형별로 수식이 다르다.

![excalidraw: 히트 테스팅 수식](/images/posts/why-konva-over-canvas/hit-testing-math.png)

사각형과 원은 그나마 간단하다. 하지만 자유곡선(펜 도구)은? 사용자가 마우스를 움직이며 그린 수백 개의 점으로 이루어진 곡선 위에 마우스가 있는지 판별하려면, 모든 연속된 두 점 사이의 선분과 마우스 좌표 간 거리를 계산해야 한다. 점의 개수를 n이라 하면 `O(n)`이고, 스트로크가 여러 개면 모든 스트로크를 순회해야 한다.

## Konva의 히트 캔버스

Konva는 이 문제를 히트 캔버스(Hit Canvas)로 해결한다. 히트 캔버스란 화면에 보이지 않는 별도의 캔버스를 두고, 그 위에 각 도형을 고유한 색상으로 칠해서 클릭 지점의 픽셀 색상만으로 어떤 도형인지 식별하는 기법이다. 원리는 단순하다.

쉽게 비유하자면, 같은 그림을 두 장 그리는 것과 비슷하다. 한 장은 사용자에게 보여주는 예쁜 그림이고, 다른 한 장은 각 도형에 번호표를 붙인 지도다. 사용자가 그림의 어느 지점을 클릭하면, 뒤에 숨겨둔 지도에서 같은 위치를 찾아 "여기는 3번 도형 영역이군" 하고 바로 알아내는 원리다.

구체적으로는 이렇다. 화면에 보이는 캔버스 뒤에 숨겨진 캔버스를 하나 더 만든다. 이 히트 캔버스에서는 각 도형을 고유한 색상으로 칠한다. 첫 번째 도형은 `#000001`, 두 번째는 `#000002`... 색상 자체가 ID 역할을 하는 셈이다. 사용자가 클릭하면,

1. 클릭 좌표 `(x, y)`에서 히트 캔버스의 픽셀 색상을 `getImageData(x, y, 1, 1)`로 읽는다.
2. 색상 값을 도형 ID로 변환한다.
3. 해당 도형 객체를 반환한다.

![excalidraw: 히트 캔버스 원리](/images/posts/why-konva-over-canvas/hit-canvas.png)

이 방식은 도형의 복잡도와 무관하게 항상 `O(1)`이다. 자유곡선이든 복잡한 다각형이든, 결국 픽셀 하나만 읽으면 된다. 도형이 1000개여도 성능은 동일하다.

## Konva의 씬 그래프 구조

Konva가 단순히 히트 테스팅만 해결하는 건 아니다. Canvas 위에 씬 그래프를 만든다. Stage → Layer → Shape 계층 구조로, 각 도형이 JavaScript 객체로 존재한다.

```text
Stage (최상위 컨테이너)
├── Layer 1 (도형 레이어)
│   ├── Line (펜 스트로크)
│   ├── Rect (사각형)
│   └── Circle (원)
└── Layer 2 (텍스트 레이어)
    └── Text (텍스트)
```

내부적으로는 결국 Canvas API의 `beginPath()`, `stroke()`, `fill()` 등을 호출한다. 하지만 그 위에 객체 모델을 얹었기 때문에, "세 번째 스트로크를 삭제하라"는 명령이 가능해진다. Canvas API만으로는 불가능했던 일이다.

## 그러면 SVG를 쓰면 되지 않나?

처음에는 SVG도 고려했다. DOM 기반이라 이벤트 처리도 쉽고, 개별 요소 삭제도 가능하다. 하지만 SVG를 선택하지 않은 이유가 있다.

SVG는 각 도형이 곧 DOM 노드다. `<rect>`, `<circle>`, `<polyline>` 하나하나가 HTML의 `<div>`와 같은 레벨의 DOM 요소로 존재한다. 도형 10개면 DOM 노드 10개, 100개면 100개다. 자유곡선 하나에 점이 200개면 그 `<polyline>`의 `points` 속성에 400개의 좌표값이 들어간다. 스트로크 50개면 DOM에 50개의 SVG 요소가 존재하고, 하나를 수정할 때마다 브라우저는 전체 레이아웃을 다시 계산한다.

```mermaid
sequenceDiagram
    participant U as 사용자
    participant B as 브라우저
    participant D as SVG DOM
    participant L as 레이아웃 엔진

    U->>D: 세 번째 도형 색상 변경
    D->>B: DOM 변경 감지
    B->>L: 레이아웃 재계산 요청
    L->>L: 50개 SVG 요소 전체 재계산
    L->>B: 리페인트
    B->>U: 화면 갱신
    Note over L: 도형이 늘어날수록<br/>재계산 비용 증가
```

Canvas(와 Konva)는 DOM 노드 하나(`<canvas>`)만 사용한다. 도형이 아무리 많아도 DOM 구조는 변하지 않는다. 브라우저의 레이아웃 엔진에 부하를 주지 않는다.

세 가지 선택지의 트레이드오프를 정리하면 다음과 같다.

|                     | SVG          | Canvas API   | Konva (Canvas 기반) |
| ------------------- | ------------ | ------------ | ------------------- |
| DOM 노드 수         | 도형 수만큼  | 1개          | 1개                 |
| 이벤트 처리         | 네이티브     | 직접 구현    | 히트 캔버스         |
| 개별 도형 관리      | DOM 조작     | 불가         | 씬 그래프           |
| 성능 (도형 많을 때) | 느려짐       | 빠름         | 빠름                |
| 번들 크기           | 0 (네이티브) | 0 (네이티브) | ~150KB              |

만들고 있던 드로잉 도구는 자유곡선이 핵심이고, 사용자가 많이 그릴수록 도형이 늘어난다. SVG는 이 상황에서 성능 문제가 생길 수밖에 없었다. Canvas의 성능은 유지하면서 객체 관리와 이벤트 처리가 가능한 Konva를 선택했다.

## 편집 모드와 읽기 모드의 분리

프로젝트에서 한 가지 더 결정해야 할 것이 있었다. 드로잉을 "편집"하는 화면과 "읽기만" 하는 화면이 따로 존재한다는 점이다. 두 화면의 요구사항이 다르기 때문에 같은 렌더링 방식을 쓸 이유가 없었다.

편집 모드에서는 Konva가 필요하다. 도형을 추가/삭제하고, Undo/Redo를 처리하고, 마우스 이벤트에 반응해야 한다. 씬 그래프 없이는 이런 상호작용이 불가능하다.

읽기 모드에서는 저장된 스트로크 데이터를 화면에 표시만 하면 된다. 상호작용이 없다. 이 경우 Konva의 씬 그래프를 메모리에 올릴 이유가 없다. Canvas API로 한번 쭉 그리면 끝이다.

```typescript
// 읽기 모드: Canvas API 직접 사용
const renderStroke = (ctx: CanvasRenderingContext2D, stroke: StrokeData) => {
  ctx.save();
  ctx.scale(scale, scale);
  ctx.strokeStyle = stroke.color;
  ctx.lineWidth = stroke.strokeWidth;

  if (stroke.type === "pen") {
    ctx.beginPath();
    for (let i = 0; i < stroke.points.length; i += 2) {
      if (i === 0) ctx.moveTo(stroke.points[i], stroke.points[i + 1]);
      else ctx.lineTo(stroke.points[i], stroke.points[i + 1]);
    }
    ctx.stroke();
  }
  // rect, circle, arrow, text도 각각 처리
  ctx.restore();
};
```

이 분리가 특히 중요했던 건 읽기 모드의 드로잉이 댓글마다 하나씩 붙기 때문이다. 댓글이 20개이고 각각 드로잉이 있으면 20개의 캔버스 인스턴스가 생긴다. 전부 Konva로 렌더링하면 씬 그래프 20개가 메모리에 올라간다. Canvas API로 직접 그리면 그릴 때만 컨텍스트를 사용하고, 결과는 비트맵으로 남아서 메모리 부담이 훨씬 적다.

## 정리

Canvas API만으로도 드로잉 도구를 만들 수 있다. 다만 도형 관리, 이벤트 처리, Undo/Redo를 전부 직접 구현해야 한다. Konva는 그 수고를 덜어주되, 읽기 전용처럼 상호작용이 필요 없는 곳에서는 오히려 불필요한 무게가 된다. 그래서 편집 화면에는 Konva를, 읽기 화면에는 Canvas API를 각각 적용했다.


비트맵의 한계와 씬 그래프 도입기

Canvas 위에 Konva 한 겹 얹기


## 개요

Vue로 만든 v1에서는 네이티브 Canvas API로 직접 그리고, `canvas.toDataURL()`로 캔버스를 캡처해서 서버에 저장하는 방식이었다. `toDataURL()`은 캔버스에 현재 그려진 픽셀을 그 순간 PNG로 변환해서 `data:image/png;base64,...` 형태의 문자열로 돌려주는 메서드다. 서버에서 이미지를 가져오는 게 아니라 캔버스의 스크린샷을 찍는 것이다. React로 새로 만드는 v2에서는 스트로크 데이터를 JSON으로 저장하는 방식으로 바꾸려 했는데, 기존에 PNG로 저장된 드로잉도 보여줘야 했기 때문에 두 포맷을 모두 지원해야 했다.

v2에서는 react-konva를 사용했다. Konva는 Canvas를 다루는 바닐라 JS 라이브러리다. React 없이 Konva를 쓰면 명령적으로 하나하나 지시해야 한다.

```typescript
// Konva만 사용 -> 명령적
const line = new Konva.Line({
  points: [0, 0, 100, 100],
  stroke: "red",
});
layer.add(line);
layer.draw();
```

react-konva는 이걸 React 컴포넌트로 감싸서, 선언적으로 쓸 수 있게 해준다.

```tsx
// react-konva 사용 -> 선언적
<Line points={[0, 0, 100, 100]} stroke="red" />
```

react-konva가 내부적으로 `new Konva.Line()` 생성, props 변경 시 `line.points()` 호출, 컴포넌트 제거 시 `line.destroy()` 같은 명령적 작업을 대신 처리한다. 개발자는 원하는 결과만 선언하면 된다.

다만 `stageRef.current.toDataURL()`처럼 ref로 Konva에 직접 접근하면, react-konva의 선언적 흐름을 거치지 않고 Canvas를 즉시 읽는 명령적 호출이 된다. 그리기/Undo/Redo가 일어날 때마다 현재 드로잉 데이터를 상위 컴포넌트에 전달하는 구조였고, v1 하위 호환을 위해 `stage.toDataURL()`로 PNG 캡처하는 경로도 남아 있었다.

여기서 이상한 버그를 만났다. Undo를 누르면 캔버스에서는 스트로크가 사라지는데, 캡처된 이미지에는 여전히 남아 있었다. 한참을 헤매다가 `setTimeout(0)` 한 줄로 해결했는데, 왜 이게 되는지 이해하기까지가 더 오래 걸렸다.

## 선언적 vs 명령적

이 버그의 근본 원인은 React와 Canvas가 서로 다른 모델로 동작한다는 데 있다.

선언적(Declarative)이란 "무엇을 원하는지"만 말하고 과정은 맡기는 것이다. React가 이 방식이다. `setStrokes([A, B])`를 호출하면 "스트로크가 A, B인 상태를 원해"라고 선언할 뿐, 실제로 DOM에서 어떤 노드를 지우고 어떤 노드를 추가할지는 React가 결정한다. 호출 시점에는 아무 일도 일어나지 않는다.

명령적(Imperative)이란 "어떻게 할지"를 하나하나 지시하는 것이다. Canvas가 이 방식이다. `ctx.clearRect()`로 지우고, `ctx.beginPath()`로 선을 시작하고, `ctx.stroke()`로 그린다. `stage.toDataURL()`을 호출하면 그 순간 캔버스에 그려진 픽셀을 바로 돌려준다. 호출한 시점의 상태가 곧 결과다.

```mermaid
gantt
    dateFormat X
    axisFormat %s
    title 호출 → 결과

    section React
    호출           :a1, 0, 1
    스케줄링       :a2, 1, 3
    화면 반영      :crit, a3, 3, 4

    section Canvas
    호출 → 즉시 반환 :active, b1, 0, 1
```

문제는 이 두 모델을 한 함수 안에서 섞어 쓸 때 생긴다. `setStrokes`(선언적)와 `toDataURL()`(명령적)을 순서대로 호출하면, 선언적 세계에서는 아직 "예약"만 된 상태인데 명령적 세계에서는 "지금 당장" 읽어버린다. 둘 다 선언적이었으면 React가 배치 처리를 알아서 해주고, 둘 다 명령적이었으면 실행 순서가 보장된다. 두 모델이 섞이는 순간 타이밍 간극이 생기고, 따라서 이 타이밍에 버그가 터지게 된 것이다.

## 상태 변경 != 화면 반영

이걸 더 구체적으로 이해하려면 React의 렌더링 파이프라인을 알아야 한다. React 공식 문서에서는 이걸 레스토랑에 비유한다. React는 웨이터, 컴포넌트는 요리사, DOM은 테이블이다.

![excalidraw: React Render 단계 — Component Kitchen에서 Card를 받아오는 장면](/images/posts/settimeout-zero-react-canvas/react-render.png)

`setState`를 호출하는 건 웨이터에게 주문을 넣는 것이다. 주문이 들어갔다고 요리가 바로 나오지는 않는다. React는 주문을 받아서 주방(컴포넌트)에 전달하고, 요리(렌더링 결과)를 받아서 테이블(DOM)에 서빙한다. 이 과정이 세 단계로 나뉜다.

1. **Trigger** — 상태가 변경되어 렌더링이 예약된다.
2. **Render** — 컴포넌트 함수를 호출해서 새로운 UI를 계산한다. 이 단계에서는 DOM을 건드리지 않는다.
3. **Commit** — 계산된 변경 사항을 실제 DOM에 반영한다.

![excalidraw: React Re-render — 상태 변경으로 새로운 Card를 요청하는 장면](/images/posts/settimeout-zero-react-canvas/react-renderer.png)

Commit 이후에도 끝이 아니다. Konva를 쓰는 경우, React가 Commit에서 하는 일은 Konva 컴포넌트(`<Line>`, `<Rect>` 등)에 새 props를 전달하는 것이다. 그러면 Konva가 내부적으로 캔버스에 다시 그린다. 그 다음에야 브라우저가 **Paint**를 수행해서 화면에 픽셀을 찍는다.

![excalidraw: Browser Paint — 브라우저가 최종 결과를 화면에 그리는 장면](/images/posts/settimeout-zero-react-canvas/browser-paint.png)

> 이미지 출처: [React 공식 문서 — Render and Commit](https://react.dev/learn/render-and-commit)

전체 흐름을 정리하면 이렇다.

```mermaid
sequenceDiagram
    participant S as setState
    participant R as React
    participant K as Konva
    participant B as Browser

    S->>R: Trigger — 렌더링 예약
    R->>R: Render — 새 UI 계산
    R->>K: Commit — 새 props 전달
    K->>K: 캔버스 다시 그리기
    K->>B: Paint — 화면에 픽셀 표시

    Note over S,K: toDataURL()은 여기 이후에 호출해야 정확함
```

`toDataURL()`로 정확한 결과를 얻으려면 최소한 Konva가 캔버스를 다시 그린 이후에 호출해야 한다. `setState`를 호출한 시점(Trigger)과 Konva가 캔버스를 업데이트하는 시점 사이에 간격이 있고, 이 간격 안에서 Canvas를 읽으면 이전 상태가 읽힌다.

## 화면에서는 사라졌는데 캡처에는 남아 있다

드로잉 에디터에서 스트로크를 그리거나 Undo/Redo를 할 때마다 현재 캔버스를 이미지로 캡처해서 상위 컴포넌트에 전달해야 했다. Konva의 `stage.toDataURL()`을 호출하면 캔버스를 PNG data URL로 변환할 수 있다.

```typescript
const finishStroke = useCallback(() => {
  addToHistory(strokes);

  if (stageRef.current && onDrawingChange) {
    const dataURL = stageRef.current.toDataURL();
    onDrawingChange(dataURL);
  }
}, [strokes, addToHistory, onDrawingChange]);
```

Undo를 누르면 화면에서는 스트로크가 사라지는데, `onDrawingChange`로 전달되는 이미지에는 아직 남아 있었다. 처음에는 히스토리 로직이 잘못된 줄 알고 한참 디버깅했다.

## 로그 찍기

히스토리를 아무리 살펴봐도 문제가 없었다. 혹시나 해서 `toDataURL()` 직전에 상태를 찍어봤다.

```typescript
console.log("현재 strokes:", strokes.length); // Undo 후: 2개
const dataURL = stageRef.current.toDataURL();
// dataURL 이미지에는 3개짜리 그림이 찍혀 있음
```

`strokes`는 분명 2개인데, 캡처된 이미지에는 3개가 그려져 있었다. 상태(state)와 실제 캔버스에 그려진 그림이 다른 것이다.

`setStrokes`로 상태를 바꿨지만, 그건 Trigger일 뿐이었다. React가 Render → Commit을 거쳐 Konva에 새 props를 전달하고, Konva가 캔버스에 다시 그리는 것은 그 이후에 일어난다. `toDataURL()`은 Trigger 직후에 호출되고 있었으니, 캔버스에는 아직 이전 상태가 그려져 있는 것이다.

```mermaid
sequenceDiagram
    participant H as 이벤트 핸들러
    participant R as React
    participant K as Konva Canvas
    participant T as 태스크 큐

    Note over H,T: 문제 — setTimeout 없이 직접 호출

    H->>R: setStrokes(2개) — 상태 변경 예약
    H->>K: toDataURL() — 아직 3개짜리 캔버스를 캡처
    Note over H: 함수 종료

    R->>R: Render — 새 UI 계산
    R->>K: Commit — 2개짜리 strokes 전달
    K->>K: 캔버스 업데이트 — 비로소 2개만 그려짐
```

## 일단 다음 틱으로

원인은 알겠는데, 어떻게 고칠지가 막막했다. React의 Commit이 끝난 후에 `toDataURL()`을 호출해야 하는데, "Commit이 끝났다"를 직접 알 수 있는 방법이 마땅치 않았다.

그러다 "일단 다음 이벤트 루프 틱으로 밀어보자"는 생각에 `setTimeout(0)`을 넣어봤다.

```typescript
const finishStroke = useCallback(() => {
  addToHistory(strokes);

  setTimeout(() => {
    if (stageRef.current && onDrawingChange) {
      const dataURL = stageRef.current.toDataURL();
      onDrawingChange(dataURL);
    }
  }, 0);
}, [strokes, addToHistory, onDrawingChange]);
```

이렇게 바꾸니 Undo를 눌렀을 때 캡처된 이미지도 정확하게 나왔다. 되긴 됐는데, 왜 되는 건지 정확하게 알지 못해 찜찜했다.

## 이벤트 루프

`setTimeout(fn, 0)`은 "0밀리초 후에 실행"이 아니다. 브라우저 이벤트 루프는 세 단계로 돌아간다.

1. **콜 스택** — 현재 실행 중인 코드를 끝까지 처리한다.
2. **마이크로태스크 큐** — `Promise.then`, React 배치 처리 등이 실행된다.
3. **태스크 큐(macrotask)** — `setTimeout` 콜백 등이 실행된다.

`setTimeout(fn, 0)`의 콜백은 3번 태스크 큐에 들어간다. 0ms라고 해도 1번(현재 코드)과 2번(마이크로태스크)이 전부 끝난 후에야 실행된다. React의 배치 처리는 2번에서 일어나기 때문에, 3번에 있는 `setTimeout` 콜백이 실행되는 시점에는 React가 이미 Render → Commit을 마친 후다.

```mermaid
sequenceDiagram
    participant H as 이벤트 핸들러
    participant R as React
    participant K as Konva Canvas
    participant T as 태스크 큐

    Note over H,T: 해결 — setTimeout(0)으로 다음 틱에 호출

    H->>R: setStrokes(2개) — 상태 변경 예약
    H->>T: setTimeout(callback, 0) — 콜백 등록
    Note over H: 함수 종료, 콜 스택 비워짐

    R->>R: Render — 새 UI 계산
    R->>K: Commit — 새 props 전달
    K->>K: 캔버스 업데이트 (2개만 그려짐)

    Note over T: 배치 처리 완료 후 실행
    T->>K: toDataURL() — 최신 캔버스 캡처
```

핵심은 React의 배치 처리가 콜 스택이 비워진 직후에 마이크로태스크로 실행된다는 것이다. `setTimeout(0)`의 콜백은 태스크 큐(macrotask)에 있기 때문에, 마이크로태스크인 React 배치 처리가 끝난 후에야 실행된다. 그래서 `toDataURL()`이 호출되는 시점에는 캔버스가 이미 최신 상태다.

## 같은 패턴이 여기저기에

`finishStroke`에서 해결하고 나니, 같은 문제가 `undo`, `redo`, `addStroke`에도 전부 있다는 걸 발견했다. "상태를 바꾸고 캔버스를 캡처하는" 모든 곳에서 동일한 타이밍 이슈가 있었다.

```typescript
const undo = useCallback(() => {
  if (historyIndex > 0) {
    const newIndex = historyIndex - 1;
    setStrokes(history[newIndex].strokes);
    setHistoryIndex(newIndex);

    setTimeout(() => {
      if (stageRef.current && onDrawingChange) {
        const dataURL = stageRef.current.toDataURL();
        onDrawingChange(dataURL);
      }
    }, 0);
  }
}, [historyIndex, history, onDrawingChange]);
```

결국 모든 캡처 코드에 `setTimeout(0)`을 넣었다.

## 다른 방법

### useEffect

"상태 변경 후에 뭔가를 실행하고 싶다"면 보통 `useEffect`를 떠올린다.

```typescript
useEffect(() => {
  if (stageRef.current && onDrawingChange) {
    const dataURL = stageRef.current.toDataURL();
    onDrawingChange(dataURL);
  }
}, [strokes]);
```

`strokes`가 바뀔 때마다 캡처하는 방식이다. 동작은 하지만 두 가지 문제가 있었다.

첫째, `useEffect`의 실행 시점이 애매하다. `useEffect`는 Commit 이후 브라우저가 Paint를 마친 다음에 비동기적으로 실행된다. React에서는 이 단계를 Passive Effects라고 부른다. 화면 업데이트를 차단하지 않기 위해 Paint 이후로 미루는 것이다. Mark Erikson의 설명에 따르면 "React가 짧은 timeout을 설정하고, 그것이 만료되면 모든 useEffect를 실행한다." 이 시점에 Konva가 실제로 캔버스에 픽셀을 찍었는지는 보장되지 않는다.

둘째, `strokes`는 마우스 드래그 중에도 `updateLastStroke`로 계속 바뀐다. 그리는 중간에 매 프레임마다 `toDataURL()`이 호출되면 불필요한 캡처가 반복된다. 성능을 직접 측정하지는 않았지만, 확정되지 않은 스트로크를 매번 캡처할 이유는 없었다. `setTimeout(0)`은 `finishStroke` 안에서만 호출되기 때문에, 스트로크가 확정된 시점에서만 캡처가 일어난다.

### flushSync

나중에 찾아보니 `react-dom`에 `flushSync`라는 API가 있었다. 상태 업데이트를 즉시 동기적으로 Commit까지 수행한다. "배치하지 말고 지금 당장 DOM에 반영하라"는 명령이다.

```typescript
import { flushSync } from "react-dom";

flushSync(() => {
  setStrokes(newStrokes);
});
// 이 시점에서 DOM은 이미 업데이트됨
const dataURL = stageRef.current.toDataURL();
```

당시에는 이런 API가 있는지 몰랐다. 나중에 찾아보니 React 공식 문서에서도 "마지막 수단(last resort)"으로 소개하고 있었다. 배치 최적화를 무력화하기 때문에 성능에 영향을 줄 수 있고, 드로잉처럼 빈번한 상태 업데이트가 일어나는 곳에서는 부담이 된다고 생각했다.

### requestAnimationFrame

`requestAnimationFrame`은 브라우저가 다음 화면을 그리기 직전에 콜백을 실행한다. 이후 창 크기 계산 같은 곳에서는 `requestAnimationFrame`으로 바꿨다.

```typescript
requestAnimationFrame(() => {
  calculateVideoSize();
});
```

하지만 `toDataURL()` 캡처 용도에서는 `setTimeout(0)`을 유지했다. `requestAnimationFrame`은 다음 Paint 직전에 실행되는데, 이 시점에 React의 Commit은 완료되었지만 react-konva가 내부적으로 `batchDraw`를 통해 캔버스 드로잉을 비동기 처리하는 경우, 우리가 등록한 콜백이 Konva의 실제 캔버스 드로잉보다 먼저 실행될 수 있기 때문이다.

## React 18에서 달라진 점

한 가지 주의할 점이 있다. React 18에서는 Automatic Batching이 도입됐다. React 17에서는 이벤트 핸들러 내부에서만 배치가 적용됐지만, React 18에서는 `setTimeout`, `Promise.then` 안의 `setState`도 배치된다.

이 프로젝트는 React 18을 사용하고 있었고, `setTimeout(0)` 안에서 `setState`를 호출하는 경우는 없었기 때문에 문제가 되지 않았다. 하지만 만약 `setTimeout(0)` 콜백 안에서 상태를 업데이트하는 패턴을 쓴다면 React 18에서 의도와 다르게 배치될 수 있다.

## 정리

React는 선언적이다. "이 상태일 때 이렇게 보여라"고 선언하면 React가 알아서 그린다. Canvas는 명령적이다. "지금 캔버스에 뭐가 그려져 있지?"를 물으면 그 즉시의 상태를 돌려준다.

이 두 세계를 함께 쓰면 반드시 타이밍 문제를 만난다. `setState`는 주문이고, 캔버스에 그려지는 건 서빙이다. 주문 직후에 테이블을 보면 아직 이전 요리가 놓여 있다.

`setTimeout(0)`은 우아한 해결책이 아니다. 하지만 "React가 서빙을 끝낼 때까지 한 틱 기다린다"는 의도를 명확하게 표현한다. 처음에는 왜 되는지도 모르고 넣었지만, 렌더링 파이프라인을 따져보고 나서야 이게 적절한 해결이라는 확신이 생겼다.

돌아보면 이 버그를 찾는 데 오래 걸린 이유가 하나 더 있다. `DrawingCanvas` 컴포넌트 하나에 히스토리 관리, 이미지 캡처, 스케일 계산이 전부 들어 있었다. 상태를 바꾸는 코드와 캔버스를 읽는 코드가 같은 함수 안에 붙어 있으니, 둘 사이의 타이밍 간극을 의심하기가 어려웠다. 역할이 분리되어 있었다면 "캡처는 상태 반영 이후에 해야 한다"는 걸 구조적으로 더 빨리 알아챘을 것이다.


setState 직후에 toDataURL()을 호출하면 안 되는 이유

setTimeout(0)으로 React와 Canvas 타이밍 맞추기

useMemo, useCallback 없이 자동 최적화되는 React 19

React Compiler 톺아보기

참조 동등성이 리렌더링을 결정하는 방식

왜 React는 객체 비교에 민감할까

몰입과 실험, 기본기의 중요성을 깨달은 한 학기

2025년 3~6월 회고


## 들어가며

블로그에 마크다운을 쓰다 보니 표준 문법만으로는 해결되지 않는 것들이 쌓였다. 이미지 캡션, 수식 렌더링, 한국어 볼드 깨짐까지 성격이 제각각이었다. remark/rehype 파이프라인에 플러그인을 끼워 넣어 이 문제들을 하나씩 해결했다.

## remark/rehype

마크다운을 HTML로 변환하는 라이브러리는 `marked`, `markdown-it` 등 여러 가지가 있다. 이 블로그에서는 `remark`/`rehype` 조합을 사용했다.

블로그에 이미지를 넣다 보니 이미지 아래에 캡션을 달고 싶었다.

![이미지 캡션 예시](/images/posts/blog-dev-5-markdown-pipeline/01-caption-example.webp)

_이미지 아래에 이런 캡션을 자동으로 붙이고 싶었다_

그런데 마크다운에는 표준 캡션 문법이 없다. 그래서 이미지 바로 다음 줄에 이탤릭(`_캡션_`)이 단독으로 오면 캡션으로 인식하는 규칙을 정했다. 이탤릭은 본문에서도 쓰이지만, 이미지 바로 뒤에 단독으로 오는 경우는 거의 캡션 용도뿐이라 충돌할 일이 없었다.

문제는 이 규칙을 어떻게 구현하느냐였다. 마크다운은 문자열이다. 문자열 상태에서 "이미지 뒤에 이탤릭이 오면 캡션으로 감싸라" 같은 조작을 하려면 정규식으로 패턴을 찾아야 한다. 그런데 마크다운에서는 이미지를 링크로 감쌀 수도 있고(`[![alt](img.png)](url)`), 코드 블록 안에 이미지 문법을 그대로 적을 수도 있다.

코드 블록 안의 `![alt](url)`은 이미지가 아니라 설명을 위한 텍스트인데, 정규식은 이 둘을 구분하지 못한다. 이탤릭도 마찬가지다. 캡션용 이탤릭인지, 본문에서 강조하려고 쓴 이탤릭인지 정규식만으로는 문맥을 알 수 없다. 예외 케이스가 늘어날수록 정규식은 점점 복잡해지고 깨지기 쉬워진다.

결국 문자열 상태에서는 문맥을 알 수 없다는 게 근본적인 문제였다. 그래서 마크다운을 문자열이 아니라 트리 구조로 바꿔서 다루는 방법을 찾았다.

![AST Explorer에서 마크다운을 파싱한 결과](/images/posts/blog-dev-5-markdown-pipeline/02-ast-explorer.webp)

_AST Explorer에서 마크다운을 파싱한 결과. 이미지와 캡션이 각각 별도의 paragraph 노드로 분리되어 있다_

파서가 마크다운을 파싱하면서 "이건 이미지 노드", "이건 이탤릭 노드", "이건 코드 블록 안이니까 문법이 아니라 텍스트"를 미리 구분해둔다. 코드 블록 안의 `![alt](url)`은 이미지 노드가 아니라 텍스트 노드로 파싱되어 있으니까 애초에 걸리지 않는다. "이미지 노드를 찾아서 다음 노드가 이탤릭이면 figure로 감싸라"고만 하면 된다.

remark/rehype는 이 변환을 세 단계로 나눈다.

- **remark**: 마크다운 텍스트를 mdast(마크다운 트리)로 파싱한다. remark 플러그인들이 이 트리를 변환한다.
- **remark-rehype**: mdast를 hast(HTML 트리)로 변환하는 플러그인이다. mdast의 마크다운 개념을 HTML 개념으로 매핑한다. `heading` + `depth: 2`는 `h2`가 되고, `emphasis`는 `em`이 되는 식이다.
- **rehype**: hast를 받아 HTML 단계에서 추가 처리를 한다. rehype 플러그인들이 이 단계에서 동작한다.

두 단계로 나누는 이유는, 어떤 문제는 마크다운 단계에서 잡는 게 자연스럽고 어떤 문제는 HTML 단계에서 처리하는 게 자연스럽기 때문이다. CJK(중국어·일본어·한국어 문자) 볼드 보정은 마크다운 트리에서 텍스트 노드를 찾아 변환하는 게 맞고, 수식을 KaTeX HTML로 렌더링하는 건 HTML 트리에서 하는 게 맞다. 각 단계에 플러그인을 끼워넣을 수 있어서, 이런 문제들을 독립된 플러그인으로 분리할 수 있었다.

```mermaid
sequenceDiagram
    participant MD as 마크다운 텍스트
    participant mdast as 마크다운 AST
    participant hast as HTML AST
    participant HTML as HTML 문자열

    MD->>mdast: remark-parse
    mdast->>mdast: remark 플러그인들
    mdast->>hast: remark-rehype
    hast->>hast: rehype 플러그인들
    hast->>HTML: rehype-stringify
```

마크다운 텍스트가 파싱되어 AST가 되고, remark 플러그인들이 그 트리를 변환한 뒤 HTML AST로 넘어간다. rehype 플러그인들이 HTML 단계에서 추가 처리를 하고 최종 HTML 문자열로 직렬화된다.

이 파이프라인을 React에서 쓸 때는 `react-markdown`을 사용한다. 이 라이브러리가 내부적으로 remark/rehype 파이프라인을 돌리면서, 결과물을 React 컴포넌트로 렌더링해 준다. 현재 블로그의 플러그인 구성은 이렇다.

```typescript
<ReactMarkdown
  remarkPlugins={[remarkGfm, remarkMath, remarkMediaCaption, remarkCjkBold]}
  rehypePlugins={[rehypeRaw, rehypeSlug, rehypeKatex]}
  components={{ /* 커스텀 컴포넌트 */ }}
>
  {postData.content}
</ReactMarkdown>
```

각 플러그인이 어떤 문제를 해결하는지 하나씩 살펴보자.

## remark, rehype의 플러그인

### GFM

표준 마크다운(CommonMark, 마크다운 표준 스펙)은 생각보다 지원하는 문법이 적다. 테이블, 취소선, 체크박스 같은 것들은 표준에 없다. `remarkGfm`은 GFM(GitHub Flavored Markdown, GitHub에서 확장한 마크다운 스펙)을 추가해서 이런 문법들을 사용할 수 있게 한다.

| 문법      | 마크다운              | 결과             |
| --------- | --------------------- | ---------------- |
| 테이블    | `\| A \| B \|`        | 표 렌더링        |
| 취소선    | `~~텍스트~~`          | ~~텍스트~~       |
| 작업 목록 | `- [x] 완료`          | 체크박스         |
| 자동 링크 | `https://example.com` | 클릭 가능한 링크 |

GFM 없이는 이런 것들을 전부 raw HTML로 작성해야 한다.

### KaTeX 수식

기술 노트를 쓰다 보면 수학 수식이 필요할 때가 있다. 알고리즘의 시간 복잡도를 $O(n \log n)$으로 표기하거나, 공식을 블록으로 보여주고 싶은 경우다. 처음에는 LaTeX를 떠올렸는데, LaTeX는 논문 조판용 시스템이라 웹에서 쓰기엔 너무 무겁다. KaTeX는 LaTeX 수식 문법을 브라우저에서 빠르게 렌더링하기 위해 만들어진 경량 라이브러리다. 문법은 거의 같으면서 훨씬 가볍다.

`remarkMath`가 `$inline$`과 `$$block$$` 문법을 인식해서 AST 노드로 변환하고, `rehypeKatex`가 그 노드를 KaTeX로 렌더링한다.

```mermaid
sequenceDiagram
    participant MD as $O(n \log n)$
    participant remark as remarkMath
    participant rehype as rehypeKatex
    participant HTML as 렌더링 결과

    MD->>remark: $ 문법 인식
    remark->>remark: math 노드로 변환
    remark->>rehype: mdast → hast
    rehype->>rehype: KaTeX HTML 생성
    rehype->>HTML: 수식 렌더링
```

두 플러그인이 remark 단계와 rehype 단계에서 각각 역할을 나눠 처리하는 구조다.

### 헤딩 ID와 Raw HTML

`rehypeSlug`는 `## 제목`을 `<h2 id="제목">제목</h2>`으로 변환해서 목차(TOC) 클릭 시 해당 헤딩으로 스크롤할 수 있게 해준다. `rehypeRaw`는 마크다운 안에 `<div class="callout">` 같은 raw HTML을 직접 쓸 수 있게 통과시켜 준다. 이 플러그인이 없으면 HTML 태그가 텍스트로 이스케이프되어 그대로 노출된다.

## 이미지 캡션 플러그인 (remarkMediaCaption)

앞서 설명한 이미지 캡션 규칙을 직접 구현한 플러그인이다. 이미지 뒤에 이탤릭이 단독으로 오면 `<figure>` + `<figcaption>`으로 자동 변환한다. 기존 오픈소스 플러그인에는 원하는 동작과 맞는 게 없어서 다른 플러그인과는 다르게 직접 만들게 되었다.

### AST 변환 로직

remark 플러그인은 AST를 입력받아 AST를 반환하는 함수다. 마크다운이 파싱되면 각 요소가 노드로 표현된 트리 구조가 만들어지는데, 이 트리를 순회하면서 원하는 패턴을 찾아 변환하는 것이 플러그인의 역할이다.

```typescript
const remarkMediaCaption: Plugin<[], Root> = () => {
  return (tree: Root) => {
    // 1. AST의 최상위 노드들 순회
    for (let i = 0; i < tree.children.length; i++) {
      const node = tree.children[i];

      // 2. 이미지를 포함한 paragraph 탐색
      if (!isImageParagraph(node)) continue;

      // 3. 바로 다음 노드가 이탤릭(캡션)인지 확인
      const nextNode = tree.children[i + 1];
      const caption = isCaptionParagraph(nextNode);

      // 4. 이미지 + 캡션을 <figure> HTML로 교체
      const html = createFigureHtml(node, caption);
      tree.children.splice(i, caption ? 2 : 1, { type: "html", value: html });
    }
  };
};
```

가독성을 위해 간략하게 작성했지만, 실제 코드는 연속 이미지 그리드나 비디오 처리도 포함한다.

`tree.children`은 AST의 최상위 노드 목록이다. 문단, 헤딩, 코드 블록 등이 이 배열에 하나씩 들어있다. 이 노드들을 순서대로 돌면서 이미지 paragraph를 찾고, 바로 다음 노드가 이탤릭이면 캡션으로 간주한다. 이미지와 캡션을 합쳐서 `<figure>` HTML로 교체하면 변환이 완료된다.

### 이미지 그리드

이미지를 두 장 넣어야 할 때가 있다. 세로로 나열하면 스크롤이 길어지고 비교가 어려운데, 한 행에 나란히 놓으면 훨씬 자연스럽다. 그래서 연속된 이미지가 2개 이상이면 자동으로 그리드 레이아웃으로 묶는 기능도 추가했다.

![excalidraw: 그리드 예시 이미지 1](/images/posts/blog-dev-5-markdown-pipeline/03-grid-1.webp)

![excalidraw: 그리드 예시 이미지 2](/images/posts/blog-dev-5-markdown-pipeline/04-grid-2.webp)

_연속된 이미지가 자동으로 한 행에 나란히 배치된다_

`image-grid-2` 클래스에 CSS Grid를 적용하면 2열 레이아웃이 되고, 이미지가 3개면 `image-grid-3`이 붙어서 3열이 된다. 마크다운에서 이미지를 연속으로 나열하기만 하면 나머지는 자동이다.

## CJK 볼드 보정 플러그인 (remarkCjkBold)

한국어 노트를 작성하다 보면 `**볼드**` 처리가 안 되는 경우가 있었다. 모든 볼드가 깨지는 게 아니라 특정 패턴에서만 발생했다. `**Observable**이라는`은 잘 되는데 `**연산자(operator)**를`은 안 된다. 괄호 뒤에 한국어가 바로 오는 경우에만 깨지는 것 같았는데, 그 당시에는 정확한 원인을 모르고 넘겼었다.

### CommonMark의 flanking delimiter 규칙

원인은 CommonMark 스펙에 있었다. CommonMark는 마크다운의 표준 스펙이고, remark의 파서도 이 스펙을 따른다. CommonMark 파서는 `**`를 볼드로 인식할 때 앞뒤 문자를 검사하는데, 이 검사 규칙을 [flanking delimiter rule](https://spec.commonmark.org/0.31.2/#left-flanking-delimiter-run)이라고 한다.

간단하게 말해서 여는 `**`는 왼쪽에, 닫는 `**`는 오른쪽에 인접한 문자가 특정 조건을 만족해야 한다. 닫는 `**`의 조건은 이렇다.

> 닫는 `**` 바로 앞이 `)` 같은 구두점이면, `**` 바로 뒤에 공백이나 구두점이 와야 한다.

영어에서는 단어 뒤에 공백이 자연스럽게 오기 때문에 이 조건에 걸릴 일이 거의 없다. 하지만 한국어에서는 조사가 바로 붙는다. `**연산자(operator)**를`처럼 닫는 `**` 뒤에 "를", "을", "라고" 같은 조사가 공백 없이 오면 파서가 이걸 볼드의 끝으로 인식하지 못한다.

```markdown
**연산자(operator)**를 제공한다. → )**를 → 볼드 실패
**Observable**이라는 단일 추상화 → e**이 → 볼드 성공 (앞이 알파벳)
**않는** 문제가 발생한다. → 는\*\* → 볼드 성공 (뒤에 공백)
```

결국 닫는 `**` 앞이 `)` + 뒤에 한글이 바로 오는 조합이 문제였다. `**FOUC(Flash of Unstyled Content)**라고`, `**지각적 균일성(perceptual uniformity)**을` 같은 패턴이 전부 해당된다.

### AST 레벨에서 확인

실제로 파서가 `**연산자(operator)**를`을 어떻게 처리하는지 AST로 찍어봤다.

![excalidraw: CJK 볼드가 파싱되지 않은 AST](/images/posts/blog-dev-5-markdown-pipeline/05-cjk-bold-ast.webp)

_볼드 마커가 strong 노드로 분리되지 않고 text 노드의 value 안에 리터럴로 남아있다_

볼드가 제대로 인식되었다면 이렇게 되어야 한다.

```json
{
  "type": "paragraph",
  "children": [
    { "type": "text", "value": "...조합하는 " },
    {
      "type": "strong",
      "children": [{ "type": "text", "value": "연산자(operator)" }]
    },
    { "type": "text", "value": "를 제공한다." }
  ]
}
```

`**`가 strong 노드로 분리되지 않고 텍스트 노드 안에 리터럴 문자열로 남아있었다. 파서 단계에서 이미 "이건 볼드가 아니다"라고 판단한 거라, 파서 자체를 고칠 수는 없었다. 대신 파서 이후 단계에서 후처리하는 방법을 찾아야 했다.

### remarkCjkBold 플러그인 구현

파서 자체를 수정할 수는 없으니, 파서 이후 단계에서 후처리하는 방식을 찾았다. 텍스트 노드를 순회하면서 리터럴로 남아있는 `**...**` 패턴을 찾아 strong 노드로 변환하는 remark 플러그인을 만들었다.

```typescript
const remarkCjkBold: Plugin<[], Root> = () => {
  return (tree: Root) => {
    visit(tree, "text", (node: Text, index, parent) => {
      if (!parent || index === undefined) return;

      // 텍스트 노드에 남아있는 **...** 패턴 탐색
      const regex = /\*\*([^\s*](?:[^*]*[^\s*])?)\*\*/g;
      const matches = [...node.value.matchAll(regex)];

      if (matches.length === 0) return;

      // 텍스트 노드를 분할해서 strong 노드 삽입
      const newChildren: PhrasingContent[] = [];
      let lastIndex = 0;

      for (const match of matches) {
        const startIdx = match.index!;

        if (startIdx > lastIndex) {
          newChildren.push({ type: "text", value: node.value.slice(lastIndex, startIdx) });
        }

        newChildren.push({
          type: "strong",
          children: [{ type: "text", value: match[1] }],
        });

        lastIndex = startIdx + match[0].length;
      }

      if (lastIndex < node.value.length) {
        newChildren.push({ type: "text", value: node.value.slice(lastIndex) });
      }

      parent.children.splice(index, 1, ...newChildren);
    });
  };
};
```

앞서 만든 `remarkMediaCaption`과 같은 패턴이다. AST를 순회하면서 원하는 노드를 찾고, 새로운 노드로 교체한다. 커스텀 플러그인을 만드는 것이 거창해 보일 수 있지만, 결국 "트리에서 패턴 찾기 → 변환"이라는 동일한 구조의 반복이다.

기존 동작을 망가뜨리지 않을까 걱정했는데, 확인해보니 괜찮았다. 정상적으로 파싱된 볼드는 이미 strong 노드가 되어 있어서 텍스트 노드 안에 `**`가 남아있지 않다. 이 플러그인은 파서가 놓친 케이스, 즉 텍스트 노드 안에 리터럴로 남은 `**...**`만 잡아준다.

이 문제를 해결하다 보니 오픈소스로 플러그인을 배포하면 어떨까 싶었다. 내가 겪은 문제라면 분명 다른 사람도 겪었을 것 같아서 찾아보니 역시 [remark-cjk-friendly](https://www.npmjs.com/package/remark-cjk-friendly)라는 플러그인이 이미 있었다. [CommonMark 이슈 #650](https://talk.commonmark.org/t/cjk-and-bold-tags-possibly-complex-issue/4034)에서 7년 넘게 논의되고 있는 문제이기도 하다.

remark-cjk-friendly는 파서 레벨에서 토크나이저 규칙 자체를 수정하는 방식이라, 내 플러그인처럼 후처리로 잡는 것보다 근본적인 해결이다. 내가 직접 만든 플러그인은 블로그에서 마주친 케이스는 잘 잡아주고 있지만, 모든 경우의 수를 커버하지는 못할 수 있다는 약간의 아쉬움이 들었다.

## 커스텀 컴포넌트

지금까지는 마크다운이 HTML로 변환되는 과정에 개입하는 플러그인을 살펴봤다. 하지만 변환된 HTML이 React 컴포넌트로 렌더링되는 마지막 단계에서도 커스터마이징할 수 있다. `react-markdown`의 `components` prop을 사용하면, 특정 HTML 요소를 기본 태그 대신 커스텀 React 컴포넌트로 대체할 수 있다.

### 이미지 모달

블로그 글에 포함된 스크린샷이나 다이어그램은 원본 크기로 보고 싶을 때가 있다. 이미지를 클릭하면 확대된 모달이 열리도록 `img` 태그를 커스텀 컴포넌트로 교체했다.

```typescript
components={{
  img: ({ src, alt, ...props }) => (
    <img
      src={src}
      alt={alt || ""}
      className="cursor-pointer transition-transform hover:scale-[1.02]"
      onClick={() => handleImageClick(src || "", alt || "")}
    />
  ),
}}
```

마크다운에서 `![alt](/src.png)`로 이미지를 삽입하면, 기본 `<img>` 태그 대신 클릭 이벤트가 달린 컴포넌트가 렌더링된다. 호버 시 살짝 커지는 효과를 넣어서 클릭 가능하다는 힌트를 준다.

### 테이블 래퍼

GFM으로 테이블을 쓸 수 있게 됐지만, 열이 많은 테이블은 모바일에서 화면을 넘친다. 테이블 자체는 건드리지 않고, 감싸는 `div`를 추가해서 가로 스크롤을 적용했다.

```typescript
table: ({ children, ...props }) => (
  <div className="table-wrapper">
    <table {...props}>{children}</table>
  </div>
),
```

`table-wrapper`에 `overflow-x: auto`를 적용하면 테이블이 넘칠 때만 스크롤바가 나타난다. 페이지 전체가 흔들리지 않고 테이블 영역만 스크롤된다.

### 외부 링크 처리

블로그 글에는 참고 자료나 공식 문서 링크를 자주 달게 된다. 외부 링크를 클릭했을 때 현재 탭에서 이동해버리면 읽던 글을 잃게 되니까, 외부 링크는 새 탭에서 열리도록 했다. 동시에 보안을 위해 `rel="noopener noreferrer"`도 자동으로 추가했다.

```typescript
a: ({ href, children, ...props }) => {
  const isExternal = href?.startsWith("http") && !href?.includes(SITE_URL);
  return (
    <a
      href={href}
      {...props}
      {...(isExternal ? {
        target: "_blank",
        rel: "noopener noreferrer"
      } : {})}
    >
      {children}
    </a>
  );
},
```

내부 링크(`/posts/...`)는 기존대로 같은 탭에서 이동하고, 외부 링크만 새 탭으로 열린다. 마크다운을 쓸 때 매번 `target="_blank"`를 수동으로 붙일 필요가 없다.

## 정리

처음에는 "이미지 캡션 하나 넣으려는데 이렇게까지 해야 하나" 싶었다. 하지만 문제가 하나씩 추가될 때마다 플러그인 구조의 가치를 체감했다. CJK 볼드 문제가 터졌을 때도 기존 파이프라인을 건드리지 않고 플러그인 하나를 추가하는 것만으로 해결할 수 있었다.

현재 파이프라인에 올라가 있는 플러그인들이다.

- GFM 확장 문법 지원
- 수학 수식 렌더링 (KaTeX)
- 이미지 캡션/그리드 자동 처리
- CJK 볼드 보정
- 헤딩 자동 id 부여 (TOC 연동)
- 코드 블록 Shiki 하이라이팅 (다음 편에서 다룸)


이미지 캡션, 수식, CJK 볼드 처리하기

remark/rehype 플러그인으로 마크다운의 한계 넘기


## 들어가며

기술 블로그에서 코드 하이라이팅이 깨지면 독자의 시선이 내용보다 먼저 오류에 걸린다. TypeScript 제네릭이나 데코레이터 같은 복잡한 문법을 정확하게 표현하는 것이 중요해서 라이브러리 선택에 신경을 썼다. 이 글에서는 VS Code와 동일한 토크나이저를 사용하는 Shiki를 빌드 타임에 적용한 과정을 정리한다.

## Shiki를 선택한 이유

코드 하이라이팅 라이브러리는 크게 두 종류다.

**Prism/highlight.js**: 정규식 기반이다. 가볍고 빠르다. 이 블로그도 처음엔 Prism을 썼는데, TypeScript 코드가 부정확하게 하이라이팅되는 경우를 몇 번 겪었다. 원인이 궁금해서 Prism 레포를 보니 2020년부터 열려 있는 이슈가 있었다.

https://github.com/PrismJS/prism/issues/2594

제네릭과 JSX 태그의 문법이 충돌해서 특정 패턴의 코드를 만나면 그 뒤의 하이라이팅이 풀리는 버그였다. 2020년에 임시 우회 PR이 머지됐지만 제목부터 "Temporary workaround"가 붙어 있고, 이슈는 머지 후에도 의도적으로 열린 채 남아 있다. 메인테이너도 코멘트에서 "정규식 기반 접근으로는 완벽히 고치기 어렵다"고 인정했다. Prism v1은 v2 개발 때문에 유지보수 모드로 돌아가 보안 패치만 받고 있어서, 근본 수정도 기대하기 어려운 상황이었다. 그래서 Shiki로 갈아탔다.

**Shiki**: TextMate 문법 기반이다. TextMate는 2004년에 나온 macOS 텍스트 에디터인데, 이 에디터가 만든 XML 기반 문법 정의 포맷이 이후 VS Code에 채택되면서 사실상 업계 표준이 됐다. Shiki는 VS Code와 동일한 grammar 파일을 써서 토큰화 결과가 동일하다. 정확도가 높고, VS Code 테마도 그대로 쓸 수 있다.

## 빌드 타임 하이라이팅

1. Shiki는 정확하지만 약 1MB의 WASM 엔진과 언어별 grammar·테마를 전부 로드해야 해서 런타임에 돌리면 무겁다.
2. 블로그 글은 내용이 빌드 시점에 고정되므로 매번 색칠할 필요가 없다.
3. 빌드 타임에 색칠을 끝내고 독자에겐 결과 HTML만 내려주면 된다.

Next.js에서 이걸 구현하는 건 세 조각으로 나뉜다. **`getStaticProps`** 가 진입점으로 "언제" 할지(빌드 타임에)를 정하고, **`extractAndHighlightCodeBlocks`** 함수가 "무엇을 어떻게" 색칠할지(코드 블록 찾고 Shiki 호출)를 담당하고, **페이지 컴포넌트**가 결과를 DOM에 주입한다.

`getStaticProps`는 Next.js가 빌드할 때 딱 한 번 실행하는 함수다. 여기서 색칠까지 끝내두면 그 결과가 정적 HTML에 담긴 채로 독자에게 전달된다.

```typescript
export const getStaticProps: GetStaticProps = async ({ params }) => {
  const postData = await getPostData(params.id);
  const codeBlocks = await extractAndHighlightCodeBlocks(postData.content);
  return { props: { postData, codeBlocks } };
};
```

실제 추출/하이라이팅 로직은 `extractAndHighlightCodeBlocks` 함수로 분리했다. 이 함수는 마크다운 원문을 스캔해서 각 코드 블록을 찾고, 각각 `highlightCode`를 호출한 결과를 `block-${index}` 키로 저장한 맵을 반환한다. 페이지 컴포넌트는 이 맵을 받아서 `dangerouslySetInnerHTML`로 렌더링한다. 단, Mermaid 다이어그램은 빌드 타임 처리 대상에서 빼고 클라이언트에서 별도 컴포넌트로 렌더링한다.

## 다크모드 대응

Shiki는 테마를 한 번에 하나만 적용할 수 있다. 다크모드를 지원하려면 두 가지 방법이 있다.

1. CSS 변수로 색상 오버라이드
2. 라이트/다크 HTML을 둘 다 생성

Shiki 테마의 색상 체계를 CSS 변수로 바꾸는 건 번거롭고 테마를 바꿀 때마다 같은 작업을 반복해야 한다. 반면 라이트/다크 HTML을 빌드 타임에 둘 다 생성해두면 Tailwind `dark:` 접두사로 간단히 토글할 수 있어서 2번을 선택했다.

```typescript
function isValidLanguage(lang: string): boolean {
  return /^[a-zA-Z0-9#+-]+$/.test(lang);
}

export async function highlightCode(code: string, language?: string): Promise<string> {
  // 유효하지 않은 언어명은 "text"로 fallback
  const safeLang = language && isValidLanguage(language) ? language : "text";

  const lightHtml = await codeToHtml(code, {
    lang: safeLang,
    theme: "github-light",
  });

  const darkHtml = await codeToHtml(code, {
    lang: safeLang,
    theme: "github-dark",
  });

  return `
    <div class="light-theme block dark:hidden">${lightHtml}</div>
    <div class="dark-theme hidden dark:block">${darkHtml}</div>
  `;
}
```

`isValidLanguage`는 언어명에 알파벳·숫자·`-`·`#`·`+`만 허용하는 1차 방어선이다. 이상한 값이 들어오면 `"text"`로 fallback해서 Shiki가 에러를 던지기 전에 막는다. HTML이 두 배가 되지만 빌드 타임에 생성되므로 런타임 비용은 없다.

## 커스텀 CodeBlock 컴포넌트

하이라이팅된 HTML을 감싸는 래퍼 컴포넌트다. 상단 바에 언어명과 복사 버튼을 붙였다.

```typescript
import { useState } from "react";
import { Check, Copy } from "lucide-react";

export default function CodeBlock({ language, children, html }: CodeBlockProps) {
  const [copied, setCopied] = useState(false);

  const handleCopy = async () => {
    await navigator.clipboard.writeText(children);
    setCopied(true);
    setTimeout(() => setCopied(false), 2000);
  };

  return (
    <div>
      <div>
        <span>{language || "text"}</span>
        <button onClick={handleCopy}>
          {copied ? <><Check size={16} /> Copied!</> : <><Copy size={16} /> Copy</>}
        </button>
      </div>
      <div dangerouslySetInnerHTML={{ __html: html || "" }} />
    </div>
  );
}
```

`children`에는 원본 코드 문자열이, `html`에는 빌드 타임에 만들어둔 하이라이팅 HTML이 들어있다. 복사 버튼을 누르면 하이라이팅 HTML이 아니라 원본 코드(`children`)를 클립보드에 넣는다.

## react-markdown 연동

`react-markdown`의 `components` prop에서 `code` 요소를 커스터마이징한다. 마크다운 파서가 발견한 코드 블록마다 이 컴포넌트가 호출되는데, 여기서 미리 만들어둔 `codeBlocks` 맵에서 해당 블록의 HTML을 꺼내 `CodeBlock`에 넘긴다.

```typescript
components={{
  pre: ({ children }) => <>{children}</>,
  code: ({ inline, className, children }) => {
    const match = /language-(\w+)/.exec(className || "");

    if (!inline && match) {
      const code = String(children).replace(/\n$/, "");
      const language = match[1];

      // Mermaid는 클라이언트에서 렌더링
      if (language === "mermaid") {
        return <MermaidBlock chart={code} />;
      }

      const blockKey = `block-${codeBlockIndex++}`;
      const html = codeBlocks[blockKey] || "";

      return (
        <CodeBlock language={language} html={html}>
          {code}
        </CodeBlock>
      );
    }

    return <code className={className}>{children}</code>;
  },
}}
```

`pre` 태그는 그냥 children을 반환한다. `react-markdown`이 `pre > code` 구조로 렌더링하는데, `pre`를 없애고 `code`만 커스터마이징하면 된다. 인라인 코드는 기본 스타일을 유지하고, 코드 블록만 `CodeBlock` 컴포넌트로 대체한다.

Mermaid는 빌드 타임에 스킵했기 때문에 여기서도 별도 분기가 필요하다. `extractAndHighlightCodeBlocks`에서 스킵한 것과 이 분기가 한 쌍으로 동작한다. 한쪽만 있으면 Mermaid 블록이 엉뚱하게 렌더링된다.

## 정리

- Shiki는 TextMate 문법 기반으로 VS Code와 동일한 토크나이저를 사용해 복잡한 TypeScript 문법도 정확하게 하이라이팅한다
- WASM 번들이 무거워서 런타임에 돌리기 부담스럽다. `extractAndHighlightCodeBlocks` 함수로 빌드 타임에 미리 처리하고 `getStaticProps`에서 호출한다
- 언어명 정규화, Mermaid 스킵, try/catch fallback을 한 함수 안에 묶어서 빌드가 깨지지 않도록 방어한다
- 다크모드는 라이트/다크 HTML을 둘 다 생성해두고 Tailwind `dark:` 접두사로 토글한다
- `react-markdown`의 `code` 컴포넌트를 커스터마이징해 미리 만들어둔 HTML을 `dangerouslySetInnerHTML`로 주입한다. Mermaid는 별도 분기로 클라이언트에서 렌더링한다


빌드 타임 하이라이팅으로 런타임 부담 없애기

Shiki로 빌드 타임 코드 하이라이팅 구현하기


## 들어가며

지금은 Obsidian으로 글을 쓰지만, 한동안 Notion을 SSoT로 두고 마크다운으로 동기화하는 구조로 블로그를 운영했다. SSoT(Single Source of Truth, 단일 진실 공급원)는 원본 데이터가 한 곳에만 존재하고 나머지는 거기서 파생된다는 개념인데, Notion에 글을 쓰면 그게 원본이고 레포의 마크다운 파일은 동기화된 복사본이었다.

그때 가장 골치 아팠던 부분은 이미지였다. Notion 이미지 URL은 만료 시간이 있어서 그대로 두면 글이 깨졌다. 여러 선택지를 두고 고민한 끝에, 동기화 시점에 이미지를 다운로드해서 최적화하고 영구적인 URL로 재업로드하는 파이프라인을 만드는 쪽으로 결정했다.

지금은 레거시가 된 코드지만 그때 고민했던 것들은 지금도 유효하다고 생각해서 정리하게 되었다. 어떤 라이브러리를 쓸지, 이미지를 어디에 저장할지, 같은 글을 여러 번 동기화해도 안전하게 만들려면 무엇이 필요한지 등이다.

## Notion 이미지 URL 문제

Notion 이미지 URL은 이렇게 생겼다.

```text
https://prod-files-secure.s3.us-west-2.amazonaws.com/...?X-Amz-Expires=3600...
```

이 링크에는 두 가지 문제가 있다.

1. 만료 시간이 있다. URL에 서명이 포함되어 있어서 일정 시간이 지나면 접근할 수 없다.
2. 원본 크기 그대로다. 4K 스크린샷을 올리면 4K 그대로 로드된다.

## 어떤 선택지가 있었나

만료되는 URL을 다루는 방법은 여러 가지였다.

1. **빌드 타임에 매번 새 URL 받기**: Notion API는 페이지를 fetch할 때마다 새 signed URL을 발급한다. 이론적으로는 빌드할 때마다 다시 받으면 만료 문제가 사라진다. 하지만 빌드 시간이 글 수에 비례해서 늘어나고, Notion API에 장애가 생기면 빌드 자체가 깨진다. 무엇보다 원본 크기 문제는 그대로 남는다.
2. **이미지 프록시 서비스(Cloudinary 등)에 올리기**: 원본 URL을 던지면 캐시·최적화·CDN까지 알아서 처리해준다. 가장 빠른 길이지만 외부 서비스 비용과 의존성이 추가되고, 만료 URL을 프록시가 어떻게 다루는지에 따라 안정성이 달라진다.
3. **다운로드해서 영구 저장소에 올리기**: 동기화 시점에 한 번만 처리하면 그 후로는 신경 쓸 게 없다. 동기화 스크립트가 좀 복잡해진다는 점을 감수하면, 빌드도 빠르고 외부 의존성도 최소화된다.

선택지를 찾아보고 정답은 없다는 생각이 들었다. 하지만 블로그라는 특성상 글을 한 번 쓰고 거의 안 고치는 식으로 가기 때문에 3번 방식이 가장 잘 맞을 것 같았다. 빌드 시간을 늘리고 싶지 않았고, 외부 서비스에 의존하지 않아서 개인적으로 만족스러웠다.

## sharp로 이미지 처리

Node.js에서 이미지 처리는 `sharp`가 주로 사용된다. 내부적으로 libvips라는 C로 작성된 이미지 처리 라이브러리를 사용한다. ImageMagick 같은 전통적인 이미지 처리 라이브러리는 이미지 전체를 메모리에 올린 뒤 작업하지만, libvips는 픽셀 데이터를 작은 청크 단위로 흘려보내며 처리한다.

여기서 중요한 건 단순히 "나눠서 처리한다"가 아니라 "한 청크를 처리한 직후 즉시 메모리에서 버린다"는 점이다. 어느 순간에도 메모리에는 지금 처리 중인 한 조각만 존재한다. 이게 가능한 이유는 리사이즈나 컬러 필터 같은 연산이 출력 픽셀 하나를 계산할 때 입력의 작은 이웃 픽셀들만 필요로 하기 때문이다. 이미지 전체를 동시에 들고 있을 필요가 없다.

![excalidraw: ImageMagick vs libvips 메모리 사용 패턴 비교](/images/posts/blog-dev-3-image-optimization/01-libvips-streaming.png)

4K 이미지(3840 × 2160 × 4바이트)는 약 33MB를 차지하는데, ImageMagick은 원본과 출력을 둘 다 들고 있어야 해서 60MB 이상을 쓰는 반면, libvips는 청크 한 조각만 들고 있어서 보통 1-2MB 수준에 머무른다. 같은 작업에서 ImageMagick보다 4배 이상 빠르고 메모리는 훨씬 적게 쓴다고 알려져 있다.

API도 메서드 체이닝으로 처리 단계를 자연어처럼 이어 쓸 수 있다. 아래 코드처럼 '버퍼를 받아 1200px로 리사이즈하고, WebP로 변환한 뒤, 다시 버퍼로 돌려준다'는 흐름을 그대로 메서드 호출 순서로 표현할 수 있다.

```typescript
import sharp from "sharp";

const optimizedBuffer = await sharp(Buffer.from(buffer))
  .resize(1200, null, {
    withoutEnlargement: true,
    fit: "inside",
  })
  .webp({
    quality: 85,
    effort: 6,
  })
  .toBuffer();
```

최대 너비를 1200px로 제한하고, WebP 포맷으로 변환한 결과를 버퍼로 반환한다.

### 리사이징 전략

`maxWidth: 1200`으로 큰 변 기준 최대 너비를 제한한다. 본문 폭은 768px 정도지만 고밀도 디스플레이(HiDPI)에서 흐릿하지 않으려면 본문보다 큰 원본이 필요해서 1200으로 두었다. `withoutEnlargement: true`는 원본보다 크게 확대하지 않는다는 뜻이고, 작은 이미지를 1200px로 늘리면 픽셀이 깨지기 때문에 넣었다.

### WebP 변환

모든 이미지를 WebP로 변환한다. JPEG보다 같은 화질에서 25-35% 작고, PNG처럼 투명도도 지원하고, 주요 브라우저에서 모두 동작한다. 압축률·투명도·호환성 세 가지를 모두 챙길 수 있는 포맷이라 골랐다.

`effort: 6`은 압축 효율과 속도를 조정하는 옵션이다. 총 0-6 범위이고, 높을수록 압축률이 좋지만 느리다. 빌드 시 한 번만 실행하므로 6으로 설정했다.

## Vercel Blob Storage

최적화된 이미지를 어디에 저장할지 고민했다. Git 저장소에 넣으면 용량이 커지고, 외부 서비스(Cloudinary, S3)는 별도 설정이 필요하다.

Vercel Blob은 Vercel 프로젝트와 통합이 잘 되어 있어서 선택했다.

```typescript
import { put } from "@vercel/blob";

const { url } = await put(webpFileName, optimizedBuffer, {
  access: "public",
  contentType: "image/webp",
});
```

반환된 URL은 영구적이고, CDN으로 서빙된다.

## 마크다운 내 이미지 자동 처리

글 동기화 시 마크다운을 스캔해서 Notion 이미지를 찾고, 최적화 후 URL을 교체한다.

```typescript
async processImagesInMarkdown(markdown: string, postSlug: string) {
  const imageRegex = /!\[([^\]]*)\]$([^)]+)$/g;
  let processedMarkdown = markdown;

  // 모든 이미지 매치 수집
  const matches: RegExpExecArray[] = [];
  let match;
  while ((match = imageRegex.exec(markdown)) !== null) {
    matches.push(match);
  }

  for (const match of matches) {
    const [fullMatch, altText, imageUrl] = match;

    // 이미 처리된 이미지는 스킵
    if (this.isVercelBlobUrl(imageUrl)) continue;

    // Notion 이미지만 처리
    if (this.isNotionImageUrl(imageUrl)) {
      const result = await this.optimizeAndUploadImage(imageUrl, fileName, postSlug);
      processedMarkdown = processedMarkdown.replace(
        fullMatch,
        `![${altText}](${result.url})`
      );
    }
  }

  return processedMarkdown;
}
```

정규식으로 마크다운 이미지 문법을 찾고, Notion URL인 경우에만 최적화 및 업로드를 수행한 뒤 URL을 교체한다.

### 멱등성 보장

같은 글을 여러 번 동기화해도 이미지가 중복 업로드되지 않는다.

```typescript
private isVercelBlobUrl(url: string): boolean {
  return url.includes('blob.vercel-storage.com');
}
```

이미 Vercel Blob URL이면 스킵한다. 한 번 처리된 이미지는 다시 처리하지 않는다.

## 하지만..

Obsidian으로 옮긴 이후로는 이미지 관리가 훨씬 단순해졌다. 이미지를 붙여넣으면 Custom Attachment Location 플러그인이 `public/images/posts/{slug}/` 경로에 자동 저장하고, Next.js가 정적 파일로 서빙하므로 별도 파이프라인이 필요 없다. 기존 글의 Vercel Blob URL은 그대로 유지된다.

파이프라인 코드는 레거시가 됐지만 삭제하지 않고 남겨뒀다. Notion 연동이 필요한 다른 프로젝트에서 그대로 떼어다 쓸 수 있는 형태이기도 하고, 같은 문제를 다시 만났을 때 참고하기 위해서다.

## 정리

- Notion 이미지 URL은 서명 기반 만료 방식이라 동기화 시점에 로컬로 내려받아야 한다
- `sharp`로 1200px 리사이즈 + WebP 변환을 적용하면 파일 크기를 크게 줄일 수 있다
- Vercel Blob에 업로드하면 영구 URL과 CDN 서빙을 동시에 확보한다
- 이미 처리된 URL은 건너뛰는 조건을 두어 멱등성을 보장한다
- Obsidian으로 전환한 이후에는 `public/images/` 로컬 저장 방식으로 대체되어 파이프라인은 레거시가 됐다


Notion 이미지 URL 만료 문제 해결과 sharp 기반 최적화

만료되는 Notion 이미지를 Sharp로 영구 저장하기


## 들어가며

촬영한 이미지를 합성하고, 영상을 서버에 전송하는 과정이 필요했다. 브라우저에서 이미지와 영상을 어떻게 처리했는지, 그리고 포맷을 선택하면서 부딪힌 문제를 정리한다.

## 브라우저에서 이미지를 처리해야 했던 이유

촬영한 사진 4장을 하나의 이미지로 합성하고, 프레임 배경을 씌우고, QR코드를 올리는 작업이 필요했다. 이 과정을 서버에서 처리하면 원본 4장을 모두 업로드한 뒤 합성 결과를 다시 받아야 한다. 여러 사용자가 동시에 촬영하면 업로드 대기 시간이 길어졌고, 사용자가 결과를 받기까지 체감이 느려지는 문제로 이어졌다.

브라우저의 Canvas API를 사용하면 이미지 합성을 클라이언트에서 직접 처리할 수 있다. 서버 왕복 없이 촬영 직후 바로 결과물을 만들 수 있다는 점이 이 환경에 적합했다.

## Canvas API로 이미지 처리하기

### canvas.toBlob()과 canvas.toDataURL()

브라우저에서 이미지를 Canvas로 처리한 결과를 내보내는 네이티브 API는 두 가지다.

https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/toBlob

https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/toDataURL

둘 다 canvas에 그린 내용을 원하는 포맷으로 인코딩하지만 반환 형태가 다르다.

- `toDataURL()`은 Base64 인코딩된 문자열을 동기적으로 반환한다.
  - Base64는 바이너리를 텍스트로 변환하기 때문에 원본 대비 약 33% 크기가 증가한다.
  - 중간 처리 단계에서 이미지를 문자열로 다룰 때 유용하다.
- `toBlob()`은 바이너리 Blob을 비동기 콜백으로 반환한다.
  - 바이너리 그대로 다루기 때문에 크기 증가가 없고, File 객체로 변환하기도 간편하다.
  - 서버에 전송할 최종 파일을 만들 때 적합하다.

실제로는 두 API를 용도에 따라 섞어 사용했다. 좌우반전이나 4컷 합성처럼 중간 단계에서는 `toDataURL()`로 이미지를 문자열로 넘기고, 서버에 업로드할 최종 파일을 만들 때는 `toBlob()`을 사용했다.

### 이미지 합성 흐름

`drawImage()`는 canvas 위에 이미지를 그리는 Canvas 2D API 메서드다. 4컷 합성은 이 메서드를 호출하는 순서를 조절하는 것만으로 해결했다.

```typescript
// 4장의 사진을 각 위치에 배치
for (const [index, photo] of photos.entries()) {
  const img = await loadImage(photo);
  ctx.drawImage(img, positions[index].left, positions[index].top, photoWidth, photoHeight);
}

// 프레임 배경을 위에 덮어씌우기
const bg = await loadImage(backgroundImage);
ctx.drawImage(bg, 0, 0, baseWidth, baseHeight);
```

Canvas는 나중에 그린 것이 위에 온다. 사진 4장을 먼저 깔고, 프레임 배경을 그 위에 덮으면 프레임의 투명 영역을 통해 아래의 사진이 보이는 구조가 된다. 합성이 끝나면 `canvas.toDataURL("image/png", 1.0)`으로 결과를 뽑아낸다.

`devicePixelRatio`(DPR, 디스플레이의 물리 픽셀과 CSS 픽셀의 비율)를 곱해 canvas 해상도를 높이는 시도도 했다. DPR이 2인 화면에서 canvas 내부 픽셀 수를 2배로 늘리면 이론적으로 더 선명한 이미지를 얻을 수 있다. 하지만 고해상도 캔버스에 저해상도 이미지를 크게 그리는 것뿐이었기 때문에 실제 인쇄 결과는 달라지지 않았다. 코드로 할 수 있는 조치는 다 했지만, 원본 해상도의 한계는 소프트웨어로 넘을 수 없었다.

### 리사이징

촬영된 이미지의 해상도가 목표 크기와 다른 경우 리사이징이 필요하다. 단순히 크기를 줄이면 이미지가 찌그러질 수 있기 때문에, 비율을 유지하면서 중앙 크롭하는 방식을 사용했다.

```typescript
// 원본과 목표의 가로/세로 비율을 비교하여 크롭 방향을 결정
const imgRatio = img.width / img.height;
const targetRatio = targetWidth / targetHeight;

if (imgRatio > targetRatio) {
  // 원본이 목표보다 가로가 넓으면 좌우를 자른다
  sw = img.height * targetRatio;
  sx = (img.width - sw) / 2;
} else {
  // 원본이 목표보다 세로가 높으면 상하를 자른다
  sh = img.width / targetRatio;
  sy = (img.height - sh) / 2;
}

ctx.drawImage(img, sx, sy, sw, sh, 0, 0, targetWidth, targetHeight);
```

`drawImage`의 9개 인자 버전은 원본에서 잘라낼 영역과 canvas에 그릴 영역을 각각 지정한다. `sx`, `sy`는 원본에서 잘라내기 시작할 좌표, `sw`, `sh`는 잘라낼 영역의 크기다. 비율 비교로 어느 방향을 잘라야 하는지 판단한 뒤, 중앙을 기준으로 크롭하여 이미지가 찌그러지지 않도록 했다.

## WASM 기반 FFmpeg 라이브러리로 영상 압축하기

### 브라우저에서 ffmpeg를 실행하는 방법

브라우저에서 영상을 다루는 네이티브 API로 `MediaRecorder`가 있다. 웹캠 스트림을 실시간으로 녹화할 때 사용하며, `videoBitsPerSecond` 옵션으로 비트레이트 힌트를 줄 수 있다. 하지만 이 값은 브라우저가 정확히 지키는 것이 보장되지 않고, 코덱도 브라우저가 지원하는 것만 선택할 수 있다. 무엇보다 `MediaRecorder`는 녹화 시점에 동작하는 API라서, **이미 녹화된 영상을 다시 압축하는 용도로는 쓸 수 없다**.

`@ffmpeg/ffmpeg`는 C로 작성된 ffmpeg를 WebAssembly(WASM, 브라우저에서 네이티브에 가까운 속도로 실행되는 바이너리 포맷)로 컴파일해 브라우저에서 실행할 수 있게 만든 패키지다. 실제 파일시스템 대신 메모리(Emscripten FS)를 사용한다는 점만 다르고, ffmpeg 명령어를 그대로 쓸 수 있다.

### 구현

```typescript
const ffmpeg = createFFmpeg({ log: false });

async function compressVideo(file: File): Promise<File> {
  if (!ffmpeg.isLoaded()) await ffmpeg.load();

  ffmpeg.FS("writeFile", file.name, await fetchFile(file));
  await ffmpeg.run("-i", file.name, "-c:v", "libvpx", "-b:v", "1M", "-c:a", "libvorbis", "output.webm");
  const data = ffmpeg.FS("readFile", "output.webm");

  // 메모리 누수 방지
  ffmpeg.FS("unlink", file.name);
  ffmpeg.FS("unlink", "output.webm");

  return new File([data.buffer], "output.webm", { type: "video/webm" });
}
```

### 프로덕션에 적용하지 못한 이유

영상 압축 로직은 구현까지 완료했지만, 실제 서비스에 적용하지는 못했다. 2주라는 짧은 외주 기간 안에 결과물을 내야 했고, 같은 날 다양한 기능들을 통합해서 구현하는 상황이었다. 원본 그대로 올려도 동작은 했기 때문에, 압축 연결보다 다음 기능 구현이 우선순위에서 앞섰다. 결과적으로 압축 유틸은 만들어둔 채로 다시 돌아오지 못했다.

## 정리

- Canvas API의 `toBlob()`과 `toDataURL()`은 용도에 따라 사용처가 다르다. 중간 처리에는 `toDataURL()`, 최종 파일 생성에는 `toBlob()`이 적합하다.
- `drawImage()`의 호출 순서로 이미지 합성을 구현했다. Canvas는 나중에 그린 것이 위에 오는 특성을 이용해 사진 위에 프레임을 덮는 구조를 만들었다.
- 이미지 리사이징 시 비율을 유지하면서 중앙 크롭하는 방식으로 찌그러짐을 방지했다.
- `@ffmpeg/ffmpeg` WASM으로 브라우저 영상 압축을 구현했지만, 제한된 일정 안에서 우선순위가 밀려 프로덕션에 적용하지 못했다.

## 참고 자료

- [HTMLCanvasElement.toBlob() - MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/toBlob)
- [HTMLCanvasElement.toDataURL() - MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/toDataURL)
- [@ffmpeg/ffmpeg - npm](https://www.npmjs.com/package/@ffmpeg/ffmpeg)
- [WebP - Google Developers](https://developers.google.com/speed/webp)


Canvas API 이미지 처리와 포맷 선택, ffmpeg WASM 영상 압축까지

네컷사진 이미지를 브라우저에서 처리한 과정


Denamu 프로젝트에서 최신 포스트 피드를 만들면서 무한 스크롤을 구현했다. 처음엔 단순하게 생각했는데, 구현하다 보니 고려할 게 꽤 많았다.

---

## 필요한 것 알아내기

무한 스크롤은 사용자가 페이지 하단에 도달하면 콘텐츠가 계속 로드되는 UX 패턴이다.

구현에 필요한 두 가지 조건을 정리하면:

1. **사용자가 페이지 하단에 도달했는지 감지**
2. **다음 데이터를 요청하고 기존 데이터에 이어붙이기**

이 두 가지를 해결하면 무한 스크롤이 완성된다.

---

## 1. 하단 도달 감지하기

### Scroll Event로 구현

간단하게 생각하면, scroll 이벤트가 발생할 때마다 현재 스크롤 위치가 하단인지 확인하면 된다.

```typescript
useEffect(() => {
  const handleScroll = () => {
    const scrollTop = document.documentElement.scrollTop;
    const scrollHeight = document.documentElement.scrollHeight;
    const clientHeight = document.documentElement.clientHeight;

    if (scrollTop + clientHeight >= scrollHeight - 100) {
      fetchNextPage();
    }
  };

  window.addEventListener("scroll", handleScroll);
  return () => window.removeEventListener("scroll", handleScroll);
}, []);
```

`scrollHeight`는 문서 전체 높이, `clientHeight`는 화면에 보이는 높이, `scrollTop`은 현재 스크롤 위치다. 세 값을 조합하면 하단에 도달했는지 알 수 있다. (자세한 내용은 [Scroll Properties](/notes/javascript/scroll-properties) 참고)

### 문제점

이 방식에는 문제가 있다. scroll 이벤트는 스크롤할 때마다 발생한다. 마우스 휠을 한 번 굴려도 수십 번 호출된다.

JavaScript는 싱글 스레드다. 스크롤할 때마다 콜스택에 함수가 쌓이고, 불필요한 연산이 계속된다. 쓰로틀링이나 디바운싱을 걸 수 있지만, 그래도 여전히 "필요 없는 시점"에 함수가 호출된다.

우리가 원하는 건 "하단에 도달했을 때만" 콜백이 실행되는 것이다.

### IntersectionObserver로 개선

IntersectionObserver API는 특정 요소가 뷰포트에 들어왔는지를 감지한다. 스크롤 이벤트처럼 매번 호출되지 않고, 요소가 "보이기 시작할 때"만 콜백이 실행된다. (자세한 내용은 [IntersectionObserver](/notes/javascript/intersection-observer) 참고)

```typescript
useEffect(() => {
  const observer = new IntersectionObserver(
    (entries) => {
      if (entries[0].isIntersecting) {
        fetchNextPage();
      }
    },
    { threshold: 0.1 }
  );

  if (targetRef.current) {
    observer.observe(targetRef.current);
  }

  return () => observer.disconnect();
}, []);
```

리스트 맨 아래에 빈 `<div>`를 두고, 이 요소가 화면에 보이면 다음 페이지를 로드한다.

```tsx
<>
  <PostCardGrid posts={items} />
  <div ref={targetRef} className="h-10" /> {/* 이 요소가 보이면 fetch */}
</>
```

`threshold: 0.1`은 요소의 10%만 보여도 콜백을 실행한다는 뜻이다. `rootMargin: "100px"`을 추가하면 요소가 화면에 들어오기 100px 전에 미리 로드해서 더 부드러운 UX를 만들 수 있다.

---

## 2. 데이터 요청과 상태 관리

### useState로 구현

하단 감지는 해결됐다. 이제 데이터를 요청하고 관리해야 한다.

```typescript
const [posts, setPosts] = useState<Post[]>([]);
const [page, setPage] = useState(0);
const [hasMore, setHasMore] = useState(true);

const fetchNextPage = async () => {
  const response = await api.getPosts({ page, limit: 12 });
  
  setPosts((prev) => [...prev, ...response.data]);
  setPage((prev) => prev + 1);
  setHasMore(response.hasMore);
};
```

### 문제점

이 방식도 문제가 있다. 사용자가 포스트 상세 페이지로 이동했다가 뒤로 가기를 누르면? 컴포넌트가 언마운트되면서 state가 초기화된다. 처음부터 다시 로드해야 한다.

사용자 입장에서 답답하고, 불필요한 API 요청도 늘어난다.

이걸 해결하려면 데이터를 전역 상태로 관리해야 한다. 직접 구현할 수도 있지만, 이미 이 문제를 잘 해결해둔 라이브러리가 있다.

### React Query useInfiniteQuery

TanStack Query(React Query)의 `useInfiniteQuery`는 무한 스크롤에 필요한 것들을 제공한다:

- 데이터 캐싱 (페이지 이동 후 돌아와도 유지)
- 페이지별 데이터 관리
- 다음 페이지 파라미터 자동 처리
- 로딩/에러 상태

```typescript
import { useInfiniteQuery } from "@tanstack/react-query";

export function useInfiniteScrollQuery<T extends { id: number }>({
  queryKey,
  fetchFn,
  tags,
}: UseInfiniteScrollQueryOptions<T>) {
  const { data, fetchNextPage, hasNextPage, isFetchingNextPage, isLoading } = 
    useInfiniteQuery({
      queryKey: [queryKey, tags],
      queryFn: ({ pageParam = 0 }) =>
        fetchFn({
          limit: 12,
          lastId: pageParam,
          tags: tags || [],
        }),
      getNextPageParam: (lastPage) => {
        if (!lastPage.hasMore) return undefined;
        const lastItem = lastPage.result[lastPage.result.length - 1];
        return lastItem.id;
      },
      initialPageParam: 0,
    });

  const items = data?.pages.flatMap((page) => page.result) ?? [];

  return { items, isLoading, isFetchingNextPage, hasNextPage, fetchNextPage };
}
```

`getNextPageParam`에서 다음 요청에 사용할 파라미터를 정의한다. 여기선 cursor 기반 페이지네이션을 사용해서 마지막 아이템의 `id`를 다음 요청의 `lastId`로 넘긴다.

---

## 최종 구현

IntersectionObserver + useInfiniteQuery를 조합한 최종 코드:

```tsx
export default function LatestSection() {
  const observerTarget = useRef<HTMLDivElement>(null);
  
  const { items, isLoading, isFetchingNextPage, hasNextPage, fetchNextPage } = 
    useInfiniteScrollQuery<Post>({
      queryKey: "latest-posts",
      fetchFn: posts.latest,
      tags: [],
    });

  useEffect(() => {
    const observer = new IntersectionObserver(
      (entries) => {
        if (entries[0].isIntersecting && hasNextPage && !isFetchingNextPage) {
          fetchNextPage();
        }
      },
      { threshold: 0.3, rootMargin: "100px" }
    );

    if (observerTarget.current) {
      observer.observe(observerTarget.current);
    }

    return () => observer.disconnect();
  }, [fetchNextPage, hasNextPage, isFetchingNextPage]);

  if (isLoading) return <PostGridSkeleton count={8} />;

  return (
    <>
      <PostCardGrid posts={items} />
      {isFetchingNextPage && <PostGridSkeleton count={4} />}
      <div ref={observerTarget} className="h-10" />
    </>
  );
}
```

`hasNextPage && !isFetchingNextPage` 조건으로 중복 요청을 방지한다. 다음 페이지가 있고, 현재 로딩 중이 아닐 때만 fetch한다.

---

## 정리

무한 스크롤 구현에 필요한 두 가지:

| 문제 | 단순한 방법 | 개선된 방법 |
|-----|-----------|-----------|
| 하단 감지 | scroll event | IntersectionObserver |
| 데이터 관리 | useState | useInfiniteQuery |

scroll event는 불필요한 호출이 많고, useState는 페이지 이동 시 데이터가 날아간다. IntersectionObserver와 React Query를 조합하면 이 문제들을 해결할 수 있다.


스크롤 감지부터 React Query까지

무한 스크롤 구현하기


![image.png](https://jant31jr2n1d0dxw.public.blob.vercel-storage.com/context-api-usereducer-flux/image-1762678308451-1.webp)


## 서론


React에서 여러 컴포넌트가 공유하는 상태를 관리할 때 prop-drilling 문제에 직면한다. 부모에서 자식으로, 또 그 자식으로 props를 계속 전달하다 보면 코드가 복잡해지고 유지보수가 어려워진다.


Flux 패턴은 이런 상태 관리를 체계적으로 수행하기 위한 아키텍처다. 데이터 흐름을 단방향으로 유지해서 상태 변경을 예측 가능하게 만든다. Redux가 Flux 패턴을 기반으로 만들어졌지만, 추가 라이브러리 없이 React의 Context API와 `useReducer`만으로도 같은 패턴을 구현할 수 있다.


본 글에서는 Context API와 `useReducer`를 활용해 Flux 패턴을 구현하는 방법을 다룬다.


## 왜 Flux 패턴인가


과거 Backbone 같은 프레임워크는 이벤트 기반으로 상태를 관리했다. Model이 변경되면 이벤트를 발생시키고, 여러 View가 이 이벤트를 구독해서 반응하는 구조다.


![image.png](https://jant31jr2n1d0dxw.public.blob.vercel-storage.com/context-api-usereducer-flux/image-1762678308451-1.webp)


문제는 이벤트가 연쇄적으로 발생할 때다. View A가 Model을 변경하면, 그게 View B를 업데이트하고, View B가 다시 다른 Model을 변경하고, 이게 또 View C를 업데이트한다. 상태 변경의 흐름을 추적하기 어렵고, 버그가 발생했을 때 원인을 찾기 힘들다.


Flux는 단방향 데이터 흐름으로 이 문제를 해결한다. 상태를 변경하는 방법이 하나로 제한되고, 그 과정을 추적할 수 있다.


## Flux 패턴의 이해


![https://www.youtube.com/watch?v=N9PT9iNTZAE&list=PLuHgQVnccGMB-iGMgONoRPArZfjRuRNVc&index=2&ab_channel=생활코딩](https://jant31jr2n1d0dxw.public.blob.vercel-storage.com/context-api-usereducer-flux/image-1762678312027-2.webp)


Flux 패턴은 4가지 요소로 구성된다.


### Action


애플리케이션에서 발생하는 이벤트나 사용자 상호작용을 표현한다. 보통 `type`과 `payload`를 포함한다. 그림에서 배달부로 표현되듯이, **액션은 정보를 담아서 Store로 전달하는 택배 상자** 같은 역할을 한다.


```javascript
// 카운터 증가
{ type: 'INCREMENT', payload: 1 }

// 사용자 로그인
{ type: 'USER_LOGIN', payload: { userId: 123, userName: 'john' } }

// 할일 추가
{ type: 'ADD_TODO', payload: { id: 1, text: '장보기', completed: false } }

// 데이터 로딩 시작
{ type: 'FETCH_DATA_START' }
```


`type`은 무슨 일이 일어났는지 알려주고, `payload`는 필요한 데이터를 전달한다. `payload`가 필요 없는 액션도 있다.


### Dispatcher


액션을 받아서 Store로 전달하는 중앙 허브다. 모든 액션이 Dispatcher를 거치기 때문에 상태 변경을 일관되게 처리할 수 있다. 그림에서 카운터 직원으로 표현되듯이, **배달부(액션)가 가져온 택배를 확인하고 처리 담당자(reducer)에게 넘겨주는 관문** 역할을 한다.


```javascript
// 컴포넌트에서 사용
const handleClick = () => {
  dispatch({ type: 'INCREMENT', payload: 1 });
};

// 여러 액션을 순차적으로 dispatch
const handleLogin = async (credentials) => {
  dispatch({ type: 'LOGIN_START' });

  try {
    const user = await loginAPI(credentials);
    dispatch({ type: 'LOGIN_SUCCESS', payload: user });
  } catch (error) {
    dispatch({ type: 'LOGIN_FAILURE', payload: error.message });
  }
};
```


`dispatch` 함수는 동기적으로 동작한다. 액션을 받으면 즉시 reducer를 호출해서 상태를 업데이트한다.


### Store


애플리케이션의 상태와 상태 변경 로직을 관리한다. Dispatcher로부터 액션을 받으면 상태를 업데이트하고, 구독자에게 변경을 알린다. **상태를 직접 수정하지 않고 항상 새로운 객체를 반환한다.**


그림에서 Store는 여러 요소를 포함하는 큰 상자로 표현된다.

- `state` (책): 현재 상태 데이터를 기록
- `reducer` (펜으로 쓰는 사람): 액션을 보고 새로운 상태를 작성
- `dispatch` (카운터): 액션을 받아서 reducer로 전달
- `getState` (카운터): 컴포넌트에게 현재 state를 제공
- `subscribe` (카운터): 상태 변경을 구독하는 컴포넌트 등록

```javascript
// 현재 상태
const currentState = {
  count: 5,
  user: null,
  todos: []
};

// INCREMENT 액션을 받으면
const action = { type: 'INCREMENT', payload: 1 };

// reducer가 새 상태를 반환
const newState = {
  count: 6,        // 변경됨
  user: null,      // 유지
  todos: []        // 유지
};

// currentState !== newState (다른 객체)
// currentState.user === newState.user (같은 참조)
```


변경되지 않은 부분은 같은 참조를 유지한다. 이를 통해 React는 어떤 부분이 바뀌었는지 확인할 수 있다.


### View


사용자 인터페이스를 구성하고 Store의 상태를 화면에 표시한다. 사용자 상호작용을 액션으로 변환해서 Dispatcher로 보낸다. React 컴포넌트가 View 역할을 한다. 그림에서 render(삽으로 땅 파는 사람)로 표현되듯이, **Store의 state를 받아서 실제 UI를 구축하는 작업자** 역할을 한다.


```javascript
const TodoList = () => {
  // Store에서 상태 읽기
  const { state, dispatch } = useContext(AppContext);

  // 사용자 상호작용을 액션으로 변환
  const handleAddTodo = (text) => {
    dispatch({
      type: 'ADD_TODO',
      payload: { id: Date.now(), text, completed: false }
    });
  };

  const handleToggleTodo = (id) => {
    dispatch({ type: 'TOGGLE_TODO', payload: id });
  };

  // Store의 상태를 화면에 표시
  return (
    <div>
      <h1>할 일: {state.todos.length}개</h1>
      <ul>
        {state.todos.map(todo => (
          <li key={todo.id} onClick={() => handleToggleTodo(todo.id)}>
            {todo.text}
          </li>
        ))}
      </ul>
    </div>
  );
};
```


View는 상태를 직접 변경하지 않는다. 항상 `dispatch`를 통해 액션을 보내고, Store가 상태를 업데이트하면 자동으로 리렌더링된다.


## Context API와 useReducer로 구현하기


Context API는 컴포넌트 트리 전체에 데이터를 전달하는 방법을 제공한다. `useReducer`는 복잡한 상태 로직을 관리하는 훅이다. 이 둘을 합치면 Flux 패턴을 구현할 수 있다.


### 프로젝트 구조


```plain text
project-root/
├── src/
│   ├── components/
│   │   ├── Counter.js
│   ├── context/
│   │   ├── AppContext.js
│   ├── reducers/
│   │   ├── appReducer.js
│   ├── actions/
│   │   ├── actionTypes.js
│   │   ├── actions.js
│   ├── App.js
│   ├── index.js
```


### 1. Reducer 작성 (Store)


`reducers/appReducer.js` 파일을 만든다. Reducer는 현재 상태와 액션을 받아서 새로운 상태를 반환하는 함수다.


```javascript
export const initialState = {
  count: 0,
};

export const appReducer = (state, action) => {
  switch (action.type) {
    case 'INCREMENT':
      return { ...state, count: state.count + 1 };
    case 'DECREMENT':
      return { ...state, count: state.count - 1 };
    default:
      return state;
  }
};
```


`action.type`을 확인해서 어떤 상태 변경을 수행할지 결정한다. `{ ...state }`로 기존 상태를 복사하고, 변경할 부분만 덮어쓴다. 원본 상태를 직접 수정하지 않는 것이 핵심이다.

> state.count += 1 같은 직접 수정은 React가 변경을 감지하지 못한다. 항상 새 객체를 반환해야 한다.
> Reducer는 순수 함수여야 한다. fetch 같은 비동기 로직은 컴포넌트에서 처리하고, reducer는 결과 데이터만 받아서 상태를 업데이트한다.

### 2. Action 정의


`actions/actionTypes.js`에 액션 타입을 상수로 정의한다.


```javascript
export const INCREMENT = 'INCREMENT';
export const DECREMENT = 'DECREMENT';
```


문자열을 직접 쓰지 않고 상수로 정의하는 이유는 두 가지다. 첫째, 오타를 방지한다. `'INCREMNET'` 같은 실수를 컴파일 단계에서 잡을 수 있다. 둘째, 나중에 액션 타입을 변경할 때 한 곳만 수정하면 된다.


`actions/actions.js`에 액션 생성자 함수를 만든다.


```javascript
import { INCREMENT, DECREMENT } from './actionTypes';

export const increment = () => ({
  type: INCREMENT,
});

export const decrement = () => ({
  type: DECREMENT,
});
```


컴포넌트에서 `dispatch({ type: 'INCREMENT' })` 대신 `dispatch(increment())`를 사용할 수 있다. 나중에 payload를 추가하기도 쉽다.


```javascript
export const increment = (amount = 1) => ({
  type: INCREMENT,
  payload: amount,
});
```


### 3. Context 생성 (Dispatcher + Store 연결)


`context/AppContext.js`에서 Context를 만들고 Provider를 정의한다.


```javascript
import { createContext, useReducer } from 'react';
import { appReducer, initialState } from '../reducers/appReducer';

const AppContext = createContext();

const AppProvider = ({ children }) => {
  const [state, dispatch] = useReducer(appReducer, initialState);

  return (
    <AppContext.Provider value={{ state, dispatch }}>
      {children}
    </AppContext.Provider>
  );
};

export { AppContext, AppProvider };
```


`useReducer`는 `[state, dispatch]`를 반환한다. `state`는 현재 상태고, `dispatch`는 액션을 보내는 함수다. 이 둘을 Context로 제공하면 하위 컴포넌트 어디서든 접근할 수 있다.


### 4. Component에서 사용 (View)


`components/Counter.js`에서 Context를 사용한다.


```javascript
import { useContext } from 'react';
import { AppContext } from '../context/AppContext';
import { increment, decrement } from '../actions/actions';

const Counter = () => {
  const { state, dispatch } = useContext(AppContext);

  return (
    <div>
      <p>Count: {state.count}</p>
      <button onClick={() => dispatch(increment())}>+</button>
      <button onClick={() => dispatch(decrement())}>-</button>
    </div>
  );
};

export default Counter;
```


`useContext(AppContext)`로 `state`와 `dispatch`를 가져온다. 버튼을 클릭하면 `dispatch`로 액션을 보낸다.

> dispatch는 액션 객체를 받는다. dispatch(INCREMENT) 같이 타입만 전달하면 reducer에서 action.type이 undefined가 된다. dispatch({ type: INCREMENT }) 또는 dispatch(increment())를 사용한다.

### 5. Provider 적용


`App.js`에서 `AppProvider`로 컴포넌트를 감싼다.


```javascript
import React from 'react';
import { AppProvider } from './context/AppContext';
import Counter from './components/Counter';

const App = () => (
  <AppProvider>
    <Counter />
  </AppProvider>
);

export default App;
```


`index.js`에서 앱을 렌더링한다.


```javascript
import React from 'react';
import ReactDOM from 'react-dom';
import App from './App';

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


## 전체 동작 흐름


사용자가 `+` 버튼을 클릭하면 다음 과정이 실행된다.


```mermaid
graph TD
    A[View<br/>Counter 컴포넌트] -->|사용자 클릭| B[Action<br/>increment]
    B -->|type: INCREMENT| C[Dispatcher<br/>dispatch]
    C -->|액션 전달| D[Reducer<br/>appReducer]
    D -->|새 상태 반환| E[Store<br/>state]
    E -->|리렌더링| A
```


각 요소의 세부 동작을 보면 다음과 같다.

1. View에서 사용자가 버튼 클릭
2. Action에서 `increment()`가 `{ type: 'INCREMENT' }` 액션 객체 반환
3. Dispatcher에서 `dispatch`가 액션을 `appReducer`로 전달
4. Reducer에서 `action.type`을 확인하고 `{ ...state, count: state.count + 1 }` 반환
5. Store에서 `useReducer`가 새 상태로 업데이트하고 Context 값 변경
6. View에서 Counter 컴포넌트가 리렌더링되어 새 count 값 표시

이 흐름은 계속 반복된다. 사용자가 다시 버튼을 클릭하면 같은 순환이 다시 시작된다.


## 마무리


이 글은 "전역 상태 관리 라이브러리를 꼭 사용해야 할까?"라는 의문에서 시작했다. Redux, Zustand, Recoil 같은 라이브러리를 추가하기 전에, React 자체 기능만으로 충분한지 알고 싶었다.


검색 결과 Context API와 `useReducer`를 조합하면 Flux 패턴을 구현할 수 있었다. Action, Dispatcher, Store, View로 이어지는 단방향 데이터 흐름을 React 내장 기능만으로 만들 수 있다. Redux가 제공하는 핵심 패턴을 추가 라이브러리 없이 구현 가능하다는 점이 고무적이다.


물론 Redux를 완벽하게 대체할 수 있는지는 이 글에서 깊이 있게 검증하지 않았다. Redux DevTools, 미들웨어 생태계, 성능 최적화 같은 부분에서는 여전히 Redux가 우위에 있을 수 있다. 하지만 중소규모 프로젝트에서 단순히 상태 관리 패턴이 필요하다면, Context API와 `useReducer`로 충분히 해결할 수 있다는 걸 확인했다.


## references


[https://velog.io/@j7papa/Context-API-useReducer](https://velog.io/@j7papa/Context-API-useReducer)


[https://youtu.be/BCD2irXaVoE?si=bt6dFuSF67iceULb](https://youtu.be/BCD2irXaVoE?si=bt6dFuSF67iceULb)


[https://medium.com/@amodes/redux-redux-toolkit-context-api-flux-what-problems-they-solve-and-when-to-use-them-94131ad1398b](https://medium.com/@amodes/redux-redux-toolkit-context-api-flux-what-problems-they-solve-and-when-to-use-them-94131ad1398b)



Redux 없이 단방향 데이터 흐름 만들기

Context API + useReducer로 flux 패턴 구현하기


## 개요


TypeScript의 `enum`을 사용하면 번들 크기가 예상보다 커지는 현상이 발견되었다. 특히 미사용 enum이 최종 번들에 포함되어 tree shaking이 제대로 동작하지 않는 문제였다. 더 흥미로운 점은 이 현상이 번들러마다 다르게 나타난다는 것이다.


## 문제의 원인


### enum이 컴파일되는 방식


문제의 근본 원인은 TypeScript enum의 컴파일 방식에 있다. enum은 JavaScript의 네이티브 기능이 아니기 때문에, TypeScript 컴파일러가 이를 IIFE(즉시 실행 함수)로 변환한다.


```typescript
// TypeScript 코드
export enum MOBILE_OS {
  IOS = 'iOS',
  ANDROID = 'Android'
}
```


위 코드는 다음과 같이 컴파일된다.


```javascript
// 컴파일된 JavaScript
export var MOBILE_OS;
(function (MOBILE_OS) {
    MOBILE_OS["IOS"] = "iOS";
    MOBILE_OS["ANDROID"] = "Android";
})(MOBILE_OS || (MOBILE_OS = {}));
```


### 왜 IIFE가 문제인가


IIFE는 즉시 실행되는 함수이기 때문에 번들러가 이를 "부수 효과(side effect)가 있는 코드"로 판단한다.

> **부수 효과(Side Effect)란?**  
> 함수가 반환값 외에 외부에 영향을 미치는 모든 동작을 의미한다. 전역 변수를 수정하거나, DOM을 조작하거나, CSS 파일을 import하거나, 이벤트 리스너를 등록하는 것이 대표적이다. 번들러는 부수 효과가 있는 코드를 제거하면 프로그램 동작이 달라질 수 있으므로 함부로 제거할 수 없다.

enum의 IIFE 패턴에서 특히 문제가 되는 부분은 `(MOBILE_OS || (MOBILE_OS = {}))` 구문이다. 이 코드는 외부 변수 `MOBILE_OS`를 읽고, 값이 없으면 빈 객체로 초기화한다. 번들러 입장에서는 외부 상태를 변경하는 코드로 보인다. 실제로 `MOBILE_OS`를 사용하지 않더라도 번들러는 "이 코드를 제거하면 프로그램 동작이 달라질 수 있다"고 판단한다. 그래서 안전을 위해 코드를 그대로 남긴다.


이 문제는 TypeScript의 [Issue #27604](https://github.com/microsoft/TypeScript/issues/27604)에서 2018년부터 논의되고 있다. 해결 방법으로 **`/*#__PURE__*/`** 주석을 IIFE 앞에 추가하여 "이 함수는 순수 함수이며 부수 효과가 없다"고 명시하는 방안이 제안되었다. 이렇게 하면 번들러가 안전하게 제거할 수 있지만, 아직 TypeScript 컴파일러 자체에는 반영되지 않았다.


### 번들러별 동작 비교


세 가지 주요 번들러는 enum tree shaking을 서로 다르게 처리한다.


### Vite (Rollup 기반)


Vite의 경우, 미사용 enum과 함수가 완벽히 제거되었다. 최종 빌드에는 실제 사용되는 코드만 포함되어 가장 효율적인 번들 크기를 달성했다.


```javascript
// Vite 빌드 결과 - 미사용 ENUM_TEST는 제거됨
const ENUM_COUNT = { ONE: 1, TWO: 2 };
console.log(ENUM_COUNT.ONE);
```


### Webpack


Webpack의 경우, `/* unused harmony exports ENUM_TEST, result */` 주석으로 미사용 코드를 표시하지만 실제 코드는 제거하지 않았다. 모듈 캐시 형태로 전체 enum 파일을 require하는 방식을 사용했다.


```javascript
// Webpack 빌드 결과 - 미사용 코드도 포함됨
/* unused harmony exports ENUM_TEST, result */
const ENUM_TEST = { ... };  // 사용하지 않지만 남아있음
const ENUM_COUNT = { ... };
```


Webpack은 `usedExports` 최적화를 통해 미사용 export를 표시하지만, 실제 제거는 Terser 같은 minifier에게 위임한다. 문제는 Terser가 IIFE의 부수 효과를 확신할 수 없어서 보수적으로 코드를 유지한다는 점이다.


### 왜 이런 차이가 발생하는가


같은 TypeScript enum 코드를 빌드했는데 결과가 다른 이유를 이해하려면, 두 번들러가 실제로 어떤 코드를 생성했는지 비교해야 한다.


**원본 TypeScript 코드**


```typescript
// enums.ts
export enum USED_ENUM { VALUE_A = 'A', VALUE_B = 'B', VALUE_C = 'C' }
export enum UNUSED_ENUM { VALUE_X = 'X', VALUE_Y = 'Y', VALUE_Z = 'Z' }

// main.ts
import { USED_ENUM } from './enums';
console.log(USED_ENUM.VALUE_A);
```


**Vite가 생성한 코드**


```javascript
var o=(t=>(t.VALUE_A="A",t.VALUE_B="B",t.VALUE_C="C",t))(o||{});
console.log("USED_ENUM.VALUE_A:",o.VALUE_A);
// UNUSED_ENUM은 어디에도 없음
```


**Webpack이 생성한 코드**


```javascript
var A,o;
!function(A){A.VALUE_A="A",A.VALUE_B="B",A.VALUE_C="C"}(A||(A={})),
function(A){A.VALUE_X="X",A.VALUE_Y="Y",A.VALUE_Z="Z"}(o||(o={})),
console.log("USED_ENUM.VALUE_A:",A.VALUE_A);
// UNUSED_ENUM(o)도 포함됨
```


두 번들 모두 enum을 IIFE로 변환했다. 그런데 Vite는 미사용 IIFE를 제거했고, Webpack은 그대로 남겼다. 이 차이는 어디서 오는 걸까?


**Rollup/Vite의 전략**


Rollup은 "사람이 작성한 것처럼 보이는 최대한 효율적인 번들"을 목표로 한다. ES 모듈의 정적 구조를 분석하여 사용되지 않는 export를 추적하고, 해당 IIFE가 참조되지 않으면 제거한다. 실제로 `UNUSED_ENUM`은 import되지도, 사용되지도 않았으므로 Rollup은 이 IIFE를 안전하게 제거할 수 있다고 판단했다.


**Webpack의 전략**


Webpack은 `usedExports` 최적화로 미사용 export를 표시하지만, 실제 제거는 Terser에게 위임한다. Terser는 IIFE 패턴을 보고 "이 코드가 외부 상태를 변경할 수도 있다"고 보수적으로 판단한다. `sideEffects: false`를 명시적으로 선언하지 않는 한, 안전을 위해 IIFE를 보존한다.


흥미로운 점은 두 번들러 모두 `unusedFunction`은 제거했다는 것이다. 일반 함수는 명확히 부수 효과가 없다고 판단할 수 있지만, IIFE는 즉시 실행되므로 더 신중하게 처리한다. Rollup은 이런 경우에도 사용 여부를 추적해서 제거하지만, Webpack/Terser는 보수적으로 유지한다.


## bundler 테스트


레퍼런스들에서 설명한 내용이 실제로 그런지 직접 확인해보자. Vite와 Webpack 최신 버전으로 동일한 코드를 빌드하여 번들 결과를 비교한다.


### 테스트 환경 구성


간단한 테스트 케이스를 작성한다. 여러 개의 enum을 정의하되 일부만 실제로 사용하는 코드다.


![enums.ts - USED_ENUM과 UNUSED_ENUM 정의](/images/posts/bundler-enum-tree-shaking/01-enums-ts.webp)


![main.ts - USED_ENUM만 import하여 사용](/images/posts/bundler-enum-tree-shaking/02-main-ts.webp)


이 코드를 Vite 최신 버전에서 빌드하면 `UNUSED_ENUM`과 `unusedFunction`이 제거되는지 확인할 수 있다.


### Vite 빌드 결과 뜯어보기


테스트 환경은 Vite v7.2.2이다. `npm run build`를 실행하면 다음과 같이 빌드된다.


```plain text
vite v7.2.2 building client environment for production...
✓ 5 modules transformed.
dist/assets/index-DXZEMrmh.js   1.04 kB │ gzip: 0.58 kB
✓ built in 42ms
```


![Vite 빌드 결과 - dist 폴더 구조](/images/posts/bundler-enum-tree-shaking/03-vite-dist.webp)


빌드된 JavaScript 파일을 열어보면 다음과 같다.


![Vite 번들 파일 - UNUSED_ENUM이 제거된 결과](/images/posts/bundler-enum-tree-shaking/04-vite-bundle.webp)


번들 파일을 살펴보면 흥미로운 결과를 발견할 수 있다. 31번 라인에 `var o=(t=>(t.VALUE_A="A",t.VALUE_B="B",t.VALUE_C="C",t))(o||{})` 형태로 압축된 IIFE가 보이는데, 이것이 USED_ENUM이다. 반면 UNUSED_ENUM은 어디에도 존재하지 않는다. 함수도 마찬가지다. `function c(t){return...}` 형태로 usedFunction은 남아있지만, unusedFunction은 흔적도 없다.


번들 파일 전체에서 "UNUSED"나 "unused" 문자열을 검색해도 아무것도 나오지 않는다. Vite는 enum에 대한 tree shaking을 완벽하게 수행했다.


### Webpack 빌드 결과 뜯어보기


같은 코드를 Webpack v5.102.1에서 빌드해본다. `optimization.usedExports`와 `minimize`를 모두 활성화한 production 모드다. Vite와 동일한 테스트 환경을 위해 CSS import와 DOM 조작 코드도 포함했다.


```plain text
> webpack

asset bundle.js 4.47 KiB [emitted] [minimized] (name: main)
webpack 5.102.1 compiled successfully in 517 ms
```


![Webpack 빌드 결과 - dist 폴더 구조](/images/posts/bundler-enum-tree-shaking/05-webpack-dist.webp)


빌드된 파일을 열어보면, 대부분의 코드는 style-loader와 CSS 관련 모듈이다. 번들 말미에 실제 enum과 애플리케이션 코드가 위치한다.


![Webpack 번들 파일 - UNUSED_ENUM이 남아있는 결과](/images/posts/bundler-enum-tree-shaking/06-webpack-bundle.webp)


놀랍게도 `UNUSED_ENUM`이 그대로 남아있다. 번들 파일을 검색하면 `VALUE_X`, `VALUE_Y`, `VALUE_Z`가 모두 포함되어 있음을 확인할 수 있다. `unusedFunction`은 제거되었지만, **enum은 제거되지 않았다.**


Webpack은 enum의 IIFE를 제거하지 못했다.


### 테스트 결과 정리


Vite v7.2.2는 enum tree shaking에 완벽하게 성공했다. 번들 크기는 1.04 kB다. 반면 Webpack v5.102.1은 enum tree shaking에 실패했다. UNUSED_ENUM이 번들에 포함되어 308 bytes를 차지한다. 코드가 단순해서 번들 크기 자체는 작지만 불필요한 enum이 포함되어 있다.


흥미로운 점은 두 번들러 모두 `unusedFunction`은 제거했다는 것이다. 일반 함수는 tree shaking이 작동하지만, enum의 IIFE 패턴은 Webpack에서 여전히 처리하지 못한다.


### 왜 Vite는 성공하고 Webpack은 실패하는가


같은 TypeScript enum 코드인데 번들러에 따라 결과가 다른 이유는 무엇일까?


Rollup은 특정 패턴의 IIFE를 인식하고 분석할 수 있다. TypeScript enum이 생성하는 IIFE 패턴은 충분히 예측 가능하므로, Rollup은 이를 "순수한 코드"로 판단하여 미사용 시 제거한다. 반면 Webpack의 Terser는 더 보수적으로 접근하여 IIFE를 부수 효과가 있는 코드로 간주한다.


결론적으로 **Vite 환경에서는 enum을 사용해도 번들 크기 걱정을 덜 수 있다.** 하지만 Webpack을 사용하는 프로젝트에서는 여전히 Union Types나 const enum으로 전환하는 것이 안전하다.


## 해결 방법


enum의 tree shaking 문제를 해결하려면 다음 방법들을 고려할 수 있다.


### Union Types로 전환


모든 번들러에서 적용되는 방법은 enum 대신 객체와 Union Type을 사용하는 것이다.


```typescript
// enum 대신 as const 객체 사용
const MOBILE_OS = {
  IOS: 'iOS',
  ANDROID: 'Android'
} as const;

// 타입 정의
type MOBILE_OS = typeof MOBILE_OS[keyof typeof MOBILE_OS];  // 'iOS' | 'Android'

// 사용 예시
function getDevice(os: MOBILE_OS) {
  return `Your device is ${os}`;
}

getDevice(MOBILE_OS.IOS);  // 타입 체크 완벽하게 작동
```


이 방식은 컴파일 후 순수한 객체만 남기 때문에 IIFE가 생성되지 않는다.


```javascript
// 컴파일 결과
const MOBILE_OS = {
  IOS: 'iOS',
  ANDROID: 'Android'
};
```


객체는 번들러가 쉽게 분석할 수 있다. 미사용 시 완벽하게 tree shaking되며, Webpack과 Vite 모두에서 작동한다. 타입 안정성도 enum과 동일하게 유지되면서 런타임 overhead도 없다. 컴파일 결과가 간단하고 예측 가능하며, Babel과 TSC 모두 지원한다.


반면 enum보다 문법이 약간 복잡하다는 단점이 있다. 숫자 enum의 역방향 매핑도 불가능하지만, 문자열 enum에서는 어차피 역방향 매핑이 안 되므로 실질적인 제약은 아니다.


### const enum 사용


```typescript
const enum MOBILE_OS {
  IOS = 'iOS',
  ANDROID = 'Android'
}

console.log(MOBILE_OS.IOS);
```


`const enum`은 컴파일 시점에 인라인으로 대체되어 런타임 코드가 전혀 생성되지 않는다.


```javascript
// 컴파일 결과 - enum이 완전히 사라짐
console.log("iOS");
```


완벽한 tree shaking처럼 보이지만 제약이 있다. 런타임 코드가 전혀 생성되지 않고 enum 문법을 그대로 사용할 수 있다는 장점이 있다. 반면 Babel에서 지원하지 않아 TypeScript 전용이며, `--isolatedModules` 옵션과 호환 문제가 있다. 다른 모듈에서 import할 때 문제가 발생할 수 있고, 값이 인라인되어 있어서 디버깅이 어렵다.


### Vite로 번들러 전환


Webpack을 사용 중이라면 Vite로 전환하는 것도 방법이다. 실제 테스트에서 확인했듯이 Vite는 enum tree shaking을 완벽하게 지원한다. 기존 enum 코드를 수정하지 않고도 번들 크기를 최적화할 수 있고 빌드 속도도 향상된다. 다만 프로젝트 마이그레이션 비용이 들고 기존 Webpack 설정을 재구성해야 한다.


### 권장 전략


새 프로젝트라면 Vite를 사용하는 것이 좋다. Vite는 내부적으로 Rollup을 사용하므로 enum tree shaking이 잘 작동하고 빌드 속도도 빠르다. Vite 환경에서는 enum을 그대로 써도 되지만, Union Types를 쓰면 모든 빌드 툴에서 안전하고 더 명시적이다.


Webpack을 사용하는 기존 프로젝트는 점진적으로 Union Types로 마이그레이션한다. 레거시 프로젝트에서는 const enum을 고려할 수 있으나 제약 사항을 반드시 확인해야 한다.


## 정리

TypeScript enum은 IIFE로 컴파일되어 번들러가 부수 효과 있는 코드로 판단한다. 이로 인해 미사용 enum이 tree shaking되지 않는 문제가 발생한다.

번들러별로 처리 방식이 다르다:
- Vite(Rollup): enum tree shaking 완벽 지원
- Webpack: IIFE를 보수적으로 유지, tree shaking 실패

해결책으로는 Union Types(`as const` 객체)가 가장 범용적이다. Vite 환경이라면 enum을 그대로 써도 되지만, Webpack 프로젝트에서는 Union Types 전환을 권장한다.

## References


[Enum tree shaking](https://jicjjang.github.io/posts/enum-tree-shaking)


[TypeScript enum의 Tree-shaking - Line Engineering](https://engineering.linecorp.com/ko/blog/typescript-enum-tree-shaking)


[TypeScript Issue #27604 - Make generated codes from enum could be minified when not used](https://github.com/microsoft/TypeScript/issues/27604)


[Webpack Tree Shaking Guide](https://webpack.js.org/guides/tree-shaking/)


[Tree-shaking versus dead code elimination by Rich Harris](https://medium.com/@Rich_Harris/tree-shaking-versus-dead-code-elimination-d3765df85c80)



IIFE로 컴파일되는 enum이 번들 크기를 키우는 이유

Bundler에서의 Enum Tree Shaking 문제


## 왜 SSG인가

블로그를 만들 때 가장 먼저 결정해야 하는 건 렌더링 방식이다. Next.js는 SSR, SSG, ISR을 지원하는데, 블로그에는 SSG가 가장 적합했다.

블로그 글은 한 번 작성하면 자주 바뀌지 않는다. 매 요청마다 서버에서 렌더링할 필요가 없다. 빌드 타임에 모든 페이지를 미리 생성해두면 CDN에서 정적 파일로 서빙할 수 있다. 서버 비용이 거의 들지 않고, 응답 속도도 빠르다.

ISR은 "주기적으로 재생성"이라는 개념이 블로그와 맞지 않았다. 글을 수정하면 즉시 반영되어야 하는데, ISR의 revalidation 주기 동안 구버전이 보일 수 있다. 차라리 수정할 때마다 빌드를 새로 돌리는 게 명확하다.

## 핵심 구조

Next.js Page Router에서 SSG를 구현하는 핵심은 두 함수다.

### getStaticPaths

빌드 타임에 어떤 페이지들을 생성할지 알려준다.

```typescript
export const getStaticPaths: GetStaticPaths = async () => {
  const posts = getSortedPostsData();
  const paths = posts.map((post) => ({
    params: { id: post.id },
  }));

  return {
    paths,
    fallback: false,
  };
};
```

`fallback: false`는 정의되지 않은 경로로 접근하면 404를 반환한다는 의미다. 블로그는 빌드 시점에 모든 글이 확정되므로 이 설정이 적합하다. `fallback: true`나 `'blocking'`은 동적으로 새 페이지를 생성할 때 쓴다.

### getStaticProps

각 페이지에 필요한 데이터를 빌드 타임에 가져온다.

```typescript
export const getStaticProps: GetStaticProps = async ({ params }) => {
  const id = params?.id as string;
  const postData = await getPostData(id);
  const headings = extractHeadings(postData.content);
  const adjacentPosts = getAdjacentPosts(id);
  const relatedPosts = getRelatedPosts(id, postData.tags);
  const readingTime = calculateReadingTime(postData.content);

  return {
    props: {
      postData: { ...postData, headings },
      adjacentPosts,
      relatedPosts,
      readingTime,
    },
  };
};
```

여기서 반환하는 props가 페이지 컴포넌트의 props로 전달된다. 빌드 타임에 실행되므로 파일 시스템 접근, 데이터베이스 쿼리 등 서버 사이드 작업이 가능하다.

## 데이터 레이어 설계

마크다운 파일에서 데이터를 추출하는 로직은 `src/lib/posts.ts`에 모아뒀다.

### 파일 시스템 기반 CMS

```typescript
const postsDirectory = path.join(process.cwd(), "posts");

export function getPostsList(): PostListItem[] {
  const fileNames = fs.readdirSync(postsDirectory);
  const allPostsData = fileNames
    .filter((fileName) => fileName.endsWith(".md"))
    .flatMap((fileName) => {
      const id = fileName.replace(/\.md$/, "");
      const fullPath = path.join(postsDirectory, fileName);
      const fileContents = fs.readFileSync(fullPath, "utf8");
      const matterResult = matter(fileContents);
      const data = matterResult.data as PostFrontmatter;

      if (data.published !== true) return [];

      return [
        {
          id,
          title: data.title,
          created: toDateString(data.created),
          tags: data.tags || [],
          excerpt: generateExcerpt(matterResult.content),
        },
      ];
    });

  return allPostsData.sort((a, b) => (a.created < b.created ? 1 : -1));
}
```

`fs.readdirSync`로 posts 폴더의 파일 목록을 읽고, 각 파일을 파싱해서 데이터를 추출한다. `gray-matter` 라이브러리가 frontmatter와 본문을 분리해준다.

`published !== true`인 글은 `flatMap`에서 빈 배열을 반환해 필터링한다. `filter` + `map` 조합보다 한 번에 처리할 수 있어서 간결하다.

### Frontmatter 타입 정의

```typescript
export interface PostFrontmatter {
  title: string;
  created: string | Date;
  updated?: string | Date;
  published?: boolean;
  tags?: string[];
}
```

`gray-matter`는 날짜 문자열을 자동으로 Date 객체로 파싱한다. `"2025-01-15"` 형식을 Date로 변환해주는데, 문제는 UTC로 파싱한다는 것이다. 한국 시간대에서 작성한 날짜가 하루 전으로 표시될 수 있다.

```typescript
function toDateString(value: string | Date): string {
  if (value instanceof Date) {
    // gray-matter가 UTC로 파싱하므로 UTC 메서드 사용
    const year = value.getUTCFullYear();
    const month = String(value.getUTCMonth() + 1).padStart(2, "0");
    const day = String(value.getUTCDate()).padStart(2, "0");
    return `${year}-${month}-${day}`;
  }
  return value;
}
```

`getUTCFullYear()`, `getUTCDate()` 등 UTC 메서드를 사용해서 파싱된 그대로의 날짜를 문자열로 변환한다. 로컬 시간대 메서드(`getFullYear()`)를 쓰면 시간대 변환이 일어나서 날짜가 어긋날 수 있다.

## 빌드 타임 최적화

SSG에서 중요한 건 빌드 타임이다. 글이 많아질수록 빌드 시간이 길어지는데, 몇 가지 최적화를 적용했다.

### 코드 하이라이팅 캐싱

코드 블록 하이라이팅은 비용이 크다. 매 빌드마다 모든 코드 블록을 하이라이팅하면 시간이 오래 걸린다.

```typescript
export const getStaticProps: GetStaticProps = async ({ params }) => {
  // ...
  const codeBlockRegex = /```([^\n\r]*)\r?\n([\s\S]*?)```/g;
  const codeBlocks: { [key: string]: string } = {};
  let match;
  let blockIndex = 0;

  while ((match = codeBlockRegex.exec(postData.content)) !== null) {
    const language = match[1]?.trim() || "text";
    const code = match[2];
    const blockKey = `block-${blockIndex++}`;
    codeBlocks[blockKey] = await highlightCode(code, language);
  }
  // ...
};
```

`getStaticProps`에서 코드 블록을 미리 하이라이팅해서 props로 전달한다. 클라이언트에서 하이라이팅하지 않으므로 번들 크기도 줄고, 사용자가 보는 시점에는 이미 처리가 끝나 있다.

### 날짜순 정렬 한 번만

```typescript
return allPostsData.sort((a, b) => (a.created < b.created ? 1 : -1));
```

정렬은 `getPostsList` 함수 내에서 한 번만 수행한다. 호출하는 쪽에서 매번 정렬하지 않아도 된다. 최신 글이 먼저 오도록 내림차순 정렬한다.

## 실제 빌드 결과

현재 블로그는 빌드 시 약 120개 페이지를 생성한다. Vercel에서 빌드 시간은 1분 내외다.

```text
Route (pages)                              Size     First Load JS
├ ● /                                      5.2 kB        89.4 kB
├ ● /posts/[id]                            12.1 kB       96.3 kB
├ ● /notes/[...slug]                       8.7 kB        92.9 kB
└ ... (120 more routes)
```

SSG의 장점은 배포 후 비용이 거의 없다는 것이다. Vercel 무료 티어로 충분하다. 서버리스 함수 호출이 없으니 사용량 걱정도 없다.


2026