bfs를 어떻게든 이해해보아요…..

[Algorithm] BFS(너비 우선 탐색)

yarn berry 마이그레이션 2탄 - CI/CD를 구축해보아요

[DevOps] yarn berry + Docker 마이그레이션

[기획] IA 공부하기

지금 이 블로그를 자동 배포하는 CD를 구축해보아요

[DevOps] 지금 이 블로그 자동 배포 구축하기

[Library] RTK Query VS. Tanstack Query

react-virtual을 사용하여 성능을 최적화해보아요

[react-virtual] virtualization으로 데이터 렌더링 최적화하기

gemini code assist로 코드 리뷰를 받아보아요

[AI] gemini code assist 로 무료 코드 리뷰 받기

2025 회고로 한 해 돌아보기 ☺️

[Retrospect] 2025 회고

utils와 lib 폴더의 차이점을 알아보아요

[Frontend] utils vs lib

[Internship] 2025-12 인턴일지

[Internship] 2025-11 인턴일지

(도커와의) 첫 만남은 너무 어려워

[Docker] (도커와의) 첫 만남은 너무 어려워

yarn에서 yarn berry로 마이그레이션 해보아요

[Package] yarn berry로 마이그레이션 하기

RTK Query의 transformResponse에 대해 알아 보아요

[RTK Query] transformResponse

[Internship] 2025-10 인턴일지

[Internship] 2025-09 인턴일지

hydration error에 대해 알아보아요

[Next.js] hydration

코드 스플리팅에 대해 알아보아요

[Next.js] 코드 스플리팅 (Code Splitting)

[Internship] 2025-08 인턴일지

재귀함수를 사용하여 하노이 타워를 구현해보아요

[Algorithm] 하노이 타워

맨날 까먹어서 메모해놓은 tailwind v3 초기 세팅 방법

[Memo] tailwind 초기 세팅

디프만 16기의 16주간 여정을 담은 회고

[Depromeet] 디프만 16기 회고

CSS에서 framer-motion으로 애니메이션 리팩토링을 해보아요

쌩CSS에서 framer-motion으로 갈아타기

디퍼드 딥링크를 구현해보아요

[React] 디퍼드 딥링크 구현

calc()을 활용해 요소를 원하는 좌표에 배치해보아요

[React] calc()을 활용해 요소를 원하는 좌표에 배치하는 방법

translate를 이용하여 인터랙션 구현하기

[React] CSS 애니메이션의 모든 것

본격적으로 shadcn/ui + Tailwind CSS 조합 써보기!

[React] shadcn/ui를 본격적으로 사용해보자

[React] shadcn/ui

morethan-log로 노션 블로그를 만들어요 🤩

[Blog] 노션 블로그, morethan-log

2024 회고로 한 해 돌아보기 ☺️

[Retrospect]2024 회고

use 훅이 바꿀 리액트 비동기 처리의 미래 맛보기

[Conference] FEConf 2023 - use 훅이 바꿀 리액트 비동기 처리의 미래 맛보기

[React] 구글 로그인 구현하기

useRef를 사용하여 탭바를 구현해보아요

[React] useRef로 Tab 구현하기

react로 이미지 업로드를 구현해보아요

[React] 이미지 업로드 구현하기


## <strong>💡 시작하기</strong>


이걸 갑자기 왜 뜬금없이 정리하냐면


코테 문제 풀 때 내가 제일 약한 게 트리랑 그래프다 트리가 특히 진짜 약하다.. 머리가 1도 안 돌아감.


그리고 맨날 DFS, BFS 언제 쓰는지도 모르고 어떻게 구현하는지도 까먹는다 ㅜ.ㅜ 친구한테 설명을 들어도 이해가 되기는 하는데 막상 구현하려면 그래서 어떻게 하는 건데..? 가 되어버림..


그래서 냅다 정리해보았다


## <strong>🖥️</strong> BFS 쓰는 이유 : 최단 경로 보장

> <strong>왜 BFS는 최단 경로를 보장할까?</strong>
>
> 각 지점으로 갈 수 있는 모든 방향으로 뻗음
> 따라서 BFS는 각 지점의 단계별 탐색 깊이가 같으므로 도착 지점까지의 최단 거리를 찾을 수 있음
>
>

또한 각 과정마다 최선의 탐색을 하므로 이미 거쳐온 경로는 다시 탐색하지 않아도 됨


### BFS에서 큐를 사용하는 이유


먼저 들어온 노드를 먼저 탐색하기 위해서이다<span class="notion-color-gray"><em>(라고만 들었을 때 이해를 1도 못함)</em></span>


BFS는 가까운 노드부터 차례대로 탐색하는 알고리즘인데, 이 순서를 보장해주는 자료구조가 바로 큐다!

1. 시작점에서 출발
2. 시작점과 인접한 노드를 모두 큐에 넣음
3. 큐에서 하나씩 꺼내면서 탐색 진행

이 과정을 반복하면 자연스럽게 거리 1 → 거리 2 → 거리 3 … 순으로 탐색이 진행된다.


이로 인해 최단 경로가 보장되는 것도 자연스럽게 설명된다!!


## 🤔 문제 - 미로 탈출


<div class="notion-bookmark"><a href="https://school.programmers.co.kr/learn/courses/30/lessons/159993" target="_blank" rel="noopener noreferrer"><div class="notion-bookmark-content"><div class="notion-bookmark-title">코딩테스트 연습 - 미로 탈출 | 프로그래머스 스쿨</div><div class="notion-bookmark-desc">알고리즘 문제 연습 카카오톡 친구해요! 프로그래머스 교육 카카오 채널을 만들었어요. 여기를 눌러, 친구 추가를 해주세요. 신규 교육 과정 소식은 물론 다양한 이벤트 소식을 가장 먼저 알려드립니다.</div><div class="notion-bookmark-url">school.programmers.co.kr</div></div></a></div>


나는 프로그래머스에서 풀어봤다!

<details>
<summary><span class="notion-color-yellow_background"><strong>문제 설명</strong></span></summary>

1 x 1 크기의 칸들로 이루어진 직사각형 격자 형태의 미로에서 탈출하려고 합니다. 각 칸은 통로 또는 벽으로 구성되어 있으며, 벽으로 된 칸은 지나갈 수 없고 통로로 된 칸으로만 이동할 수 있습니다. 통로들 중 한 칸에는 미로를 빠져나가는 문이 있는데, 이 문은 레버를 당겨서만 열 수 있습니다. 레버 또한 통로들 중 한 칸에 있습니다. 따라서, 출발 지점에서 먼저 레버가 있는 칸으로 이동하여 레버를 당긴 후 미로를 빠져나가는 문이 있는 칸으로 이동하면 됩니다. 이때 아직 레버를 당기지 않았더라도 출구가 있는 칸을 지나갈 수 있습니다. 미로에서 한 칸을 이동하는데 1초가 걸린다고 할 때, 최대한 빠르게 미로를 빠져나가는데 걸리는 시간을 구하려 합니다.


미로를 나타낸 문자열 배열 <code>maps</code>가 매개변수로 주어질 때, 미로를 탈출하는데 필요한 최소 시간을 return 하는 solution 함수를 완성해주세요. 만약, 탈출할 수 없다면 -1을 return 해주세요.


---


<strong>제한사항</strong>

- 5 ≤ <code>maps</code>의 길이 ≤ 100
    - 5 ≤ <code>maps[i]</code>의 길이 ≤ 100
    - <code>maps[i]</code>는 다음 5개의 문자들로만 이루어져 있습니다.
        - S : 시작 지점
        - E : 출구
        - L : 레버
        - O : 통로
        - X : 벽
    - 시작 지점과 출구, 레버는 항상 다른 곳에 존재하며 한 개씩만 존재합니다.
    - 출구는 레버가 당겨지지 않아도 지나갈 수 있으며, 모든 통로, 출구, 레버, 시작점은 여러 번 지나갈 수 있습니다.

---


<strong>입출력 예</strong>


| maps                                                                                        | result |
| ------------------------------------------------------------------------------------------- | ------ |
| [&quot;SOOOL&quot;,&quot;XXXXO&quot;,&quot;OOOOO&quot;,&quot;OXXXX&quot;,&quot;OOOOE&quot;] | 16     |
| [&quot;LOOXS&quot;,&quot;OOOOX&quot;,&quot;OOOOO&quot;,&quot;OOOOO&quot;,&quot;EOOOO&quot;] | -1     |


</details>


## 📖 진짜 어떻게든 이해하려고 적은 나만의 노트


<figure class="notion-image">
  <img src="https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F9b1af274-6edf-4f5c-b4c9-d8db23308ba6%2Fde9365ea-dbd2-42c1-9556-f491b3506c9e%2Fimage.png%3FX-Amz-Algorithm%3DAWS4-HMAC-SHA256%26X-Amz-Content-Sha256%3DUNSIGNED-PAYLOAD%26X-Amz-Credential%3DASIAZI2LB466SMDPCTWA%252F20260329%252Fus-west-2%252Fs3%252Faws4_request%26X-Amz-Date%3D20260329T073408Z%26X-Amz-Expires%3D3600%26X-Amz-Security-Token%3DIQoJb3JpZ2luX2VjED0aCXVzLXdlc3QtMiJIMEYCIQDx27McnY5wp6DgvNMjgxnHi%252BH%252FFU8%252FBAYNfu2UgxLs%252BAIhAKthyMybG2G9PjUg12%252BFSLghZtlk7lzyxh1u%252BYqup7EqKv8DCAYQABoMNjM3NDIzMTgzODA1IgwXWmpt5ZseDJnGj9Qq3AMTrQ0ueqCo6XiyyO%252FsWQY6iCSeviJC1S5e%252B7KqxObJI87OJvu%252BGktsovV%252FhxzCcBK5NgL2zkPYrN6Bbcj9ee40PqW4al%252BF%252Fj0MXWu3hUds8kvEapBOExGxbjQ65HjY4hC%252BnBj%252FM1rE5x3Ppsg8x8X%252F08o76QWzmKD%252F3KE9ztt%252F663yI8yyHcXsBKbDT3g8tdlgFKCcYV3Jdx%252FNQTqU%252FXv3ua7JjzufIXL64AScGs0bsDzKUzNRCmIGY5zaled4PuoziKbaeOl%252F5kavkr5XkHF9QCEx3Lc9itN5e5jyC6aw0DohnbTkJMTFTV4uOmY4ytSKas3a%252BhYaJdpinXNhZk7ARmup2QdIEOM76Nsd26QUCqxzYlUHepymRjB7TK61ZFZm2a5bI3VGCwxICj1es8kNBieimPBc4g4Fyb%252F4pR%252ByzJg1Pwp8r7WHVkxqFyiTL3E93xGWpagjoLZojEB72WKhUngu9%252Bpc0PxnJwrL15PrLdVvKtBomik9il4%252BvGeWzSmBOo2JBvjNrx5rMl1x7hU2hqp4qO8rfjbgKfvRwJyZyJl%252BO1fFkRx0GuuLHLwBUkF6WpSXreQmBP1grhMbTM1uMgx2zY%252FII8Nur0zI2n%252BmqsTeRx4FJV%252FBzbcCDTCs36LOBjqkARQnWUj2QuTJLTmP%252FYBFuS8wMxGtACg3%252FCLPsQl7pxLEV0UenrmByXvccNs7oj3EEghpVS9bcaMOeB4ZX2VLiaarO4wSq07WlLq%252FotSNz3gQe1iDjovYig5MNj5TBMMKVRZdkoI1ClEgLOJXnUXG6qok3IBzOAttzJHc%252BXqBNXAKJ78Z1kvRwo6qA7D20qYVl5liyPTXjCmUuNRkGcseIAYYTN7D%26X-Amz-Signature%3Dc7f1589a9e425d5ce2235fd1a08bef06a893e7b29355f9635f766158e3477f8b%26X-Amz-SignedHeaders%3Dhost%26x-amz-checksum-mode%3DENABLED%26x-id%3DGetObject?table=block&amp;id=3297763d-d03a-8032-9cc7-f7f7c6e8ed30&amp;cache=v2" alt="" />
  
</figure>

> <strong>코드를 짤 때는</strong>
1. 시작점을 큐에서 shift()
2. 상하좌우로 갈 수 있는 곳들은 모두
    - visited ⇒ true
    - queue에 push() → 넣을 때 shift했던 값의 dist + 1
3. 도착지점 오면 거리 출력

### 🔡 코드


```javascript
function bfs(maps, start, target) {
  const dx = [0, 0, -1, 1];
  const dy = [-1, 1, 0, 0];

  const col = maps.length;
  const row = maps[0].length;

  var queue = [];
  var visited = Array.from({ length: col }, () => Array(row).fill(false));

  queue.push([start[0], start[1], 0]);
  visited[start[0]][start[1]] = true;

  while (queue.length) {
    const [x, y, dist] = queue.shift();

    if (x === target[0] && y === target[1]) return dist;

    for (let i = 0; i < 4; i++) {
      const xpos = x + dx[i];
      const ypos = y + dy[i];

      if (
        xpos >= 0 &&
        xpos < col &&
        ypos >= 0 &&
        ypos < row &&
        !visited[xpos][ypos] &&
        maps[xpos][ypos] !== "X"
      ) {
        visited[xpos][ypos] = true;
        queue.push([xpos, ypos, dist + 1]);
      }
    }
  }
  return -1;
}

function solution(maps) {
  var start = [0, 0];
  var lever = [0, 0];
  var exit = [0, 0];

  for (let i = 0; i < maps.length; i++) {
    for (let j = 0; j < maps[i].length; j++) {
      let pos = maps[i][j];
      if (pos == "S") start = [i, j];
      if (pos == "L") lever = [i, j];
      if (pos == "E") exit = [i, j];
    }
  }

  const toLever = bfs(maps, start, lever);
  if (toLever === -1) return -1;

  const toExit = bfs(maps, lever, exit);
  if (toExit === -1) return -1;

  return toLever + toExit;
}
```


## <strong>📝 정리</strong>


트리가 너무 약해서 걱정이다


dfs는 이미 이해한 상태인데 bfs는 대체 언제 사용하는지 어떻게 해서 최단경로가 나오는 지를 이해하지 못했는데 이렇게 이해해서 정말 다행이다…


다음부터 잊지 않도록 bfs에 대한 문제를 종종 풀어봐야겠다 😊




## <strong>💡 시작하기</strong>


yarn berry로 마이그레이션을 진행한 이후, Docker 환경에서 빌드를 수행하는 과정에서 오류가 발생하였다. 알고 보니 yarn classic과 yarn berry는 의존성 관리 방식 자체가 다르기 때문에, 기존에 사용하던 Docker 설정을 그대로 사용할 수 없었다.


이에 따라 Docker 환경에서도 yarn berry에 맞게 빌드 과정과 설정을 수정하게 되었다!


<span class="notion-color-gray"><del>(11월에 진행한 태스크를 2월이 되어서야 올린다 허허)</del></span>


## 🔥 <strong>트러블 슈팅 1</strong>


```bash
ERROR: failed to build: failed to solve: process 
"/bin/sh -c 
if [ -f yarn.lock ]; then yarn --frozen-lockfile;     
else echo \"Lockfile not found.\" && exit 1;     
fi" 
did not complete successfully: exit code: 1
```


yarn berry로 바꾼 후 CI를 새로 구축하였는데 도커를 빌드하는 과정에서 오류가 생겼다.

> <strong>왜 이런 오류가 났을까?</strong>

yarn berry에서는 --immutable 옵션을 사용해야 lockfile과 설치 상태의 불일치를 정확히 검증할 수 있는데,
기존 CI 설정을 그대로 가져오면서 yarn classic 기준 옵션이 남아 있어 빌드 단계에서 실패가 발생했다.

> <strong>해결 방법</strong>

```bash
RUN yarn install --immutable

RUN \
    if [ -f yarn.lock ]; then yarn run build; \
    else echo "Lockfile not found." && exit 1; \
    fi
```


Yarn Classic에 맞춰져 있던 로직을 Yarn Berry에 맞게 수정해주었다


## 🔥 <strong>트러블 슈팅 2</strong>


---


<figure class="notion-image">
  <img src="https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F9b1af274-6edf-4f5c-b4c9-d8db23308ba6%2F77fde0fe-c16e-47eb-934c-f64e60116eab%2Fimage.png%3FX-Amz-Algorithm%3DAWS4-HMAC-SHA256%26X-Amz-Content-Sha256%3DUNSIGNED-PAYLOAD%26X-Amz-Credential%3DASIAZI2LB466S6BQHZ45%252F20260329%252Fus-west-2%252Fs3%252Faws4_request%26X-Amz-Date%3D20260329T073422Z%26X-Amz-Expires%3D3600%26X-Amz-Security-Token%3DIQoJb3JpZ2luX2VjED0aCXVzLXdlc3QtMiJHMEUCIQCX9Zu3shxz1iVJxpBqReF%252BJYy4QRgh8pKOQVjBF3vragIgV0SlF00fKvxRIkloEumGfwn5UY%252BW7xLu2SCXcXiHAncq%252FwMIBhAAGgw2Mzc0MjMxODM4MDUiDMfK%252Fw5jUg1cV5bHYyrcA5AZCL01wUrrhI1sWPZ8uiZnFbDFfCPi2WD137LwMGueu55nQ5WcYNlkrkrHYzv13N4HrkAji1G2wYYkaeQPKlpLwQ2Zf5UHyugfb3BVQKYzk1TkkQoQTvI%252FtyAdYxj9wa34MLsXGlrIgON%252B%252Bf4PYgf%252Ba2dbV1P%252FLPSpgPr3Hdd8vIu6avJi4WututBU9JW5PIodYeWgwWo0GR5qR%252FU7VzxcV8TltACrnEoO5s70vg5QEV2ONNlBQ5oFiHyiuzk0amXrdb2ohT8piLzmZEDPdthC8eCgi9r%252B9NAsd0wb%252BeJeTWeITI5wBY9neblt43Dq7mW8BCgIU%252Bd6NqZDBjvw2gAdFhhRvkwMkVOuZ1vZvI%252B0CrwstD8KwocJPp9a0SxiWNBkXq%252Br449h%252BSJ8%252BnjZY%252FcxYCyoPQyTOHCaTd0UHE9x4wtl9vyWRqEQeLYlQxZcJXu3Tfg%252FUioJUvCNVlZjbmLC2aPirGPstcT2rEhSwlzblUjANGhqlB%252BS0L%252BifUjnUMlxr8nyhyJveB52oU8M0m5LVbYYKMPkSUD5n3sGTbnruFWTsK9MY3HZxBQ%252F4yYE06LeiKTlxsrJ0z1diX%252F28JkCcVuH9lGm%252BjQjU%252BxmcG9PhcDHAp%252FetbPKMyWqMJrgos4GOqUBtqdxrpH4xz%252BsQ7YP%252FnzAudwLbOxdk70fJwlfsN4cuiitZf2Uo%252FAwd%252Bz0Nghh2As08eH3pdJtz9AfnPvtaXiGm7U6z2KXccW0uGzjdLcGSVAgkCIM11zEnDxxmvXV0wrSyFOz9he3HFJMZmIsbrxEPlv2zKFK5OPQ0hs04lSVSpZR1GpgMhmncqYIOAOwRn4jXmVfT0DuPFOhijdH8igjsYT8RH7E%26X-Amz-Signature%3D4a72b2d6dccac301d02f2d6b9f8a69d279e93905734c80e0189bc6d23015cac1%26X-Amz-SignedHeaders%3Dhost%26x-amz-checksum-mode%3DENABLED%26x-id%3DGetObject?table=block&amp;id=2b17763d-d03a-80fe-bdb8-ee0eab77fa59&amp;cache=v2" alt="" />
  
</figure>


ECS에 배포하니까 다음과 같은 에러가 떴다


알고보니 node_modules랑 관련된 에러였다


yarn berry로 바꿔서 node_modules가 존재하지 않게 되었으나
cd에서는 node_modules가 웬만하면 있어야 오류가 안 난다고 한다.


⇒ yarn berry의 nodeLinker를 도커에서 빌드하는 과정에서만 node_modules로 설정하여 
     도커가 생성한 이미지에만 node_modules가 존재하도록 수정하였다


```bash
RUN yarn config set nodeLinker node-modules
RUN yarn install --immutable
```


윗 줄 추가하니까 와아 성공~!


<figure class="notion-image">
  <img src="https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F9b1af274-6edf-4f5c-b4c9-d8db23308ba6%2F83262d65-6d17-4fcf-b412-2cf4b708033d%2Fimage.png%3FX-Amz-Algorithm%3DAWS4-HMAC-SHA256%26X-Amz-Content-Sha256%3DUNSIGNED-PAYLOAD%26X-Amz-Credential%3DASIAZI2LB466S6BQHZ45%252F20260329%252Fus-west-2%252Fs3%252Faws4_request%26X-Amz-Date%3D20260329T073422Z%26X-Amz-Expires%3D3600%26X-Amz-Security-Token%3DIQoJb3JpZ2luX2VjED0aCXVzLXdlc3QtMiJHMEUCIQCX9Zu3shxz1iVJxpBqReF%252BJYy4QRgh8pKOQVjBF3vragIgV0SlF00fKvxRIkloEumGfwn5UY%252BW7xLu2SCXcXiHAncq%252FwMIBhAAGgw2Mzc0MjMxODM4MDUiDMfK%252Fw5jUg1cV5bHYyrcA5AZCL01wUrrhI1sWPZ8uiZnFbDFfCPi2WD137LwMGueu55nQ5WcYNlkrkrHYzv13N4HrkAji1G2wYYkaeQPKlpLwQ2Zf5UHyugfb3BVQKYzk1TkkQoQTvI%252FtyAdYxj9wa34MLsXGlrIgON%252B%252Bf4PYgf%252Ba2dbV1P%252FLPSpgPr3Hdd8vIu6avJi4WututBU9JW5PIodYeWgwWo0GR5qR%252FU7VzxcV8TltACrnEoO5s70vg5QEV2ONNlBQ5oFiHyiuzk0amXrdb2ohT8piLzmZEDPdthC8eCgi9r%252B9NAsd0wb%252BeJeTWeITI5wBY9neblt43Dq7mW8BCgIU%252Bd6NqZDBjvw2gAdFhhRvkwMkVOuZ1vZvI%252B0CrwstD8KwocJPp9a0SxiWNBkXq%252Br449h%252BSJ8%252BnjZY%252FcxYCyoPQyTOHCaTd0UHE9x4wtl9vyWRqEQeLYlQxZcJXu3Tfg%252FUioJUvCNVlZjbmLC2aPirGPstcT2rEhSwlzblUjANGhqlB%252BS0L%252BifUjnUMlxr8nyhyJveB52oU8M0m5LVbYYKMPkSUD5n3sGTbnruFWTsK9MY3HZxBQ%252F4yYE06LeiKTlxsrJ0z1diX%252F28JkCcVuH9lGm%252BjQjU%252BxmcG9PhcDHAp%252FetbPKMyWqMJrgos4GOqUBtqdxrpH4xz%252BsQ7YP%252FnzAudwLbOxdk70fJwlfsN4cuiitZf2Uo%252FAwd%252Bz0Nghh2As08eH3pdJtz9AfnPvtaXiGm7U6z2KXccW0uGzjdLcGSVAgkCIM11zEnDxxmvXV0wrSyFOz9he3HFJMZmIsbrxEPlv2zKFK5OPQ0hs04lSVSpZR1GpgMhmncqYIOAOwRn4jXmVfT0DuPFOhijdH8igjsYT8RH7E%26X-Amz-Signature%3D121df18e46b1d24fa179ccfea1087c59e0d778d5723d98701f69445480b490f8%26X-Amz-SignedHeaders%3Dhost%26x-amz-checksum-mode%3DENABLED%26x-id%3DGetObject?table=block&amp;id=2b17763d-d03a-8094-8569-f4a1fbdb312a&amp;cache=v2" alt="" />
  
</figure>


---


yarn classic과는 다른 패키지와 구성이 있었기에 Dockerfile에서 수정을 많이 해야했다


## <strong>🖥️  Dockerfile에서 수정한 부분</strong>


```docker
# stage 1에 추가한 내용

COPY package.json yarn.lock .yarnrc.yml ./
COPY .yarn ./.yarn

RUN corepack enable
RUN yarn set version berry
RUN yarn install --immutable

# Stage 2에 추가한 내용

COPY --from=deps /app/.pnp.cjs /app/.pnp.cjs
COPY --from=deps /app/.yarnrc.yml ./.yarnrc.yml

COPY . .

ENV NODE_OPTIONS="--require=/app/.pnp.cjs"
RUN yarn install --immutable
```


## <strong>📝 결과 및 정리</strong>


<figure class="notion-image">
  <img src="https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F9b1af274-6edf-4f5c-b4c9-d8db23308ba6%2F72578da6-c338-44d3-afab-879d6796d2be%2Fimage.png%3FX-Amz-Algorithm%3DAWS4-HMAC-SHA256%26X-Amz-Content-Sha256%3DUNSIGNED-PAYLOAD%26X-Amz-Credential%3DASIAZI2LB466S6BQHZ45%252F20260329%252Fus-west-2%252Fs3%252Faws4_request%26X-Amz-Date%3D20260329T073423Z%26X-Amz-Expires%3D3600%26X-Amz-Security-Token%3DIQoJb3JpZ2luX2VjED0aCXVzLXdlc3QtMiJHMEUCIQCX9Zu3shxz1iVJxpBqReF%252BJYy4QRgh8pKOQVjBF3vragIgV0SlF00fKvxRIkloEumGfwn5UY%252BW7xLu2SCXcXiHAncq%252FwMIBhAAGgw2Mzc0MjMxODM4MDUiDMfK%252Fw5jUg1cV5bHYyrcA5AZCL01wUrrhI1sWPZ8uiZnFbDFfCPi2WD137LwMGueu55nQ5WcYNlkrkrHYzv13N4HrkAji1G2wYYkaeQPKlpLwQ2Zf5UHyugfb3BVQKYzk1TkkQoQTvI%252FtyAdYxj9wa34MLsXGlrIgON%252B%252Bf4PYgf%252Ba2dbV1P%252FLPSpgPr3Hdd8vIu6avJi4WututBU9JW5PIodYeWgwWo0GR5qR%252FU7VzxcV8TltACrnEoO5s70vg5QEV2ONNlBQ5oFiHyiuzk0amXrdb2ohT8piLzmZEDPdthC8eCgi9r%252B9NAsd0wb%252BeJeTWeITI5wBY9neblt43Dq7mW8BCgIU%252Bd6NqZDBjvw2gAdFhhRvkwMkVOuZ1vZvI%252B0CrwstD8KwocJPp9a0SxiWNBkXq%252Br449h%252BSJ8%252BnjZY%252FcxYCyoPQyTOHCaTd0UHE9x4wtl9vyWRqEQeLYlQxZcJXu3Tfg%252FUioJUvCNVlZjbmLC2aPirGPstcT2rEhSwlzblUjANGhqlB%252BS0L%252BifUjnUMlxr8nyhyJveB52oU8M0m5LVbYYKMPkSUD5n3sGTbnruFWTsK9MY3HZxBQ%252F4yYE06LeiKTlxsrJ0z1diX%252F28JkCcVuH9lGm%252BjQjU%252BxmcG9PhcDHAp%252FetbPKMyWqMJrgos4GOqUBtqdxrpH4xz%252BsQ7YP%252FnzAudwLbOxdk70fJwlfsN4cuiitZf2Uo%252FAwd%252Bz0Nghh2As08eH3pdJtz9AfnPvtaXiGm7U6z2KXccW0uGzjdLcGSVAgkCIM11zEnDxxmvXV0wrSyFOz9he3HFJMZmIsbrxEPlv2zKFK5OPQ0hs04lSVSpZR1GpgMhmncqYIOAOwRn4jXmVfT0DuPFOhijdH8igjsYT8RH7E%26X-Amz-Signature%3D4ab7a8201d0dc59895cdadbedf11d5974b8186ac2bb0d38bb1ab7b444641ac81%26X-Amz-SignedHeaders%3Dhost%26x-amz-checksum-mode%3DENABLED%26x-id%3DGetObject?table=block&amp;id=2fe7763d-d03a-8045-a07a-d1881f373b9e&amp;cache=v2" alt="" />
  
</figure>


yarn berry로 마이그레이션을 진행하면서 도커의 이미지 용량이 꽤 많이 압축되었다 :)


yarn berry는 node_modules 의존성을 제거하여 저장 공간을 줄이고, 의존성 관리의 일관성을 높일 수 있다는 장점이 있다. 그러나 실제 배포 환경에서는 여전히 node_modules 구조를 전제로 동작하는 경우가 많아, Docker 빌드 과정에서만 node_modules를 생성하도록 설정하는 방식을 선택하게 되었다.


이 과정은 yarn berry의 철학과는 다소 아이러니하게 느껴졌지만, 운영 환경의 안정성을 고려했을 때 현실적인 선택이었다고 판단한다.


이 부분에 대해서는 내가 알고 있는 yarn berry에 대한 정보가 약하다고 생각한다. 따라서 추후에는 PnP 환경을 보다 자연스럽게 배포에 적용할 수 있는 방법을 더 찾아볼 예정이다 :)


## <strong>🔗 참고</strong>


<div class="notion-bookmark"><a href="https://blog.naver.com/biud436/223211308347" target="_blank" rel="noopener noreferrer"><div class="notion-bookmark-content"><div class="notion-bookmark-title">러닝은빛의 작업실 : 네이버 블로그</div><div class="notion-bookmark-url">blog.naver.com</div></div></a></div>


<div class="notion-bookmark"><a href="https://well-balanced.medium.com/github-action%EC%9D%84-%ED%99%9C%EC%9A%A9%ED%95%9C-ecs-%EB%B0%B0%ED%8F%AC%EC%9E%90%EB%8F%99%ED%99%94-dd359c259910" target="_blank" rel="noopener noreferrer"><div class="notion-bookmark-content"><div class="notion-bookmark-title">https://well-balanced.medium.com/github-action%EC%9D%84-%ED%99%9C%EC%9A%A9%ED%95%9C-ecs-%EB%B0%B0%ED%8F%AC%EC%9E%90%EB%8F%99%ED%99%94-dd359c259910</div><div class="notion-bookmark-url">well-balanced.medium.com</div></div></a></div>


<div class="notion-bookmark"><a href="https://november-itstime.tistory.com/44" target="_blank" rel="noopener noreferrer"><div class="notion-bookmark-content"><div class="notion-bookmark-title">Front-End 배포 (2) - Github Actions로 CI/CD 구축해보기</div><div class="notion-bookmark-desc">이전에 AWS S3와 CloudFront로 배포했었는데 자동 빌드 및 배포를 위해 CI/CD를 구축해보고자 한다. CI/CD를 구축하는 법은 다양하게 있는데 흔히 Jenkins 와 Github Actions 두 가지 방법 중 하나를 사용하는 것 같았다. 난 이 중에서 Github Actions를 선택 했다. 이유는 Jenkins보다 초기 설정이 간단하다는 장점이 있고 현재 회사에서 프론트엔드 업무를 혼자 맡다 보니 시간이나 일정을 고려했을 때 조금이라도 빨리 구축해두는게 낫겠다 싶어서 Github Actions를 선택 했다. 1. IAM 권한 설정 : AWS S3와 CloudFront 로 배포했기 때문에 IAM 권한 설정을 해준다. 나는 회사 AWS 계정 중에서 CI/CD 전용 계정을 새로 만들어서 IA..</div><div class="notion-bookmark-url">november-itstime.tistory.com</div></div><div class="notion-bookmark-thumb"><img src="https://img1.daumcdn.net/thumb/R800x0/?scode=mtistory2&amp;fname=https%3A%2F%2Fblog.kakaocdn.net%2Fdna%2FS6YMw%2FbtsGmu6OQ9S%2FAAAAAAAAAAAAAAAAAAAAAGo9S6jmommCBFKu_6LB_5rpbQ1SF2DKeRDXucLc-5A5%2Fimg.png%3Fcredential%3DyqXZFxpELC7KVnFOS48ylbz2pIh7yKj8%26expires%3D1774969199%26allow_ip%3D%26allow_referer%3D%26signature%3DkaS%252FtU%252Bh93paX2vuEp9DE7i9JCw%253D" alt="" /></div></a></div>




## <strong>💡 시작하기</strong>


> <span class="notion-callout-icon">🖌️</span> <span class="notion-callout-text"><span class="notion-color-blue"><strong>IA(Information Architecture)</strong></span> ? 웹 · 앱 구축 시 필요한 화면과 메뉴의 정보 구조를 설계 및 정의하는 문서</span>
> 
> - 정보의 구조화를 통해 사용자가 어떤 목표를 달성하기까지 필요한 화면들의 흐름을 시각화함


<figure class="notion-image">
  <img src="https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F9b1af274-6edf-4f5c-b4c9-d8db23308ba6%2F08c3af4f-0494-4e14-bd2a-1c200b1e9de8%2Fimage.png%3FX-Amz-Algorithm%3DAWS4-HMAC-SHA256%26X-Amz-Content-Sha256%3DUNSIGNED-PAYLOAD%26X-Amz-Credential%3DASIAZI2LB466VK42D625%252F20260329%252Fus-west-2%252Fs3%252Faws4_request%26X-Amz-Date%3D20260329T073432Z%26X-Amz-Expires%3D3600%26X-Amz-Security-Token%3DIQoJb3JpZ2luX2VjED0aCXVzLXdlc3QtMiJHMEUCIQDieGpg4c%252FMv7Pz%252Bu%252FdiewBTUulfkrtWNZRxs%252Fq%252B3Ml%252BwIgR%252BKq%252BZ1DbSswK%252BVuOevtoUheOcL%252Fgav%252BEaDTI30EvWIq%252FwMIBhAAGgw2Mzc0MjMxODM4MDUiDAU7wxh66L1OZd8PAircA%252F5%252FOtrwrcjC1%252FUcp4OCndabEFvzKGswI8M4DC5l1ousYTLji%252B%252Bv6Ecla6gefpVDE9vOg6c%252FW0CDG7xRcgwAJMljVLtIeFu%252BQWL0DHRyLpvazhCrq7AEWac%252FFY1lE%252BCnvXZeC%252BrJowb8AXi3flkJPPRiB1Sts8z0%252FdP1cwbD7sLjg9dV1XSxN%252F92N6eb%252Fu9OfDoBzGDK9QKq%252FJXJIOky%252BNRwLjxfedEeeEVsi2xn6GtUzRcfXdCJf1TDopDQIljEDieVLzvu9bJUf9%252B9ywIEgJXzqjeXm23Eq64oDohKqWhKb0DoE9NvTxS7VuMvhQxiAnrmOaaNGs6w8fA2S97Bc0%252BO6Ao6bble79qbRCxe5cvAuWyf%252BxSMUfB18bB8Z419IPJMcAkt%252FzddKo3EGIna8Yd3QBxZlSm0SLathibEtpjGlrCW9HVT2wCacxbLuV5E%252BZZIILCW%252Bwya1E06ES3OAMh8aHw9JkrODul50SS0h3lWuB4JxrCl0hgjuNcYMgL4v6frsza4wLxo8UfhT8BUruRwOobVDvC9RJvzcbCuU87%252FDhmx1q0KUIKbEi2VkX6XarXIPIkj9Q%252Bm6j1Olz4sYJOLGLqqvbKf1PSAL%252FYFjAfQd4JUypECXU8xDV7dMOjgos4GOqUBrH09k1UYFdczDI8TnAFHgwHZoTk%252FijtPRVLsmfct7f6xmcIXeinkMmobb%252FU8Ketji1bMU8n3bPD2ZQMKleUN8MZ%252BicgmnqFpdDP1fR36uqx1LDm34cOHFN0pypq%252BTkwHDifHRwbGdcXhQUS68VHIK9DQE6kgpU%252BUka2F4wdVCfsNvlgiZaJBjS3p6iaQ5XfWKIvb5AWGXGvXzE1q%252BA4AmNtlJ8dQ%26X-Amz-Signature%3Dc5c358fdf2d5bf9b306aed2fe5a69d4ab2add556906da54ebf0cf32c70f9e3cf%26X-Amz-SignedHeaders%3Dhost%26x-amz-checksum-mode%3DENABLED%26x-id%3DGetObject?table=block&amp;id=2e27763d-d03a-8048-b963-faf9fed5a13a&amp;cache=v2" alt="이전 프로젝트 때 만들었던 IA이다" />
  <figcaption>이전 프로젝트 때 만들었던 IA이다</figcaption>
</figure>


## 0️⃣ IA 구성 시 고려해야 할 사항 3가지

- <strong>USER</strong>
    - 사용자가 기존에 어떠한 경험을 가지고 있는지
        - 사용자는 왜 이 서비스를 이용하려고 하며, 서비스를 통해 얻고자 하는 것이 무엇인지
        - 사용자가 서비스를 이용하는 도중 어떤 행동 패턴을 보이는지
- <strong>CONTENTS</strong>
    - 서비스에서 제공하는 컨텐츠가 공급자 중심인지 사업자 중심인지
    - 컨텐츠의 이름이 사용자가 인지하고 있는 이름인지
- <strong>SCENARIO</strong>
    - 정보의 시나리오는 어떻게 전달이 되어야 하는지

## 1️⃣ Depth 이해하기


IA에서의 depth : 서비스의 주요 기능을 사용하기 위해 실행해야 하는 행위가 얼마나 발생하는가? 의 수치

> Step vs Depth
- Step은 단계에 해당하므로, Depth 구조에서 하위로 내려가지 않음
    - Step은 그 스텝이 필요한 기능의 바로 다음 depth에 작성됨

> <details>
> <summary><strong>ex) 발전사업자 등록</strong></summary>
> 
> ---
> 
> 
> 발전사업자 등록의 과정은 총 3개의 step을 거침
> 
>     - 사업자등록번호 입력 → 인증서 등록 → 데이터 동기화
> 
> | 1 depth  | 2 depth    | 3 depth         |
> | -------- | ---------- | --------------- |
> | 발전사업자 등록 | 사업자등록번호 입력 | 사업자 이름, 위치 등 조회 |
> |          |            |                 |
> |          | 인증서 등록     | 인증서 등록  프로그램 설치 |
> |          |            | 인증서 파일 찾기       |
> |          |            | 인증서 비밀번호 입력     |
> |          | 데이터 동기화    |                 |
> 
> 
> </details>


## 2️⃣ 스크린 타입 정의하기

- Page  화면 그 자체에서 제공되는 화면
- Popup : 사용자의 이벤트로 인해 Page 내에서 새롭게 열리는 화면
    - popup, dialog, alert 등을 한 번에 칭하기도 함
- Tab: 같은 Page 안에서의 정보 분기를
- Link : 다른 화면으로 이동시키는 연결 지점

## 3️⃣ IA 표현 방식 정하기

> <strong>트리형 vs 엑셀형</strong>
- <strong>트리형</strong>: 화면 간 구조와 Depth를 직관적으로 파악하기 좋음

    <figure class="notion-image">
      <img src="https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F9b1af274-6edf-4f5c-b4c9-d8db23308ba6%2F7ae7e9e5-5e38-4890-890a-ff2ad6409ef7%2Fb9dea84b-d59d-425f-86e7-713db6c08f0c.png%3FX-Amz-Algorithm%3DAWS4-HMAC-SHA256%26X-Amz-Content-Sha256%3DUNSIGNED-PAYLOAD%26X-Amz-Credential%3DASIAZI2LB466YHAXZIKH%252F20260329%252Fus-west-2%252Fs3%252Faws4_request%26X-Amz-Date%3D20260329T073445Z%26X-Amz-Expires%3D3600%26X-Amz-Security-Token%3DIQoJb3JpZ2luX2VjED4aCXVzLXdlc3QtMiJGMEQCIGvzt1irtCH%252FtPUxNn4h8ivXaJayhodQ2YALZHPsPjnaAiBjm%252B%252Bz%252BSNs1AvIDm17R0OW9s9SvqS2WwBRsnKoz8VnIyr%252FAwgHEAAaDDYzNzQyMzE4MzgwNSIMRl7lGfn0MFvFPrBxKtwDBkTgox01LD%252B0Vg2JnjcMbaC9dkUO8FBXMz%252BOaYwhrau9zUbWl%252BalMCJlinFK68OR%252BQbNSyW2MysafbmCSfR66Rwq7ZSP0pfo3YROGa7cPB0frlldoOrlfSRPGgnc5pQ4fV9IvMFHXvgp28%252FLiyldj4E7NCFGZx2KZs5X6DWR%252Bt23MQELbVS7uv1VxxLOuPT9XFjAG4tNpOShCaAn%252BU4kzn5kvB%252BxQhIk2c883tQx0or955bZo3WW1y0u2Zd0NkwhMAt594qcev%252FS5gxDun62PYvf9jnccswj0dkxiWpRc3rX%252FZPqVdqHfLSIrEg5AC0PYvmwQBnP4QS2pW8M8ejXIoyMBffGKij8ewxk%252Bf544aCCXvOozYAhI0zwHvxbKdGLkm3uDJwbS24j0jUgpzh2nwm20%252BwcZ9Y1gDn9xmt3vYI64OdD0BrNcbfdev1agFPGQ5jLfBGXVXdM1hZsRi4QtkgHhJqsv031cMeimPCGYVRXWTy8TO3oeShDaVmxLk20D8ixNZ5yAXB%252FwWw1o8YzwehvFDcxmRr49%252BPxAKkJ1cU0HU01i1E77oFHb5H%252FVUfewkSsRlhFDmbxWdqzHXNeX5ycr3C0hkXNeGfowfaOIUDn5NCSzJRkxIEZ9Sswv%252FCizgY6pgHuQ0DSkS4jAqVeGAFCd9s9QPBPk37APppv35ccpQ4CT7dAtCXj3HN%252Frey5L5fm8eethqM%252Fa5MRJQbNkbo4Lpp5vgGFAUXItM43KYUpbKVQ4kQzCJxvr7%252FH1TczxKBqiWgTJ%252BqjogF6iRGHU397w16tR8Mw7eZhD8s0szOpPEUDEd6hJm9GjT3bySxHn%252BDyMX6DB%252FDx04wQf6vU%252Fh86R49O7uSU%252BjK%252F%26X-Amz-Signature%3Dea19de0c6ec176f7c125295c9da0ea67ddeffcc9a5916f3e1e3f2bb2fc0983e5%26X-Amz-SignedHeaders%3Dhost%26x-amz-checksum-mode%3DENABLED%26x-id%3DGetObject?table=block&amp;id=2ef7763d-d03a-804d-926c-e5298a15a9fe&amp;cache=v2" alt="" />
      
    </figure>

- <strong>엑셀형</strong>: 화면별 속성(타입, 권한, 정책 등)을 상세히 관리하기 좋음

    <figure class="notion-image">
      <img src="https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F9b1af274-6edf-4f5c-b4c9-d8db23308ba6%2F504259a9-5bb3-4f33-8757-7cc3a789afa8%2Fimage.png%3FX-Amz-Algorithm%3DAWS4-HMAC-SHA256%26X-Amz-Content-Sha256%3DUNSIGNED-PAYLOAD%26X-Amz-Credential%3DASIAZI2LB4662RFGB6JP%252F20260329%252Fus-west-2%252Fs3%252Faws4_request%26X-Amz-Date%3D20260329T073450Z%26X-Amz-Expires%3D3600%26X-Amz-Security-Token%3DIQoJb3JpZ2luX2VjED0aCXVzLXdlc3QtMiJGMEQCIB7RT5zQcAbtfQUqK2WRDqLm0WzZTFK%252BbcyEYjYnZ%252FGvAiA3o%252BTLYh8QHD0OfKtUoGwHfyQ7V4YGShmZupIRm4I8cyr%252FAwgGEAAaDDYzNzQyMzE4MzgwNSIMrfitbew5pJQlwnhdKtwDfx9Ec57woTiqCQMAudXYd7Ge6MRvh1FooUCrYlz%252FVCSRQsaft6ZmWjDCxEM19Y%252FnVCtSdIlI7%252FrXq5Pb3vwinVA1zbxfPSLmeBTyMbTAZIBgBIarG%252BI9BirFa56UmMrbcfAu6S0Fve8j4AZAmoT5roPCno3ZaHCnDdSqdFi5BAXcYXJh0YHM90vb5b3Iz6m78L5sckbnXfsehqveu8wSh0dxTh0aF3%252BfH2lTE1nLRRQ5znyVsJFazbX6d3hn%252FxECa4hSW8R8s04IU4bkITPYAFI0RECYywVDFAynEhGVeohdg6xmo%252BwXVB%252BFetChMsOdu2PSerzy419JCDNrKgbqWGBPDfQxYwCAFmmdilTC3vYqo3qAkfEUw9jxdYOmY%252B4B2V37uhSF1tIYZgAwXUmcT37%252F79cx9toqgrChGLwtpyIJJ%252BfE42s%252FJLUWgOBBsQfPIrIoIyblSJwxzqTq8ROP%252BSsxQv6Gjy%252BywiYOmEJBl6GunOoJtnJpGZW%252FUud0a4wbImrWURr7ShpA7PbxZYVfpVhXAkGQWyhsK4JmOgGgIt3uKyGJT1SDxNil7vZWIG6bJwyRhVhnqrG3UmyPwQ4LoDEuTuf4Bbz4DvNiHhnMWujfcF9N3HBHZPErZkww8N%252BizgY6pgHONTZlmk5Qdu5fCIBS129thjHMaqphU0oCLE8MncOotVUnq%252BpMHO6NABi2UrSVmwShxllGvct11N9MNG5lv7bKN5oEMNb3CqwfKm1at1EscWAzTXEaRRvZvknVY2hZixnZNIeWEhP2YW%252BZmFbKGfve0HJVUbDatQadHYW5wB6OjcJ%252BmX6ELgqMRv4vDKa7FLdM9GrxHCuQKnnvY23PlRs%252FwNdAjQzg%26X-Amz-Signature%3Dd2863bc9eefce0ae4aef489c3c673b34db6dfff5f8f48bdeaf07f5d1e618cc6b%26X-Amz-SignedHeaders%3Dhost%26x-amz-checksum-mode%3DENABLED%26x-id%3DGetObject?table=block&amp;id=2ef7763d-d03a-801d-a202-c0fe80bd853b&amp;cache=v2" alt="" />
      
    </figure>


⇒  <strong>전체 구조와 사용자 이동 흐름을 한눈에 보여주는 것이 중요하다고 판단하여 트리형을 선택했다.</strong>


필요한 화면 속성이나 정책은 별도의 문서로 보완할 예정이다.


## 💡유의사항

> <strong>📌 사용자 입장에서 고려해야 한다</strong>

사용자가 우리의 서비스를 편하게 사용하고 이해하기 쉽게 하기 위한 IA를 짜는 것이 굉장히 중요함!!!!!!


## <strong>📝 정리</strong>


## <strong>🔗 참고</strong>


<div class="notion-bookmark"><a href="https://brunch.co.kr/@applehong/80" target="_blank" rel="noopener noreferrer"><div class="notion-bookmark-content"><div class="notion-bookmark-title">IA 정보구조도 설계 첫번째 :: Depth 이해하기</div><div class="notion-bookmark-desc">IA는 Information Architecture 의 줄임말로 우리말로는 정보구조도라고 합니다.  이 단계에 들어서면 프로젝트의 단계가 설계에 들어섰다는 것을 의미합니다.  본격적인 학습에 들어가기 전에 한가지 알아두면 좋은 것은 IA는 한 번에 완성하기 어렵다는 것입니다.  특히나 새로운 서비스를 만드는 중이라면 이 IA는 여러번의 업데이트를 거쳐서 완</div><div class="notion-bookmark-url">brunch.co.kr</div></div><div class="notion-bookmark-thumb"><img src="https://img1.daumcdn.net/thumb/R1280x0.fwebp/?fname=http://t1.daumcdn.net/brunch/service/user/9j1a/image/J998CJpld5aKrCXm4Sir8dOya60" alt="" /></div></a></div>


<div class="notion-bookmark"><a href="https://zero-base.co.kr/event/media_insight_contents_PM_IA" target="_blank" rel="noopener noreferrer"><div class="notion-bookmark-content"><div class="notion-bookmark-title">국내최초 취업정보회사 - 제로베이스</div><div class="notion-bookmark-desc">단 한 번의 가입으로 취업 · 이직 고민을 한 번에 해결하는 초개인화 맞춤형 취업 서비스, 오직 당신만을 위한 1:1 취업 전략을 설계합니다.</div><div class="notion-bookmark-url">zero-base.co.kr</div></div><div class="notion-bookmark-thumb"><img src="https://cdn.zero-base.co.kr/static/zerobase-opengraph.png" alt="" /></div></a></div>




# 1️⃣ 이 주제로 글을 쓰는 이유


회사에서 웹과 앱을 각각 다른 스택으로 운영하고 있었고,
서버 상태 관리는 웹은 TanStack Query, 앱은 RTK Query를 사용하고 있었다.


이 상태에서 모노레포 도입을 고려하게 되었고, 공통 API / 인증 로직을 어떻게 가져가야 할지가 문제였다.


이로 인해 하나의 라이브러리로 통합하려는 고민과 어떤 선택이 장기적으로 더 나은지 고민하게 되었다.


# 2️⃣ RTK Query vs Tanstack Query


이번 선택에서 중요하게 본 기준은 다음과 같았다.

- 웹 / 앱 구조 차이에 대한 유연성
- 서버 상태와 UI 상태의 분리 정도
- 기존 코드베이스와의 정합성
- 모노레포 환경에서의 코드 공유 용이성

### 각 라이브러리 정의 


---

> <strong>RTK Query</strong>
- Redux와 깊게 통합되어 전역 상태 관리를 하면서 데이터를 가져오고 동기화함
- createApi를 통해 API Slice를 정의하며, 이 slice는 자동으로 데이터 요청/조작용 훅 생성
    - 훅 : ex. useLoginMutation, useFetchPowerplantQuery
> <strong>Tanstack Query</strong>
- Tanstack Query는 상태 관리 라이브러리와 독립적으로 동작하며, 컴포넌트 수준에서 캐싱과 서버 상태 관리를 처리함
- queryKey, select, invalidateQueries 등을 제공함
- axios와 같은 요청 라이브러리를 직접 사용하여 요청 로직을 구성함

|              | RTK Query                                                   | Tanstack Query                                                 |
| ------------ | ----------------------------------------------------------- | -------------------------------------------------------------- |
| 상태 관리        | Redux가 제공하는 기능 중 하나.
Redux가 적용된 프로젝트에 추가하기 쉬움               | 상태를 저장하는 저장소가 따로 존재하지 X, 
Redux가 아닌 여러 상태 관리 라이브러리와 호환하여 사용 가능 |
| API 호출법      | createAPI 메서드 사용                                            | useQuery, useMutation 메서드 사용                                   |
| 데이터 정규화      | createAPI에서 데이터를 정규화하여 상태 관리 최적화                            | 데이터를 자동으로 정규화하지는 않으나
API의 요청 중복 방지 및 캐싱을 통해 성능 향상              |
| 캐싱 및 태그 관리   | providesTags와 invalidatesTags를 통해 데이터 변경 시 쿼리 데이터를 자동으로 갱신함 |                                                                |
| 철학           | 중앙 집중식 엔드포인트 정의                                             | 컴포넌트 단위의 선언적 페칭                                                |
| Github Stars | 11.2k                                                       | 48.6k                                                          |
| 번들 사이즈       | 13.4KB                                                      | 13.3KB                                                         |


## 📜1️⃣ <strong>RTK Query로 통합하는 경우</strong>


---


### 개요

- 서버 상태 관리를 RTK Query + Redux Store 기준으로 통합
- 앱은 기존 구조 유지
- 웹은 기존 Tanstack Query 기반 API 로직을 RTK Query로 전환

### 적합한 경우

- Redux를 팀 표준 상태 관리로 강하게 가져가려는 경우
- 앱 중심 구조이며 웹은 상대적으로 단순한 경우
- API 구조 변경 가능성이 낮은 내부 관리용 서비스

<div class="notion-columns">
  <div class="notion-column"><h3>장점</h3>
<hr>
<ul>
<li>Redux 기반 전역 상태 관리에 익숙할 경우, 효율 증가</li>
<li>앱 쪽 추가 작업이 거의 없음</li>
</ul>
</div><div class="notion-column"><h3>단점</h3>
<hr>
<ul>
<li>웹에서 이미 사용 중인 Tanstack 생태계와 철학적 불일치<ul>
<li>Tanstack Table / Virtual과 데이터 연결 구조가 어색해질 수 있음</li>
</ul>
</li>
<li>웹의 기존 API 코드 마이그레이션 비용이 큼</li>
<li>Redux 의존도가 웹까지 확대됨</li>
<li>서버 상태와 UI 상태가 Redux에 함께 쌓이며 장기적으로 store의 복잡도 증가 우려됨</li>
<li>모노레포 환경에서<ul>
<li>store 구조 차이로 공통 API 로직 재사용이 어려워질 가능성</li>
</ul>
</li>
</ul>
</div>
</div>


## 📜2️⃣ <strong>TanStack Query로 통합하는 경우</strong>


---


### 개요

- 서버 상태 관리를 Tanstack Query + Zustand 기준으로 통합
- 웹은 기존 구조 유지
- 앱은 RTK Query 기반 API 로직을 Tanstack Query로 전환

### 적합한 경우

- 테이블 / 리스트 / 대용량 데이터 중심 서비스
- 웹과 앱을 동등하게 혹은 웹 중심 구조일 경우
- 장기적인 확장성과 유연성을 중시하는 경우

<div class="notion-columns">
  <div class="notion-column"><h3>장점</h3>
<hr>
<ul>
<li>웹에서 이미 사용 중인 Tanstack Table / Virtual과 라이브러리 생태계 일치 → 통일성 증가, 데이터 연결 자연스럽게 연계 가능</li>
<li>모노레포에서<ul>
<li>API 함수 / query key / 훅을 패키지 단위로 공유하기 쉬움</li>
</ul>
</li>
<li>앱 번들 크기 및 구조 단순화</li>
</ul>
</div><div class="notion-column"><h3>단점</h3>
<hr>
<ul>
<li>앱에서 RTK Query 제거 및 마이그레이션 비용 발생</li>
<li>Redux 기반 패턴에 익숙할 경우 초기 적응 비용 존재</li>
</ul>
</div>
</div>


# 3️⃣ 웹, 앱 인증 및 토큰 로직 통합 플랜


## 1. 방식 설정


---

> <strong>1. 웹과 앱을 같은 로그인 상태로 묶고 싶은가?</strong>
- 웹에서 로그아웃 → 앱에서도 자동 로그아웃
- 하나의 세션으로 관리
> <strong>2. 웹과 앱을 독립적인 로그인 세션으로 가져가고 싶은가?</strong>
- 웹과 앱이 다른 쿠키를 쓰도록 분리시킴

<span class="notion-color-blue"><strong>⇒ 2번 방안으로 확정</strong></span> 


## 2. 통합 규칙


---

1. 쿼리 라이브러리, 전역 상태 관리 라이브러리 통일

    : <span class="notion-color-orange"><strong>RTK Query + Redux</strong></span> <strong>VS.</strong> <span class="notion-color-green"><strong>Tanstack Query + Zustand</strong></span>

    - 웹에서 사용하는 토큰 관리 방식
        - zustand : accessToken, sessionReady
        - axios interceptor : 토큰 부착 + refresh
        - custom hook
    - 앱에서 사용하는 토큰 관리 방식

        ```plain text
        login mutation
          ↓
        onQueryStarted
          ↓
        setAccessToken(accessToken)
        ```

2. Middleware는 유지

## 3. 개발 플랜


---

1. accessToken 저장소 통일하기
2. 웹의 인증 API 단계 통일하기
    - 인증 API : login, refresh, logout
3. 세션 초기화 로직을 웹 + 앱 하나로 통합

# 4️⃣ 결론


---

> RTK Query로의 통합은 단기적으로 앱 구조와의 정합성이 높으나,   
> 이미 웹이 TanStack 생태계를 중심으로 확장되고 있는 상황에서는   
> 웹의 구조적 변경 비용과 장기 유지보수 리스크가 존재한다.
>
> 반면 TanStack Query 기준 통합은 앱의 마이그레이션 비용이 발생하지만, 
> 웹과 앱 모두에서 서버 상태 관리 패턴을 통일할 수 있으며 
> 모노레포 운영과 장기 확장성 측면에서 더 안정적인 선택지라고 판단했다.
>
>

###  Tanstack Query를 선택하게 된 이유


개인적으로 Tanstack Query가 선택하는 것이 더 좋다고 생각하였고, 이에 대한 나의 의견을 작성해보았다.


---

1. <strong>현재 웹에서 Tanstack Query뿐만 아니라 Tanstack Virtual, Tanstack Table을 사용 중</strong>
    - API 호출만 RTK Query를 사용할 경우, 프론트엔드 전반의 일관성이 떨어짐
    - TanStack Table의 필터/정렬 상태를 Tanstack Query의 키값으로 연결해 서버 데이터를 페칭하는 구조를 모노레포 전체에서 재사용하기 유리해짐
2. <strong>Zustand 용량 &lt;&lt;&lt; Redux Toolkit 용량</strong>
    - 앱 환경에서는 번들 크기와 메모리 관리가 중요함
    - 상대적으로 경량화된 라이브러리인 zustand를 사용하는 게 앱의 특성에 있어 적합함

    | 라이브러리 | redux-toolkit | zustand |
    | ----- | ------------- | ------- |
    | 용량    | 5.51MB        | 327KB   |

    - 앱의 기존 Redux 로직도 Zustand를 통해 점진적으로 단순화하면 전체적인 코드 베이스가 가벼워질 것으로 예상됨
3. <strong>모노레포에서의 코드 공유</strong>
    - 모노레포의 핵심 : <code>packages/api</code> 와 같은 공통 로직을 분리하는 것
    - Tanstack Query : API 요청 함수와 커스텀 훅을 순수하게 정의
    → 웹과 앱에서 그대로 import하여 유연하게 사용 가능
    - RTK Query : createApi로 정의된 서비스 객체가 Redux store 구성 방식에 강하게 결합
    → 플랫폼별로 store 구조가 다를 경우 공유 로직 작성이 까다로움

# 5️⃣ 참고


<div class="notion-bookmark"><a href="https://tanstack.com/query/v4/docs/framework/react/comparison" target="_blank" rel="noopener noreferrer"><div class="notion-bookmark-content"><div class="notion-bookmark-title">Comparison | React Query vs SWR vs Apollo vs RTK Query vs React Router | TanStack Query React Docs</div><div class="notion-bookmark-desc">This comparison table strives to be as accurate and as unbiased as possible. If you use any of these libraries and feel the information could be improved, feel free to suggest changes (with notes or e...</div><div class="notion-bookmark-url">tanstack.com</div></div><div class="notion-bookmark-thumb"><img src="https://github.com/tanstack/query/raw/main/media/repo-header.png" alt="" /></div></a></div>


<div class="notion-bookmark"><a href="https://junsangyu.gitbook.io/rtk-query/comparison" target="_blank" rel="noopener noreferrer"><div class="notion-bookmark-content"><div class="notion-bookmark-title">다른 라이브러리들과 비교 | RTK Query</div><div class="notion-bookmark-url">junsangyu.gitbook.io</div></div><div class="notion-bookmark-thumb"><img src="https://junsangyu.gitbook.io/rtk-query/~gitbook/ogimage/-MewVhfS0HXNoVwMZUQt" alt="" /></div></a></div>


<div class="notion-bookmark"><a href="https://medium.com/@uyijustindavid/rtk-query-vs-react-tanstack-query-a-comprehensive-comparison-for-frontend-developers-a2f431a8167b" target="_blank" rel="noopener noreferrer"><div class="notion-bookmark-content"><div class="notion-bookmark-title">https://medium.com/@uyijustindavid/rtk-query-vs-react-tanstack-query-a-comprehensive-comparison-for-frontend-developers-a2f431a8167b</div><div class="notion-bookmark-url">medium.com</div></div></a></div>


# 6️⃣ 번외


## ➕ 시나리오 : Redux/Toolkit + Tanstack Query


### 개요

1. 서버 상태는 Tanstack Query로, 클라이언트/전역 상태는 RTK를 사용함
    - 서버 데이터 : Tanstack Query를 통해 가져옴
    - UI 상태 / 전역 상태 (폼, 모달, 필터, 탭) : RTK에서 slice로 관리
2. <strong>Redux를 “전역 UI 상태 전용”으로 최소화</strong>
    - 서버 상태를 Redux로까지 끌고 오는 경우는 <strong>불필요한 boilerplate + 동기화 버그</strong> 발생 가능
    - TanStack Query가 이미 <strong>컴포넌트 레벨 캐시</strong>를 제공하기 때문에, 대부분 UI 상태만 Redux로 유지

```typescript
// Redux: filter 상태
const filter = useSelector((state) => state.ui.filter);

// TanStack Query: 서버 데이터
const { data: users } = useQuery(['users'], fetchUsers);

// 결합
const filteredUsers = users?.filter(u => u.role === filter);
```


<div class="notion-columns">
  <div class="notion-column"><h3>장점</h3>
<hr>
<ul>
<li><strong>서버 상태와 클라이언트 상태의 역할이 명확함</strong><ul>
<li>각 라이브러리가 잘하는 역할에만 집중 → 구조 이해가 쉬움</li>
</ul>
</li>
<li><strong>대규모 서비스에서 확장성 좋음</strong><ul>
<li>UI 상태는 전역으로 공유하면서도 서버 상태는 컴포넌트 단위로 독립적으로 관리 가능</li>
<li>팀 단위 협업 시 책임 범위가 명확해짐</li>
</ul>
</li>
<li><strong>불필요한 Redux boilerplate 감소</strong><ul>
<li>async thunk, loading/error 상태 관리 코드가 줄어듦</li>
<li>Redux는 순수 상태 관리에만 사용되어 코드가 가벼워짐</li>
<li>참고 블로그 : <a href="https://mkdiriandev.tistory.com/4">https://mkdiriandev.tistory.com/4</a></li>
</ul>
</li>
</ul>
</div><div class="notion-column"><h3>단점</h3>
<hr>
<ul>
<li><strong>상태 관리 도구가 2개라 러닝 커브가 있음</strong><ul>
<li>Redux Toolkit + TanStack Query 모두에 대한 이해 필요</li>
</ul>
</li>
<li><strong>Redux를 쓰는 이유가 약해질 수 있음</strong><ul>
<li>전역 UI 상태가 많지 않은 서비스라면 굳이 Redux 쓸 필요 X</li>
</ul>
</li>
<li><strong>역할 분리가 무너지면 오히려 혼란</strong><ul>
<li>Redux와 Query를 사용하는 기준이 없으면 상태가 중복되거나 책임이 섞일 위험 있음</li>
</ul>
</li>
</ul>
</div>
</div>


### 주의할 점

- Tanstack Query로 fetch한 데이터를 Redux store에 복사하지 말 것

    → 중복 캐시 + 상태 동기화 문제 발생 가능

- 명확한 역할 분리

## ➕ tanstack query + zustand 에서 전역 store 파일 하나로 공유하여 사용할 수 있을까?


```typescript
import { create } from "zustand";

const useStore = create((set) => ({
  count: 0,
  increment: () => set((state) => ({ count: state.count + 1 })),
}));

// 컴포넌트 어디서든
const count = useStore((state) => state.count);
```

> <strong>장점</strong>
- <strong>boilerplate 없이 전역 상태 생성</strong>
    - Redux처럼 <strong>Provider/Context/Reducer/Action</strong> 구조가 필요 없고, 단일 훅으로 상태와 수정 함수를 정의해서 사용 가능

        → useStore()를 호출하는 모든 컴포넌트는 <strong>같은 전역 store에 접근!</strong>

- <strong>selector 기반 구독으로 성능 최적화</strong>
    - Zustand는 selector를 지원하므로, 필요한 상태만 구독하여 <strong>불필요한 리렌더 감소시킴</strong>

## ➕ 쿼리 + 전역 상태 조합 비교


📍 작고 빠른 SPA / 팀 소규모 / 단순 UI 로직


    👉 <strong>TanStack Query + Zustand</strong> 


📍 중대형 앱 / 구조화된 전역 상태 필요


    👉 <strong>TanStack Query + Redux Toolkit</strong>


📍 대형 조직 / Redux 중심 아키텍처


    👉 <strong>RTK Query + Redux Toolkit</strong>




## <strong>💡 시작하기</strong>


12월 업무에서 약 2,000개에 달하는 발전소 데이터를 테이블로 렌더링하는 과정에서 심각한 성능 이슈를 겪었다. 이에 react-virtual을 도입한 경험과 공부한 내용들에 대해 적어보려고 한다.


## 1️⃣ react-virtual


> <span class="notion-callout-icon">💡</span> <span class="notion-callout-text"><span class="notion-color-blue"><strong>react-virtual</strong></span> ? 많은 요소의 리스트를 가상화하는 라이브러리</span>


여기서 말하는 가상화를 쉽게 말해본다면, <span class="notion-color-yellow_background"><strong>보이는 만큼만 그린다</strong></span> 라는 의미이다.


예를 들어 1000개의 데이터 중 화면 상에 20개만 보이게 한다면,
20개만 DOM에 올리고, 스크롤 위치에 따라 데이터를 바꿔간다는 뜻이다

> <strong>example code</strong>

```typescript
const parentRef = useRef(null);

const rowVirtualizer = useVirtualizer({
  count: rows.length,
  estimateSize: () => 48,
  getScrollElement: () => parentRef.current,
  overscan: 3,
});

const virtualItems = rowVirtualizer.getVirtualItems();
..
{virtualItems.map((row) => (
    <TableRow key={row.id} onDoubleClick={() => onRowDoubleClick?.(row)}>
      {row.getVisibleCells().map((cell) => {
        const cellContent = flexRender(
          cell.column.columnDef.cell,
          cell.getContext(),
        );
        return (
          <TableCell
            key={cell.id}
            className={cn(
              "h-12 overflow-hidden whitespace-nowrap border-0 p-3 first:pl-6 last:pr-6",
            )}
            style={{
              width: `${cell.column.getSize()}px`,
            }}
          >
            {cellContent}
          </TableCell>
        );
      })}
    </TableRow>
  ))}
```

- <strong>count</strong> : 전체 행의 수
- <strong>estimateSize</strong>: 행 하나의 높이
    - 실제 행의 높이와 크게 달라지면 스크롤 위치가 튀는 현상이 발생함
- <strong>getScrollElement</strong> : 어떤 DOM의 scrollTop을 기준으로 계산할지 지정
- <strong>overscan</strong> : 화면에 보이는 행의 수보다 더 렌더링할 행의 수
    - 스크롤할 때 지지직 거리는 오류가 발생함
    - 미리 준비해두는 버퍼 역할!
- <strong>useVirtualizer</strong> : 현재 스크롤 위치를 기준으로 지금 렌더링되어야 할 행 목록을 계산

## 2️⃣ 내가 도입한 방식 : react-virtual + shadcn/ui datatable

> <strong>기존에 서비스가 가지고 있었던 문제 상황</strong>
- 서버에서 몇천 개의 데이터를 한꺼번에 불러오는 상황
- 하나의 행에 들어가는 데이터의 종류가 굉장히 많음

⇒ 이 테이블이 있는 페이지를 새로고침하면 약 6-7초의 로딩 후 테이블이 보이게 됨


이 data-table의 형태를 유지하되, virtual scroll을 도입하기로 했다. virtual scroll을 도입하면 무한 스크롤의 성능과 비슷하게 만들 수 있기 때문이다!


<figure class="notion-image">
  <img src="https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F9b1af274-6edf-4f5c-b4c9-d8db23308ba6%2F6b5fb31a-96d2-4f3c-8418-2215994927b5%2F2026-01-186.50.20-ezgif.com-video-to-gif-converter.gif%3FX-Amz-Algorithm%3DAWS4-HMAC-SHA256%26X-Amz-Content-Sha256%3DUNSIGNED-PAYLOAD%26X-Amz-Credential%3DASIAZI2LB4664SZTTKNV%252F20260329%252Fus-west-2%252Fs3%252Faws4_request%26X-Amz-Date%3D20260329T073602Z%26X-Amz-Expires%3D3600%26X-Amz-Security-Token%3DIQoJb3JpZ2luX2VjED0aCXVzLXdlc3QtMiJIMEYCIQCRC7pK9ojpPYjL0iu9z2RjqjaTe4JZXjC8iQLqmUKIaAIhAJ6Prn2qvhIZBwZtImZQmS%252FzElKmimJnkCr826Hg5dFzKv8DCAYQABoMNjM3NDIzMTgzODA1IgxT57Q8rkTZd3B5RBkq3AOBIjDFqoY2EF5pfw0wZLT8TpbX6xqNvVIs2GGAkNX6pJI%252FO9Y5x2JMrUAY0JzYZ7mD5QxhFdyUMA127MVLmgSaDvEas%252Bemw94uLzFgdfOw3hp9A4NFXe9H%252F9KnlginhqVnouNFdPlOrLV%252FfBcfYxLJetmlXwjZAb14bxSALfIFwLjaPk38DJY5AQhbabeXcmiXOFe9n4Wai9uu1En9SxVO6P7vvD5txRcNUFRSHPJ96Kp6EoWND1XZDki2MbRfLMXt5s6F2%252FTsFep954LiYc5xwR1HgQ2f%252BiEBLeuG%252Bq%252FCGFrlhV60YV99XKzFx3vUUQbKD7UHU3iFHvqMQh77lgFIpTWvcD6M9Yn4nofEThFqKWEBmuwCS6KCpAF7SuAm7j7qwKez4eR%252FyM7D2eoY9Y1xM7Ziz9dk9jBxO9kmZQORQl%252FxhgIR1leKI3lZyW9S4m4HT%252F7R0iRowK%252B9UBE%252B143AMnqDptvlIklN5hCw6bQRFbhLNkwvEgS3yu5Sgj%252FCDnbVWROzSRl45xQ7F8%252BSx4mhKIrJun6AcIG9sBHHLG%252B8xsEFcL09zG6%252BAlY4mOa0Ki2%252BXq6qgGFAHT8bWD4FAJrWzcc58ve2zAujzGNQ2upir%252FsEVgV2DnANcnqznjCy4KLOBjqkASGXdGZZNmhhMKuHW5UXEag6JxzODuLUPXgQBKFi%252FycSwKBWIdUmlw9oUtaHUDYfnsBbR33I2qAQ3vlUWEyDoTILTk6010MBarHDgyZR4Sx2h9TrknFAAbatlYnb0DGnqYFBe2KLa97qVqMASNwDwqKOQM0xFF5jMtzGjZiIHtHK4Almmdrm223gGawc5w4LKSVP5pDEv2%252Bi%252BPsbI1Wl7tk1p1Wt%26X-Amz-Signature%3D0c76b0ee5b11a0f7019098646c04e3a3b94b222649e3e59785a70ead8ffc90ac%26X-Amz-SignedHeaders%3Dhost%26x-amz-checksum-mode%3DENABLED%26x-id%3DGetObject?table=block&amp;id=2ec7763d-d03a-80f6-b690-ffdc3685e9a3&amp;cache=v2" alt="" />
  
</figure>


기존에는 한 번에 모든 리스트의 행이 렌더링되었었지만
virtual scroll을 도입하면서 정해진 개수의 행만 렌더링되고 있다.


기존에는 행의 개수가 1,234개 라고 하면 DOM에 있는 행의 수는 1,234개였지만
virtual scroll을 도입한 지금, DOM에 있는 행의 수는 22개로 확연히 줄어들었다.


## 3️⃣ 성능 결과


왼쪽이 Before, 오른쪽이 After다


<div class="notion-columns">
  <div class="notion-column"><figure class="notion-image">
  <img src="https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F9b1af274-6edf-4f5c-b4c9-d8db23308ba6%2Ffb351e58-9296-4e7c-b358-458433009126%2Fimage.png%3FX-Amz-Algorithm%3DAWS4-HMAC-SHA256%26X-Amz-Content-Sha256%3DUNSIGNED-PAYLOAD%26X-Amz-Credential%3DASIAZI2LB4662OVFRN7M%252F20260329%252Fus-west-2%252Fs3%252Faws4_request%26X-Amz-Date%3D20260329T073608Z%26X-Amz-Expires%3D3600%26X-Amz-Security-Token%3DIQoJb3JpZ2luX2VjED0aCXVzLXdlc3QtMiJHMEUCIQDQrHdnQkIX0T8duBlpr84gwzrUIrkSCA85PZiz0lWzOQIgWWQUC3rKpmiCFRwnZp7jym4K44vu4ngcsvQ6%252Bmi3%252FhAq%252FwMIBhAAGgw2Mzc0MjMxODM4MDUiDD4Ypripa1DpSMP1zircA5mXYkL4hNP4vMKBQpxuwy8%252FeUl%252FYU3vSQcRRPvTvVuXqGFf3YBZHLGu4qLh3SRAgdD6WFQvML0uCJFb2DCo%252FLLgYSJ65SLNJIXnNiF8x0GKdZLiEXCQdevtM7M1mOw3fUWORLmpbFR2U7Hqyuju5%252FJjbfaakfWzobBkMEAXXy9aUdT%252F1vJTP6L2xxkzoLqZDUKkEC3oqdkeE%252BVcYmL%252FSSX15jVfgvlkw6nj1wFV3PmZOJLogb%252BoqcZ%252BD%252FGD32wrYYlnJ9cqHl4WVtXEfD2dkKYxWuuj%252BBmBZCOjsrMah9i5VwePMIw%252FHCjDj9CFKzkgekaqHbqc1soPWaxR6kSI3uaXAHguo5uLeO%252FmCIn1TWppHG0VYHR%252FOAs5mWC7sEuWxSL9W8Yblgby1qurRzEkEWStmZ37fCAOy3smIoc%252BSl3FuB%252BOLeLg5Y6oqbGSgRRniOt%252BTDUK08Qv6TitwHXIcc7WsNl%252FhfOKRQc37vVKd14c1y%252FNdSDC5SQ5DK%252BYydUUmgCpgacX2qXHOEgnsdh0pXC%252BVTw2TL2PpGmtVuTljWqHMQIdYu%252BrZa2wu02oX40IQgGsLlvuBcbcDj9FUngNsArNOmIIQBM3bxf2Hn3OjxF%252FQHXcNI%252BGnEEVFVaRMIvgos4GOqUBwe1%252BWU0vFf0TT2iS5eS0kEjAfIaYCyrW1YIabpO%252BYsY7mmE45PO2ieS156eJCd8kgA5cfzBFQ%252FBoiBXoaEWx2ha0B4btrPj0PtDJfn%252FGbLy1jfYNT05cXHgkyvRHraqigcPJwYNvU1%252BMAbK8q7XxiRnBVHHB0Z%252B4oF%252FXIcP4T%252BImf6Frz7hdqX6%252FCSlvWAA3Mx6QUNs92a9jiVIwrI2Ze57LmN5L%26X-Amz-Signature%3D7eaef5614d3436f7468f33446868ea46e2dda5d2f29e3ddf04e2ae723089fe4c%26X-Amz-SignedHeaders%3Dhost%26x-amz-checksum-mode%3DENABLED%26x-id%3DGetObject?table=block&amp;id=2ec7763d-d03a-8015-97bc-ddbb482bf12a&amp;cache=v2" alt="" />
  
</figure>

</div><div class="notion-column"><figure class="notion-image">
  <img src="https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F9b1af274-6edf-4f5c-b4c9-d8db23308ba6%2F6daf2938-1cfa-4a35-97c1-9dd2ba9537b4%2Fimage.png%3FX-Amz-Algorithm%3DAWS4-HMAC-SHA256%26X-Amz-Content-Sha256%3DUNSIGNED-PAYLOAD%26X-Amz-Credential%3DASIAZI2LB4666Z6URCJ5%252F20260329%252Fus-west-2%252Fs3%252Faws4_request%26X-Amz-Date%3D20260329T073607Z%26X-Amz-Expires%3D3600%26X-Amz-Security-Token%3DIQoJb3JpZ2luX2VjED0aCXVzLXdlc3QtMiJGMEQCIDSCaYnjMMUGBiP4RRIloE236%252FIO550sS%252F%252FJYzrXGc8SAiB6SSaOK7k%252FXLufWto7eIWvj%252FTSQwb2bcl4Nen9wRpU5ir%252FAwgGEAAaDDYzNzQyMzE4MzgwNSIMOnpKoM6JMwPajstsKtwDiuwkFoaOdNsDbDeZJIKuK0KoiJ3fX%252FlTFd53F4ib0WHOgIXN304P%252B9uSjBaj3B7sEJCWK%252FyUgOvRMcUH4BBuQ2BeA3IoV6aFaTAnIlZPShQ1mDfLidIW5ujYIQ%252B130MdnAbQmqA6QbTuNGwtSPN9ig%252BEn3SxMOoxsCkAPZPdOgL6reDCibD8Z0DixXiLHqEHKCkvHNo5pjQv%252FOkaeMTjRA7P1eV5ZC9U4%252B1FEz1PpUMxzO0Dbii917BFcXyAtA8JQsIFya%252BI45d2Jof%252FvATG3a77%252FdEkEtube5LjV7993H8B7MZ7QQzT8UXZzw95gG2O6BOsK1sotDICN0PXRPxty2xa1T%252F4TZmYEDNcsdrHPBYGmYPlfUZRgXPWTeeSazVJQ2CSgw8zBpVED7XTIZUDaeby82D1IisxJ5u2BN8h2ojUcJA%252B%252BL%252B%252BCcVPIz5VNMxGKHW2SzNMCdkcWwSpSgLmKRQGgmaikjArvmhzs3mPj092cYrB0QEBtIgmLxbHwHczCR482aTIcZhF8oeKnwFXCIpGlrf%252BrwxBzgXMtWCu6dxZtjDGj8WbuRlgvOvF9ZSw0X4iw0%252F16XQFVhtlR8weENzCS1qZeHAZDERVU9nsus4O8z7D3r7Fwd13LX4w5%252BCizgY6pgGWd4Fb14BcCTnarbE2GppKfxHN5fyCartPk%252B82RXqoQWYtcHzUYEsg%252B2G6GM2mm7TwsBeYEp47ks97OJs5NSZvGjjXV%252Fd%252B4k%252FiOmJlAeOC6Tk1hwtlpGYeSzQNXEbaMdM3A9Tfzl0uQn6zEUHPHSxmoCDlgeEpN7nWpEo7HdXFj1yVG0dpQbsH3MdF3c%252BgS7YbRCoQMPBUp8ZwlHTjGFyDu8vhQFsD%26X-Amz-Signature%3D599cf89395aa3f79bcd92c843bf708f850e24af08b8d3061939b5a810bed3e89%26X-Amz-SignedHeaders%3Dhost%26x-amz-checksum-mode%3DENABLED%26x-id%3DGetObject?table=block&amp;id=2ec7763d-d03a-801f-a117-c8a7172ebc7d&amp;cache=v2" alt="" />
  
</figure>

</div>
</div>


수치로 확인한 결과, 개선 폭은 예상보다 훨씬 컸다..


<div class="notion-columns">
  <div class="notion-column"><blockquote>
<p><strong>렌더링</strong></p>
</blockquote>
<ul>
<li>350ms → 39ms</li>
</ul>
<p>⇒ 약 89% 단축 시킴</p>
</div><div class="notion-column"><blockquote>
<p><strong>페인팅</strong></p>
</blockquote>
<ul>
<li>50ms → 24ms</li>
</ul>
<p>⇒ 약 52% 단축 시킴</p>
</div>
</div>


스크립트는 1ms에서 410ms 증가했지만, 가상화 로직이 추가된 자연스러운 결과이다. 기존에 브라우저 레이아웃이 담당하던 작업들이 JS 영역으로 이동한 것으로 해석될 수 있다.


결과적으로 DOM 노드 수가 대폭 감소하며 reflow/repaint 병목이 해소되었고, 대용량 테이블에서도 안정적인 UX를 제공할 수 있게 되었다.


## 📝 정리


이번 작업은 처음으로 ‘성능’이라는 관점에서 프론트엔드를 바라본 경험이었다. react-virtual을 적용하며 DOM 구조가 성능에 얼마나 큰 영향을 주는지 체감했고, 단순히 기능 구현을 넘어 렌더링 방식 자체를 설계하는 과정이 중요하다는 걸 배웠다.


특히 2,000개 이상의 데이터를 다루는 실무 환경에서 렌더링 시간을 대폭 단축하며, 대량의 데이터를 사용해도 쾌적한 UX를 제공할 수 있다는 자신감을 얻었다.!!


## <strong>🔗 참고</strong>


<div class="notion-bookmark"><a href="https://tanstack.com/virtual/latest/docs/framework/react/examples/table" target="_blank" rel="noopener noreferrer"><div class="notion-bookmark-content"><div class="notion-bookmark-title">React TanStack Virtual Table Example | TanStack Virtual Docs</div><div class="notion-bookmark-desc">An example showing how to implement Table in React using TanStack Virtual.</div><div class="notion-bookmark-url">tanstack.com</div></div><div class="notion-bookmark-thumb"><img src="https://github.com/tanstack/query/raw/main/media/header.png" alt="" /></div></a></div>


<div class="notion-bookmark"><a href="https://jobkaehenry.tistory.com/62" target="_blank" rel="noopener noreferrer"><div class="notion-bookmark-content"><div class="notion-bookmark-title">[@tanstack/react-virtual] 대형 리스트 최적화하기</div><div class="notion-bookmark-desc">React-virtual? React-virtual 라이브러리는 Tanstack 이라는 단체에서 관리되는 DOM 가상화 라이브러리이다. 리액트의 옛 공식문서에서 확인할 수 있 듯, 거대한 크기의 리스트를 화면에 랜더링할 경우, &amp;quot;가상화&amp;quot; 라는 방법을 통해 최적화 하는것을 권한다. 사용 필요성 모든 SNS 에 필수적으로 들어가는 기능인 무한 스크롤 (Infinite scroll) 은 무한 스크롤은 웹 페이지에서 사용자가 스크롤을 내릴 때 자동으로 추가 콘텐츠를 로드하여 페이지를 끊임없이 확장하는 기술로, 스크롤을 끝까지 내리면 새로운 콘텐츠가 동적으로 로드되어 사용자 경험을 향상시킨다. 또한 페이지 이동 없이 사용자가 머무는 시간을 늘려 사용자 유지율을 향상시킬 수 있어 웹 어플리케이션에 자주 사용되는 기..</div><div class="notion-bookmark-url">jobkaehenry.tistory.com</div></div><div class="notion-bookmark-thumb"><img src="https://img1.daumcdn.net/thumb/R800x0/?scode=mtistory2&amp;fname=https%3A%2F%2Fblog.kakaocdn.net%2Fdna%2F65wF1%2FbtsDkESgAyS%2FAAAAAAAAAAAAAAAAAAAAAMvn8pDs6fjuWydSEVcKm-lI7HXv4AmI8SxCdAGPi3FY%2Fimg.png%3Fcredential%3DyqXZFxpELC7KVnFOS48ylbz2pIh7yKj8%26expires%3D1774969199%26allow_ip%3D%26allow_referer%3D%26signature%3DWL0LnOjrbER01NKms7H8XE%252BHaZ8%253D" alt="" /></div></a></div>




## 📌  Gemini code assist


> <span class="notion-callout-icon">📌</span> <span class="notion-callout-text"><strong>새로운 PR이 올라가면 코드를 리뷰해주는 AI 어시스턴트</strong></span>

- 새로운 PR이 올라가면 5분 이내에 summary, review 제공

| <strong>특징</strong> | <strong>명령</strong>          | <strong>설명</strong>                       |
| ------------------- | ---------------------------- | ----------------------------------------- |
| 코드 검토               | <code>/gemini review</code>  | 현재 상태의 풀 리퀘스트에 대한 코드 리뷰를 수행합니다.           |
| 보도자료 요약             | <code>/gemini summary</code> | 현재 풀 리퀘스트의 현재 상태에 대한 요약을 제공합니다.           |
| 논평                  | @gemini-code-assist          | 이슈 댓글과 리뷰 댓글 모두에서 명시적으로 태그된 경우 댓글로 답변합니다. |
| 돕다                  | <code>/gemini help</code>    | 사용 가능한 명령 목록을 표시합니다.                      |


## 📌 동작 맞춤설정

> <strong>.gemini/config.yaml</strong>

: 무시할 파일을 지정하는 등 사용 설정하거나 사용 중지할 수 있는 다양한 구성 가능한 기능이 포함된 파일


```yaml
have_fun: false # 재미/창의적 응답 비활성화
code_review:
  disable: false # 코드 리뷰 활성화
  comment_severity_threshold: MEDIUM # 이 수준 이상만 댓글 남김
  max_review_comments: -1 # -1이면 리뷰 댓글 개수 제한 없음
  pull_request_opened:
    help: false # PR 생성 시 도움말 자동 게시 안 함
    summary: true # PR 생성 시 요약 게시
    code_review: true # PR 생성 시 코드 리뷰 실행
    include_drafts: true # 드래프트 PR에도 적용
ignore_patterns: [] # 무시할 경로/패턴 (빈 값이면 없음)
```

> <strong>.gemini/styleguide.md</strong>

코드 검토를 실행할 때 따라야 하는 특정 규칙을 Gemini Code Assist에 안내하는 마크다운 파일


```markdown
# Gemini Code Assist Style Guide

## Language

Please provide all code reviews, summaries, and help messages in Korean (한글).

# Introduction
This style guide outlines the coding conventions for TypeScript code developed at Company X.
It's based on common TypeScript + ESLint/Prettier practices, with a few adjustments for our
organization.

All code changes must also follow the conventions defined in [CODE_CONVENTION_AGENT.md](CODE_CONVENTION_AGENT.md); treat that document as mandatory alongside this guide.

# Key Principles
* **Readability:** Code should be easy to understand for all team members.
* **Maintainability:** Code should be easy to modify and extend.
* **Consistency:** Adhering to a consistent style across all projects improves
  collaboration and reduces errors.
* **Performance:** While readability is paramount, code should be efficient.

## Line Length
* **Maximum line length:** 100 characters (align with Prettier default when possible).
    * Modern screens allow for wider lines, improving code readability in many cases.
    * If a line naturally exceeds 100 (e.g., long URLs), prefer breaking lines with clear continuations.

## Indentation
* **Use 2 spaces per indentation level.**

## Imports
* **Group imports:**
    * Node/DOM built-ins
    * Third-party packages
    * Internal aliases
    * Relative paths (`../`, `./`)
* **Use path aliases** where configured (e.g., `@/`), otherwise prefer relative paths that minimize `../`.
* **Import order within groups:** Alphabetical; keep type-only imports separated using `import type` when applicable.
* **Avoid default exports** unless a module has a single clear export; prefer named exports for clarity.

## Naming Conventions

* **Variables and functions:** camelCase: `userName`, `totalCount`, `calculateTotal()`
* **Constants:** UPPER_SNAKE_CASE: `MAX_VALUE`, `DEFAULT_TIMEOUT_MS`
* **Classes, types, interfaces, enums:** PascalCase: `UserManager`, `PaymentProcessor`, `User`, `UserRole`
* **React components:** PascalCase for component names and file names when a file exports a single component.
* **Files and modules:** kebab-case for general utilities (e.g., `user-utils.ts`), PascalCase for single-component React files.

## Documentation Comments
* **Use JSDoc (`/** ... */`) for exported functions, classes, and complex public APIs.**
* **First line:** Concise summary of the object's purpose.
* **Detail:** Add `@param`, `@returns`, and relevant tags (`@throws`, `@deprecated`) when helpful.
    ```ts
    /**
     * Formats a price with currency symbol.
     * @param amount Amount in minor units (e.g., cents)
     * @param currency ISO currency code
     */
    export function formatPrice(amount: number, currency: string): string {
      // ...
    }
    ```

## Types
* **Prefer explicit return types** for exported functions and components; allow inference for local helpers when clear.
* **Use `type` aliases for data shapes and union types**; use `interface` for public contracts that may be extended.
* **Favor `readonly` and `as const`** to express immutability where useful.
* **Avoid `any` and `unknown`** unless absolutely necessary; prefer precise types or generics.

## Comments
* **Explain the why, not the obvious what.**
* **Use JSDoc or block comments for non-trivial logic; keep inline comments short.**
* **Comment sparingly; favor readable code and clear naming.**

## Logging
* **Use structured logging or a shared logger utility** when available; avoid scattered `console.log`.
* **Log at appropriate levels:** debug, info, warn, error.
* **Provide context:** Include identifiers (userId, requestId) to aid debugging.

## Error Handling
* **Throw specific errors** with meaningful messages; avoid catching all errors unless rethrowing with context.
* **Narrow `try/catch` blocks** around code that can fail; handle recovery paths explicitly.
* **Propagate errors** with context (`new Error("Invalid state: ...")`) and avoid silent failures.

# Tooling
* **Code formatter:** Prettier (project defaults). Do not hand-format around Prettier.
* **Linter:** ESLint (project config). Fix lint errors; do not suppress without a clear reason.
* **Type checker:** `tsc --noEmit` for CI/local checks; keep the codebase type-clean.
```


## 📌 리뷰 방식


gemini-code-assist의 가장 좋았던 점은 피드백의 우선순위 뱃지를 함께 달아
어떤 점을 더 빨리 수정해야하는 지를 명확하게 알 수 있었다!


시험 삼아 테스트 해본 PR에는 많은 파일이 수정되지 않았지만 생각보다 세세하게 달아줘서 너무 좋았뜸 ㅎㅅㅎ


내 프로젝트에 조금 더 확실한 코드 컨벤션 같은 게 잡힌다면, 이를 제미나이에 적용해보고 싶다. 그렇게 하면 내가 원하는 코드 리뷰의 방향이 나올 수도 ?!


<div class="notion-columns">
  <div class="notion-column"><figure class="notion-image">
  <img src="https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F9b1af274-6edf-4f5c-b4c9-d8db23308ba6%2F26728c8e-a5d5-43a7-8720-e5c5e5122a71%2Fimage.png%3FX-Amz-Algorithm%3DAWS4-HMAC-SHA256%26X-Amz-Content-Sha256%3DUNSIGNED-PAYLOAD%26X-Amz-Credential%3DASIAZI2LB4667YVJ6HSI%252F20260329%252Fus-west-2%252Fs3%252Faws4_request%26X-Amz-Date%3D20260329T073653Z%26X-Amz-Expires%3D3600%26X-Amz-Security-Token%3DIQoJb3JpZ2luX2VjED0aCXVzLXdlc3QtMiJHMEUCIQDYZdGcAPMLcO5z6rqkHvs8LN%252FFMItHujKB9OAiMZoC0QIgIv3aaHqfhkD%252BBxX9U9OuJga1vifFInZxSesq6gbHiokq%252FwMIBhAAGgw2Mzc0MjMxODM4MDUiDE1s%252FgEH9Cwz4UAL8yrcA0wDEhXO6f%252F6ha2i3YEgqmGwttFcluncZqdU4%252Blfwix5Xp51STvCUM3LcTZJKfU%252Fwy7H1ypyZv2t31qfcpF4BALPzGM0%252Bdo%252FlArUDtxdr27ZDUa3lnOSNrHCys%252Fv1sZ5tHcmVTWvQET9LrGZzjFhU9ikHTE%252BP0DAekIx2Gpo6x0ih2nXuxU8gQ5y6XmJjhY5IBQjkW46qeu6EHe%252B1fW66177khcqA4vR06L2UEBOYaXzzYWeTinH2bd%252BgVISNPaWlaH8A0YR2XHtwXg3gkwrqlFNw0CWK73AOHcF%252BmBaKSSeWPcj8CfcUYCQ3zsKEnpinRYZFk0OWPJIrpNmp39r%252Fva8gDkciwr7Gp9PmPt38ja59LfKN5XwzNAgRUtsX9pgj8zdbiwAztAM%252FuTYghqFgxhN1hZ%252Bftts9XBkTIAKn7WRTX%252FRqZm1FU3o10vX7FDl1KMYbwRYqsfmORdfp7sHlCxVp4vFrLafcaByPDDpGJTi7%252B%252FLSR8X7ryF7%252BrIslPG8o6jb0dGBEoTKG1cTSG7L5ZKFE6x1AHLW2SEeVnbegtYoQWUcR3asfpMcU9iL7oMFUWF9xNKvr1WmovcId7M%252B7cBbB9HcLknfUmG%252BMp2mUFNMkpelYtm7rWvWs7mMJDgos4GOqUBrzIbh3P%252BR5%252BCWVVmEwc4CKCKQ1Okw636cR%252BkKpJouKpbxXPpYBGSRk%252Bu5PIdXH3paBzszEY0uZqVT8g0vBeZUQXRMSSTZ6hsaSvjTCoV4f2IEO1Pl4ZtCPUBG8cOqFyQBgyMvCnpRGmQJqJvZtTcKaXU2%252F6EwEhVqa6Ff4Sa6YShxDMryqb81PrjWLGdMTHyh%252FKDKPckUdHW8kO4GPmAucONQ%252B1X%26X-Amz-Signature%3D39a69322eb57dafd213879dae8ec2c1fda774e1d6d64fdda16c0b5194249fb3e%26X-Amz-SignedHeaders%3Dhost%26x-amz-checksum-mode%3DENABLED%26x-id%3DGetObject?table=block&amp;id=2ec7763d-d03a-80b4-a035-daa52f03f556&amp;cache=v2" alt="" />
  
</figure>

</div><div class="notion-column"><figure class="notion-image">
  <img src="https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F9b1af274-6edf-4f5c-b4c9-d8db23308ba6%2Fff8723ff-47ca-4030-bb6e-83f9a239895c%2Fimage.png%3FX-Amz-Algorithm%3DAWS4-HMAC-SHA256%26X-Amz-Content-Sha256%3DUNSIGNED-PAYLOAD%26X-Amz-Credential%3DASIAZI2LB466YULBYLQJ%252F20260329%252Fus-west-2%252Fs3%252Faws4_request%26X-Amz-Date%3D20260329T073651Z%26X-Amz-Expires%3D3600%26X-Amz-Security-Token%3DIQoJb3JpZ2luX2VjEEAaCXVzLXdlc3QtMiJIMEYCIQC9O9uyNc9VBu71YmJZYUMRGCf00V%252BkZDSTNstGUskFTgIhAJK2wMshiopN0ZSogjLClN%252BN04ZQMFLxOeSglVxQ5r3kKv8DCAkQABoMNjM3NDIzMTgzODA1Igz6uKYQIDcwrGJabCAq3AOwm2KaJMC1JsIcwHIMngBauTpKdBwmRjXCIxezaTzpW%252F5bPA9JtmhLwi8Hx85KKeOwz4md2IHdL%252Bn46y7Sv8SKkyVYklD2q2ZE%252FnXBwYEgX2dZHXqXF2ITE4zaKXXdvkgtPNmKzpnaqOHaxPrsCk%252BiliwDlY7RtppVi1s%252FYvi4FK5TgRnVqudMdeo6r2yzInJgtt2rlBUiEr50qDHlPgxNXcywkge%252BfvKXLjsJNeiOrWRi5cx4I09vcK4eV9pTF2YvZM89VZTh%252FNXei7Vc9TH%252FRiJ20NNUEnDfu5ld%252FWvR30PxmEn9Tg5xZgSD04GFq%252F%252F9HCXpf%252BO2riSePoj%252BobKRMWtZ%252BZfEA1UEVqiXzvgyfXecB0HKLYRFijEpG5iSCDUWDADA34hgIL2KNEW26fGV7R2zLL5%252F3xow%252Bbq5vnfA%252FCyTWixKguksrUlaJio3Fv0ex2%252BeeK%252FYr9JTgpWZ4enIZxO%252Bt3RHM3Wg5INl3D669br2oW3wv8WQkbz5xKJ0v3yLz%252FPvoZzjoog77ZC3LMs1KNP5TFuVLPP2IVO3%252FebXeASGUv5ebdFssfanbkISpw3gGX4jF9Dd76m%252FixpJ7ruStOZNsfMD1p8gCW361yCjuhO6GDziK76CFIzPwjDOrKPOBjqkAWjpyeemlfxjb%252FT8nAt4wlYbhM%252FIy47r0Tapt073FqndRsis1nf%252FnOivp88poz3Jdor7ikqKLlc7resOKUiPOrsq10O3eJCQ6RHZGuN54QmPfEBUYtIoLDBlkG%252FDvRwSveOkl1%252F8vlMuoq5xe%252FIhm0InpwU3zarbqkrbPGtU0j5NLfxI47iwyvxY%252BBJ6gW%252FjgfTXDR8TMmg3fBEBdOO3%252B2SCAGSy%26X-Amz-Signature%3D3a09102c6ed0c7ccc6e2a5c6f1258d3cb71c595b214e71d45af3dfe533e6c846%26X-Amz-SignedHeaders%3Dhost%26x-amz-checksum-mode%3DENABLED%26x-id%3DGetObject?table=block&amp;id=2ec7763d-d03a-80fc-b3a8-f215f7f7aafc&amp;cache=v2" alt="" />
  
</figure>

</div><div class="notion-column"><figure class="notion-image">
  <img src="https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F9b1af274-6edf-4f5c-b4c9-d8db23308ba6%2F8cbca17c-c058-4aba-89a4-e86279d43295%2Fimage.png%3FX-Amz-Algorithm%3DAWS4-HMAC-SHA256%26X-Amz-Content-Sha256%3DUNSIGNED-PAYLOAD%26X-Amz-Credential%3DASIAZI2LB4663ZVJM2AJ%252F20260329%252Fus-west-2%252Fs3%252Faws4_request%26X-Amz-Date%3D20260329T073649Z%26X-Amz-Expires%3D3600%26X-Amz-Security-Token%3DIQoJb3JpZ2luX2VjED0aCXVzLXdlc3QtMiJIMEYCIQDos8HlT7rzM42tBv%252FVawA5RsVoW4QKxmajcSSn%252BEoNXQIhAI5BCJl9fdmaKGKw%252FL48xhqN4NvTA1i1f%252Ft%252FnP9XdmaQKv8DCAYQABoMNjM3NDIzMTgzODA1Igx%252F66ADFFSVZSf5j0Iq3AMWFT7OdjdZged8b%252BaAY5mzfz8fRrTOFnCAdAH7yw9zddmJbzwyqrtk7yWyXyO2V%252B884UgAveUqccYz%252BAjQQbIlmjlKrI9Fmr4nrgU05K1wZSi6bOQAZMLRwjUUwoALcFmRQYsZ2QoOdwLQc8nC%252F2RFW3dFnIixrfxSJpOIDtPzc5nQXyUEwO1S2Z0KKPpW8GC4NB5oG%252FezyuHmgTApHK0mB8h5P1DVFDxCJeKdvKV7FYLfo8WARBXLm%252FZo7BtGH2aSYt7zujvIbx6SFPtrdmwH9WUUwqx%252BPFxu8f60CGwwysMEt7ywcS5huCTrG7shF7Y9Eu7Ll3U7omdmNqUZwy5PMuh0KmDP4F32sVTXJlsnaZAU8itmiJFUfhOw4LAbGu%252BP03HB1GqtFTXJJu8fIM6fEO%252BGtnSGMGcK1sUUxvWXWhqwe1%252B8Yqfdi%252BQdkESR8iF7x709PN0uHF7hf1qpxKJtWtIU3xSK0NXh7Y53eNJRwabgOnwP94yz%252BZZu93We9UYtnY7CBRLUCm9wfRpN5ZKDdGXg8dpt3XOEyOAEOfCs5pFzr%252BTg3cvgE4TBKvuke6TADT%252FaUyIrNcIJIzgcnwybgiMCX4BnMZHAC2Gl%252FnJF2edIaju%252BqlmYXPuuYjDx36LOBjqkAbKny9ld8f2T%252FKGWqkcxm4zSkbK09CVJH8L9oqnVvCbho1FSlruumJNfagKvqT8Hdpb%252FhueqDmnziJbstIsly5JwECkkOgehAkYNdqSVPusLux0vgunTkC9WXRsHUejB7Jkwojnn2pn5yfUtm0HsmwOw0%252FB0AtJ4CaPkPP2iK4mnnpMaHaQ2nsHrefdpiSbfSxGdF5KqkCLvxlpuxEhmKlF73lqU%26X-Amz-Signature%3Daad2869388f2b164a015b10ac6de86f948609eeb5fff1c526a529483d65dd435%26X-Amz-SignedHeaders%3Dhost%26x-amz-checksum-mode%3DENABLED%26x-id%3DGetObject?table=block&amp;id=2ec7763d-d03a-8078-98e8-d5bbf95aec54&amp;cache=v2" alt="" />
  
</figure>

</div>
</div>


## 📌 참고 


<div class="notion-bookmark"><a href="https://github.com/marketplace/gemini-code-assist" target="_blank" rel="noopener noreferrer"><div class="notion-bookmark-content"><div class="notion-bookmark-title">Gemini Code Assist - GitHub Marketplace</div><div class="notion-bookmark-desc">Bring the power of Gemini to the pull request process</div><div class="notion-bookmark-url">github.com</div></div><div class="notion-bookmark-thumb"><img src="https://opengraph.githubassets.com/036048fd48b0213601f6c8cadd938c5a97c3d9e75267bae309e5c88e7f60d7d4/marketplace/gemini-code-assist" alt="" /></div></a></div>




## 💡 <strong>시작하기</strong>


함수 하나 만들 때마다 “이거 utils에 넣어야 하나? lib인가…?” 이 고민을 진짜 백 번쯤 하다가 이것저것 찾아보았다. 근데 솔직히 말하면, 찾아봐도 처음엔 잘 이해가 안 됐다. 일단 최대한 <strong>내가 이해한 기준으로</strong> 정리해보겠뜸


<strong>utils vs lib, 매번 헷갈려서 정리해봄 ㅎㅅㅎ 언젠간 또 찾아볼 미래의 나를 위해 작성해보아요</strong>


---


### 1️⃣ <strong>utils</strong>


> <span class="notion-callout-text"><span class="notion-color-blue"><strong>utils</strong></span> ? <strong>유틸리티 폴더</strong>, 특정 기능이나 모듈에 속하지 않고 작고 일반적인 함수들을 모아두는 곳</span>


보통 아래와 같은 함수들이 들어간다

- 날짜, 숫자 포매터
- 정렬, 파싱
- 단순 값 가공 함수

입력값을 받아 가공한 뒤 결과만 반환하는, 상태를 갖지 않고, 외부 API를 호출하지도 않으며, 
비즈니스 로직과도 크게 엮이지 않는 수행하는 함수들을 이 폴더에 넣는다.

> <strong>예시</strong>

```typescript
// utils/formatDate.ts
export function formatDate(date: Date) {
  return date.toISOString().slice(0, 10);
}
```


```typescript
// utils/sortByDate.ts
export function sortByDate<T extends { createdAt: string }>(list: T[]) {
  return [...list].sort(
    (a, b) =>
      new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime(),
  );
}
```


<strong>특징</strong>

- 입력 → 가공 → 출력
- 외부 의존성 없음
- 비즈니스 맥락 없음

---


### 2️⃣ <strong>lib</strong>


> <span class="notion-callout-text"><span class="notion-color-blue"><strong>lib</strong></span> ? 라이브러리 폴더, 체계적으로 구조화되어있고 재사용 가능한 코드가 저장되는 곳 </span>


<strong>utils보다 한 단계 위의 개념이라고 보면 된다.</strong>

- 특정 문제를 해결하기 위한 함수/클래스 묶음
- 내부적으로 여러 유틸 함수를 조합
- 경우에 따라 독립 패키지로 분리해도 될 정도의 단위

특징은 다음과 같다.

- <span class="notion-color-pink_background">외부 라이브러리</span>를 감싸서 사용하는 코드
- <span class="notion-color-pink_background">특정 기능</span>(인증, 결제 등)을 담당하는 로직 집합

utils에 있던 함수들이 많아져, 하나의 역할군이 되면 lib으로 옮기기도 한다.

> <strong>예시</strong>

```typescript
// lib/authClient.ts
import axios from 'axios';

export const authClient = axios.create({
  baseURL: '/api',
  withCredentials: true,
});
```


```typescript
// lib/tokenManager.ts
import { authClient } from './authClient';

export async function refreshToken() {
  const res = await authClient.post('/auth/refresh');
  return res.data;
}
```


<strong>특징</strong>

- 특정 기능(인증)을 담당
- 외부 라이브러리(axios)에 의존
- 여러 로직이 하나의 목적 아래 묶여 있음

---


### 3️⃣ <strong>구분 기준 (개인 견해…)</strong>


일단 나는 다음과 같은 기준으로 utils, lib 폴더 중 어디에 저장할 지를 결정하였다!

- 함수 이름만 보고 바로 역할이 보이면 → <span class="notion-color-blue_background"><strong><code>utils</code></strong></span>
- 특정 기능의 일부처럼 느껴지면 → <span class="notion-color-blue_background"><strong><code>lib</code></strong></span>
- 나중에 통째로 분리해도 될 것 같으면 → <span class="notion-color-blue_background"><strong><code>lib</code></strong></span>

## ✏️ <strong>정리</strong>


utils냐 lib이냐보다 중요한 건 <strong>코드의 책임 범위와 맥락</strong>이다.

- 책임이 작고 단순하면 utils
- 책임이 커지고 맥락이 생기면 lib

이 기준을 잡고 나서 폴더 구조 때문에 고민하는 일이 훨씬 줄었다 ㅎㅅㅎ


## 🔗 참고


<div class="notion-bookmark"><a href="https://www.reddit.com/r/nextjs/comments/1l1csl7/lib_vs_utils_vs_services_folders_simple/?captcha=1" target="_blank" rel="noopener noreferrer"><div class="notion-bookmark-content"><div class="notion-bookmark-title">https://www.reddit.com/r/nextjs/comments/1l1csl7/lib_vs_utils_vs_services_folders_simple/?captcha=1</div><div class="notion-bookmark-url">www.reddit.com</div></div></a></div>


<div class="notion-bookmark"><a href="https://github.com/Prismatik/dendritic/issues/159" target="_blank" rel="noopener noreferrer"><div class="notion-bookmark-content"><div class="notion-bookmark-title">&amp;quot;utils&amp;quot; vs &amp;quot;lib&amp;quot; · Issue #159 · Prismatik/dendritic</div><div class="notion-bookmark-desc">I notice there is no scaffolded /src/lib folder, and instead things that look like libraries to me are placed in /src/utils. Can someone please enlighten me on the difference(s) between the two, an...</div><div class="notion-bookmark-url">github.com</div></div><div class="notion-bookmark-thumb"><img src="https://opengraph.githubassets.com/59e0fb2daf53efd333721c9e6c2c63d164069b676e78d20c9e5c555a190c936c/Prismatik/dendritic/issues/159" alt="" /></div></a></div>




## 👩🏻‍💻 12월 동안 인턴을 하면서 진행한 작업들


### <strong>1️⃣  개발 배포 환경 구축 및 메타데이터 리서치</strong>


12월에는 dev 배포 환경을 새로 구축하며 전체적인 개발 환경 안정화를 진행했다. 기존에는 main 브랜치 단일 배포 구조로 인해 개발 중 테스트가 제한적인 문제가 있었고, 이를 해결하기 위해 dev 브랜치를 새로 생성하고 prod와 완전히 분리된 배포 파이프라인을 구성했다.


GitHub Actions에서 workflow_run 트리거 조건으로 인해 dev 배포 시에도 main 브랜치가 checkout되는 문제가 발생했으나, github.event.workflow_run.head_sha 기반으로 체크아웃 로직을 수정하고 브랜치 조건을 재정의하여 해결했다. buildx 설정과 스크립트 내 줄바꿈 문제로 인해 발생하던 빌드 오류도 정리하여 배포 안정성을 높였다.


이와 함께 Next.js App Router 기반 메타데이터 설정에 대한 리서치를 진행했다. Open Graph, Twitter 카드 설정 구조를 분석하고, 페이지별로 필요한 metadata 전략을 비교했다. 배포 환경에 따라 OG 이미지가 다르게 노출되는 문제를 방지하기 위해 환경변수 기반 메타데이터 주입 방식도 문서화했다.


### 2️⃣  <strong>인증 · 쿠키 이슈 분석 및 사용자 기능 연동</strong>


개발 배포 환경에서 발생하는 인증 및 쿠키 관련 이슈를 집중적으로 분석하고 해결했다. 로컬과 개발 배포 환경에서 인증 동작이 서로 다르게 나타나는 문제를 확인했고, 프록시 설정, 쿠키 도메인, CORS 정책이 복합적으로 얽혀 있음을 파악했다.


먼저 Next.js의 rewrites 기능을 활용해 /api/* 요청이 백엔드 서버로 전달되도록 프록시를 구성했다. 이를 통해 브라우저 기준 동일 출처 요청처럼 동작하게 만들었고, 로컬 환경에서 쿠키 저장 및 접근이 정상적으로 이루어지도록 개선했다.


그러나 개발 배포 환경에서는 쿠키 도메인이 API 호스트로 설정되어 Next.js 미들웨어에서 쿠키를 읽지 못하는 문제가 발생했다. 이를 통해 fetch 및 RTK Query의 baseQuery 설정에 따라 프록시를 우회하는 요청이 존재함을 확인했다. 이후 RTK Query의 baseUrl을 개발·로컬 환경 모두 /api로 통일하여 모든 인증 요청이 프록시를 타도록 수정했고, 쿠키 스코프 문제를 해결했다.


추가로 인증 만료 시 토큰 재발급 로직이 개발 환경에서만 동작하지 않는 이슈를 분석했다. 원인은 401 응답에 포함된 WWW-Authenticate 헤더를 브라우저에서 읽지 못하는 것이었고, CORS 정책으로 인해 해당 헤더가 차단되고 있음을 확인했다. 서버 측에서 Access-Control-Expose-Headers에 WWW-Authenticate를 추가하도록 정리하여, 프론트엔드에서 만료 상태를 정상적으로 감지하고 refresh API를 호출할 수 있도록 개선했다.


이와 함께 설정 페이지와 회원탈퇴 페이지에 API를 연결했다. 탈퇴 사유 선택 UI를 개선하고, 선택된 항목을 Set 기반 타입으로 관리하여 payload를 간결하게 유지하도록 구현했다.


### 3️⃣ <strong>CMS 계좌 등록 플로우 Step2 화면 개선</strong>


CMS 계좌 등록 플로우 중 Step2 화면을 중심으로 UX 개선 및 구조 리팩토링 작업을 진행했다. 개인 계좌와 사업자 계좌를 탭으로 전환하며 입력하는 구조로, UX와 코드 구조 모두에서 개선이 필요한 상태였다.


탭 전환 시 화면이 자연스럽게 이동하도록 translateX 기반 슬라이딩 인터랙션을 구현했다. 모바일 환경에서 드래그 시 숨겨진 영역이 노출되는 문제를 발견했고, 컨테이너 구조 및 overflow 처리를 조정하여 화면이 과도하게 이동하지 않도록 개선했다.


입력 폼에서는 은행 선택 → 계좌번호 → 예금주명 → 전화번호 순으로 입력 흐름이 자연스럽게 이어지도록 자동 포커싱 로직을 구현했다. React Hook Form의 setFocus를 활용해 특정 값 입력 또는 Enter 키 입력 시 다음 필드로 포커스가 이동하도록 처리했다.


또한 개인/사업자 폼이 하나의 화면에 공존하면서 포커스가 잘못 이동하는 문제가 발생해, 각 폼이 동일한 form context를 공유하지 않도록 구조를 분리했다. 이 과정에서 발생한 hydration error를 분석했고, Zustand 상태와 form 초기값 설정 시점 차이로 인해 서버·클라이언트 렌더 결과가 달라지는 것이 원인임을 파악했다. 상태 동기화 시점을 조정하여 안정적인 렌더링 구조를 구현했다.


마지막으로 fixed 레이아웃의 CTA 버튼이 form submit과 충돌하는 문제를 해결하며, 외부에 위치한 버튼에서도 정상적으로 submit이 동작하도록 개선했다.


## ✏️ 총정리


12월에는 dev/prod 배포 환경을 분리하며 개발 안정성을 크게 향상시켰고, 인증·쿠키·CORS 이슈를 실제 서비스 환경 기준으로 분석하며 깊이 있는 이해를 쌓을 수 있었다.




## 👩🏻‍💻 11월 동안 인턴을 하면서 진행한 작업들


### <strong>1️⃣  Yarn Berry로 마이그레이션하기</strong>


기존 프로젝트의 패키지 관리 방식을 개선하기 위해 Yarn Berry로 마이그레이션을 진행했다. 처음 사용하는 번들러 환경이라 개념을 이해하는 데 시간이 필요했지만, 그 과정에서 Yarn과 Yarn Berry의 구조적 차이와 Yarn Berry가 제공하는 장점들을 깊이 있게 공부할 수 있었다. 특히 Yarn Berry는 node_modules를 생성하지 않고 ZIP 기반으로 패키지를 관리하는 구조라, 더 빠른 설치 속도와 명확한 디펜던시 매핑, 충돌 방지 등 기존 Yarn보다 훨씬 안정적인 장점을 가지고 있다는 것을 직접 경험하며 깨달았다.


마이그레이션 과정에서는 .pnp.cjs를 활용한 패키지 로딩 구조를 이해하는 것이 핵심이었다. 처음에는 익숙한 node_modules가 보이지 않아 적응이 어려웠지만, 오히려 PnP 방식 덕분에 “어디에서 어떤 패키지가 사용되는지”가 훨씬 명확해지는 장점을 느꼈다. 기존 패키지 구조와 충돌하는 영역을 해결하며 프로젝트 전체의 의존성 구조를 재정비할 수 있었고, 이를 통해 Yarn Berry 환경에 대한 이해도도 크게 높아졌다.


또한 앞으로는 Yarn Berry의 핵심 기능 중 하나인 <strong>Zero-Install</strong>도 적용해볼 계획이다. 팀원 환경 간 패키지 버전 불일치 문제를 근본적으로 해결할 수 있고, 설치 속도도 더 빨라지는 등 효율적인 개발 환경을 만들 수 있을 것이라는 기대가 생겼다.


### 2️⃣ Dockerfile 작성부터 CI/CD 구축을 지나 AWS 배포 자동화까지


이번 달의 가장 큰 도전은 Docker 빌드와 CI/CD 구축이었다. 사실 Docker를 이번에 처음 설치해봤을 정도로 DevOps 경험이 거의 없었기 때문에, Dockerfile을 작성하는 과정 하나하나가 전부 새로웠고 엄청 어려웠다. 특히 Yarn Berry로 마이그레이션한 직후라 기존 Yarn 기반 Dockerfile 명령어 일부와 안 맞다는 걸 깨닫는 순간 진짜 큰일났다 싶었다.. 허허.. 이걸 하루 안에 끝내면 난 진짜 천재다 라는 생각이 맨 먼저 듦.. 일단 리서치부터 시작했는데 Yarn Berry 환경에서의 Dockerfile 예시가 인터넷에 거의 없어 2~3시간 동안 구글링과 레퍼런스 검색만 반복하며 하나씩 시행착오를 겪었다. 너무 힘들었다 흑흑…. 


일단 Dockerfile의 코드 한 줄 한 줄을 다 뜯어보고 해석하기 시작했다. 어느 정도의 플로우와 명령어 등을 이해했고 결국 Dockerfile을 만들어 빌드, 태그 달기, 푸시까지 성공했다! Yarn Berry는 node_modules가 없는 구조라 빌드 때 종속성 문제가 생길 수 있다는 조언을 듣고 <strong>빌드 단계에서만 node_modules를 생성하도록 추가 처리</strong>했다. .pnp.cjs, .yarnrc.yml, .yarn 디렉토리가 Docker 빌드에서 누락되면 바로 실패한다는 것도 직접 부딪히며 이해했다. 처음 겪는 문제였지만, 실행할 때마다 왜 실패했는지 원인을 추적하고 해결해가는 과정 자체가 큰 공부가 되었다.


CI/CD 역시 처음 연동해보는 작업이라 한 단계 한 단계가 전부 도전이었다. GitHub Actions에서 테스트와 빌드를 분리하고, 빌드된 이미지를 ECR로 push한 뒤 ECS 서비스에서 자동으로 롤링 업데이트가 되도록 워크플로우를 구성했다. 이를 통해 AWS가 어떤 식으로 실제 서비스를 업데이트하는지, ECS와 ECR이 어떤 역할을 하는지, 태스크 정의가 어떻게 동작하는지까지 이해할 수 있었다.


무엇보다 AWS 자체를 잘 몰랐기 때문에 서버 개발자 동료분에게 질문을 정말 많이 했다. 너무 많이 여쭤봐서 죄송한 마음도 컸지만, 덕분에 ECS/ECR 구조와 배포 흐름을 훨씬 깊게 이해하게 되었고 지금은 감사한 마음뿐이다.


DevOps에 대해 감자였던 내가 실무에서 직접 Dockerfile을 만들고 CI/CD를 구성하고 AWS 배포까지 연결해본 경험은 정말 값진 시간이었다. 너무 힘들었지만 결국 해냈다는 사실이 너무 뿌듯하고, 내가 직접 서비스 배포 자동화까지 만들었다는 게 믿기지 않을 정도로 행복했다 희희..


### 3️⃣ RefreshToken 작업하기


이번 달에는 인증 구조를 개선하는 과정에서 AccessToken과 RefreshToken의 동작 원리를 깊이 이해하게 되었다. 기존에는 AccessToken을 localStorage에 저장하는 방식으로 동작하고 있었는데, 이는 보안 측면에서 취약하고 토큰 탈취 위험이 높다는 단점이 있었다. 이를 개선하기 위해 AccessToken을 메모리 기반인 Redux store에서 관리하도록 변경했다. (RefreshToken은 현재 Cookie에 저장하는 방식을 이용하고 있다!)


AccessToken을 store에서 관리하는 방식은 보안적으로 훨씬 안전하지만, 새로고침 시 store가 초기화된다는 특성 때문에 사용자가 매번 로그인 페이지로 이동하는 문제가 있었다.


이 문제를 해결하기 위해 새로고침 시마다 RefreshToken을 이용해 AccessToken을 재발급받는 흐름을 구축했다. 페이지에 다시 진입할 때 Refresh API를 호출하고, 성공하면 AccessToken을 다시 store에 저장하도록 처리해 초기화 문제를 해결했다. 이를 통해 사용자는 RefreshToken이 만료되지 않는 한 로그인 상태를 안정적으로 유지할 수 있게 되었다.


## 📋 회고


### AWS 공부를 하기로 다짐했다


위에서 언급했듯이, AWS 배포 자동화를 구현하면서 내가 AWS가 무엇이고 어떤 서비스들이 있는지 거의 모르고 있었다는 사실을 깨달았다. 배포 실패 시 확인해야 하는 로그들, 현재 배포가 진행 중인 태스크 넘버 등은 이번 경험을 통해 기본적인 수준까지는 익힐 수 있었지만, 앞으로 원활한 운영과 관리까지 생각하면 더 깊게 공부가 필요하다는 생각이 들었다.


## ✏️ 총정리


11월은 정말 새로운 것들을 많이 배우고 실무에 적용해본 달이었다.


지금까지 해본 적 없던 환경 설정, 배포 자동화, 인프라 구성까지 직접 다뤄보면서 서비스가 사용자에게 도달하기까지의 전 과정을 경험할 수 있었다. 이 과정에서 시행착오도 많았지만 결국 문제를 해결해나가며 성장하는 경험을 할 수 있었다.




### <strong>💡 시작하기</strong>


냅다 Docker 빌드와 CI/CD 구축을 하게 된 나.. 


게다가 패키지 매니저도 yarn classic에서 yarn berry로 마이그레이션해야 해서, 기존에 쓰던 Dockerfile과는 조금 다르게 진행해야 한다고 한다.


하지만 난 Docker 빌드와 CI/CD 구축이 모두 처음인걸…?


그래서 Docker build를 수행할 수 있는 Dockerfile에 대해 자세히 알아보고자 합니당


## 🐳 Dockerfile 작성하기 


Dockerfile을 작성하기 전, 알아두어야 할 것이 있다. 바로 <u><strong>빌드 과정</strong></u>!


빌드 과정은 총 3개의 스테이지를 거친다

- <strong>stage 1 : deps 단계</strong>

    <code>FROM base AS deps</code>

- <strong>stage 2: builder 단계</strong>

    <code>FROM base AS builder</code>

- <strong>stage 3 : runner 단계</strong>

    <code>FROM base AS runner</code>


### 1️⃣ Sta<strong>ge 1 :</strong> <span class="notion-color-blue"><strong>deps</strong></span> <strong>단계</strong>


> <span class="notion-callout-icon">📖</span> <span class="notion-callout-text"><span class="notion-color-blue"><strong>패키지 설치 전용 단계</strong></span></span>
> 
> - package.json / yarn.lock 기반으로 .yarn/cache와 .pnp.cjs를 만든다

> <em>yarn berry 마이그레이션으로 인해 기존 Dockerfile에서 수정된 부분</em>

```docker
# package.json, yarn.lock, .yarnrc.yml을 복사한다
# 패키지가 변경되지 않으면 해당 단계는 캐시된다 -> 속도 향상됨
COPY package.json yarn.lock .yarnrc.yml ./


# yarn berry의 경우, .yarn 폴더에 패키지가 ZIP 파일로 저장되어있으므로 해당 코드가 필요하다
# COPY {source} {destination} 

# ./.yarn -> /app/.yarn


COPY .yarn ./.yarn

# corepack으로 yarn을 활성화하고, berry로 설정 후, immutable로 yarn install을 진행한다
# --immutable = yarn.lock이 조금이라도 다르면 오류 → Docker/CI에서 필수
RUN corepack enable
RUN yarn set version berry
RUN yarn install --immutable
```

- 해당 단계가 끝나면
    - .pnp.cjs 생성
    - .yarn/cache/*.zip 생성

### 2️⃣ Sta<strong>ge 2:</strong> <span class="notion-color-blue"><strong>builder</strong></span> <strong>단계</strong>


> <span class="notion-callout-icon">📖</span> <span class="notion-callout-text"><span class="notion-color-blue"><strong>앱을 빌드하는 단계</strong></span></span>
> 
> - deps 단계에서 만든 의존성 + 소스코드를 합쳐 next 빌드를 수행한다
> 
> → .next/standalone, .next/static 이 생성된다

> <em>yarn berry 마이그레이션으로 인해 기존 Dockerfile에서 수정된 부분</em>

```docker
# deps 단계에서 만든 여러 PnP파일들을 복사한다
COPY --from=deps /app/.pnp.cjs /app/.pnp.cjs
COPY --from=deps /app/.yarnrc.yml ./.yarnrc.yml
COPY --from=deps /app/.yarn ./.yarn
COPY --from=deps /app/package.json ./package.json
COPY --from=deps /app/yarn.lock /app/yarn.lock

# 앱의 소스코드 전체를 복사한다
COPY . .

# Next.js 빌드 과정에서 패키지를 찾을 때 node_modules 대신 PnP 방식을 사용해야 하므로, 
# NODE_OPTIONS로 .pnp.cjs를 강제 로드한다.
ENV NODE_OPTIONS="--require=/app/.pnp.cjs"

# 이 단계가 deps, builder에 둘 다 있는 이유는
# builder 단계에서는 .pnp.cjs를 소스코드와 연결하는 작업이기 때문에 빠르게 진행된다
RUN yarn install --immutable

# Next.js 빌드를 수행한다
RUN yarn run build
```


### 3️⃣ Sta<strong>ge 3 :</strong> <span class="notion-color-blue"><strong>runner</strong></span> <strong>단계</strong>


> <span class="notion-callout-icon">📖</span> <span class="notion-callout-text"><span class="notion-color-blue"><strong>실행 단계</strong></span></span>
> 
> - builder 단계에서 나온 빌드 결과만 가져온다
> 
> → next.js app을 noder server.js로 실행한다

> <em>runner 단계에서의 코드</em>

```docker
# production 환경 설정
ENV NODE_ENV=production

# 새로운 시스템 그룹과 사용자 생성
RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs

# builder 단계에서 public 폴더 복사
COPY --from=builder /app/public ./public

# prerender cache를 위한 .next 디렉토리 생성 및 권한 설정
RUN mkdir .next
RUN chown nextjs:nodejs .next

# 빌드 결과물 복사
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

# 애플리케이션을 nextjs 사용자로 실행
USER nextjs

# 컨테이너 포트 설정
EXPOSE 3000
ENV PORT=3000

# 서버 실행
ENV HOSTNAME="0.0.0.0"
CMD ["node", "server.js"]
```


## 🐳 <span class="notion-color-blue"><strong>Docker build</strong></span> 실행하기

1. CLI를 통해 aws에 로그인을 한다
2. 도커에서 빌드를 시작한다
    - 도커 빌드 시, M1의 경우 이미지를 amd64로 만들어야 하는 경우가 있기에 <code>--platform linux/amd64</code> 를 꼭 추가해야 하며, 만약 그 외라면 해당 부분은 생략해도 된다!

        <code>docker build --platform linux/amd64 -t {이미지 이름:이미지버전} {Dockerfile의 경로}</code>

3. 생성된 이미지에 태그를 붙인다

    <code>docker tag {이미지 이름} {이미지 링크}</code>

4. 도커에 올린다

    <code>docker push {링크}</code>

5. 생성된 이미지를 확인한다 : <code>docker images</code>
> <strong>example</strong>

```shell
docker build --platform linux/amd64 -t my-next-app:1.0 .
docker tag my-next-app:1.0 123456789012.dkr.ecr.ap-northeast-2.amazonaws.com/my-next-app:1.0
docker push 123456789012.dkr.ecr.ap-northeast-2.amazonaws.com/my-next-app:1.0
```


## 📒 정리


yarn berry가 생각보다 신경쓸 만한 게 많아서 빌드 실패를 어마어마하게 많이 했다 흑흑


그래도 성공하니까 굉장히 뿌듯했다 희희..


<figure class="notion-image">
  <img src="https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F9b1af274-6edf-4f5c-b4c9-d8db23308ba6%2F2bff00f5-6fa1-4731-bc3d-7e36d4f16c1c%2F%25E1%2584%2589%25E1%2585%25B3%25E1%2584%258F%25E1%2585%25B3%25E1%2584%2585%25E1%2585%25B5%25E1%2586%25AB%25E1%2584%2589%25E1%2585%25A3%25E1%2586%25BA_2025-11-19_%25E1%2584%258B%25E1%2585%25A9%25E1%2584%2592%25E1%2585%25AE_5.58.43.png%3FX-Amz-Algorithm%3DAWS4-HMAC-SHA256%26X-Amz-Content-Sha256%3DUNSIGNED-PAYLOAD%26X-Amz-Credential%3DASIAZI2LB466ROVGSEQD%252F20260329%252Fus-west-2%252Fs3%252Faws4_request%26X-Amz-Date%3D20260329T073731Z%26X-Amz-Expires%3D3600%26X-Amz-Security-Token%3DIQoJb3JpZ2luX2VjED0aCXVzLXdlc3QtMiJIMEYCIQDTn8qgYmvTNfkxcTiKwZqfW%252FG3Xcr1YfWYANbB1zweyQIhAL%252BhXpMXHYuiZ3bgBxsIBs2HfQ%252FvqfG6tncnRtTWf85aKv8DCAYQABoMNjM3NDIzMTgzODA1Igy4V44Cp26CNM3dH4Aq3APBy2iaqLc2l93KYkbvwcFj%252BrOltrEBJr20OBZON6pe01dNKG4pVLWDDjkwh08pwVzxZs%252FSI58BOvn3VB4REnEQMAC2k5P7hhgrihlJGzjLnoAVPpcB1CzCqMNA%252FwiY07Z%252FaOwi1PXUkq1AoG573swq%252BOvjmAMeTPWwEJIP83H9mTFEL8HqM%252BjXifFcotK%252FxWebGfI2SDYyEbXI62s8rr8ZWN34MAIlbOs4CUhpA6UQAE5luQyIxC5AR8jgwvUWHtMVPvz99LLtUob7Km9yPFbC%252FwIVA8Kov7vprx94bDV5bqqp1GBfYksMDAM8cF8SLL7aSwbWHV0fMEzOjjqjS%252B2wQnSy9xMSn4tF8cNKrIRSKnGxE3fZkfErE76Uyf7%252BrDBucHKhXk4hWKh%252BiIO%252B5ESCxAmyI%252FLZRoRcK4ze2nnZYzlPPi9FjPAQCKYqI0YCoPLykWCBaS6bDPQpQ0nvjBmmdAgyGYc%252BIIec7e3RZ6H82Jq9BRfMfFtfxyldE%252B%252FEGSP%252BCE2c%252F1BoZAOIQP16IEWvGiLEZ%252BjZGCylfYSA2WLo697RT2Yi7ZzAxeRYO5TtWUzRFxEMhZOYxso7tDJmNgVPLJM2aApoPiVD8m42%252F2zIkd6QtRkLKuxfrRjU5TCp36LOBjqkAQIu59ta3KQKM4dnOtYOGZI1isxEXV5UD14qDTx3rp4SFVYsJBx%252FIyev8Chw5dKLOIIsKYaaKbyTLLI4RqAAxbtxNDg5Uw5yrH65%252F9G32BEnN7p%252B5Dj%252FvZ1ggBzaT7kuD0Yhupj%252B3ZMX3I6S14nQAmxTllFaftqB261c2GBEjppqpgIJE77aw4v4TDV7YhVlcwLYWz4DBmBCJ8OeNOqk2d%252Bijs4S%26X-Amz-Signature%3Ddedcb4a2557403d1367d2e9062c68df8580f62314916af34fd030a5b907eb785%26X-Amz-SignedHeaders%3Dhost%26x-amz-checksum-mode%3DENABLED%26x-id%3DGetObject?table=block&amp;id=2b07763d-d03a-803f-b4cf-df9c2e2b90c8&amp;cache=v2" alt="수많은 나의 빌드 성공신화 과정.. 다 도커 빌드 실패해서 난 에러…" />
  <figcaption>수많은 나의 빌드 성공신화 과정.. 다 도커 빌드 실패해서 난 에러…</figcaption>
</figure>


근데 생각해보면 걍 로컬에서 빌드해보면 될 것을 왜 굳이 깃허브에 올려서 테스트를 했었는지 모르겠다 <del>레전드 바보</del>


다음 글에서는 이 과정을 바탕으로, <span class="notion-color-blue"><strong>Github Action에서 도커 빌드 → ECR 이미지 업로드 → ECS Task Definition</strong></span>까지 자동화하는 과정을 정리해볼 예정이다!


## 🔗 참고


<div class="notion-bookmark"><a href="https://docs.docker.com/reference/dockerfile/" target="_blank" rel="noopener noreferrer"><div class="notion-bookmark-content"><div class="notion-bookmark-title">Dockerfile reference</div><div class="notion-bookmark-desc">Find all the available commands you can use in a Dockerfile and learn how to use them, including COPY, ARG, ENTRYPOINT, and more.</div><div class="notion-bookmark-url">docs.docker.com</div></div></a></div>


<div class="notion-bookmark"><a href="https://wooono.tistory.com/123" target="_blank" rel="noopener noreferrer"><div class="notion-bookmark-content"><div class="notion-bookmark-title">[Docker] Dockerfile 개념 및 작성법</div><div class="notion-bookmark-desc">Dockerfile Dockerfile은 DockerImage를 생성하기 위한 스크립트(설정파일)이다. 여러가지 명령어를 토대로 Dockerfile을 작성한 후 빌드하면 Docker는 Dockerfile에 나열된 명령문을 차례대로 수행하며 DockerImage를 생성해준다. Dockerfile을 읽을 줄 안다는 것은 해당 이미지가 어떻게 구성되어 있는지 알 수 있다는 의미이다. Dockerfile의 장점 (1) 이미지가 어떻게 만들어졌는지를 기록한다. 보통 사람들은 완성된 이미지를 가져다 쓰기 때문에 이미지가 어떻게 만들어졌는지에 대해서는 알 필요가 없다. 그러나 개발자의 경우라면 조금 다르다. 어떠한 애플리케이션을 담고 있는 이미지가 설치 되기 위한 과정은 어떠한지, 중간에 어떠한 과정을 수정해야 하는..</div><div class="notion-bookmark-url">wooono.tistory.com</div></div><div class="notion-bookmark-thumb"><img src="https://img1.daumcdn.net/thumb/R800x0/?scode=mtistory2&amp;fname=https%3A%2F%2Ft1.daumcdn.net%2Ftistory_admin%2Fstatic%2Fimages%2FopenGraph%2Fopengraph.png" alt="" /></div></a></div>




## <strong>💡 시작하기</strong>


yarn classic에서 yarn berry로 마이그레이션하라는 업무를 맡게 되었다


근데 yarn berry라는 게 뭔지 몰라서 이번 기회에 공부하면서 세팅까지 해보기로 했다!


## 🍓 yarn berry


npm, yarn을 쓰다보면 가장 골치 아픈 게 바로 node_modules다.


<figure class="notion-image">
  <img src="https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F9b1af274-6edf-4f5c-b4c9-d8db23308ba6%2Fd757877c-e1f9-44ae-bc84-ec4bf3df198f%2Fimage.png%3FX-Amz-Algorithm%3DAWS4-HMAC-SHA256%26X-Amz-Content-Sha256%3DUNSIGNED-PAYLOAD%26X-Amz-Credential%3DASIAZI2LB466QNWKM7JN%252F20260329%252Fus-west-2%252Fs3%252Faws4_request%26X-Amz-Date%3D20260329T073744Z%26X-Amz-Expires%3D3600%26X-Amz-Security-Token%3DIQoJb3JpZ2luX2VjED0aCXVzLXdlc3QtMiJGMEQCIG6sH4JsXaEPl6FJIEk5rQfo3GNp0N7NnaG9akK9TFrLAiBmr3WlnFe%252BDMOaH%252F00wND19wMEU7qd6Wvw252NPbNwiyr%252FAwgGEAAaDDYzNzQyMzE4MzgwNSIMaU0Di%252Fl2XI5j7LLVKtwDw%252BgHpi9zdtJZvemvPDVkWaswFUAt6N%252FowYRjiKC6pabr3cFMyK5RFQjrhSAbHc6uo7FLz7JY9pIg2dZVYQdGxlCxCPYSei%252FADBb47AUIfaRrOq6hsk8J%252BrLdjYt7kbJ5YRsBWcU36C7lLWARA%252F%252FECBXJ7JG9HmHOLB9yu82TqY7BVcgMBPaQT6rqoZd9P4YywPA%252FntIF7rVG10FyyIVvEVyxrFHcEdy%252F8xGNpHEsqVZJSL7vee%252F1FCYX1BFB%252FVRJbf1h7l2%252F8cSGoNStGddWPh%252Ffd28VGrIZCmVL6WpnUmFGrS2l0KT%252B1D6ioI2MN5xEn1XkMxOpV%252BbqJ2NfihpIXhzdt%252BaTRr481FWuoHLDz%252Bpb3CVK6ytYITaA%252BlCSA5HIWz4ZMVr0zNh2CAqNA%252BiIFNlw6OQR1vKa6f%252B3mtUh%252FCg%252F11qgJQM%252B40M1n5G7be5wsQIOhciVEiqyULY6HpQhGsvyj476HARdFd0z0Jz4cOFLQXcwekKqQbvIB97e7o0sG%252Bw6R6WxtMZsbSyCw4%252Bfdx%252F3mv%252FUcm%252FU1xfvWVcO%252BO1OqASNYefU%252Bbe6NH1UC6A39ui1b8aHchUyaPjZc0ttZBOuYdrpYQZ%252BXFKWbs5Wh2nKsE3BUFzUr3eh7JswxOCizgY6pgHixIBCN01MP%252FXN6rDGqTFVNWcwfb%252Fj%252FfXUj8myDgrjImCDlVKz62%252Bzq7zgz6VM%252BsRpJJwoM1B%252Fq1GG88o43Sh1%252B5ZM2TCmvpND3sGPr5ot%252FpEsVkHFeX4FgDROaP3hwn92IJQ9pX6GO2ZkRwLoMuElbHSitMX5BXa65eq4j1YKWfQNfGJa3RF2f2fRlPNlcwtuKQ3Ctue8fH%252B%252FXDGKns1Ixh82xCXK%26X-Amz-Signature%3Dbaab409c33e9ae5bcb8d70af1fd3c2b54b2c281357b4b039c85b4aaa7ab3bab9%26X-Amz-SignedHeaders%3Dhost%26x-amz-checksum-mode%3DENABLED%26x-id%3DGetObject?table=block&amp;id=2b17763d-d03a-807f-aaf7-efe2abcaa84d&amp;cache=v2" alt="맨날 노트북 용량 없어서 이전 프로젝트 node_modules 
지우면 한 5기가는 나옴 ㅎ" />
  <figcaption>맨날 노트북 용량 없어서 이전 프로젝트 node_modules 
지우면 한 5기가는 나옴 ㅎ</figcaption>
</figure>

- <strong>npm</strong> : node_modules 폴더에서 찾는 패키지가 있는지 없는지를 계속해서 탐색하고,
- <strong>yarn</strong> : 패키지의 유효성만 검사하고 그 패키지가 올바른지에 대한 건 검사를 하지 않는다

⇒ <em><code>package.json</code></em> 파일을 기반으로 의존성 트리를 생성하고, 디스크에 <em><code>node_modules</code></em> 디렉토리 구조를 만들기에 용량이 큼 + 원하는 패키지를 찾는 데에 많은 시간이 듦 = npm과 yarn의 단점


하지만 이것을 <span class="notion-color-blue"><strong>yarn berry</strong></span>를 쓰면 해결이 가능하다고 한다!


## 🆙 <strong>yarn berry로 마이그레이션하기</strong>

> <strong>1. 설치</strong>

```bash
yarn set version berry
```

> <strong>2. 생성되어 있는 yarn.lock을 berry로 마이그레이션하기</strong>

```yaml
# .yarnrc.yml 
nodeLinker: node-modules # 추가하기
enableGlobalCache: false # 추가하기
```


```yaml
yarn install
```


<figure class="notion-image">
  <img src="https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F9b1af274-6edf-4f5c-b4c9-d8db23308ba6%2F03f4f5f1-a363-475c-bb59-50fd67f71791%2Fimage.png%3FX-Amz-Algorithm%3DAWS4-HMAC-SHA256%26X-Amz-Content-Sha256%3DUNSIGNED-PAYLOAD%26X-Amz-Credential%3DASIAZI2LB466QNWKM7JN%252F20260329%252Fus-west-2%252Fs3%252Faws4_request%26X-Amz-Date%3D20260329T073744Z%26X-Amz-Expires%3D3600%26X-Amz-Security-Token%3DIQoJb3JpZ2luX2VjED0aCXVzLXdlc3QtMiJGMEQCIG6sH4JsXaEPl6FJIEk5rQfo3GNp0N7NnaG9akK9TFrLAiBmr3WlnFe%252BDMOaH%252F00wND19wMEU7qd6Wvw252NPbNwiyr%252FAwgGEAAaDDYzNzQyMzE4MzgwNSIMaU0Di%252Fl2XI5j7LLVKtwDw%252BgHpi9zdtJZvemvPDVkWaswFUAt6N%252FowYRjiKC6pabr3cFMyK5RFQjrhSAbHc6uo7FLz7JY9pIg2dZVYQdGxlCxCPYSei%252FADBb47AUIfaRrOq6hsk8J%252BrLdjYt7kbJ5YRsBWcU36C7lLWARA%252F%252FECBXJ7JG9HmHOLB9yu82TqY7BVcgMBPaQT6rqoZd9P4YywPA%252FntIF7rVG10FyyIVvEVyxrFHcEdy%252F8xGNpHEsqVZJSL7vee%252F1FCYX1BFB%252FVRJbf1h7l2%252F8cSGoNStGddWPh%252Ffd28VGrIZCmVL6WpnUmFGrS2l0KT%252B1D6ioI2MN5xEn1XkMxOpV%252BbqJ2NfihpIXhzdt%252BaTRr481FWuoHLDz%252Bpb3CVK6ytYITaA%252BlCSA5HIWz4ZMVr0zNh2CAqNA%252BiIFNlw6OQR1vKa6f%252B3mtUh%252FCg%252F11qgJQM%252B40M1n5G7be5wsQIOhciVEiqyULY6HpQhGsvyj476HARdFd0z0Jz4cOFLQXcwekKqQbvIB97e7o0sG%252Bw6R6WxtMZsbSyCw4%252Bfdx%252F3mv%252FUcm%252FU1xfvWVcO%252BO1OqASNYefU%252Bbe6NH1UC6A39ui1b8aHchUyaPjZc0ttZBOuYdrpYQZ%252BXFKWbs5Wh2nKsE3BUFzUr3eh7JswxOCizgY6pgHixIBCN01MP%252FXN6rDGqTFVNWcwfb%252Fj%252FfXUj8myDgrjImCDlVKz62%252Bzq7zgz6VM%252BsRpJJwoM1B%252Fq1GG88o43Sh1%252B5ZM2TCmvpND3sGPr5ot%252FpEsVkHFeX4FgDROaP3hwn92IJQ9pX6GO2ZkRwLoMuElbHSitMX5BXa65eq4j1YKWfQNfGJa3RF2f2fRlPNlcwtuKQ3Ctue8fH%252B%252FXDGKns1Ixh82xCXK%26X-Amz-Signature%3Ddab6dcafbd9d02de4a68b1ef666c639fcecee997e03c6d2291085197aa4b8276%26X-Amz-SignedHeaders%3Dhost%26x-amz-checksum-mode%3DENABLED%26x-id%3DGetObject?table=block&amp;id=2ae7763d-d03a-8047-b906-efd14633023b&amp;cache=v2" alt="" />
  
</figure>

> <strong>3. PnP(Plug’n’play) 만들기</strong>

전 단계에서 .yarnrc.yml에 추가해놨던 nodeLinker: node-modules 지우고


```bash
yarn install
```


<figure class="notion-image">
  <img src="https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F9b1af274-6edf-4f5c-b4c9-d8db23308ba6%2F09a01636-6de3-44e6-a103-5afaea170884%2Fimage.png%3FX-Amz-Algorithm%3DAWS4-HMAC-SHA256%26X-Amz-Content-Sha256%3DUNSIGNED-PAYLOAD%26X-Amz-Credential%3DASIAZI2LB466QNWKM7JN%252F20260329%252Fus-west-2%252Fs3%252Faws4_request%26X-Amz-Date%3D20260329T073744Z%26X-Amz-Expires%3D3600%26X-Amz-Security-Token%3DIQoJb3JpZ2luX2VjED0aCXVzLXdlc3QtMiJGMEQCIG6sH4JsXaEPl6FJIEk5rQfo3GNp0N7NnaG9akK9TFrLAiBmr3WlnFe%252BDMOaH%252F00wND19wMEU7qd6Wvw252NPbNwiyr%252FAwgGEAAaDDYzNzQyMzE4MzgwNSIMaU0Di%252Fl2XI5j7LLVKtwDw%252BgHpi9zdtJZvemvPDVkWaswFUAt6N%252FowYRjiKC6pabr3cFMyK5RFQjrhSAbHc6uo7FLz7JY9pIg2dZVYQdGxlCxCPYSei%252FADBb47AUIfaRrOq6hsk8J%252BrLdjYt7kbJ5YRsBWcU36C7lLWARA%252F%252FECBXJ7JG9HmHOLB9yu82TqY7BVcgMBPaQT6rqoZd9P4YywPA%252FntIF7rVG10FyyIVvEVyxrFHcEdy%252F8xGNpHEsqVZJSL7vee%252F1FCYX1BFB%252FVRJbf1h7l2%252F8cSGoNStGddWPh%252Ffd28VGrIZCmVL6WpnUmFGrS2l0KT%252B1D6ioI2MN5xEn1XkMxOpV%252BbqJ2NfihpIXhzdt%252BaTRr481FWuoHLDz%252Bpb3CVK6ytYITaA%252BlCSA5HIWz4ZMVr0zNh2CAqNA%252BiIFNlw6OQR1vKa6f%252B3mtUh%252FCg%252F11qgJQM%252B40M1n5G7be5wsQIOhciVEiqyULY6HpQhGsvyj476HARdFd0z0Jz4cOFLQXcwekKqQbvIB97e7o0sG%252Bw6R6WxtMZsbSyCw4%252Bfdx%252F3mv%252FUcm%252FU1xfvWVcO%252BO1OqASNYefU%252Bbe6NH1UC6A39ui1b8aHchUyaPjZc0ttZBOuYdrpYQZ%252BXFKWbs5Wh2nKsE3BUFzUr3eh7JswxOCizgY6pgHixIBCN01MP%252FXN6rDGqTFVNWcwfb%252Fj%252FfXUj8myDgrjImCDlVKz62%252Bzq7zgz6VM%252BsRpJJwoM1B%252Fq1GG88o43Sh1%252B5ZM2TCmvpND3sGPr5ot%252FpEsVkHFeX4FgDROaP3hwn92IJQ9pX6GO2ZkRwLoMuElbHSitMX5BXa65eq4j1YKWfQNfGJa3RF2f2fRlPNlcwtuKQ3Ctue8fH%252B%252FXDGKns1Ixh82xCXK%26X-Amz-Signature%3D5c0799e3cb4307e41739c5318743ea7662a28169c991a9882da98cbdbd8308ad%26X-Amz-SignedHeaders%3Dhost%26x-amz-checksum-mode%3DENABLED%26x-id%3DGetObject?table=block&amp;id=2ae7763d-d03a-8017-a77f-dccf20de8749&amp;cache=v2" alt="아 저 sdks는 아래 4단계하면 생김" />
  <figcaption>아 저 sdks는 아래 4단계하면 생김</figcaption>
</figure>


<figure class="notion-image">
  <img src="https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F9b1af274-6edf-4f5c-b4c9-d8db23308ba6%2F47c02ad2-74f7-4609-96ee-2d8cee04f625%2Fimage.png%3FX-Amz-Algorithm%3DAWS4-HMAC-SHA256%26X-Amz-Content-Sha256%3DUNSIGNED-PAYLOAD%26X-Amz-Credential%3DASIAZI2LB466QNWKM7JN%252F20260329%252Fus-west-2%252Fs3%252Faws4_request%26X-Amz-Date%3D20260329T073744Z%26X-Amz-Expires%3D3600%26X-Amz-Security-Token%3DIQoJb3JpZ2luX2VjED0aCXVzLXdlc3QtMiJGMEQCIG6sH4JsXaEPl6FJIEk5rQfo3GNp0N7NnaG9akK9TFrLAiBmr3WlnFe%252BDMOaH%252F00wND19wMEU7qd6Wvw252NPbNwiyr%252FAwgGEAAaDDYzNzQyMzE4MzgwNSIMaU0Di%252Fl2XI5j7LLVKtwDw%252BgHpi9zdtJZvemvPDVkWaswFUAt6N%252FowYRjiKC6pabr3cFMyK5RFQjrhSAbHc6uo7FLz7JY9pIg2dZVYQdGxlCxCPYSei%252FADBb47AUIfaRrOq6hsk8J%252BrLdjYt7kbJ5YRsBWcU36C7lLWARA%252F%252FECBXJ7JG9HmHOLB9yu82TqY7BVcgMBPaQT6rqoZd9P4YywPA%252FntIF7rVG10FyyIVvEVyxrFHcEdy%252F8xGNpHEsqVZJSL7vee%252F1FCYX1BFB%252FVRJbf1h7l2%252F8cSGoNStGddWPh%252Ffd28VGrIZCmVL6WpnUmFGrS2l0KT%252B1D6ioI2MN5xEn1XkMxOpV%252BbqJ2NfihpIXhzdt%252BaTRr481FWuoHLDz%252Bpb3CVK6ytYITaA%252BlCSA5HIWz4ZMVr0zNh2CAqNA%252BiIFNlw6OQR1vKa6f%252B3mtUh%252FCg%252F11qgJQM%252B40M1n5G7be5wsQIOhciVEiqyULY6HpQhGsvyj476HARdFd0z0Jz4cOFLQXcwekKqQbvIB97e7o0sG%252Bw6R6WxtMZsbSyCw4%252Bfdx%252F3mv%252FUcm%252FU1xfvWVcO%252BO1OqASNYefU%252Bbe6NH1UC6A39ui1b8aHchUyaPjZc0ttZBOuYdrpYQZ%252BXFKWbs5Wh2nKsE3BUFzUr3eh7JswxOCizgY6pgHixIBCN01MP%252FXN6rDGqTFVNWcwfb%252Fj%252FfXUj8myDgrjImCDlVKz62%252Bzq7zgz6VM%252BsRpJJwoM1B%252Fq1GG88o43Sh1%252B5ZM2TCmvpND3sGPr5ot%252FpEsVkHFeX4FgDROaP3hwn92IJQ9pX6GO2ZkRwLoMuElbHSitMX5BXa65eq4j1YKWfQNfGJa3RF2f2fRlPNlcwtuKQ3Ctue8fH%252B%252FXDGKns1Ixh82xCXK%26X-Amz-Signature%3D796b1fd5254a9b5a1f534d4f867ca1325b41c0b3d6368ae3e88b30b7faf114de%26X-Amz-SignedHeaders%3Dhost%26x-amz-checksum-mode%3DENABLED%26x-id%3DGetObject?table=block&amp;id=2ae7763d-d03a-8085-a12a-d7d66b2632a4&amp;cache=v2" alt="" />
  
</figure>

> <strong>4. ZipFS 설치하기</strong>

<figure class="notion-image">
  <img src="https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F9b1af274-6edf-4f5c-b4c9-d8db23308ba6%2F2d8d5851-8e61-447d-9b4b-07d6d147b753%2Fimage.png%3FX-Amz-Algorithm%3DAWS4-HMAC-SHA256%26X-Amz-Content-Sha256%3DUNSIGNED-PAYLOAD%26X-Amz-Credential%3DASIAZI2LB466QNWKM7JN%252F20260329%252Fus-west-2%252Fs3%252Faws4_request%26X-Amz-Date%3D20260329T073744Z%26X-Amz-Expires%3D3600%26X-Amz-Security-Token%3DIQoJb3JpZ2luX2VjED0aCXVzLXdlc3QtMiJGMEQCIG6sH4JsXaEPl6FJIEk5rQfo3GNp0N7NnaG9akK9TFrLAiBmr3WlnFe%252BDMOaH%252F00wND19wMEU7qd6Wvw252NPbNwiyr%252FAwgGEAAaDDYzNzQyMzE4MzgwNSIMaU0Di%252Fl2XI5j7LLVKtwDw%252BgHpi9zdtJZvemvPDVkWaswFUAt6N%252FowYRjiKC6pabr3cFMyK5RFQjrhSAbHc6uo7FLz7JY9pIg2dZVYQdGxlCxCPYSei%252FADBb47AUIfaRrOq6hsk8J%252BrLdjYt7kbJ5YRsBWcU36C7lLWARA%252F%252FECBXJ7JG9HmHOLB9yu82TqY7BVcgMBPaQT6rqoZd9P4YywPA%252FntIF7rVG10FyyIVvEVyxrFHcEdy%252F8xGNpHEsqVZJSL7vee%252F1FCYX1BFB%252FVRJbf1h7l2%252F8cSGoNStGddWPh%252Ffd28VGrIZCmVL6WpnUmFGrS2l0KT%252B1D6ioI2MN5xEn1XkMxOpV%252BbqJ2NfihpIXhzdt%252BaTRr481FWuoHLDz%252Bpb3CVK6ytYITaA%252BlCSA5HIWz4ZMVr0zNh2CAqNA%252BiIFNlw6OQR1vKa6f%252B3mtUh%252FCg%252F11qgJQM%252B40M1n5G7be5wsQIOhciVEiqyULY6HpQhGsvyj476HARdFd0z0Jz4cOFLQXcwekKqQbvIB97e7o0sG%252Bw6R6WxtMZsbSyCw4%252Bfdx%252F3mv%252FUcm%252FU1xfvWVcO%252BO1OqASNYefU%252Bbe6NH1UC6A39ui1b8aHchUyaPjZc0ttZBOuYdrpYQZ%252BXFKWbs5Wh2nKsE3BUFzUr3eh7JswxOCizgY6pgHixIBCN01MP%252FXN6rDGqTFVNWcwfb%252Fj%252FfXUj8myDgrjImCDlVKz62%252Bzq7zgz6VM%252BsRpJJwoM1B%252Fq1GG88o43Sh1%252B5ZM2TCmvpND3sGPr5ot%252FpEsVkHFeX4FgDROaP3hwn92IJQ9pX6GO2ZkRwLoMuElbHSitMX5BXa65eq4j1YKWfQNfGJa3RF2f2fRlPNlcwtuKQ3Ctue8fH%252B%252FXDGKns1Ixh82xCXK%26X-Amz-Signature%3D3a1af1c3057c15e40f634df0cb9d0711ce32d37fb947159c5871c4eccc0fc054%26X-Amz-SignedHeaders%3Dhost%26x-amz-checksum-mode%3DENABLED%26x-id%3DGetObject?table=block&amp;id=2ae7763d-d03a-8081-9e1b-c1871ee5b2d7&amp;cache=v2" alt="" />
  
</figure>


```typescript
// 설치 후 다음 명령어 입력
yarn dlx @yarnpkg/sdks vscode
```


## 💥 트러블 슈팅

> <strong>4단계까지도 했는데 모든 라이브러리를 읽어들이지 못하는 에러 발생</strong>

<strong>⬇️ SOLUTION</strong>


ts 파일을 아무거나 킨 다음, <u><strong>Cmd + Shift + P</strong></u> 를 입력하면 다음과 같은 창이 뜬다


<figure class="notion-image">
  <img src="https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F9b1af274-6edf-4f5c-b4c9-d8db23308ba6%2F9d7df6da-d5a3-488e-a1f6-fccdea948cc5%2F%25E1%2584%2589%25E1%2585%25B3%25E1%2584%258F%25E1%2585%25B3%25E1%2584%2585%25E1%2585%25B5%25E1%2586%25AB%25E1%2584%2589%25E1%2585%25A3%25E1%2586%25BA_2025-11-17_%25E1%2584%258B%25E1%2585%25A9%25E1%2584%2592%25E1%2585%25AE_5.08.52.png%3FX-Amz-Algorithm%3DAWS4-HMAC-SHA256%26X-Amz-Content-Sha256%3DUNSIGNED-PAYLOAD%26X-Amz-Credential%3DASIAZI2LB466QNWKM7JN%252F20260329%252Fus-west-2%252Fs3%252Faws4_request%26X-Amz-Date%3D20260329T073744Z%26X-Amz-Expires%3D3600%26X-Amz-Security-Token%3DIQoJb3JpZ2luX2VjED0aCXVzLXdlc3QtMiJGMEQCIG6sH4JsXaEPl6FJIEk5rQfo3GNp0N7NnaG9akK9TFrLAiBmr3WlnFe%252BDMOaH%252F00wND19wMEU7qd6Wvw252NPbNwiyr%252FAwgGEAAaDDYzNzQyMzE4MzgwNSIMaU0Di%252Fl2XI5j7LLVKtwDw%252BgHpi9zdtJZvemvPDVkWaswFUAt6N%252FowYRjiKC6pabr3cFMyK5RFQjrhSAbHc6uo7FLz7JY9pIg2dZVYQdGxlCxCPYSei%252FADBb47AUIfaRrOq6hsk8J%252BrLdjYt7kbJ5YRsBWcU36C7lLWARA%252F%252FECBXJ7JG9HmHOLB9yu82TqY7BVcgMBPaQT6rqoZd9P4YywPA%252FntIF7rVG10FyyIVvEVyxrFHcEdy%252F8xGNpHEsqVZJSL7vee%252F1FCYX1BFB%252FVRJbf1h7l2%252F8cSGoNStGddWPh%252Ffd28VGrIZCmVL6WpnUmFGrS2l0KT%252B1D6ioI2MN5xEn1XkMxOpV%252BbqJ2NfihpIXhzdt%252BaTRr481FWuoHLDz%252Bpb3CVK6ytYITaA%252BlCSA5HIWz4ZMVr0zNh2CAqNA%252BiIFNlw6OQR1vKa6f%252B3mtUh%252FCg%252F11qgJQM%252B40M1n5G7be5wsQIOhciVEiqyULY6HpQhGsvyj476HARdFd0z0Jz4cOFLQXcwekKqQbvIB97e7o0sG%252Bw6R6WxtMZsbSyCw4%252Bfdx%252F3mv%252FUcm%252FU1xfvWVcO%252BO1OqASNYefU%252Bbe6NH1UC6A39ui1b8aHchUyaPjZc0ttZBOuYdrpYQZ%252BXFKWbs5Wh2nKsE3BUFzUr3eh7JswxOCizgY6pgHixIBCN01MP%252FXN6rDGqTFVNWcwfb%252Fj%252FfXUj8myDgrjImCDlVKz62%252Bzq7zgz6VM%252BsRpJJwoM1B%252Fq1GG88o43Sh1%252B5ZM2TCmvpND3sGPr5ot%252FpEsVkHFeX4FgDROaP3hwn92IJQ9pX6GO2ZkRwLoMuElbHSitMX5BXa65eq4j1YKWfQNfGJa3RF2f2fRlPNlcwtuKQ3Ctue8fH%252B%252FXDGKns1Ixh82xCXK%26X-Amz-Signature%3D6c6a32526293fdf37ca9879799299a10233af9bbc3de78c87f954aac11ace72d%26X-Amz-SignedHeaders%3Dhost%26x-amz-checksum-mode%3DENABLED%26x-id%3DGetObject?table=block&amp;id=2ae7763d-d03a-8019-b5b3-c482d80e2ff7&amp;cache=v2" alt="" />
  
</figure>


검색창에 <span class="notion-color-blue"><strong>typescript version</strong></span>을 입력한다


<figure class="notion-image">
  <img src="https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F9b1af274-6edf-4f5c-b4c9-d8db23308ba6%2F97447e8f-ce21-4acc-b383-38eddac5c713%2Fimage.png%3FX-Amz-Algorithm%3DAWS4-HMAC-SHA256%26X-Amz-Content-Sha256%3DUNSIGNED-PAYLOAD%26X-Amz-Credential%3DASIAZI2LB466QNWKM7JN%252F20260329%252Fus-west-2%252Fs3%252Faws4_request%26X-Amz-Date%3D20260329T073744Z%26X-Amz-Expires%3D3600%26X-Amz-Security-Token%3DIQoJb3JpZ2luX2VjED0aCXVzLXdlc3QtMiJGMEQCIG6sH4JsXaEPl6FJIEk5rQfo3GNp0N7NnaG9akK9TFrLAiBmr3WlnFe%252BDMOaH%252F00wND19wMEU7qd6Wvw252NPbNwiyr%252FAwgGEAAaDDYzNzQyMzE4MzgwNSIMaU0Di%252Fl2XI5j7LLVKtwDw%252BgHpi9zdtJZvemvPDVkWaswFUAt6N%252FowYRjiKC6pabr3cFMyK5RFQjrhSAbHc6uo7FLz7JY9pIg2dZVYQdGxlCxCPYSei%252FADBb47AUIfaRrOq6hsk8J%252BrLdjYt7kbJ5YRsBWcU36C7lLWARA%252F%252FECBXJ7JG9HmHOLB9yu82TqY7BVcgMBPaQT6rqoZd9P4YywPA%252FntIF7rVG10FyyIVvEVyxrFHcEdy%252F8xGNpHEsqVZJSL7vee%252F1FCYX1BFB%252FVRJbf1h7l2%252F8cSGoNStGddWPh%252Ffd28VGrIZCmVL6WpnUmFGrS2l0KT%252B1D6ioI2MN5xEn1XkMxOpV%252BbqJ2NfihpIXhzdt%252BaTRr481FWuoHLDz%252Bpb3CVK6ytYITaA%252BlCSA5HIWz4ZMVr0zNh2CAqNA%252BiIFNlw6OQR1vKa6f%252B3mtUh%252FCg%252F11qgJQM%252B40M1n5G7be5wsQIOhciVEiqyULY6HpQhGsvyj476HARdFd0z0Jz4cOFLQXcwekKqQbvIB97e7o0sG%252Bw6R6WxtMZsbSyCw4%252Bfdx%252F3mv%252FUcm%252FU1xfvWVcO%252BO1OqASNYefU%252Bbe6NH1UC6A39ui1b8aHchUyaPjZc0ttZBOuYdrpYQZ%252BXFKWbs5Wh2nKsE3BUFzUr3eh7JswxOCizgY6pgHixIBCN01MP%252FXN6rDGqTFVNWcwfb%252Fj%252FfXUj8myDgrjImCDlVKz62%252Bzq7zgz6VM%252BsRpJJwoM1B%252Fq1GG88o43Sh1%252B5ZM2TCmvpND3sGPr5ot%252FpEsVkHFeX4FgDROaP3hwn92IJQ9pX6GO2ZkRwLoMuElbHSitMX5BXa65eq4j1YKWfQNfGJa3RF2f2fRlPNlcwtuKQ3Ctue8fH%252B%252FXDGKns1Ixh82xCXK%26X-Amz-Signature%3D524544d4ec43c698841d98512750e32680c440ddde7b40a7b96ea0abbf46f9d7%26X-Amz-SignedHeaders%3Dhost%26x-amz-checksum-mode%3DENABLED%26x-id%3DGetObject?table=block&amp;id=2ae7763d-d03a-800f-95cc-edb3240eb29a&amp;cache=v2" alt="" />
  
</figure>


sdk가 달려있는 <span class="notion-color-blue"><strong>“작업 영역 버전 사용”</strong></span>을 클릭하고 vscode를 재실행하면 에러 해결~!


원래는 <code>yarn dlx @yarnpkg/sdks vscode</code>를 입력하면 팝업이 뜨면서 해당 사항을 바로 설정할 수 있도록 하는데 내가 그걸 못 봤었다 허허.. 팝업을 놓치면 해당 방법으로 수정하면 된다!


## <strong>📝 정리</strong>


이번 글에서는 기존 <span class="notion-color-blue"><strong>Yarn Classic 프로젝트를 Yarn Berry로 마이그레이션</strong></span>하는 과정을 기록했다.


node_modules 없이 의존성을 관리하는 PnP와 ZipFS를 적용하면서 빌드 과정에서 발생한 트러블을 해결하는 법도 함께 정리해봤다.


다음 글에서는 이렇게 Yarn Berry로 바꾼 프로젝트를 기반으로, <strong>Docker를 사용하여 빌드하는 과정</strong>을 기록할 예정이다.


## <strong>🔗 참고</strong>


<div class="notion-bookmark"><a href="https://toss.tech/article/node-modules-and-yarn-berry" target="_blank" rel="noopener noreferrer"><div class="notion-bookmark-content"><div class="notion-bookmark-title">node_modules로부터 우리를 구원해 줄 Yarn Berry</div><div class="notion-bookmark-desc">토스 프론트엔드 레포지토리 대부분에서 사용하고 있는 패키지 매니저 Yarn Berry. 채택하게 된 배경과 사용하면서 좋았던 점을 공유합니다.</div><div class="notion-bookmark-url">toss.tech</div></div><div class="notion-bookmark-thumb"><img src="https://static.toss.im/assets/tech-blog/og-image:/techblog-04-yarn-berry-og.png?v=2" alt="" /></div></a></div>


<div class="notion-bookmark"><a href="https://blog.naver.com/biud436/223211308347" target="_blank" rel="noopener noreferrer"><div class="notion-bookmark-content"><div class="notion-bookmark-title">러닝은빛의 작업실 : 네이버 블로그</div><div class="notion-bookmark-url">blog.naver.com</div></div></a></div>




### <strong>⚙️ transformResponse</strong>


> <span class="notion-callout-text"><span class="notion-color-blue"><strong>transformResponse</strong></span> ? 서버의 엔드포인트를 통해 받은 response를 클라이언트에서 가공할 수 있도록 하는 옵션이에요</span>
> 
> - 해당 API를 호출하여 사용하는 데이터는 transformResponse를 자동적으로 거치게 되고, 가공된 데이터를 사용할 수 있어요

> <em><strong>ex) 차트 데이터가 월별로 정렬되지 않은 데이터</strong></em>

```typescript
transformResponse: (res: ITransactionSummary) => {
    const sorted = res.series.sort((a, b) => a.month.localeCompare(b.month));
    return { ...res, series: sorted };
  },
```


<div class="notion-columns">
  <div class="notion-column"><figure class="notion-image">
  <img src="https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F9b1af274-6edf-4f5c-b4c9-d8db23308ba6%2F1cbb4151-76b2-4af6-aa96-dfb2f19a4425%2Fimage.png%3FX-Amz-Algorithm%3DAWS4-HMAC-SHA256%26X-Amz-Content-Sha256%3DUNSIGNED-PAYLOAD%26X-Amz-Credential%3DASIAZI2LB4664X23YA5C%252F20260329%252Fus-west-2%252Fs3%252Faws4_request%26X-Amz-Date%3D20260329T073757Z%26X-Amz-Expires%3D3600%26X-Amz-Security-Token%3DIQoJb3JpZ2luX2VjED0aCXVzLXdlc3QtMiJHMEUCIAszgpeg%252BFunuYGjnqHu%252BMXeBINp7xNFSVRZtubpnm5TAiEApWoi6C8aSm3mtAnOu%252B0uajZgFafalNz7kbZH7ripIHAq%252FwMIBhAAGgw2Mzc0MjMxODM4MDUiDKSAiHnw9IW9rhPFQSrcAwGprMrmvjrfhyduvLhRkTqykg0oQ0cXgJy25Escfp5O4tt5gFiO%252FdhxTWK2qR%252BDMfCRSKl7HETp4%252Fh52nXeHe64o5%252BSPsqPqYCv%252B8pdFFHZCkNmnKilW990y0%252Br65Nx7vRp46%252FpdINOX1H8m2ZageUmAagCA%252Fnrcv3fqHh%252FTcyj%252FSb8U1ToaIQixPnIbGarUWBmxrV8lnXOxDCGvumUv%252B1Abh1JfjpjOhF4Getz9g98e%252Fo4SUYj7Dc8RG3vySzn6K2utlh17xxLJBKAdz3Gt7sct5WmZRik6QIqSQuGMs%252FUnhcyIvrSFMmHwdY5TcmXGi8CdNsQDbFcN7F6%252BB99eoCD%252F0QHddJRoXlnFeOHh6j3u8PTsRwgRK5q0SQX%252FnEmLqGRh6fbDiDnu8e5D3uA%252FY33EpOhbIJRbHIhfqsO2fFVI%252Bb%252FlA%252FWNpY7q79ZR%252BTlXXdfK8oFSOprm9EK0bAYI1CavBES1upZKZ%252FS7RjdryhGPS0Awi961OkAw4iQMh6DnC%252BnEAREad1uFFE%252Fx1cpLot0dwE5hhX4RCguC%252FaXBcLcT4ZBWxGRmUF3LumGKspfZv9KcelnkIE2NDH%252F4%252Fw%252BcI6Au17%252FFRqPxQjSG6H8sdyhPEDTBQ6BlA8daRfkMJ3gos4GOqUB4S6YQXl16eDMI%252BbB3BU%252FOaWnC5n9VTpOyWndCoYbezHd7D7mGrlFvTGuV5hMB7czy43edFVTyeDBmJ2Vy3voSAZ7HJAYuIcIoAocHkcPM1mGqiE2qy8jx0lQ%252F44BluL0dZ0CZcZF8I5UFgLjaVUUw9H9SfPVpdbWy90iUwwqAxqzhpIFLLWlZ7ufwt8rTVj3%252Fb9UBXfwxYINOWjyVRiR1UHSXHsB%26X-Amz-Signature%3D864bc3076effd12ad2ffbe770b5e4c965423fceacfc9853afed87cdfec13dfb0%26X-Amz-SignedHeaders%3Dhost%26x-amz-checksum-mode%3DENABLED%26x-id%3DGetObject?table=block&amp;id=2a37763d-d03a-80e8-9c7b-c731fe7d592b&amp;cache=v2" alt="BEFORE : 월별로 정렬되지 않은 차트" />
  <figcaption>BEFORE : 월별로 정렬되지 않은 차트</figcaption>
</figure>

</div><div class="notion-column"><figure class="notion-image">
  <img src="https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2F9b1af274-6edf-4f5c-b4c9-d8db23308ba6%2F49cb7cd9-35f1-42ef-a936-09bb7443c342%2F483f749a-1e1d-46cf-885c-36a046322e0c.png%3FX-Amz-Algorithm%3DAWS4-HMAC-SHA256%26X-Amz-Content-Sha256%3DUNSIGNED-PAYLOAD%26X-Amz-Credential%3DASIAZI2LB466SJ2L772T%252F20260329%252Fus-west-2%252Fs3%252Faws4_request%26X-Amz-Date%3D20260329T073757Z%26X-Amz-Expires%3D3600%26X-Amz-Security-Token%3DIQoJb3JpZ2luX2VjED0aCXVzLXdlc3QtMiJGMEQCIFGJd%252BAGd4aXXGheqaqia85uY8Z6wG5iR3C9BrtXUOy%252BAiAU%252BOCuZFL4QAOwcxprrkSn5jZtHb%252FmWlPCJBxVPQkbhir%252FAwgGEAAaDDYzNzQyMzE4MzgwNSIMGFGpbU%252Bed1rsr%252BnYKtwDM6uwHqUEXd8F%252B1HJSqlmVDiT8%252BofNGpYx74%252BcBL65%252FKffn77KDE03%252FAkv8OgAzYmuZWIhHDJhWu2BCOu%252BJhLGSzgUOrIIb%252BNsXgxIrAQ28l0mM6X%252BMPcGZOPPApo89k54nWHBMnym7kodUbgQnvJS%252BE8LQeDb7gKHlimnxW%252F49zHjizhVUD6655JvT6on9JKYiipGuHkikcWitf0MmlFeT1jLDvUccZnD9n0F1dM1A2VdQ5ETyZbwWJFZdeHt7vBaaLLrpGELu3tzuQZqjJa%252FslQzpc7P1wYTWyhPoTu2%252B4fqwjs1gMIx0gZTPZheT3fWpfC0B%252BBOSMObGr3lX9fJZQNTWL%252FZyO4sVpMjP54N4ZufyxgifNOdOMB%252B1dstaHlsRUMOGXnsIKZzeb9gMFmMsp409yzZGkZSbX8mVpRThMB91nbh5DBOPfo3fryj9Ny9u%252BMfQ2saWSbSFDsMm22%252FUHFF36O%252F3K7wmTi4JSVcu0YmBO65iuhCUPXElCvYhpFIqJm1qqTpHCsHAo6eJB0%252B3Xa6G8bjUWpjZuLA9sfRs2yINvZBYZ5bqicZhIqE%252FFcstFIKu37SQdOhZmbfXy4fkJ6YP4LoUjpDI7PLo822DcUhfXDQsDvM4VBwqMwyd%252BizgY6pgHZeuqT8V%252BRmX8fk5vBnnNCF%252FFowVdroZDPSQ0L%252B82aCffBYMnn%252BIS%252Bdqqq4NQxiggGndJWi4tbuIBAwj7g45FyhzZ%252BetqFoMDrVoUr9K6UoqFGF4hYkmx%252BRVurLYaY%252B3bhWYIK7%252FwD87%252FwJ08XldgEAcNnvtzVXSK3PLxnzwRKpk0w%252F%252FtdVMEXtaxfMj9h6w6m0fZEphpRCshtNhgx2%252FO0gP7D55R9%26X-Amz-Signature%3D75eb3109cee0accffd3d706952379dbbf4c1849dba6071a09a17b53885aada13%26X-Amz-SignedHeaders%3Dhost%26x-amz-checksum-mode%3DENABLED%26x-id%3DGetObject?table=block&amp;id=2a37763d-d03a-8048-8059-c58e7d1c387e&amp;cache=v2" alt="AFTER : 월별로 정렬된 차트" />
  <figcaption>AFTER : 월별로 정렬된 차트</figcaption>
</figure>

</div>
</div>


### <strong>🖥️ 트러블 슈팅</strong>


서버에서 받는 response의 타입과 transformResponse의 타입이 달라서 오류가 발생했어요

- 서버에서 받는 response의 items : <code>ITask[]</code>
- transformResponse를 통해 가공한 response의 items : <code>Record&lt;string, ITask[]&gt;</code>

<strong>⇒ transformResponse에 중심을 맞춰 타입을 일치시켜야 해요!</strong>


```typescript
getMissingTaskList: builder.query<
MissingTasksByMonth
, number>({
    query: (powerPlantId) => ({
      url: `/powerplants/${powerPlantId}/tasks/missing`,
    }),
    transformResponse: (res: IMissingTaskList): 
MissingTasksByMonth
 => {
      return buildMissingTasks(res);
    },
  }),
```


### ❓ 근데 진짜 궁금한 게 있슨


getMissingTaskList를 통해 받는 response의 타입 : <code>IMissingTaskList</code>
transformResponse로 인해, query의 response 타입 자리에 <code>IMissingTaskList</code>가 아닌 <code>MissingTasksByMonth</code>가 대신 들어가게 되는데요


이렇게 해도 쿼리문이 타입 에러 없이 성립할 수 있는 이유가 뭔지에 대해 궁금했어요


⇒ builder.query의 response type은 transformResponse가 어떤 타입의 응답을 반환할 것인지를 정의하는 것이기 때문에 <span class="notion-color-blue"><u><strong>transformResponse의 res 타입의 경우, 서버로부터 받은 데이터인 baseQuery의 타입 구조와만 일치하면 되는 거였어요</strong></u></span>


### <strong>📝 정리</strong>


원래는 걍 쌩데이터만 받고 데이터 가공을 하는 유틸함수를 따로 만들거나, 변수를 재지정해서 선언하는 방식으로 진행했었는데 transformResponse를 통해 재가공한 데이터를 API 호출하면 바로 사용할 수 있다는 사실이 너무 신기했던 것 같아요! 


서버에서 보통 데이터를 정렬하긴 하나, 내 쪽에서 한 번 더 가공을 해줘야 서버 데이터가 바껴도 그나마 안전하게 데이터를 사용하고 보여줄 수 있다는 사실을 깨닫게 되었어요. 어쩌면 DX를 꽤 향상시키는 옵션이라고 생각해요.


비록 RTK Query를 많이 쓰지 않아 자주 쓰는 라이브러리인 tanstack-query에서도 같은 기능을 하는 옵션이 있나 찾아봤더니 select 라는 옵션이 있다고 해요! 이번에 공부한 내용을 꼭 기억하여 기능을 추후 애용할 거에요 😊


### <strong>🔗 참고</strong>


<div class="notion-bookmark"><a href="https://redux-toolkit.js.org/rtk-query/usage/customizing-queries" target="_blank" rel="noopener noreferrer"><div class="notion-bookmark-content"><div class="notion-bookmark-title">https://redux-toolkit.js.org/rtk-query/usage/customizing-queries</div><div class="notion-bookmark-url">redux-toolkit.js.org</div></div></a></div>


<div class="notion-bookmark"><a href="https://dev.to/lada496/rtk-query-how-to-modify-query-responses-with-transformresponse-4ikj" target="_blank" rel="noopener noreferrer"><div class="notion-bookmark-content"><div class="notion-bookmark-title">RTK Query: How to modify query responses with transformResponse</div><div class="notion-bookmark-desc">This is my note when I learned how to customize raw API responses with the...</div><div class="notion-bookmark-url">dev.to</div></div><div class="notion-bookmark-thumb"><img src="https://media2.dev.to/dynamic/image/width=1000,height=500,fit=cover,gravity=auto,format=auto/https%3A%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fuploads%2Farticles%2F7o2ql0pxhtlh0fabcokk.jpg" alt="" /></div></a></div>




## 👩🏻‍💻 10월 동안 인턴을 하면서 진행한 작업들


### <strong>1️⃣  회원가입에 funnel 구조 도입하기</strong>


서비스의 핵심 온보딩 플로우에 해당하는 회원가입과 인증서 등록 기능을 모바일 환경에 맞게 재설계 및 구현하였다.


회원가입 기능은 react-hook-form과 zod를 활용해 단계별 퍼널 구조로 구성했다. 기존 웹 버전의 회원가입은 하나의 컴포넌트 안에 모든 입력 필드를 포함하는 단일 페이지 구조로 이루어져 있었으나, 모바일 환경에서는 화면이 작아 한 화면에서 모든 정보를 입력하기에 불편함이 컸고, 이탈률 증가가 우려되었다. 따라서 모바일에서는 한 번에 한 가지 정보만 입력하도록 단계를 세분화하고, 스텝별로 화면 전환이 이뤄지는 퍼널 구조를 도입하였다. 


모바일 UX에 최적화된 구조를 위해 스텝 이동 시 입력값 초기화를 방지하고, 버튼 활성화 여부를 유효성 검증 결과에 따라 동적으로 제어했다.


### 2️⃣ 홈 화면 기획 및 개발 구현


홈 화면은 별도의 기획서나 디자인 시안이 없어, 직접 기획·디자인·개발까지 전 과정을 주도적으로 진행했다.


주요 컴포넌트로 발전소 건강검진 요약, 발전량 차트, 이달의 업무 영역을 구성했으며, 이달의 업무 영역은 피그마로 와이어프레임을 제작하고 내부 피드백을 거쳐 완성도를 높였다.


다행히 완성 디자인이 나와 이후에는 디자인을 보며 수월하게 구현을 완성할 수 있었다.


### 3️⃣ 리포트 상세 분석 및 매출 예측 차트 구조 개선


발전소의 운영년수, 분석 타입(type), 카테고리(category), 상태(status) 등 다단 조건 분기에 따라 다른 데이터와 UI를 출력해야 하는 복잡한 로직을 정리했다.


조건 조합을 테이블 형태로 정리하고, 반환 데이터를 객체 기반으로 관리하여 중복 로직을 제거하고 유지보수성을 대폭 향상시켰으며, 조건에 따라 맞춤 문장을 출력하는 함수를 구현해 UI의 일관성을 확보했다.


매출 예측 차트에서는 실제 매출과 예측 매출 데이터를 병합하고 누락된 구간이 있어도 시각적으로 끊기지 않도록 보정 로직을 추가하여 데이터 시각화 품질을 개선했다.


---


처음에는 비교적 순조롭게 진행되었으나, <strong>서버 API의 지속적인 수정으로 데이터 구조와 변수명, 타입이 수시로 변경되는 상황</strong>이 발생했다.


이 과정에서 이미 구현한 로직을 여러 번 수정해야 했고, 데이터 구조가 바뀔 때마다 프론트엔드 단의 데이터 매핑과 타입 정의를 함께 수정해야 하는 부담이 컸다.


초반에는 변경 공지가 원활하지 않아 일정 관리에 어려움이 있었지만, 후반부에는 서버 팀에서도 변경 사항을 사전에 공유하고 논의하는 협업 프로세스가 자리 잡으면서 점차 안정적으로 진행할 수 있었다. 솔직히 너무 힘들긴 했는데, 그만큼 협업의 중요성을 몸으로 배운 한 주였다


## 📋 회고


### 일이 정말 바쁘고 힘들어도 난 개발이 맞는 듯


추석 연휴 + 모바일 서비스 전시회가 얼마 남지 않음 + 개발 기간 3주 + 서비스의 볼륨이 어마어마하게 큼 이슈로 인해 10월은 정말 바쁘게 살았다..


내 인생 첫 야근이라는 것도 해보고 재택하면서 새벽 1시까지 일도 해보고, 칼퇴해서 새벽 4시까지 일해도 맡은 태스크를 그날 다 끝내지 못해본 경험도 했다.


솔직히 정말 너무 * ♾️ 힘들었다.. 일반 사이드 프로젝트를 진행했을 때도 이것보다 더 많이 개발한 적도 많았는데, 실무 일이라 생각할 것도 많고 하니 사프 개발할 때보다 훨씬 더 힘들었던 것 같다.


힘들긴 정말 힘들었지만 하나의 기능을 다 무사히 완성했을 때의 뿌듯함과 순식간에 UI 뚝딱 만들어내는 재밌음이 상시 느껴졌다.. 난 개발이 천직인 듯 ㅜ.ㅜ 


### 남의 코드를 따라가는 건 아직 어려운 일이군..


9월 인턴일지에서 남의 코드를 뜯어보는 것이 두렵지 않아졌다고 하였으나,,, 뜯어보는 것과 따라가는 것은 굉장히 다른 일이라고 느껴졌다.


모바일 서비스에는 다른 프론트엔드 외주 업체와 함께 작업하였다. 외주 업체가 초기 세팅 및 어느 정도의 작업을 이룬 후, 내가 함께 모바일 서비스 프론트엔드 개발에 참여하게 된 것이다. 외주 업체의 코드를 보는데 처음 보는 파일 아키텍처와 우리 회사와는 너무 다른 코드 스타일을 사용하는 것을 알게 되었다. 그리고 그 코드 스타일에 맞게 작업하는데 신규 기능 구현, 리팩토링보다 훨씬 더 힘들었다. 


이틀 전 미팅을 통해 해당 코드 스타일과 기술 스택을 사용한 이유들을 외주 업체 대표님께 들었었다. 이걸 먼저 들을 수 있었으면 얼마나 좋았을까 라는 생각을 함과 동시에 다음 달에는 이제 코드 스타일도 완벽하게 이해했겠다. 이 스타일에 완벽히 맞춰 코드를 리팩토링해야겠다는 생각이 확실하게 들게 되었다.


## ✏️ 총정리


10월은 스스로 구조를 설계하고 복잡한 로직을 정리하며, 협업 코드베이스에 적응하는 <span class="notion-color-red">진짜 실무력</span>을 키운 한 달이었다.


하지만 기존 웹 서비스와 새로 만들고 있는 모바일 서비스가 같은 기능을 하는 서비스이기 때문에 웹 개발 때 사용했던 로직들을 그대로 가져온 것도 많아 개발 역량이 많이 늘지는 않았다.


다음 달에는 기존 코드를 완전히 내 것으로 만들고, 코드 스타일에 맞게 리팩토링을 중심으로 성장해 나갈 예정이다.




## 👩🏻‍💻 9월 동안 인턴을 하면서 진행한 작업들


### <strong>1️⃣ GA4 연동 및 UTM Parameter 설정</strong>


회사 서비스의 유입 경로를 추적하기 위해 <span class="notion-color-blue"><strong>GA4를 연동</strong></span>했다. 단순히 이벤트 로깅을 붙이는 수준이 아니라, <strong>GA4 이벤트가 프론트에서 발생한 후 서버까지 데이터가 안전하게 전달되는지</strong> 확인해야 했다. 특히 캠페인별 트래킹을 위해 UTM parameter를 URL에서 파싱해 서버 API 요청 시 함께 넘기도록 로직을 짰다.


초반에는 GA4가 정상적으로 이벤트를 수집하지 않는 문제가 있었는데, <strong>localstorage 접근으로 인한 hydration error</strong>가 원인이었다. 클라이언트 렌더링 시점에서만 GA4가 동작하도록 useEffect 안에서 초기화 로직을 실행해 해결했다. 이 과정을 통해 hydration error에 대해 더 깊게 공부할 수 있었으며, 해당 주제로 [<span class="notion-color-blue"><strong>기술 블로그</strong></span>](https://0ju428-blog.vercel.app/hydration)도 작성했다.


### <strong>2️⃣ MDX를 사용하여 이용약관 등의 문서 제작</strong>


이전에는 이용약관, 개인정보 처리방침과 같은 법적 문서를 노션 링크로 연결했는데, 이는 서비스 신뢰성 측면에서 아쉬움이 있었다. 이를 개선하기 위해 <strong>MDX를 도입해 서비스 내부 페이지에서 문서를 렌더링</strong>하도록 구현했다.


MDX를 적용하면서 겪은 첫 문제는 <strong>리스트나 숫자 목록이 깨지는 렌더링 이슈</strong>였다. 단순한 마크다운만 쓸 때는 괜찮았지만, 커스텀 컴포넌트와 혼합되면서 스타일이 덮여서 문제가 발생했다. next-mdx-remote 라이브러리를 통해 이 문제를 해결했고, 커스텀 스타일링을 적용해 문서가 깔끔하게 보이도록 했다. 


### <strong>3️⃣ intercepting route를 사용한 프리온보딩 플로우 변경</strong>


Next.js 13의 <strong>Intercepting Route</strong>를 활용해 프리온보딩 플로우를 리팩토링했다. 신규 유저는 full page에서 온보딩 과정을 진행하고, 기존 유저는 modal에서 빠르게 인증 절차만 거칠 수 있도록 UX를 개선했다.


다만 구현 과정에서 가장 큰 어려움은 <strong>모달 내에서 쿼리 파라미터(step)가 바뀔 때마다 의도치 않게 full page로 전환되는 문제</strong>였다. 원래는 모달 상태를 유지한 채 단계별 화면이 전환되길 원했지만, 라우팅 구조와 상태 관리가 꼬여서 계속 페이지 전체가 리렌더링되는 상황이 발생했다.


이를 해결하기 위해 Next.js의 라우터 기능만 고집하지 않고, <strong>window.location을 직접 제어하는 방식</strong>을 사용했다


### <strong>4️⃣ auth entity 분리 및 파일 리팩토링</strong>


서비스 아키텍처를 FSD에 맞게 리팩토링하는 작업을 진행했다. 그중 가장 핵심은 auth 관련 코드를 entity 단위로 분리하는 것이었다. auth의 entity를 분리하고 FSD에 맞게 feature/auth와 entity/auth에서 사용하도록 리팩토링했다.


entity는 feature나 ui에 의존하지 않아야 하므로, 로그인 토큰 관리 로직과 API 스키마를 entity에 모으고, 이를 auth/feature에서 사용하도록 리팩토링했다.


리팩토링하면서 파일 경로가 바뀌어 import 에러가 엄청 쏟아져서 조금은 힘들었지만, 협업 시 <strong>“어디에 어떤 코드를 둬야 하는지 기준”</strong>이 생긴다는 점이 가장 큰 배움이었다.


### <strong>5️⃣ 데이터 동기화 로직 구현</strong>


서버에서 데이터를 동기화하는 방식이 변경되어 서버에 맞춰 프론트 측의 코드도 대폭 수정했다
진짜 제일 힘들고 어려웠던 부분.. ㅜ.ㅜ 


원래는 프론트에서 소켓을 호출하고 순차적으로 데이터를 불러와 동기화하는 로직을 통해 진행되었는데, 서버가 업데이트되면서 이제는 <strong>서버가 알아서 순차 실행을 하고, 프론트는 startStage만 호출하면 되는 구조</strong>로 바뀌었다.


웹소켓을 한 번도 사용해본 적도 없었고 공부해본 기억도 거의 없었기에 코드 이해부터 난관이었다. 그래도 데드라인이 꽤 널널했어서 아예 하루 날 잡고 소켓에 대해 가볍게 공부하며 코드를 이해하기 시작했다. 그렇게 하니 전체적인 플로우와 로직을 알 수 있게 되었고 서버에서 테스트를 하며 로직을 갈아엎는 데에 성공하였다!


### <strong>6️⃣ 모바일 서비스 기획 및 와이어프레임 제작 참여</strong>


이제 회사의 도메인에도 익숙해질 때쯤, 9월 마지막 주에는 개발뿐 아니라 기획에도 참여했다. 회사의 신규 모바일 서비스 기획과 와이어프레임 제작 과정에서 디자이너와 협업하며 사용자 경험을 중점적으로 논의했다.


평소 UX에 관심이 많고 사이드 프로젝트에서 디자이너와 협업 경험이 있었기 때문에, 사용자 중심 사고에 맞춰 다양한 의견을 내었고 그 의견들이 대부분 수용되었다 (칭찬도 들었다 &gt;&lt;)


이 경험 덕분에 단순히 개발자로서 기능을 구현하는 게 아니라, <strong>“사용자가 실제로 어떻게 느낄까?”를 고민하는 프론트엔드 개발자</strong>가 되는 것이 얼마나 중요한지 깨달았다.


## 📋 회고


### hydration error를 놓치지 말자


SSR과 Next.js를 접한 지 얼마 되지 않아 바로 실무에서 사용하다 보니 클라이언트 사이드에서만 접근할 수 있는 요소와 서버 사이드에서만 접근할 수 있는 요소들을 구분하는 것이 나에게 있어 매우 어려운 일이었다. 그 결과 가장 자주 맞닥뜨린 문제가 바로 <strong>hydration error</strong>였다.


처음에는 dev 페이지에서만 보이는 에러였고 prod에서는 이 에러가 보이지 않았기에 그냥 넘겼지만, 이 에러가 꽤 많은 영향이 된다는 걸 알고 원인을 하나씩 파고들며 해결해 나갔다. 특히 window나 localstorage와 같은 브라우저 전용 API를 서버 렌더링 단계에서 접근할 수 없다는 사실을 몸소 깨달았다. 문제를 해결하는 과정에서 <strong>SSR과 CSR의 차이를 명확히 구분하는 습관</strong>을 갖게 되었고, 이를 블로그에 따로 정리하며 다시는 같은 실수를 반복하지 않겠다고 다짐했다. 진작에 알았어야 할 에러를 이제야 알다니.. 부끄러웠지만 직접 부딪히며 배운 만큼 더 오래 기억에 남을 것 같다.


### 이제는 공부해야 할 것 같은 WebSocket 


9월 동안 진행한 작업들 중 데이터 동기화 로직에서 websocket을 흔지 않게 만날 수 있었다. 기존에 사용하던 HTTP 요청/응답 방식과는 완전히 달라서 처음에는 코드가 눈에 잘 들어오지 않았다.


이전에 단 한 번도 웹소켓을 써본 적도, 공부해본 적도 없어 코드를 이해하는 과정부터 꽤 난항을 겪었다. 회사 도메인 상 실시간으로 알림을 보내고 실시간으로 데이터를 모니터링해야했기에 반드시 알아야 할 내용이었다.


물론 아직 완벽히 다 이해했다고 할 수는 없지만, 이번 경험을 통해 “앞으로 채팅, 알림, 실시간 모니터링 같은 기능을 만들 때는 반드시 WebSocket을 알아야 한다”는 확신이 생겼다. 단순히 낯선 기술을 스쳐간 것이 아니라, 앞으로 학습해야 할 <strong>개발 로드맵의 한 축</strong>을 발견했다는 점에서 큰 의미가 있었다.


### 남의 코드를 뜯어보는 것이 두렵지 않아졌다!


예전에는 남이 짠 코드를 보는 일이 가장 어렵게 느껴졌다. 나의 코드 스타일이 다르고, 로직 전개 방식도 달라서 이해하는 데 시간이 많이 걸렸다. 하지만 인턴 생활 동안은 회사 코드베이스를 이해하고 직접 수정·리팩토링하는 일이 반복적으로 주어졌다.


처음에는 막막했지만, 여러 번 코드를 읽고 직접 고치면서 점점 코드를 작성하는 시야가 넓어졌다. 단순히 코드 한 줄을 이해하는 수준을 넘어, <strong>전체적인 아키텍처와 흐름 속에서 이 코드가 어떤 역할을 하는지</strong> 생각하는 습관이 생겼다. 이제는 남의 코드를 뜯어보는 일이 두렵지 않고, 오히려 다양한 로직을 접할 수 있는 기회라고 느껴진다.


## ✏️ 총정리


8월의 경우, 새로운 기능과 페이지를 제작한 달이었다면 9월은 <strong>실무적인 문제 해결, 구조 리팩토링, 실시간 데이터 흐름 이해</strong>에 집중한 달이었다.


데이터 동기화 과정이나 인증서 등록 과정 등 실무에서만 오로지 접할 수 있는 기능들을 다뤄보니 정말 어려웠지만
그 과정을 극복하고 기능 디벨롭을 해내면서 관련 지식들도 많이 알게 되었다


단순히 코드를 짜는 개발자가 아니라, <strong>실제 서비스의 품질과 구조를 고민하는 개발자</strong>로 성장하는 9월이었다.




## <strong>💡 시작하기</strong>


현재 다니고 있는 회사에서 Next.js를 사용하여 본격적으로 Next.js를 사용하고 공부하게 되었는데요!


그 중에 가장 자주 부딪힌 문제가 바로 <span class="notion-color-blue"><strong>Hydration Error</strong></span>였어요.
그래서 이번에는 <strong>Hydration Error</strong>가 무엇인지, 왜 발생하는지, 어떻게 해결할 수 있는지 대해 정리해보려고 해요


## <strong>⚙️ Hydration</strong> 


> <span class="notion-callout-icon">📖</span> <span class="notion-callout-text"><span class="notion-color-blue"><strong>Hydration</strong></span> ? 서버로부터 정적 렌더링으로 받은 파일을 클라이언트가 <u><strong>다양한 기능</strong></u>들을 첨부하여 동적 웹 페이지로 변환하는 기술</span>
> 
> - <u><strong>다양한 기능</strong></u>?
>     - 이벤트 처리
>     - 상태 처리
>     - 인터랙션 및 애니메이션


<span class="notion-color-blue"><strong>Hydration</strong></span>의 뜻은 <u><em><strong>“수화”</strong></em></u> 라는 뜻으로, <strong>메마른 정적 HTML 파일</strong>에 <span class="notion-color-red"><strong>동적 요소</strong></span> 라는 <span class="notion-color-red"><strong>물</strong></span>을 주기 때문에 다음과 같은 단어를 사용했다고 해요


## <strong>⚙️ Hydration Error</strong> 


> <span class="notion-callout-icon">📖</span> <span class="notion-callout-text"><span class="notion-color-blue"><strong>Hydration Error</strong></span> ? 클라이언트가 서버에서 렌더된 HTML을 재사용할 때, 서버와 클라이언트의 렌더링 결과가 다를 경우 발생하는 에러</span>

> <strong>Next.js에서의 SSR 과정</strong>
1. 서버에서 정적인 페이지인 HTML 파일 만듦
2. 클라이언트에서 HTML 파일을 초기 렌더링시킴 ← 이때의 파일과 서버에서의 파일 비교
3. 클라이언트에서 hydration 진행

<span class="notion-color-blue"><strong>hydration</strong></span>의 전제 : <span class="notion-color-red_background">서버가 만든 HTML === 클라이언트가 초기 렌더한 HTML</span>


이 전제가 맞지 않을 때 <span class="notion-color-blue"><strong>hydration error</strong></span>가 발생해요.

> <strong>ex) hydration error</strong>

```typescript
const width = window.innerWidth;
return <div>{width}</div>;
```

- 서버 : <code>&lt;div&gt;</code><span class="notion-color-gray"><code>undefined</code></span><code>&lt;/div&gt;</code> or <span class="notion-color-gray"><em>window is not defined</em></span>
- 클라이언트 : <code>&lt;div&gt;</code><strong><code>1920</code></strong><code>&lt;/div&gt;</code>

<strong>⇒ 같지 않으므로 hydration이 깨져버림</strong>


## <strong>🖥️ hydration error가 발생하는 경우</strong>


가<strong>장 많이 hydration error를 겪는 경우는</strong>

- <strong>LocalStorage</strong>, <strong>브라우저 API(window, document)</strong> 등 클라이언트에서만 접근할 수 있는 요소
- <strong><code>Date.now()</code></strong>, <strong><code>Math.random()</code></strong>과 같은 실행 시마다 달라지는 값

에 접근했을 때 발생해요


이들의 경우, 렌더링 시점에 바로 실행하기 때문이에요


## <strong>🖥️ Solution : useEffect 사용하기</strong>


hydration error를 해결하려면 위에서 언급한 값들을 반드시 useEffect 안에서 처리하면 돼요

> <strong>useEffect를 왜 써야 할까요?</strong>

useEffect는 <strong>브라우저 렌더링이 끝난 뒤(hydration 이후)</strong> 실행되는 훅이에요.


useEffect는 서버에서 실행되지 않기 때문에, 서버는 useEffect 안에 있는 코드는 건너뛰고 HTML을 만들게 되어요


클라이언트는 서버가 만들어준 HTML을 그대로 받아 hydration을 통해 초기 렌더링을 맞춘 뒤, 그 이후에 useEffect가 실행되므로 에러를 해결할 수 있어요


### <strong>기존 코드 vs 해결한 코드</strong>

> 기존 코드

```typescript
"use client";

export function ExampleComponent() {
  // 클라이언트 API를 렌더링 중에 바로 호출 → 서버에서는 window가 없음
  const hostname = window.location.hostname;

  return <div>현재 호스트: {hostname}</div>;
}
```


```typescript
"use client";

import { useEffect, useState } from "react";

export function ExampleComponent() {

  // 클라이언트에서만 실행되므로 서버에서는 에러 없음
  useEffect(() => {
    setHostname(window.location.hostname);
  }, []);

  if (!hostname) {
    return <div>호스트 이름 로딩 중...</div>;
  }

  return <div>현재 호스트: {hostname}</div>;
}
```


### <strong>🔗 참고</strong>


<div class="notion-bookmark"><a href="https://nextjs.org/docs/messages/react-hydration-error" target="_blank" rel="noopener noreferrer"><div class="notion-bookmark-content"><div class="notion-bookmark-title">Text content does not match server-rendered HTML</div><div class="notion-bookmark-url">nextjs.org</div></div><div class="notion-bookmark-thumb"><img src="https://nextjs.org/api/og?title=Text%20content%20does%20not%20match%20server-rendered%20HTML" alt="" /></div></a></div>


<div class="notion-bookmark"><a href="https://blog.hwahae.co.kr/all/tech/13604" target="_blank" rel="noopener noreferrer"><div class="notion-bookmark-content"><div class="notion-bookmark-title">React의 hydration mismatch 알아보기 – 화해 블로그 | 기술 블로그</div><div class="notion-bookmark-desc">React의 hydration mismatch 알아보기 화해는 에러 트래킹 서비스인 Sentry를 사용하고 있는데요. 지난해 Next.js의 static export로 배포한 이벤트 페이지에서 hydration mismatch 에러가 쌓이기 시작했습니다.</div><div class="notion-bookmark-url">blog.hwahae.co.kr</div></div><div class="notion-bookmark-thumb"><img src="https://blog-wp.hwahae.co.kr/wp-content/uploads/2023/09/cover-1.jpg" alt="" /></div></a></div>




## <strong>💡 코드 스플리팅 (Code Splitting)</strong>#


> <span class="notion-callout-icon">📖</span> <span class="notion-callout-text"><span class="notion-color-blue"><strong>코드 스플리팅 (Code Splitting)</strong></span> ? 웹 애플리케이션의 초기 로딩 속도를 개선하기 위해 코드 여러 개의 파일을 청크로 나누는 기법</span>
> 
> 
> 단순히 “파일을 나눈다”는 의미가 아니라, <strong>사용자가 실제로 필요로 할 때 필요한 코드만 불러오는 전략</strong>까지 포함해요


<strong>사용 이유</strong> ? 웹 애플리케이션은 <strong>하나의 큰 번들 파일</strong>로 묶음

- 파일 크기가 매우 커 초기 로딩 속도가 느려짐
- 코드 한 줄만 바뀌어도 전체 파일을 다시 빌드해야 함 → 비효율적

⇒ 코드 스플리팅을 통해 파일을 보낼 때 <span class="notion-color-red"><strong>먼저 보낼 수 있는 파일을 먼저 보냄</strong></span> → 렌더링 속도 증가 → 성능 최적화


---


## 📄 코드  스플리팅의 방식


### 1️⃣ <strong>Route 단위 분할</strong>


페이지를 전환할 때 필요한 컴포넌트만 불러와요


```typescript
import React, { Suspense } from "react";
import { BrowserRouter, Routes, Route } from "react-router-dom";

const Home = React.lazy(() => import("./pages/Home"));
const About = React.lazy(() => import("./pages/About"));

function App() {
  return (
    <BrowserRouter>
      <Suspense fallback={<div>Loading...</div>}>
        <Routes>
          <Route path="/" element={<Home />} />
          <Route path="/about" element={<About />} />
        </Routes>
      </Suspense>
    </BrowserRouter>
  );
}
```

> <strong>React.lazy</strong>

공식문서에서 <code>lazy</code>의 설명을 다음과 같이 시작해요

> <em><strong><code>lazy</code></strong></em><em><strong>를 사용하면 컴포넌트의 코드가 최초로 렌더링될 때까지 로딩을 미룰 수 있다.</strong></em>

lazy loading은 <span class="notion-color-blue">중요도가 떨어지거나 당장은 화면에 보이지 않는 요소들의 로딩을 우선적으로 시행하지 않으면서</span> 웹페이지 로딩 성능을 최적화해요. 


쉽게 말하면 페이지 내에서 <span class="notion-color-red"><strong>실제로 필요로 할 때까지 리소스의 로딩을 미루는 것</strong></span>이라고 생각하면 돼요.


```javascript
const SomeComponent = lazy(() => import('./SomeComponent'));
```


### 2️⃣ <strong>Component 단위 분할</strong>


컴포넌트를 필요할 때만 불러와요


```typescript
import React, { Suspense } from "react";

const LazyComponent = React.lazy(() => import("./LazyComponent"));

function App() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <LazyComponent />
    </Suspense>
  );
}
```


### 3️⃣ <strong>vendor 분할</strong>


> <span class="notion-callout-icon">📖</span> <span class="notion-callout-text"><span class="notion-color-blue"><strong>vendor 파일</strong></span> ? 프로젝트에서 전역적으로 사용되는 라이브러리(like react, zustand, framer-motion)를 따로 분리한 청크 파일</span>
> 
> - vendor의 경우 변경 가능성이 낮기 때문에, 유저는 브라우저에 캐시해뒀던 vendor.js를 재사용할 수 있어요. 이로 인해 <span class="notion-color-blue"><strong>서버 리소스가 절약</strong></span>되고 <span class="notion-color-blue"><strong>초기 로딩 속도가 개선</strong></span>돼요


### 4️⃣ <strong>dynamic import</strong> 


번들러의 경우, <code>import()</code> 구문을 만나면 <strong>자동으로 별도 청크로 분리</strong>해요


조건부 로딩이나 특정 상황에서만 모듈을 불러올 때 유용해요 


```typescript
async function loadModule() {
  const { myFunction } = await 
import("./module.js");

  myFunction();
}
```



[Internship] 2025-08 인턴일지

1. 디자인 시스템 구현

2. 발전소 진단 리포트 페이지 제작

2-1. 기본정보

2-2. 계약정보

2-3. 발전량

2-4. 매출 렌더링

3. PDF 다운로드

4. 초기 진입 시, UX 향상

5. Skeleton UI 도입

7. 도메인별 로고 조건부 렌더링 진행

8. EmptyCase 예외처리

9. 리팩토링 요구사항 문서화