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

---

## 이 책을 고른 이유

![러스트로 갈아타기 표지](/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에서는 접할 일이 없는 영역이라 낯설게 느껴질 수밖에 없다. 그래도 그 낯섦 자체가 시야를 넓혀주는 경험이었다.

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


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

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

시지프의 돌을 굴리며

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

## 개요

드로잉 기능을 만들고 나서 뿌듯했던 시간은 짧았다. 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로 묶여 있는 것이다. 그래서 직접 분리해야 했다.

![표시 공간과 좌표 공간 — 화면이 줄어들면 같은 좌표가 다른 위치에 렌더링된다](/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만으로는 해결할 수 없는 근본적인 한계가 있었다.

## 비트맵과 씬 그래프

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

![비트맵과 벡터 비교](/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)이라 한다.

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

![히트 테스팅 수식](/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. 해당 도형 객체를 반환한다.

![히트 캔버스 원리](/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은 테이블이다.

![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에 반영한다.

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

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

![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월 회고


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