웹 서비스를 개발하다 보면, 네트워크 요청은 항상 성공한다고 가정할 수 없다. 서버가 일시적으로 응답하지 않을 수도 있고, 사용자의 네트워크 환경이 불안정할 수도 있고, 요청이 예상보다 오래 걸리는 경우도 있다.

처음에는 단순히 fetch() 만 사용하면 충분하다고 생각했지만, 공통 Fetch 유틸리티를 구현하면서 ‘실패하는 요청을 어떻게 처리할 것인가’가 서비스의 안정성과 사용자 경험에 큰 영향을 준다는 점을 알게 되었다.

이번 글에서는 안정적인 네트워크 요청을 만들기 위해 고려했던 Timeout, AbortController, Retry Strategy에 대해 정리해보려고 한다.

프론트에서의 재시도 전략은 네트워크 일시 장애나 서버 과부하 시 사용자 경험을 해치지 않고 요청을 복구하는 패턴이다.

Fetch API에는 Timeout이 없다.

참고 자료

• MDN - Fetch API

fetch() 를 처음 사용할 때 놓치는 부분 중 하나가 바로 Timeout이다.

await fetch("/api/users");

이 코드를 보면 일정 시간이 지나면 자동으로 요청이 종료될 것처럼 느껴질 수 있지만, 실제로는 그렇지 않다.

Fetch API는 자체적으로 Timeout 기능을 제공하지 않는다. 서버가 응답하지 않더라도 브라우저는 응답이 올 때까지 계속 기다린다. 즉, Promise는 pending 상태로 남아 있고, 사용자는 로딩 화면만 계속 보게 될 수도 있다.

서비스를 운영하는 입장에서는 이러한 상황을 그대로 둘 수 없다. 실제로 프로젝트 개발 중 공동 기록 작성 후 저장 API 요청을 보내는데 서버로부터 응답이 오지 않아 10초 이상 기다렸다 끊어버린 경험이 있다.

일정 시간이 지나도 응답이 오지 않는다면 요청을 종료하고, 사용자에게 적절한 안내를 제공하는 것이 더 나은 사용자 경험을 제공할 것이다.

그래서 Timeout 처리가 필요하다.

AbortController를 이용한 Timeout 구현

참고 자료

• MDN - AbortController
• MDN - AbortSignal

Fetch API에는 Timeout 옵션은 없지만, 요청을 직접 취소할 수 있는 기능은 제공한다. 이때 사용하는 것이 AbortController 이다.

AbortController 는 비동기 작업을 중단하기 위한 Web API이다. Fetch API는 이 객체가 제공하는 signal 을 전달받아 요청을 관리한다.

const controller = new AbortController();

fetch("/api/users", {
  signal: controller.signal,
});

그리고 일정 시간이 지나면 abort() 를 호출해 요청을 종료할 수 있다.

setTimeout(() => {
  controller.abort();
}, 5000);

즉, Timeout 기능을 직접 구현하는 방식이다.

AbortSignal은 어떤 역할을 할까?

AbortController 와 함께 자주 등장하는 객체가 AbortSignal 이다.

처음에는 두 객체의 차이가 헷갈렸지만, 역할은 생각보다 단순하다.

• AbortController: 요청을 취소하는 주체
• AbortSignal: 요청이 취소되었는지 알려주는 신호

Fetch는 signal 을 계속 관찰하다가 abort() 가 호출되면 요청을 즉시 종료하고 AbortError 를 발생시킨다.

fetch 시작
      │
      ▼
AbortSignal 등록
      │
      ▼
controller.abort()
      │
      ▼
AbortSignal 상태 변경
      │
      ▼
fetch 종료 (AbortError 발생)

따라서 try...catch 를 사용할 경우에는 일반적인 네트워크 에러뿐 아니라 AbortError 도 함께 처리하는 것이 좋다.

여기서 하나 더 생각해봐야 하는게 있다. 타임 아웃 시간을 선택하는 것이다.

시간 제한을 너무 높게 설정하면 클라이언트가 대기하는 시간 동안에도 리소스가 계속 사용되기 때문에 유용성이 떨어진다. 시간 제한을 너무 낮게 설정하면 두 가지 위험이 대두된다.

• 요청의 재시도가 너무 많아져 백엔드의 트래픽과 대기 시간이 증가한다.
• 모든 요청의 재시도가 시작되기 때문에 소규모 백엔드 지연 시간 증가가 완전한 가동 중단으로 이어진다.

요청이 실패했다면 다시 요청하면 될까?

Timeout을 구현하고 나면 자연스럽게 드는 생각이 있다.

“실패했으니 다시 요청하면 되는 것 아닌가?”

Timeout뿐만 아니라, 의도치않게 실패된 것인지 의도된 실패인지 분별할 수 없을 때 요청을 재시도하는 것이다.

하지만 모든 요청을 무조건 retry 하는 것은 위험할 수 있다.

네트워크 오류나 일시적인 서버 장애처럼 잠깐의 문제라면 retry가 효과적일 수 있다. 반면, 사용자의 요청 자체가 이미 정상적으로 처리되었는데 응답만 받지 못한 상황이라면 이야기가 달라진다.

예를 들어 결제 API를 생각해보자

결제 요청
↓
서버는 결제 완료
↓
응답 전 네트워크 끊김
↓
클라이언트는 실패라고 판단
↓
Retry
↓
결제가 두 번 수행될 수도 있다.

즉, retry는 “실패했으니 다시 보내자”가 아니라 왜 실패했는지를 먼저 판단해야 하는 전략이다.

언제 Retry 해야할까?

일반적으로 retry는 일시적인 오류에 대해서만 수행하는 것이 좋다.

대표적인 예시는 다음과 같다.

• 네트워크 연결이 잠시 끊어진 경우
• 서버가 일시적으로 과부하 상태인 경우
• Timeout이 발생한 경우
• 5xx 같은 일반적인 서버 오류

이러한 경우는 잠시 후 다시 요청하면 정상적으로 처리될 가능성이 높다.

반대로 인증 오류(401), 권한 오류(403), 잘못된 요청(400)처럼 클라이언트가 수정하지 않는 이상 결과가 바뀌지 않는 오류는 retry해도 의미가 없다.

중요한 것은 HTTP Method가 아니라 멱등성

흔히 GET 은 retry가 가능하고 POST 는 위험하다고 이야기한다. 물론 일반적으로는 맞는 이야기지만, 실제로는 HTTP 메소드보다는 멱등성이 더 중요한 기준이 된다.

멱등성 동일한 요청을 여러 번 수행하더라도 결과가 동일하게 유지되는 성질

예를 들어 PUT /users/1 요청은 여러 번 호출하더라도 최종 상태는 동일하다. 따라서 retry가 비교적 안전하다.

반면 POST /payments 처럼 새로운 데이터를 생성하는 요청은 호출할 때마다 새로운 결제가 발생할 수 있기 때문에 retry가 위험하다.

즉, retry 여부는 HTTP 메소드만 보고 결정하기보다 해당 API가 멱등성을 보장하는지를 먼저 확인해야 한다.

Retry도 전략이 필요하다

참고 자료

• AWS timeouts retries and backoff with jitter

주요 재시도 전략은 다음과 같다.

1. 즉시 재시도

실패 즉시 딜레이 없이 재시도한다. 순간적인 네트워크 깜빡임이 원인일 때 유용하고, 사용자는 대기 시간 없이 원활한 이용이 가능하다.

2. 고정 간격 재시도

실패시 매번 정해진 고정 시간을 기다린 후 재시도한다. 단순한 간헐적 오류에 대응할 때 적합하지만, 서버 장애 시 짧은 시간에 요청이 몰릴 위험이 있다.

3. 지수 백오프(Exponential Backoff) 및 지터(Jitter)

재시도를 거듭할 수록 대기 시간이 지수 함수적으로 증가하며(2초, 4초, 8초..), 여기에 무작위 값(Jitter)을 추가해 요청이 동시에 서버로 쏠리는 현상을 방지한다. 서버 점검이나 트래픽 급증 시 시스템을 보호하는 가장 안정적인 전략이다.

고정 간격과 지수 백오프 모두 일정 시간을 두고 재시도를 한다는 점은 동일하다. 하지만 어차피 동시에 요청이 몰린다면 똑같은 시간 간격으로 모든 재시도가 동일하게 몰릴 것이기에 일정 시간 대기 재요청도 한계가 있다.

그래서 이를 개선하기 위한 방법이 Jitter를 도입하는 것이다.

Jitter 데이터 전송이나 신호 처리시, 시간 간격이 일정하지 않고 미세하게 흔들리거나 변동되는 현상을 말한다. 네트워크 분야에서는 패킷이 목적지에 도착하는 지연 시간(latency)이 불안정하게 요동치는 현상을 말한다. 이 개념을 retry에 적용하면, API를 요청하는 클라이언트 간의 동일한 재시도 시간 간격에 무작위성을 추가하여 서로 요청하는 시간대를 분산시킬 수 있다.

1번과 같은 실패 직후 바로 다시 요청하는 것은 좋은 방법이 아니다.

예를 들어 서버 장애가 발생한 상황에서 수천 명의 사용자가 동시에 Retry를 수행한다면, 이미 과부하 상태인 서버에 더 많은 요청을 보내게 된다.

이러한 문제를 방지하기 위해 대부분의 서비스는 3번 지수 백오프와 지터를 함께 사용한다.

AWS에서도 retry 전략으로 지수 백오프와 지터를 함께 사용하는 방식을 권장하고 있다.

아래는 AWS 문서에서 가져온 내용

• 재시도 시점 결정. 일반적으로 우리는 부작용을 수반하는 API가 멱등성을 제공하지 않는 한 안전하지 않다고 여기고 있습니다. 이것은 재시도 빈도와 상관없이 부작용이 한번만 발생하게 합니다. 읽기 전용 API는 대개 멱등적이지만 리소스 생성 API는 그렇지 않을 수 있습니다. 중복된 부작용을 방지하기 위해서는 바람직한 API 설계와 함께 클라이언트 구현 시 여러 가지 사항을 주의해야 합니다.
• 어떤 장애 발생 시 재시도할 가치가 있는지 파악하기. HTTP는 클라이언트*와 *서버 오류 간에 분명한 구분을 제공합니다. 클라이언트 오류는 나중에도 성공하지 못할 것이기 때문에 동일한 요청으로 재시도해서는 안 되지만, 서버 오류는 후속 시도에서 성공할 수 있습니다. 불행히도 시스템의 최종 일관성은 이 경계를 모호하게 만듭니다. 한 순간의 클라이언트 오류는 상태가 전파될 경우 다음 순간에 성공으로 바뀔 수 있습니다.

프로젝트에 재시도 정책 적용

참고 자료

• AWS exponential backoff and jitter

재시도 대상: 응답을 못 받은 경우만

재시도 대상은 ‘응답을 못 받은 경우’만 이다. 가장 먼저 정한 기준은 fetch 자체가 실패한 경우만 재시도 대상으로 삼는다는 것이다.

try {
  const response = await fetch(url, { ...fetchOptions, signal: controller?.signal });
  // ... 응답을 정상적으로 받았다면(4xx/5xx 포함) 그대로 반환, 재시도하지 않음
  return { ...data, headers: response.headers };
} catch (error) {
  // AbortError(타임아웃)는 재시도하지 않고 즉시 반환
  if (err.name === 'AbortError') {
    return { success: false, data: null, error: { code: 'TIMEOUT', ... } };
  }
  // JSON 파싱 에러도 재시도하지 않음 — 서버 응답 자체의 문제일 가능성
  if (err.message.includes('JSON') || ...) { ... }

  // 여기까지 걸러지고 남은 것 — 연결 실패, DNS 오류 등 순수 네트워크 예외만 재시도
  if (attempt >= maxRetries) { return { ...NETWORK_ERROR }; }
  await delay(waitTime);
  return fetchWithRetry(url, fetchOptions, attempt + 1, ...);
}

서버가 응답을 주는 순간 재시도 루프에서는 완전히 손을 뗀다. 처음엔 5xx도 재시도해야 하지 않나 고민했지만, 우리 서비스 규모에서는 fetch 자체가 실패하는 케이스(연결 끊김, DNS 실패)와 타임아웃만 우선 다루고, 서버가 명시적으로 에러를 반환한 경우는 재시도 없이 사용자에게 즉시 알리는 쪽을 택했다.

타임아웃(AbortError)을 재시도 대상에서 뺀 것도 같은 맥락이다. 이미 응답이 오래 걸리고 있다는 신호인데, 거기에 재시도까지 얹으면 사용자를 더 오래 기다리게 만들 뿐이다.

멱등성 기준으로 재시도 여부 나누기

앞서 정리했듯 HTTP 메서드보다 멱등성이 기준이 되어야 한다. 이걸 실제 코드에 반영했다.

// 네트워크 예외 재시도는 HTTP 스펙상 멱등이 보장되는 메서드(GET/PUT/DELETE)에만 기본 적용한다.
// POST(생성)와 PATCH(부분 수정, 멱등 보장 안 됨)는 요청이 서버에
// 도달해 처리된 뒤 응답만 유실됐을 수 있어, 자동 재시도가 중복 생성/중복 처리로
// 이어질 수 있다 — 필요하면 호출부에서 options.maxRetries로 명시적으로 오버라이드한다.
const method = (fetchOptions.method ?? 'GET').toUpperCase();
const isIdempotentMethod = method === 'GET' || method === 'PUT' || method === 'DELETE';
const resolvedMaxRetries = maxRetries ?? (isIdempotentMethod ? 3 : 0);

maxRetries 를 호출부에서 명시적으로 넘기면 이 기본값을 오버라이드할 수 있게 열어뒀는데, 이건 특정 POST 엔드포인트가 실제로는 멱등하다는걸 확인했을 때를 위한 탈출구라고 보면 된다.

지수 백오프 + Full Jitter

// 재시도 전 대기: 지수 백오프(최대 1 -> 2 -> 4초)에 Full Jitter 적용.
// 같은 장애로 여러 클라이언트가 동시에 재시도할 때 정확히 같은 타이밍에
// 몰려 서버 회복을 방해하지 않도록, 0~상한 사이에서 무작위로 대기 시간을 뽑는다.
const maxWaitTime = retryDelay * 2 ** attempt;
const waitTime = Math.random() * maxWaitTime;
await delay(waitTime);

AWS 문서에서 소개하는 여러 Jitter 방식 중 가장 단순하고 실측상 성능이 가장 좋다고 언급된 Full Jitter(0~상한 사이 균등 분포)를 골랐다.

상한 자체는 기존 지수 백오프 그대로 유지하고, 실제 대기 시간만 그 안에서 매번 랜덤하게 뽑는 구조다.

인증(401) 재시도는 별도 취급

토큰 만료로 인한 401 처리는 위의 재시도 로직과 분리했다.

if (!data.success && response.status === 401 && isRefreshableAuthError(errorCode) && ...) {
  const newToken = await refreshAccessToken();
  // ...
  return fetchWithRetry(
    url,
    { ...fetchOptions, headers: finalHeaders },
    attempt,       // ← 증가시키지 않는다
    maxRetries,
    ...
  );
}

이 재시도는 attempt 를 그대로 넘겨서 네트워크 예외 재시도의 횟수를 소모하지 않고, 대기 시간도 거치지 않는다.

근거는 멱등성이 아니라 401을 받았다는건 서버가 아직 이 요청의 실제 처리를 시작조차 안 했다는 것이다.

인증 가드가 비즈니스 로직 실행 전에 요청을 막기 때문에, 메서드가 POST든 뭐든 토큰을 갱신한 뒤 같은 요청을 다시 보내도 중복 처리 위험이 없다. 즉, 이 재시도가 안전한 이유는 멱등성과는 다른 축의 이야기다.

마무리

AWS의 결론을 그대로 가져와봤다.

분산 시스템에서 일시적인 장애 또는 원격 상호 작용의 지연은 불가피합니다. 시간 제한은 시스템이 과도하게 오래 중단되지 않게 하고, 재시도는 이러한 장애를 거를 수 있게 해 주며, 백오프 및 지터는 활용도를 향상시키고 시스템의 정체를 줄여 줍니다.

우리는 재시도를 조심스럽게 다루는 것이 중요하다는 것을 배웠습니다. 재시도는 종속 시스템의 부하를 증폭시킬 수 있습니다. 시스템에 대한 호출이 시간 제한을 초과하고 시스템에서 오버로드가 발생한 경우 재시도는 문제를 개선하는 것이 아니라 더욱 악화시킬 수 있습니다. 우리는 종속성이 양호한 경우에만 재시도를 수행하여 문제가 증폭되는 것을 방지하고 있습니다. 재시도는 가용성 향상을 지원하지 않기 때문에 우리는 재시도를 중단하고 있습니다.

처음 재시도 정책을 도입한 이유는 유저 입장에서의 생각한 불편함 때문이었다. 버튼을 클릭하거나 폼을 제출하는 등의 요청을 보냈는데, 네트워크와 같은 문제로 인해 요청이 실패해버리면 직접 재요청해야 하는 불편함이 생긴다.

이를 어떻게 개선할 수 있을까 고민하다 알게된게 재시도 정책이었다.

그리고 프로젝트를 진행하면서 직접 겪었던 기록 저장 API의 무한 대기로 인해 AbortController로 Timeout까지 적용하게 되었다.

사용자 경험을 개선하기 위해 도입했던 것들이지만, 실제 시스템에 적용하면서 시스템의 안정성과 안전 장치의 중요성을 체감할 수 있었다.

이렇게 구현하고 나중에 어떤 기업의 과제 테스트를 진행했었는데, 거기서 '에러 발생시 재시도 로직을 적절히 구현하라'는 요구사항을 마주했다. 그걸 보고, 좋은 경험 했구나..! 생각이 들었다.

참고자료

• MDN - Fetch API MDN - AbortController
• MDN - AbortSignal
• AWS timeouts retries and backoff with jitter
• AWS exponential backoff and jitter
• https://jungseob86.tistory.com/12

프로젝트에서 인증 구조를 개선하면서 Refresh Token의 동시 갱신 문제를 해결하기 위해 Mutex를 적용했다.

동일한 실행 환경에서는 Mutex 만으로도 중복 Refresh 요청을 방지할 수 있었지만, 설계를 검토하는 과정에서 한 가지 의문이 생겼다.

“다른 탭이나 다른 기기에서도 Mutex가 동작할까?”

결론부터 말하면, 동작하지 않는다.

이번 글에서는 그 이유와 함께, 왜 백엔드에서 Grace Period와 같은 정책이 필요한지 정리해보려고 한다.

Mutex는 어디까지 보호할 수 있을까?

Mutex는 여러 요청이 동시에 하나의 자원에 접근하지 못하도록 임계 구역을 보호하는 동기화 기법이다.

예를 들어 Access Token이 만료된 상황에서 여러 API 요청이 동시에 발생했다고 가정해보자.

API 요청 A
API 요청 B
API 요청 C
↓
모두 Access Token 만료
↓
모두 Refresh 요청 시도

이 경우 Mutex를 적용하면 첫 번째 요청만 Refresh를 수행하고, 나머지 요청은 Refresh가 끝날 때까지 대기하게 된다.

Refresh Request A
↓
Lock 획득
↓
Refresh Token 사용
↓
새로운 Access Token 발급
↓
Unlock
↓
대기 중이던 요청들이 새로운 Access Token 사용

덕분에 동일한 실행 환경에서는 Refresh 요청이 한 번만 발생하게 된다.

Mutex에도 한계가 있다.

참고 자료

• better-auth issues

중요한 점은 Mutex는 현재 실행 중인 프로세스(메모리 공간) 안에서만 동작한다는 것이다.

예를 들어, 아래와 같은 상황을 생각해보면 된다.

Chrome 탭 1
└── Mutex A

Chrome 탭 2
└── Mutex B

Safari
└── Mutex C

모바일 앱
└── Mutex D

참고로 Chrome의 각 탭은 각각 다른 프로세스로 동작한다.

각 실행 환경은 서로 다른 메모리를 사용한다.

즉,

• Chrome 탭 1의 Mutex는 Chrome 탭 2를 알지 못하고,
• Safari도 Chrome의 Mutex를 공유하지 않으며,
• 다른 기기 역시 동일하다.

따라서 각각의 환경에서 동시에 Refresh 요청이 발생할 수 있다.

다른 예시도 있다.

• 백그라운드 작업과 포그라운드 작업 모두 Refresh 시도를 유발하는 모바일 앱
• 서버에서 첫 번째 Refresh는 성공했지만, 클라이언트가 응답을 받지 못하고 동일한 Refresh 토큰을 재시도하는 경우 네트워크 시간 초과/응답 손실 발생 이 경우는 이미 만료된 토큰을 사용하므로 재사용 공격으로 간주되어 전체 토큰이 취소되고 불필요하게 로그아웃된다.

Multi Device 환경에서는 어떤 문제가 발생할까?

예를 들어 PC와 모바일이 동일한 계정으로 로그인되어 있다고 생각해보자.

PC
↓
Refresh Token RT1 사용
↓
새로운 RT2 발급

거의 동시에 모바일에서도 Refresh 요청을 보낸다.

모바일
↓
아직 RT1을 가지고 있음
↓
RT1으로 Refresh 요청

만약 서버가 Refresh Token Rotation(RTR)을 사용한다면 RT1은 이미 사용된 토큰이므로 무효화되어 있다.

따라서 서버는 이를 재사용 공격으로 판단하여 요청을 거부할 수 있다.

재사용 공격 공격자가 유효한 데이터 송수신(토큰이나 인증 정보 등)을 중간에서 탈취한 후, 이를 그대로 재전송하여 정상적인 요청인 것처럼 서버를 속이는 공격 기법을 한다.

여기서 재사용 공격 검출에 대해서 간단하게 정리해보자.

1. 정상 흐름(RTR 적용시)
   • 클라이언트가 Refresh Token A를 서버로 보내 새로운 Access Token과 Refresh Token B를 받는다.
   • 이때 서버는 Refresh Token A를 이미 사용됨(무효) 처리한다.
2. 재사용 공격 발생시
   • 만약 탈취범이 이미 무효화된 Refresh Token A를 다시 서버에 전송하면, 서버는 이를 재사용 공격으로 판단한다.
   • 서버는 해당 계정의 보안이 뚫렸다고 가정하고, 즉시 모든 Refresh Token을 만료시키거나 해당 계정을 로그아웃처리하여 피해를 막는다.

그런데 이런 재사용 공격이 다중 기기나 다중 탭 환경에서의 오탐 문제로 이어질 수 있다는 것이다.

RT1 사용
↓
이미 사용된 Refresh Token
↓
401 Unauthorized

문제는 이 요청이 공격이 아니라 정상적인 사용자의 요청이라는 점이다. 단지, 두 기기에서 거의 동시에 요청했을 뿐이다.

서버는 단순히 누군가 폐기된 Token A를 재사용하려는 공격으로 오해하게 되는 것이다.

그래서 Grace Period가 필요하다

참고 자료

• Lucid refresh token theft detection
• okta developer refresh tokens guides

이러한 문제를 해결하기 위해 일부 서비스에서는 Grace Period를 사용한다.

Grace Period는 Refresh Token이 한 번 사용되더라도 아주 짧은 시간 동안은 이전 Refresh Token도 함께 허용하는 정책이다.

RT1 사용
↓
RT2 발급
↓
(Grace Period)
↓
RT1도 잠시 허용

정상 사용자의 정당한 지연 요청이 재사용 공격으로 잘못 인식되어 로그아웃되는 것을 방지하기 위해, 서버에서 이전 토큰도 몇 초간은 예외적으로 허용해 주는 것이다.

덕분에 네트워크 지연이나 여러 기기에서 거의 동시에 발생한 Refresh 요청도 정상 요청으로 처리할 수 있다.

Grace Period가 끝나면 기존 Refresh Token은 완전히 만료된다.

물론, 유예 기간 동안 침해 탐지력이 약해지긴 하지만, 그 영향은 미미하다. Lucid에 따르면,

"A malicious actor would have to guess when the true client is going to refresh the token. And even if they guess successfully, as long as you give both of them (the malicious actor and the true client) the same new tokens, then the malicious actor will have to make another lucky guess the next time the client refreshes its tokens."

악의적인 공격자는 실제 클라이언트가 언제 토큰을 갱신할지 추측해야 합니다. 설령 예측에 성공하더라도, 악의적인 공격자와 실제 클라이언트 모두에게 동일한 새 토큰을 제공하는 한, 악의적인 공격자는 클라이언트가 다음에 토큰을 갱신할 때 다시 한번 운 좋게 예측해야 합니다.

라고 한다. 또한, 유예 기간은 60초를 넘지 않아야 한다고 전한다. 갱신 및 토큰 재발급 프로세스는 몇 초밖에 걸리지 않으므로, 1분이면 동시 요청이 안정될 수 있는 충분한 시간이라는 것이다.

프론트엔드 측만으로는 해결할 수 없는 이유

위에 먼저 설명했던 다중 탭/기기 에서의 RTR 문제를 인지한 뒤에는 Mutex만으로는 해결할 수 없겠다는 생각이 들었다.

Mutex는 동일한 실행 환경에서만 동작하기 때문에, 여러 탭이나 여러 기기에서 발생하는 경쟁 상태까지 해결할 수는 없다.

결국 문제를 해결하기 위해서는 역할을 나누어야 했다.

• 프론트엔드
  • 동일 실행 환경에서 Mutex를 사용해 중복 Refresh 요청 방지
• 백엔드
  • 여러 실행 환경에서 발생하는 경쟁 상태를 Grace Period로 허용

즉, 하나의 기술만으로 해결되는 문제가 아니라, 클라이언트와 서버가 함께 고려해야 하는 인증 설계 문제였던 것이다.

프로젝트에 적용한 인증 구조

Mutex로 Refresh Token 갱신 로직 임계 구역으로 제한하기

클라이언트 사이드와 서버 사이드를 나눠서 정리해줬다.

// 클라이언트 사이드에서 사용되는 Mutex
let isRefreshing = false;
let refreshSubscribers: ((token: string | null) => void)[] = [];

function subscribeTokenRefresh(callback: (token: string | null) => void) {
  refreshSubscribers.push(callback);
}
function onTokenRefreshed(token: string | null) {
  refreshSubscribers.forEach((callback) => callback(token));
  refreshSubscribers = [];
}

export async function refreshAccessToken(): Promise<string | null> {
  if (isRefreshing) {
    // 이미 갱신 중이면 새로 요청을 보내지 않고 대기열에 합류
    return new Promise((resolve) => subscribeTokenRefresh(resolve));
  }

  isRefreshing = true;
  let tokenResult: string | null = null;
  try {
    // ...실제 갱신 로직...
    return tokenResult;
  } finally {
    // isRefreshing을 먼저 false로 되돌린 뒤 구독자들에게 알려야
    // 콜백 실행 중 도착한 새 401이 다시 큐에 쌓이지 않음
    isRefreshing = false;
    onTokenRefreshed(tokenResult);
  }
}

refreshSubscribers에 쌓이는건 요청이 아니라 resolve 함수 그 자체다. 즉, 각 호출자는 자기만의 Promise를 하나씩 만들어서 resolve를 큐에 넘겨두고 멈춰있고, 실제 네트워크 요청(백엔드 refresh)은 딱 한 번만 일어난다.

forEach가 실행되는 시점에 이미 tokenResult가 확정된 상태라, N개의 대기자에게 같은 값을 동시에 나눠주는 것에 가깝다. 동기적으로 한 번에 쭉 돌면서 resolve(token)을 순서대로 호출만 하며, 각 콜백이 뭔가 무거운 작업을 완료할 때까지 기다렸다가 다음으로 넘어가는게 아니다.

엄밀히 말하면 먼저 대기열에 들어온 순서대로 후속 코드가 재개된다는 것은 맞지만, 요청을 순서대로 실행해서 각자 다른 결과를 받는다는 뜻은 전혀 아니다. 전원이 완전히 동일한 토큰을 받는 것이다. 순서는 그냥 '누가 먼저 깨어나는가'의 스케줄링 순서일 뿐, 실질적으로 경쟁이나 대기 시간 차이가 의미를 갖는 지점은 아니다.

비유하자면, 순차 실행 큐라기보다, 하나의 Promise 결과를 여러 구독자에게 멀티캐스트(broadcast)하는 수동 구현에 가깝다.

이걸 면접에서 물어보면 뭐라고 답해야 하나... 고민을 했는데(실제로 질문으로 들어오기도 했음), 다음과 같이 정리할 수 있을 것 같다. "요청을 일렬로 나열해서 순차 실행하는 식인가요?" -> "요청을 순서대로 하나씩 재실행하는 큐는 아니에요. 실제 refresh 요청은 딱 한 번만 나가고, 그 사이 들어온 요청들은 resolve 함수만 배열에 쌓아뒀다가 결과가 나오면 한꺼번에 같은 토큰을 나눠줘요. 그래서 순서는 누가 먼저 깨어나느냐 정도지, 각자 다른 실행을 순차 처리하는건 아니에요" 라고 답할 수 있을 것 같다.

// 서버 사이드에서 사용되는 Mutex
// 서버 사이드 토큰 갱신 동시 요청 방지용 mutex
let serverRefreshPromise: Promise<any> | null = null;

export async function refreshServerAccessToken(token: any) {
  // 이미 갱신 중이면 진행 중인 요청의 결과를 재사용
  if (serverRefreshPromise) {
    const result = await serverRefreshPromise;
    return { ...token, ...result };
  }

  serverRefreshPromise = (async () => {
    try {
      const response = await fetch(`${getBackendApiBaseUrl()}/auth/refresh`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json', Cookie: `refreshToken=${token.refreshToken}` },
      });
      // ...새 토큰 파싱 후 반환...
    } finally {
      serverRefreshPromise = null; // 락 해제
    }
  })();

  return serverRefreshPromise;
}

클라이언트와 서버 사이드를 나눠서 관리하는 이유는 서로가 분리된 실행 컨텍스트/메모리 공간으로 관리되기 때문이다.

isRefreshing 이든 serverRefreshPromise 든 결국 모듈 스코프의 변수 하나로 만드는 락인데, 이건 같은 JS 힙을 공유하는 범위 안에서만 유효하다.

서버 사이드 mutex가 따로 필요한 이유

클라이언트 mutex를 통과해서 실제로 나가는 요청이 getSession() 이고, 이게 호출되면 NextAuth의 jwt 콜백이 Next.js 서버에서 실행되면서 refreshServerAccessToken 이 백엔드 /auth/refresh 를 직접 호출한다.

즉, 실제 네트워크 요청이 나가는 지점은 브라우저가 아니라 서버이다. 그런데 이 서버 쪽 진입점은 클라이언트 mutex를 거치지 않고도 도달할 수 있는 경로가 여러 개 있다.

• 탭이 여러개: 각 탭은 독립된 JS 힙을 가지므로 isRefreshing 상태도 탭마다 따로이다. 두 탭이 거의 동시에 401을 맞으면 둘 다 자기 탭 기준으로는 처음 갱신하는 요청이라 클라이언트 mutex를 통과해버리고, 결국 같은 Next.js 서버 프로세스에 동시에 도달한다.
• 서버 컴포넌트/SSR 경로: 애초에 클라이언트 코드를 거치지 않는다. getAccessToken() 의 서버 분기는 auth() 를 직접 호출해서, 클라이언트 mutex와 무관하게 서버의 jwt 콜백으로 바로 들어간다.

그래서 클라이언트 mutex만 있으면 탭 하나 안에서의 중복은 막아도, 여러 탭 + SSR이 동시에 같은 서버 프로세스를 두드리는 상황은 그대로 뚫리게 된다.

정리하면, 두 mutex는 계층이 다른 문제를 막는 셈이다. 클라이언트에서는 브라우저 탭 하나 안에서 불필요한 getSession() 재호출 방지, 서버는 그 여러 호출 경로가 모두 모이는 실제 백엔드 호출 지점에서의 중복 방지이다.

그리고 이 서버 mutex 조차 여러 서버 인스턴스/기기 단위로는 못 막기 때문에, 그 마지막 구멍을 메우는게 Grace Period인 셈이다.

백엔드측 Grace Period 설정하기

async refreshAccessToken(
  oldToken: string,
): Promise<{ accessToken: string; refreshToken: string | null }> {
  const saved = await this.refreshTokenRepo.findOne({ where: { token: oldToken } });
  if (!saved) {
    throw new AuthUnauthorizedException(AUTH_ERROR_CODES.REFRESH_TOKEN_NOT_FOUND, ...);
  }

  // revoked 체크: 슬라이딩으로 rotation이 발생했을 때 동시 요청 처리용 grace period
  if (saved.revoked) {
    const now = new Date();
    const gracePeriod = 30 * 1000; // 네트워크 지연 고려 (30초)

    const revokedAt = new Date(saved.updatedAt).getTime();
    const diff = now.getTime() - revokedAt;

    if (diff < gracePeriod) {
      // 이미 폐기된 토큰이지만 grace period 안이면,
      // 그 사이 새로 발급된 최신 토큰을 찾아 대신 내려준다
      const latestToken = await this.refreshTokenRepo.findOne({
        where: { userId: saved.userId, revoked: false },
        order: { createdAt: 'DESC' },
      });

      if (latestToken) {
        const accessToken = this.jwtService.sign({ sub: saved.userId }, { expiresIn: '15m' });
        return { accessToken, refreshToken: latestToken.token };
      }
    }
    throw new AuthUnauthorizedException(AUTH_ERROR_CODES.REFRESH_TOKEN_REUSE_DETECTED, ...);
  }
  // ...만료 체크, 슬라이딩 rotation(issueNewTokens)...
}

처음에는 10초로 Grace Period를 설정했다가, 네트워크 지연을 고려해 30초로 늘렸다.

토큰 rotation은 트랜잭션으로 묶어, 구 토큰의 revoked 갱신과 신규 토큰 발급이 원자적으로 일어나도록 했다.

private async issueNewTokens(userId: string, oldTokenId: string) {
  return await this.refreshTokenRepo.manager.transaction(async (em) => {
    // 기존 토큰 폐기 (Grace Period를 위해 updatedAt이 갱신됨)
    await em.update(RefreshToken, { id: oldTokenId }, { revoked: true });

    const { accessToken, refreshToken, expiresAt } = this.generateTokens(userId);
    await em.insert(RefreshToken, { userId, token: refreshToken, expiresAt });

    return { accessToken, refreshToken };
  });
}

핵심 흐름은 다음과 같다.

• A 기기가 먼저 refresh 요청을 보내 토큰을 rotation한 직후, B 기기가 같은 구 토큰으로 거의 동시에 요청하면
• 프론트 mutex는 서로 다른 기기이므로 막지 못하지만, 백엔드가 revoked=true 인 토큰이라도 updateAt 기준 30초 이내면 “재사용 공격”으로 간주하지 않고 그 사이 발급된 최신 토큰을 대신 내려줘 B 기기도 정상적으로 갱신되게 한다.
• 30초가 지나면 진짜 탈취/재사용으로 간주해 REFRESH_TOKEN_REUSE_DETECTED 로 막는다.

마무리

이번 경험을 통해 가장 크게 느낀 점은 동시성 문제는 프론트엔드만 바라봐서는 해결할 수 없다는 것이었다.

Mutex는 분명 효과적인 해결책이지만, 그 범위는 하나의 실행 환경으로 제한된다. 실제 서비스에서는 여러 탭, 여러 브라우저, 여러 기기에서 동시에 요청이 발생할 수 있으며, 이러한 상황까지 고려해야 안정적인 인증 구조를 설계할 수 있다.

처음에는 Mutex를 적용하면 끝! 이라고 생각했지만, 설계를 더 깊게 고민하면서 Mutex의 한계, Refresh Token Rotation, Grace Period가 서로 연결되어 있다는 점을 이해하게 되었고, 클라이언트와 서버가 함께 협력해야 하는 이유를 배울 수 있었다.

참고자료

• better-auth issues
• Lucid refresh token theft detection
• okta developer refresh tokens guides
• auth0 refresh tokens what are to use them

프론트엔드 멀티 탭 동기화는 동일한 웹사이트의 여러 브라우저 탭 간에 상태, 로그인 세션, 장바구니 데이터를 일치시키는 기술이다.

다음과 같은 상황에서 필요하다.

• 여러 탭을 띄워둔 상태에서 한 탭에서 로그아웃하지만 다른 탭에서는 여전히 인증된 콘텐츠를 보고 있는 상황
• 테마를 다크 모드로 변경하지만 나머지 탭은 밝은 모드를 유지하는 상황
• 장바구니에 상품을 추가하고 다른 탭으로 이동하면 장바구니 금액이 0으로 표시되는 상황

브라우저는 기본적으로 탭 간에 react 상태를 공유하지 않는다. 이는 탭별로 js 스크립트가 독립적으로 실행되고 관리되기 때문이다. (컴포넌트 트리, 상태 및 메모리를 가진 자체 JavaScript 컨텐스트를 실행한다.)

하지만 사용자 입장에서 위와 같은 상황은 기대하던 결과는 아니기에 한 탭에서 변경 사항이 발생하면 모든 탭에 즉시 반영되기를 바란다.

이를 위한 멀티 탭 동기화는 주로 BroadcastChannel API나 localStorage 의 storage 이벤트를 활용해 탭 간 통신을 구현한다.

localStorage 및 Storage Event

참고 자료

• MDN-storage event
• React에서 브라우저 storage 이벤트를 이용한 탭 간 상태 동기화

한 탭에서 localStorage 의 값을 변경하면, 동일한 브라우저의 다른 탭에서 window 객체의 storage 이벤트를 감지하여 동기화한다.

구현이 매우 간단하고 직관적이며, 상태의 영속성도 함께 보장된다.

// 변경 감지
window.addEventListener('storage', (event) => {
  if (event.key === 'user-token') {
    const newToken = event.newValue;
    // 새 토큰으로 상태 업데이트
  }
});

// 값 변경 (다른 탭에서 감지됨)
localStorage.setItem('user-token', 'new_token_value');

// Tab A writes
localStorage.setItem("theme", "dark");

// Tab B listens
window.addEventListener("storage", (event) => {
  if (event.key === "theme") {
    console.log("Theme changed to:", event.newValue); // "dark"
  }
});

이 이벤트는 변경을 수행한 창에서는 발생하지 않는다.

• 같은 origin의 모든 브라우저 컨텍스트에서 이벤트가 발생한다.
• 탭 간 반응성을 무료로 얻을 수 있지만, 문자열 직렬화 가능한 데이터에만 해당한다.

이를 직접 구현하기 위해서는 다음과 같은 작업이 필요하다.

1. localStorage 에서 초기값을 읽어온다.
2. 내용 전체가 localStorage 문자열이므로 파싱한다.
3. 다른 탭의 변경 사항을 감지하도록 storage 이벤트 리스너를 설정한다.
4. 로컬 탭의 값이 변경될 때 직렬화하여 다시 저장한다.
5. 마운트 해제시 리스너를 정리한다.

import { useState, useEffect, useCallback } from "react";

function useCrossTabTheme() {
  const [theme, setThemeState] = useState<"light" | "dark">(() => {
    try {
      const stored = localStorage.getItem("app-theme");
      return stored === "dark" ? "dark" : "light";
    } catch {
      return "light";
    }
  });

  // Listen for changes from other tabs
  useEffect(() => {
    const handler = (event: StorageEvent) => {
      if (event.key === "app-theme" && event.newValue) {
        setThemeState(event.newValue as "light" | "dark");
      }
    };
    window.addEventListener("storage", handler);
    return () => window.removeEventListener("storage", handler);
  }, []);

  // Write to localStorage when local state changes
  const setTheme = useCallback((value: "light" | "dark") => {
    setThemeState(value);
    try {
      localStorage.setItem("app-theme", value);
    } catch {
      // storage full or unavailable
    }
  }, []);

  return [theme, setTheme] as const;
}

이렇게 많은 코드가 필요한데, 인증 토큰, 사용지 기본 설정, 장바구니 상태, 알림 횟수 등에 대해 이와 같은 작업을 수행한다고 하면, 더 많은 코드가 필요하게 된다.

BroadcastChannel API

동일한 오리진(origin)을 공유하는 브라우저 탭 간에 이름이 지정된 채널을 통해 직접 메시지를 송수신한다.

실시간 양방향 통신에 매우 적합하며, 문자열뿐만 아니라 객체 데이터도 쉽게 주고받을 수 있다.

// 채널 생성
const channel = new BroadcastChannel('app_sync_channel');

// 메시지 보내기
channel.postMessage({ type: 'LOGOUT', timestamp: Date.now() });

// 메시지 받기
channel.onmessage = (event) => {
  if (event.data.type === 'LOGOUT') {
    // 로그아웃 처리 수행
  }
};

// 채널 연결 해제하기 -> 가비지 컬렉션이 활성화된다.
channel.close();

MDN-Broadcast Channel API

Broadcast Channel API는 브라우저 맥락들(예: 창, 탭, 프레임, iframe)과 동일한 origin에 있는 워커들 간의 기본적인 통신을 허용한다.

broadcastChannel API는 Web Worker에서 사용할 수 있다.

통신하려는 프레임이나 워커에 대한 참조를 유지할 필요가 없다. 동일한 이름의 BroadcastChannel을 만들어, 특정 채널을 구독하고 모든 채널 간에 양방향 통신을 할 수 있다.

채널로 전송되는 데이터는 structured clone 알고리즘을 통해 직렬화된다. 즉, 다양한 데이터 객체를 직접 직렬화하지 않고도 안전하게 전송할 수 있다.

단점은 메시지를 전송한 후에는 수신 여부를 알 수 없다는 것이다. 즉, 메시지가 전송될 때 탭이 열려 있지 않으면 메시지를 수신하지 못한다.

Broadcast Channel API의 독립적인 인터페이스를 통해 다중 맥락 간 통신이 가능하다. 이는 사용자가 로그인하거나, 로그아웃하는 등의 동일한 origin 내의 다른 탭에서 사용자의 행동을 감지하는 데 사용할 수 있다.

NextAuth에서 볼 수 있는 SessionProvider 탭 동기화

<SessionProvider> 를 설정할 때 다음과 같은 옵션들을 부여할 수 있다.

• refetchOnWindowFocus

  • 사용자가 다른 탭을 보다가 다시 이 앱이 켜진 탭으로 돌아왔을 때(포커스 되었을 때) 최신 세션 정보를 서버에서 다시 가져와 동기화한다.

  • 기본적으로 켜져 있으므로, 탭 전환시 자동 동기화를 끄고 싶을 때만 false 로 설정한다.

  • 이는 visibilitychange 포커스 이벤트를 사용해 세션을 새로고침한다.

      <SessionProvider refetchOnWindowFocus={false}>
        {children}
      </SessionProvider>

        React.useEffect(() => {
          const { refetchOnWindowFocus = true } = props
          // Listen for when the page is visible, if the user switches tabs
          // and makes our tab visible again, re-fetch the session, but only if
          // this feature is not disabled.
          const visibilityHandler = () => {
            if (refetchOnWindowFocus && document.visibilityState === "visible")
              __NEXTAUTH._getSession({ event: "visibilitychange" })
          }
          document.addEventListener("visibilitychange", visibilityHandler, false)
          return () =>
            document.removeEventListener("visibilitychange", visibilityHandler, false)
        }, [props.refetchOnWindowFocus])

• refetchInterval

  • 일정 시간(초 단위)마다 주기적으로 세션을 백그라운드에서 계속 불러와 갱신한다.
  • 여러 탭이 열려 있을 때 이 값이 설정되어 있으면 각 탭이 백그라운드에서 세션을 동기화하는 데 도움을 준다.

nextauth 내부 코드

NextAuth의 내부 구현 코드를 보면, Broadcast Channel로 세션 동기화를 구현한걸 알 수 있다.

// 브로드캐스트 채널을 싱글톤 형태로 관리하기 위한 변수
let broadcastChannel: BroadcastChannel | null = null

// 브라우저 환경에서 'next-auth' 채널 이름으로 BroadcastChannel 생성
function getNewBroadcastChannel() {
  if (typeof BroadcastChannel === "undefined") {
    // SSR 환경(서버 사이드)이나 지원하지 않는 브라우저를 위한 폴백(Fallback) 객체
    return {
      postMessage: () => {},
      addEventListener: () => {},
      removeEventListener: () => {},
      name: "next-auth",
      onmessage: null,
      onmessageerror: null,
      close: () => {},
      dispatchEvent: () => false,
    } satisfies BroadcastChannel
  }
  return new BroadcastChannel("next-auth")
}

// 채널 인스턴스를 가져오는 래퍼 함수
function broadcast() {
  if (broadcastChannel === null) {
    broadcastChannel = getNewBroadcastChannel()
  }
  return broadcastChannel
}

이 로직은 사용자가 하나의 탭에서 signIn 또는 signOut 을 하거나 세션이 갱신되는 getSession 등이 실행될 때, 내부적으로 이 broadcast() 채널을 통해 다른 탭에 메시지를 보낸다.

// 예시: 세션이 새로 고쳐졌을 때 다른 탭에 알림 전송
if (newSession) {
  setSession(newSession)
  broadcast().postMessage({
    event: "session",
    data: { trigger: "getSession" },
  })
}

// signOut 호출시 다른 탭에 알림 전송
broadcast().postMessage({ event: "session", data: { trigger: "signout" } })

그리고 리액트 컨텍스트인 <SessionProvider> 내부에서는 이 채널의 message 이벤트를 듣고 있다가, 이벤트가 수신되면 자식 컴포넌트들의 세션 상태를 강제로 동기화하도록 설계되어 있다.

구버전의 초기 코드는 브라우저 호환성을 위해 BroadcastChannel 대신 window.addEventListener('storage') 이벤트를 사용하여 LocalStorage 변경을 감지하는 방식으로 구현하기도 했다. 최신 코드에는 브라우저 표준인 BroadcastChannel 위주로 안전하게 처리한다.

ReactUse의 탭 간 안전한 메시지 전송

reactuse는 Meta 공식 라이브러리는 아니고, 써드파티 오픈소스 라이브러리이다. 커스텀 훅 모음집이라 생각하면 된다.

참고자료

• 실시간 React: 브라우저 탭 간 상태 동기화

useBroadcastChannel: 탭 간 안전한 메시지 전송

ReactUse의 훅 useBroadcastChannel 은 BroadcastChannel API를 깔끔하고 선언적인 인터페이스로 감싸준다.

채널 생성, 메시지 수신, 마운트 해제 시 정리, SSR 안정성까지 모두 단일 호출로 처리한다.

import { useBroadcastChannel } from "@reactuses/core";

function NotificationSync() {
  const { data, post, error } = useBroadcastChannel<{
    type: string;
    payload?: unknown;
  }>("my-app-notifications");

  // Send a message to all other tabs
  const broadcastLogout = () => {
    post({ type: "LOGOUT" });
  };

  // React to messages from other tabs
  useEffect(() => {
    if (data?.type === "LOGOUT") {
      // Clear local auth state and redirect
      authStore.clear();
      window.location.href = "/login";
    }
  }, [data]);

  return <button onClick={broadcastLogout}>Log out everywhere</button>;
}

수동 직렬화가 필요 없으며, 정리 코드도 필요 없다. 훅은 컴포넌트가 마운트 해제될 때 채널을 자동으로 닫는다. 또한 error 값을 사용하면 BroadcastChannel이 지원되지 않는 드문 경우를 처리할 수 있다.

useLocalStorage: 자동 탭 간 동기화

탭 간에 상태를 유지하고 동기화해야 하는 경우, useLocalStorage 도구가 적합하다. localStorage 이벤트에 의해 보호되며, 모든 탭에서 자동으로 동기화된다.

import { useLocalStorage } from "@reactuses/core";

function ThemeToggle() {
  const [theme, setTheme] = useLocalStorage<"light" | "dark">(
    "app-theme",
    "light"
  );

  return (
    <button onClick={() => setTheme(theme === "light" ? "dark" : "light")}>
      Current: {theme}
    </button>
  );
}

한 탭에서 이 훅이 호출되면 동일한 키로 이 훅을 실행하는 다른 모든 탭이 자동으로 업데이트된다.

JSON 직렬화, 초기값 대체, SSR 보호 및 스토리지 이벤트 구독을 내부적으로 처리한다.

두 훅을 사용해 인증 상태 동기화를 구현한 패턴의 예시는 다음과 같다.

import { useBroadcastChannel, useLocalStorage } from "@reactuses/core";

function useAuth() {
  const [token, setToken] = useLocalStorage<string | null>("auth-token", null);
  const { data, post } = useBroadcastChannel<{ type: "LOGOUT" | "LOGIN" }>(
    "auth-channel"
  );

  // Handle messages from other tabs
  useEffect(() => {
    if (data?.type === "LOGOUT") {
      setToken(null);
      window.location.href = "/login";
    }
  }, [data, setToken]);

  const login = (newToken: string) => {
    setToken(newToken);
    post({ type: "LOGIN" });
  };

  const logout = () => {
    setToken(null);
    post({ type: "LOGOUT" });
    window.location.href = "/login";
  };

  return { token, login, logout, isAuthenticated: token !== null };
}

그 외 탭 간 테마 동기화, 전자상거래에서의 장바구니 상태 등의 패턴은 위에 올린 참고자료를 확인하면 된다.

SharedWorker와 BroadcastChannel의 결합

여러 탭에서 공유하는 백그라운드 스레드인 SharedWorker 를 두고, 각 탭이 BroadcastChannel 을 통해 SharedWorker 와 통신하여 중앙 상태를 유지한다.

복잡한 상태 관리나 웹소켓 연결을 탭마다 맺을 필요 없이 하나로 통합할 수 있어서 서버 및 네트워크 비용을 최적화할 수 있다.

raddit 코멘트 ”SharedWorker와 broadcastchannel을 사용하면 됩니다. 즉, 각 탭은 데이터/네트워크 요청을 위해 워커를 구독하고 수신된 메시지를 기반으로 상태를 업데이트합니다. 따라서 각 앱은 워커로부터 메시지를 처리하는 메시지 수신기가 필요하며, 워커는 메시지를 보내는 메서드를 제공해야 합니다.

웹소켓이나 사용하는 연결 프로토콜을 워커에서 실행하세요. 이렇게 하면 앱에서 연결 세부 사항을 추상화할 수 있습니다.”

”저는 프로덕션 앱에서 비슷한 요구 사항을 가지고 있는데, 원격 서버를 사용하고 여러 탭을 사용하는 수많은 사용자가 모두 동기화된 상태를 유지해야 합니다. 저희는 React Query를 사용하여 공유 워커에 모든 데이터를 캐싱하는 방식을 채택했습니다. 이렇게 하면 탭마다 별도의 캐시 인스턴스를 생성하지 않고, 캐시 무효화 발생 시 사용자별로 한 번의 API 호출만으로 데이터를 다시 가져올 수 있습니다. 각 사용자는 웹소켓 연결을 통해 변경 사항이 발생할 때마다 캐시 무효화 메시지를 주고받으며, 모든 데이터가 항상 동기화된 상태를 유지합니다.”

참고자료

• MDN-SharedWorker

이는 여러 브라우저 탭간에 중복 네트워크 요청을 방지하고 상태를 동기화하기 위한 아키텍처이다.

핵심은 무거운 작업(웹소켓 연결, 데이터 캐싱, API 요청)은 백그라운드의 SharedWorker가 한 번만 수행하고, 각 탭은 Worker가 주는 데이터만 받는다는 점이다.

• SharedWorker: 일반 Web Worker는 탭 하나에 종속되지만, SharedWorker는 동일한 도메인(origin)을 공유하는 모든 탭이 하나의 스레드를 공유할 수 있게 해준다. 기존의 다른 종류의 워커들과 다른 전역 스코프를 갖는 인터페이스를 구현한다.
• BroadcastChannel 또는 Port 통신: SharedWorker와 각 탭이 서로 대화하기 위한 통신 채널로 쓰인다.

중앙 집중식 데이터 캐싱: 탭마다 데이터 요청(react query)를 보내는게 아니라, SharedWorker 내부에서 캐시를 두거나(or 워커가 네트워크 요청을 통제하여) 탭들이 동일한 데이터를 공유하게 만든다.

전체적인 데이터 흐름은 다음과 같다.

[ 브라우저 탭 1 ] <───(Message)───> [ SharedWorker ] <───(WebSocket)───> [ 원격 서버 ]
[ 브라우저 탭 2 ] <───(Message)───>       │ (중앙 캐시 / 상태 관리)
[ 브라우저 탭 3 ] <───(Message)───>       ┘

1단계: SharedWorker 내부에서 웹소켓 연결 관리

먼저, SharedWorekr 스크립트(worker.js)내부에서 웹소켓 연결 코드를 작성한다. 이렇게 하면 탭이 아무리 많아도 서버와 연결된 웹소켓은 딱 1개만 유지되므로 서버 비용이 절감된다.

2단계: 탭들과 연결 끊김 관리(Port 구독)

SharedWorker는 새로운 탭이 열릴 때마다 onconnect 이벤트를 발생시킨다. 연결된 탭들의 포트를 배열 등으로 관리하여 메시지를 주고받을 준비를 한다.

3단계: React Query와의 결합(캐시 공유 및 무효화)

이는 두 가지 형태로 구현할 수 있다.

1. Worker 내부에서 데이터를 들고 있는 방식:
   • 서버에서 웹소켓으로 데이터가 변경되었다는 알림을 보낸다.
   • SharedWorker가 이 메시지를 받고, 자신이 직접 서버에 API 요청을 날려 최신 데이터를 가져온다.
   • 가져온 최신 데이터를 모든 탭에 postMessage 한다.
2. Worker는 신호만 주고, React Query의 QueryClient를 동기화하는 방식:
   • 서버가 웹소켓으로 무효화 신호를 주면 SharedWorker가 모든 탭에 "REFETCH_QUERY" 라는 메시지를 뿌린다.(postMessage)
   • 메시지를 받은 모든 탭의 React Query가 동시에 무효화된다. (queryClient.invalidateQueries())가 되면서 데이터를 다시 가져온다. 단, 이때도 중복 요청을 막기 위해 첫 번째 탭의 요청 결과를 공유하게끔 처리가 필요하다.

간단한 예시는 다음과 같다.

// SharedWorker 코드: worker.js
// 연결된 모든 탭의 포트를 저장
const ports = [];

// 1. 웹소켓 연결 (SharedWorker 내부에서 단 한 번만 실행)
const ws = new WebSocket("wss://your-server.com/sync");

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);

  // 서버에서 데이터 변경(무효화) 알림이 오면 모든 탭에 브로드캐스트
  if (message.type === "INVALIDATE_CACHE") {
    ports.forEach(port => {
      port.postMessage({ type: "SYNC_DATA", payload: message.data });
    });
  }
};

// 2. 새로운 탭이 열려 연결되었을 때
self.onconnect = (e) => {
  const port = e.ports[0];
  ports.push(port);

  // 탭으로부터 메시지를 받았을 때 처리 (예: 데이터 요청 등)
  port.onmessage = (event) => {
    if (event.data.type === "REQUEST_FETCH") {
      // 필요 시 워커가 대신 API를 호출하거나 웹소켓으로 전송
    }
  };

  port.start();
};

// React
import { useEffect } from 'react';
import { useQueryClient } from '@tanstack/react-query';

function useTabSynchronization() {
  const queryClient = useQueryClient();

  useEffect(() => {
    // 1. SharedWorker 초기화
    const worker = new SharedWorker(new URL('./worker.js', import.meta.url));

    // 2. 워커로부터 메시지 수신 (메시지 수신기)
    worker.port.onmessage = (event) => {
      const { type, payload } = event.data;

      if (type === "SYNC_DATA") {
        // React Query 캐시를 최신 데이터로 강제 업데이트 하거나 무효화
        queryClient.setQueryData(['myCachedData'], payload);
        // 또는 queryClient.invalidateQueries({ queryKey: ['myCachedData'] });
      }
    };

    worker.port.start();

    return () => {
      // 탭이 닫힐 때 포트 닫기 처리 등 필요
    };
  }, [queryClient]);
}

장점이 많지만, 2026.07 기준 지원하지 않는 환경이 있기에 불안정하거나 제한적일 수 있다.

또한 새로고침/빌드 시 번들링하는 작업이 필요하다. Next.js나 Vite 환경에서 Web Worker 파일을 올바르게 번들링하고 경로를 맞춰주는 설정이 필요하다.

추가적으로, useSyncExternalStore 와 함께 사용하여 외부 상태를 React의 렌더링 시스템과 완벽하게 유기적으로 연결할 수 있다.

SharedWorker는 브라우저 백그라운드 스레드에서 돌아가는 React 외부 데이터 소스이다. 해당 훅을 사용하면 다음과 같은 장점이 있다.

• 동기화 보장: 워커로부터 데이터가 오는 시점과 React의 렌더링 타이밍이 어긋나면서 화면이 찢어지거나 이전 데이터가 보이는 현상을 구조적으로 방지한다.
• 클린업 자동화: 탭이 닫히거나 컴포넌트가 언마운트될 때, 워커 리스너를 해제하는 이벤트를 관리해준다.
• 선언적인 코드: 외부 상태를 마치 useState 처럼 자연스럽게 다룰 수 있게 해준다.

React Query와 함께 쓰든, 아니면 독자적인 전역 상태로 쓰든 구조는 비슷하다.

1. 외부 스토어 매니저 생성 먼저 SharedWorker의 이벤트를 구독하고 현재 값을 반환하는 작은 Store 객체를 만든다.

// sharedWorkerStore.js
const worker = new SharedWorker(new URL('./worker.js', import.meta.url));
worker.port.start();

let snapshot = null; // 워커로부터 받은 최신 데이터를 담을 변수
const listeners = new Set(); // 구독 중인 컴포넌트들의 리스너 콜백 모음

// 워커로부터 메시지가 오면 스냅샷을 업데이트하고, 모든 리스너를 실행시킵니다.
worker.port.onmessage = (event) => {
  if (event.data.type === "SYNC_DATA") {
    snapshot = event.data.payload;
    listeners.forEach((listener) => listener());
  }
};

export const workerStore = {
  // 1. 구독 등록 함수 (useSyncExternalStore가 내부적으로 호출함)
  subscribe(callback) {
    listeners.add(callback);
    // 구독 취소(클린업) 함수 반환
    return () => listeners.delete(callback);
  },

  // 2. 현재 최신 값을 가져오는 함수
  getSnapshot() {
    return snapshot;
  },

  // (선택) 워커에 메시지를 보내는 메서드
  emit(message) {
    worker.port.postMessage(message);
  }
};

1. React 컴포넌트에서 사용하기 컴포넌트나 커스텀 훅에서 useSyncExternalStore 를 사용해 이 스토어를 붙여준다.

import { useSyncExternalStore, useEffect } from 'react';
import { useQueryClient } from '@tanstack/react-query';
import { workerStore } from './sharedWorkerStore';

function useSharedWorkerData() {
  const queryClient = useQueryClient();

  // useSyncExternalStore(구독함수, 스냅샷함수)
  // 워커에서 새로운 메시지가 올 때마다 이 훅이 알아서 트리거되어 최신 data를 반환합니다.
  const data = useSyncExternalStore(
    workerStore.subscribe, 
    workerStore.getSnapshot
  );

  // 만약 React Query 캐시와도 연동하고 싶다면?
  useEffect(() => {
    if (data) {
      // 워커가 준 따끈따끈한 최신 데이터로 React Query 캐시 동기화
      queryClient.setQueryData(['myCachedData'], data);
    }
  }, [data, queryClient]);

  return data;
}

// 실제 컴포넌트에서의 사용
export function MyComponent() {
  const sharedData = useSharedWorkerData();

  if (!sharedData) return <div>연결 중...</div>;

  return <div>모든 탭이 동기화된 데이터: {sharedData.message}</div>;
}

정리하면,

• SharedWorekr: 여러 탭 간의 징검다리 및 하나의 웹소켓 통신 담당
• useSyncExternalStore: 백그라운드에서 일어난 데이터 변화를 메인 스레드(React 컴포넌트)에 안전하게 렌더링 신호로 토스해주는 역할
• React Query: 토스받은 데이터를 메모리에 캐싱하고, 화면 이곳저곳에서 useQuery 로 편하게 쓸 수 있도록 관리하는 역할

참고 자료

• MDN-storage event
• React에서 브라우저 storage 이벤트를 이용한 탭 간 상태 동기화
• MDN-Broadcast Channel API
• nextauth 내부 코드
• 실시간 React: 브라우저 탭 간 상태 동기화
• raddit 코멘트
• MDN-SharedWorker

사용자에게 새로운 활동을 알려주는 푸시 알림 기능을 추가하자는 피드백이 들어왔다.

기록 서비스, 특히 공동 기록 서비스 특성상 다른 사용자가 기록을 수정하거나 추가하는 등의 활동에 대해서는 알림으로 알리는게 필요하다고 생각했다.

이번 글은 Next.js app router 기반 PWA와 Capacitor로 패키징한 Android 앱에 Firebase FCM을 활용해 푸시 알림을 구현한 과정에 대해 정리하고자 한다.

구현 목표는 다음과 같았다.

• 그룹 활동(멤버 합류, 기록 작성 등)발생 시 관련 사용자에게 알림 발송
• 알림 클릭 시 해당 기록 또는 그룹 페이지로 딥링크
• 백그라운드/포그라운드 모두에서 알림 수신

푸시 알림 지원 환경과 이유

지원 플랫폼

간단하게, 최종적으로 어떤 플랫폼에 대해 알림 기능을 지원하도록 했는지 표로 정리해봤다.

플랫폼별 지원 여부 상세

Android: 브라우저, 네이티브 앱

MDN 호환성 표를 보면 WebView Android는 Push API를 지원하지 않는다. Capacitor Android 앱은 내부적으로 WebView를 사용하므로 Web Push API로는 푸시를 받을 수 없다.

하지만 Capacitor는 @capacitor/push-notifications 플러그인을 통해 네이티브 레이어에서 직접 FCM을 처리하므로 WebView의 제약을 우회할 수 있다. Chrome Android는 Web Push API를 정상 지원한다.

iOS를 지원하지 않는 이유

iOS 16.4부터 Safari 브라우저와 홈 화면에 설치된 PWA에서 Web Push를 지원한다. 하지만 iOS에서 푸시 알림을 보내려면 Apple의 APNs(Apple Push Notification service)를 거쳐야 한다. APNs 인증 키 발급을 위해서는 연 $99의 Apple Developer Program 가입이 필요하다.

우리 팀은 아직 서비스가 완전하게 출시되지 않았기도 하고, 비용 부담의 이유로 apple은 지원하지 않는 것으로 됐다.

반면 macOS에서는 Web Push API를 통해 Apple ID만으로도 웹 푸시가 가능하다. Apple이 macOS용 웹 푸시를 W3C 표준으로 개발했기 때문이다.

참고

• Apple — Sending web push notifications in web apps and browsers
• Apple — APNs Overview
• Apple Developer Program
• MDN — Push API: Browser compatibility
• MDN — PushEvent: Browser compatibility

Firebase FCM 선택 이유

웹과 Android 모두를 단일 서버에서 처리하기 위해 FCM을 선택했다. 직접 Web Push(VAPID)를 구현하는 방법도 있겠지만, 이를 직접 검증해야 하며 개인이 검증하는 것이기에 안전하지 않다고 판단했다.

FCM을 사용하면

• 웹(VAPID)와 Android(FCM) 토큰을 단일 Admin SDK API로 발급 가능
• 만료 토큰 감지, 재시도 등 안정적인 전송 인프라 제공
• Firebase Console에서 발송 로그 모니터링 가능

위처럼 개인이 직접 구현하는 것보다는 이미 잘 만들어져 관리되고 있는 서비스를 사용하는게 더 낫다고 생각했다.

중개 서버를 거치지 않고 자체적으로 구현한다면?

FCM이나 APNs 같은 중개 서버를 거치지 않고 100% 자체 인프라로 실시간 알림을 직접 구현하려면, 클라이언트와 자체 서버 간에 지속적인 연결을 유지하는 기술을 사용해야 한다.

대표적으로는 3가지 정도가 있다.

1. WebSocket

가장 보편적인 양방향 실시간 통신 방식이다.

• 클라이언트와 서버가 한 번 연결되면, 계속 연결을 유지하며 데이터를 주고받는다.
• 실시간성이 매우 뛰어나고 데이터 전송 오버헤드가 적다.

2. SSE (Server-Sent Event)

서버가 클라이언트에게 단방향으로 데이터를 밀어주는 방식이다.

• HTTP 프로토콜을 그대로 사용하며, 연결을 끊지 않고 서버가 이벤트를 스트리밍한다.
• 웹소켓보다 구현이 간단하고, 연결이 끊겼을 때 자동 재연결 기능이 내장되어 있다.
• 보통 뉴스 피드 업데이트, 알림 피드, 실시간 점수 판 등에 활용된다.

3. MQTT

모바일 및 사물인터넷 환경에 최적화된 가벼운 메시징 프로토콜이다.

• 발행과 구독 패턴으로 동작하며, 가벼운 브로커를 두고 통신한다.
• 네트워크 전력 소비가 매우 적어서 모바일 배터리 절약에 유리하다.
• IoT 기기 제어, 모바일 메신저 백그라운드 통신 등에 활용된다.

포그라운드 상태에서는 위 방식으로 완벽하게 작동한다. 하지만 모바일 앱이 꺼져 있거나 백그라운드 상태에서는 OS 제약이 발생하게 된다.

• iOS(Apple) 제한: iOS는 앱이 백그라운드로 가면 전력 절약을 위해 네트워크 연결을 강제로 귾어버린다. 따라서 FCM을 쓰지 않더라도, 결국 Apple이 공식 제공하는 APNs 서버로는 무조건 메시지를 보내야만 아이폰 화면에 push 알림을 띄울 수 있다.
• Android 제한: 안드로이드 역시 백그라운드 배터리 최적화로 인해 백그라운드 소켓 연결을 유지하기 어렵다. 백그라운드에서 상시 연결을 유지하려면 '포그라운드 서비스'를 띄워 상단 바에 고정 알림을 상시 노출해야 하므로 사용자 경험에 좋지 않다.

그렇기에 앱이 켜져 있을 때는 WebSockets/SSE로 직접 빠르게 알림을 처리하고, 앱이 꺼져 있을 때는 FCM/APNs를 백업으로 호출하는 하이브리드 방식을 채택하기도 한다.

하지만 두 방식을 모두 지원하기엔 소규모 팀에선 리소스 소모가 크다고 생각했다. 그래서 FCM만을 사용해 push 알림을 구현하고자 했다.

참고

• Firebase Cloud Messaging 공식 문서

전체 아키텍처

푸시 알람의 흐름은 다음과 같다.

앱 실행 -> 알림 권한 요청 -> FCM 토큰 발급 -> 백엔드에 식별자 저장

그룹 활동 발생(POST_CREATE, MEMBER_JOIN 등) -> 그룹 활동에 대한 service 메소드 호출 (GroupActivityService.recordActivity()) -> 신규: 그룹 멤버들의 FCM 식별자 조회 -> Firebase Admin SDK로 푸시 발송 -> 기기에 알림 표시

웹과 안드로이드의 식별자가 다른 이유 Firebase Android SDK에서 getToken(), deleteToken(), onNewToken()이 deprecated되고 웹과 동일하게 onRegistered() 기반 FID 방식으로 전환됐다. 단 AndroidManifest.xml에 opt-in 플래그를 추가해야 활성화된다. 하지만 Capacitor 공식 문서는 현재도 registration 이벤트가 Android에서 FCM Token을 반환한다고 명시한다. Capacitor 플러그인이 내부적으로 구 API를 래핑하고 있고, 위 opt-in 플래그도 설정하지 않기 때문에 아직 FID가 아닌 토큰을 돌려준다. Capacitor 공식문서

Firebase Admin SDK?

서버 사이드 전용 SDK이다. 클라이언트가 아닌 신뢰할 수 있는 서버 환경에서 Firebase 서비스를 제어할 목적으로 사용한다. 우리 팀은 NestJS 백엔드에서 FCM 메시지를 발송하는 데 사용하고 있다.

// notification.service.ts
import { getMessaging } from 'firebase-admin/messaging';

await getMessaging(this.app).sendEach(messages); // ← 여기

클라이언트 SDK vs Admin SDK 차이

Admin SDK가 주로 쓰이는 곳은 다음과 같다.

• FCM 발송: 특정 사용자에게 푸시 알림 보내기
• Firestore/Realtime DB 관리: 보안 규칙을 우회해서 서버에서 직접 데이터 읽기/쓰기
• Auth 관리: 사용자 계성 생성/삭제, 커스텀 토큰 발급
• Storage 관리: 파일 업로드/삭제

사용자 대신 서버가 Firebase를 직접 제어해야 할 때 쓰며, 클라이언트에서 Admin SDK를 쓰면 서비스 계정 키가 노출되기 때문에 절대 사용하면 안된다.

Firebase는 Topic 구독으로 Topic별로 알림을 수신할 수 있도록 하는 기능도 제공한다. 검색하면 나오는 관련 글을 참고하면 좋을 것 같다.

우리 팀도 처음에는 Topic 구독으로 단위를 나눠 알림을 제공할 수 있었지만, 그룹 별로 알림 수신 여부를 다르게 설정할 수 있는 기능을 추가해서 Topic 단위로는 부족했다. 그래서 그룹 내에서도 '특정 멤버'에게만 보내기 편한 FID 직접 관리 방식으로 구현했다.

환경변수 발급받기

필요한 환경변수는 다음과 같다.

위와 값은 모두 Firebase 콘솔에서 발급할 수 있다. 혹시나 나 같이 이런 타 서비스 사용에 있어서 어려움을 겪는 사람을 위해 발급 과정을 하나하나 정리해봤다.

먼저, 설정의 일반 페이지로 넘어간다. 내리면 '내 앱' 세션에서 앱을 등록해주는데, 나는 </> 표시의 웹으로 등록을 먼저 해주었다. (웹으로 동작하기 때문에)

sdk 설정은 npm으로 해주었다. <script> 태그 방식은 CDN에서 직접 로드하는 방식인데, Next.js + pnpm 프로젝트에서는 번들러가 tree-shaking으로 사용하는 기능만 포함시켜 주니 npm으로 충분하다.

그리고 config 코드를 복사해서 코드에 붙여넣어준다.

// Import the functions you need from the SDKs you need
import { initializeApp } from "firebase/app";
// TODO: Add SDKs for Firebase products that you want to use
// https://firebase.google.com/docs/web/setup#available-libraries

// Your web app's Firebase configuration
const firebaseConfig = {
  apiKey: "AI...",
  authDomain: "fr...",
  projectId: "fr...",
  storageBucket: "fr...",
  messagingSenderId: "51...",
  appId: "1:51..."
};

// Initialize Firebase
const app = initializeApp(firebaseConfig);

이제 VAPID를 발급하자

알림 페이지로 접근하면 아래 사진처럼 클라우드 메시징 탭이 있다.

여기서 아래로 스크롤하면 '웹 구성' 섹션이 보인다.

여기서 Generate key pair 버튼을 클릭해 VAPID(공개 키)를 발급받는다.

BHc7cP...

이제 마지막으로 백엔드 설정을 위한 Firebase Admin SDK 서비스 계정 JSON을 발급받아야 한다.

같은 페이지에서 '서비스 계정' 탭으로 이동한다. 여기서 백엔드 환경에 맞는 탭이 선택되어 있는지 확인한다.

우리 팀은 node를 사용하고 있어서, Node.js를 선택해줬다.

선택한 뒤, '새 비공개 키 생성' 버튼을 클릭한다. 팝업창이 뜨면 '키 생성'을 누른다.

'키 생성' 버튼을 클릭하면 자동으로 브라우저를 통해 .json 파일이 다운로드된다. 이 파일은 git 등의 공유 저장소에 업로드되지 않도록 안전하게 보관해야 하는 서비스 계정 키 파일이다.

서비스 계정 JSON 파일은 프로젝트의 모든 권한을 가진 마스터 키와 같기 때문에, 절대 GitHub 같은 공용 저장소에 업로드되지 않도록 gitignore 처리를 해줘야 한다.

gitignore에 json 파일을 추가해주고,

rontend/.env 에 NEXT_PUBLIC_FIREBASE_* 7개의 값을 추가해줬다. backend/.env 에 FIREBASE_SERVICE_ACCOUNT_PATH 를 추가해줬다.

이제 capacitor android를 위한 앱을 추가한다. 기존의 웹 앱을 추가한 것처럼 진행하면 된다. 이번에는 android 아이콘을 선택하면 된다.

Firebase 콘솔 -> 프로젝트 설정 -> 앱 추가 -> Android

작업 단계

처리해야 하는 작업들은 단계별로 정리했을 때 다음과 같다.

1. 백엔드: FCM 식별자 저장 테이블 및 API 추가

fcm_token 엔티티를 생성한다. (userId, token, platform: 'web'|'android' )

POST /api/fcm-tokens 엔드포인트로 토큰을 등록하고 갱신시킨다.

2. 백엔드: 푸시 발송 서비스 생성

firebase-admin 설치 후 PushNitficationService 를 생성한다.

pnpm --filter backend add firebase-admin

recordActivity() 끝에서 엑터를 제외한 그룹 멤버들에게 알림을 발송한다.

3. 프론트: PWA/Web

firebase 패키지를 설치한다.

pnpm --filter frontend add firebase

firebase-message-sw.js 서비스 워커를 추가한다. 이 서비스 워커는 백그라운드의 알림 수신용이다.

권한 요청 + FCM 토큰 발급 + 백엔드에 등록하는 훅을 작성해 관리하기 편하게 한다.

4. 프론트: Android/Capacitor

capacitor 환경은 지원하는 플러그인을 사용하는게 좋다.

@capacitor-firebase/messaging 플러그인을 설치하고, 같은 훅 안에서 플랫폼별로 분기 처리를 한다.

백엔드 구현

1. FCM 식별자 엔티티

플랫폼별로 다른 전송 방식이 필요하므로 platform 컬럼을 함께 저장한다. 사용자당 플랫폼별 하나의 식별자만 유지한다.

@Entity('fcm_tokens')
@Unique(['userId', 'platform'])
export class FcmToken {
  @PrimaryGeneratedColumn('uuid')
  id: string;

  @Column()
  userId: string;

  @Column()
  token: string; // 웹: FID(Firebase Installation ID), Android: FCM 등록 토큰

  @Column()
  platform: 'web' | 'android';
}

2. FCM 발송 서비스

플랫폼별로 메시지 형식이 달라야 한다.

• 웹: FidMessage - fid 필드에 FID(Firebase Installation ID)를 사용, data-only 메시지
• Android: TokenMessage - token 필드에 FCM 등록 토큰을 사용, notification 필드 포함

async sendToUsers(
  userIds: string[],
  title: string,
  body: string,
  data?: Record<string, string>,
): Promise<void> {
  const tokens = await this.fcmTokenRepo.find({
    where: userIds.map((userId) => ({ userId })),
    select: ['token', 'platform'],
  });

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

  // 만료 식별자 추적을 위해 순서 보존
  const identifiers = tokens.map(({ token }) => token);

  const messages = tokens.map(({ token, platform }) =>
    platform === 'web'
      ? {
          fid: token, // FidMessage — Admin SDK에서 웹 FID 전용 필드
          data: { title, body, ...(data ?? {}) },
          webpush: { headers: { Urgency: 'high' } },
        }
      : {
          token, // TokenMessage — Android FCM 등록 토큰
          notification: { title, body },
          ...(data ? { data } : {}),
        },
  );

  const response = await getMessaging(this.app).sendEach(messages);

  // 만료 식별자 정리
  const staleIdentifiers = response.responses
    .map((r, i) => ({ ...r, identifier: identifiers[i] }))
    .filter(
      (r) =>
        !r.success &&
        (r.error?.code === 'messaging/registration-token-not-registered' ||
          r.error?.code === 'messaging/invalid-argument'),
    )
    .map((r) => r.identifier);

  if (staleIdentifiers.length > 0) {
    await this.fcmTokenRepo
      .createQueryBuilder()
      .delete()
      .where('token IN (:...tokens)', { tokens: staleIdentifiers })
      .execute();
  }
}

왜 웹은 data-only? Firebase compat SDK는 notification 필드가 있는 메시지를 수신하면 자동으로 알림을 표시하면서 동시에 onBackgroundMessage도 호출한다. 이 경우:

1. 알림이 두 번 표시된다
2. Firebase가 자동 표시한 알림의 evnet.notification.data는 FCM이 래핑한 구조라, postId, groupId 등 커스텀 데이터를 바로 꺼내기 어렵다.

data-only로 보내면 Firebase의 자동 표시 없이 onBackgroundMessage에서만 알림을 제어할 수 있다.

참고로, Firebase JS SDK v12부터 웹 푸시 등록 방식이 getToken -> register + onRegistered 방식으로 변경되었다. 새 API에서 반환하는 식별자는 FCM 등록 토큰이 아니라 FID이다. Firebase Admin SDK에서 이에 대응하는 FidMessage 타입(fid 필드)가 추가됐고, 기존 TokenMessage는 웹에 대해서는 deprecated 처리됐다.

참고

• Firebase Admin SDK — sendEach
• FCM 메시지 타입 — 알림 메시지 vs 데이터 메시지
• 웹용 백그라운드 메시지 수신

프론트엔드 구현

1. Service Worker 설정 (firebase-messaging-sw.js)

self.addEventListener('install', () => self.skipWaiting());
self.addEventListener('activate', (event) =>
  event.waitUntil(self.clients.claim()),
);

// ⚠️ 반드시 firebase.messaging() 호출 전에 등록해야 합니다
self.addEventListener('notificationclick', (event) => {
  event.notification.close();
  const { groupId, postId } = event.notification.data ?? {};
  const url =
    postId && groupId
      ? `/record/${postId}?scope=group&groupId=${groupId}`
      : postId
        ? `/record/${postId}`
        : groupId
          ? `/group/${groupId}`
          : '/';

  event.waitUntil(clients.openWindow(url));
});

// firebase.messaging() 이후에 등록하면 Firebase 내부 핸들러가 먼저 실행됩니다
importScripts('https://www.gstatic.com/firebasejs/10.14.1/firebase-app-compat.js');
importScripts('https://www.gstatic.com/firebasejs/10.14.1/firebase-messaging-compat.js');

firebase.initializeApp({ /* firebaseConfig */ });
const messaging = firebase.messaging();

messaging.onBackgroundMessage((payload) => {
  // data-only 메시지이므로 payload.data에서 읽어야 합니다
  const title = payload.data?.title ?? '알림';
  const body = payload.data?.body ?? '';
  self.registration.showNotification(title, {
    body,
    icon: '/icon-192x192.png',
    data: payload.data ?? {},  // notificationclick에서 꺼낼 데이터
  });
});

구현하면서 notificationclick 등록 순서가 중요했다. Firebase compat SDK는 firebase.messaging() 호출 시점에 내부적으로 notificationclick 이벤트 리스너를 등록한다. 이벤트 리스너는 등록 순서대로 실행되는데, Firebase 리스너가 먼저 실행되면 user gesture context를 소비해버린다. 이후 우리 리스너의 clients.openWindow()는 user gesture 없이 호출되므로 브라우저가 창 열기를 차단하게 된다.

이 때문에 나는 첫 번째 알림 클릭은 반응이 없고, 두 번째 알림 클릭부터 정상 동작하는 현상이 발생했다.

참고

• MDN — ServiceWorkerGlobalScope: notificationclick event
• MDN — Clients.openWindow()
• MDN — Service Worker API
• web.dev — Push notifications overview
• Firebase — Set up a JavaScript Firebase Cloud Messaging client app

2. FCM 등록 후

Firebase JS SDK에서 getToken/deleteToken이 deprecated되고 register/unregister/onRegistered API로 전환됐다.

• register: Promise를 반환하지 않는 콜백 기반 API
• `onRegistered(messaging, callback): FID를 전달받는 콜백 등록, register 호출 전에 먼저 등록해야 한다.
• unregister: 기존 FID 등록 정보 삭제, swRegistration 초기화 없이도 바로 호출 가능

import { register as fcmRegister, unregister, onRegistered } from 'firebase/messaging';
import type { Messaging } from 'firebase/messaging';

// onRegistered 콜백을 await 가능한 형태로 변환
function registerAndGetFid(
  messaging: Messaging,
  options: { vapidKey: string | undefined; serviceWorkerRegistration: ServiceWorkerRegistration },
): Promise<string | null> {
  return new Promise((resolve) => {
    // onRegistered를 먼저 등록한 뒤 register() 호출
    const unsubOnRegistered = onRegistered(messaging, (fid) => {
      unsubOnRegistered();
      resolve(fid);
    });
    fcmRegister(messaging, options).catch(() => {
      unsubOnRegistered();
      resolve(null);
    });
  });
}

async function getAndRegisterWebFcmToken() {
  const messaging = await getFirebaseMessaging();
  if (!messaging) return;

  const swReg = await navigator.serviceWorker.register(
    '/firebase-messaging-sw.js',
    { scope: '/firebase-cloud-messaging-push-scope' },
  );

  // SW가 활성화될 때까지 기다립니다 (race condition 방지)
  if (!swReg.active) {
    await new Promise<void>((resolve) => {
      const sw = swReg.installing ?? swReg.waiting;
      if (!sw) { resolve(); return; }
      const handler = () => {
        if (sw.state === 'activated') {
          sw.removeEventListener('statechange', handler);
          resolve();
        }
      };
      sw.addEventListener('statechange', handler);
      // 리스너 등록 후 상태를 다시 확인 (등록 전에 이미 activated된 경우 대비)
      if (sw.state === 'activated' || swReg.active) {
        sw.removeEventListener('statechange', handler);
        resolve();
      }
    });
  }

  // SW를 unregister하면 push subscription이 소멸합니다
  // 기존 구독이 없으면 FID 등록 정보가 무효화된 것이므로 강제 갱신합니다
  const existingSub = await swReg.pushManager.getSubscription().catch(() => null);
  if (!existingSub) {
    await unregister(messaging).catch(() => {});
  }

  const fid = await registerAndGetFid(messaging, {
    vapidKey: VAPID_KEY,
    serviceWorkerRegistration: swReg,
  });

  if (fid) {
    await registerFcmToken(fid, 'web').catch(() => {});
  }
}

참고

• Firebase — register()
• MDN — PushManager.getSubscription()
• MDN — ServiceWorkerRegistration

3. Android 네이티브 (Capacitor)

export async function registerAndroidToken() {
  const { PushNotifications } = await import('@capacitor/push-notifications');

  const result = await PushNotifications.requestPermissions();
  if (result.receive !== 'granted') return;

  await new Promise<void>((resolve) => {
    PushNotifications.addListener('registration', async ({ value: token }) => {
      await registerFcmToken(token, 'android').catch(() => {});
      await PushNotifications.removeAllListeners();
      resolve();
    });
    PushNotifications.addListener('registrationError', async () => {
      await PushNotifications.removeAllListeners();
      resolve();
    });
    PushNotifications.register();
  });
}

참고

• Capacitor — Push Notifications Plugin
• Capacitor — Using FCM with Capacitor

구현 중 마주한 버그와 해결

1. 서비스워커 unregister 후 알림이 오지 않는 문제

DevTools에서 서비스 워커를 unregister하고 새로고침하면 알림 토큰이 재등록되지 않아 알림이 오지 않는 문제가 발생했다.

usePushNotification의 활성화 조건을 status === 'authenticated(nextauth)로 설정해뒀었는데, fast refresh나 서비스 워커 unregister 이후에 nextauth의 SessionProvider 상태가 리셋되어서 status가 일시적으로 unauthenticated가 된 것이다.

useAuthStore(Zustand + localStorage persist)의 userType !== null로 조건을 변경해줬다. localStorage 기반이라 fast refresh에 영향을 받지 않는다.

2. 서비스워커 unregister 후 재등록시 FID가 갱신되지 않는 문제

DevTools에서 1번과 똑같이 unregister하면 push subscription이 소멸하는데, 재등록시 register()가 기존 FID 등록 정보를 재사용해서 push subscription을 생성하지 않았다.

Firebase는 FID 등록 정보를 내부적으로 캐싱한다. push subscription이 없어진 상태에서도 기존 FID가 남아 있으면 register가 push subscription 재생성 없이 캐시된 FID를 그대로 반환하기에 발생한 문제이다.

push subscription이 없을 때 (pushManager.getSubscription() -> null) unregister(messaging)를 먼저 호출해 Firebase 내부의 FID 등록 정보를 초기화한다. 이렇게 하면 이후 register가 새 push subscription과 함께 FID를 재발급한다.

const existingSub = await swReg.pushManager.getSubscription().catch(() => null);
if (!existingSub) {
  // FID 등록 정보를 초기화해 register()가 새 push subscription으로 재등록하도록 강제
  await unregister(messaging).catch(() => {});
}
const fid = await registerAndGetFid(messaging, options);

결과적으로는 서비스워커 unregister 후에도 새로고침 후 재등록 된 후에는 알림이 잘 온다.

참고

• MDN — PushManager.getSubscription()

3. 첫 번째 알림 클릭 시 아무 반응이 없던 문제

앱을 처음 실행하거나 서비스워커를 재등록한 직후에 첫 알림 클릭은 반응이 없고, 두 번째 알림 클릭부터 정상 동작하는 문제가 있었다.

Firebase compat SDK가 firebase.messaging() 호출 시 내부적으로 notificationclick 리스너를 등록한다. 우리 리스너가 Firebase 리스너 이후에 등록되면 Firebase가 먼저 실행되어 user gesture context를 소비하고, 이후 clients.openWindow()가 차단된다.

그래서 notificationclick 리스너를 importScripts/firebase.messaging() 이전에 등록해주었고, 잘 동작하는 것도 확인했다.

4. 첫 번째 알림 클릭 시 잘못된 페이지로 이동하는 문제

첫 알림 클릭 시 올바른 기록 페이지가 아닌 엉뚱한 페이지로 이동하는 문제가 발생했다.

백엔드에서 notification 필드를 포함한 메시지를 보내면 Firebase SW가 자동으로 알림을 표시하면서 onBackgroundMessage도 호출한다. 이로 인해서

• 알림이 두 번 표시됨(Firebase 자동 + onBackgroundMessage에서 수동)
• 자동 표시된 알림의 data는 Firebase가 FCM_MSG 키로 래핑한 구조 -> postId, groupId를 못 찾아 fallback URL로 이동

실제로 첫 알림이 빠르게 두 번 호출되는걸 확인했었다.

백엔드 쪽에는 웹 토큰에는 notification 필드 없이 data만 전송하도록 수정했다. (data-only 메시지) 서비스워커 쪽에서는 onBackgroundMessage에서 payload.data.title, payload.data.body를 읽도록 하고 showNotification의 data에 커스텀 필드를 전달해 notificationclick에서 바로 사용이 가능하도록 했다.

FCM 토큰 관리

기본 권장사항

토큰은 비활성 등록 토큰과 활성 토큰으로 나뉘는데, 토큰이 비활성화되는 이유는 여러 가지가 있다. 토큰이 손실되거나, 파손되거나, 스토리지로 넘어가거나, 잊혀진 경우이다.

토큰은 결국 db에 저장되고 관리되기 때문에, 비활성화된 토큰은 정리할 필요가 있다. 그렇지 않으면 리소스를 계속 잡아먹게 되기 때문에 불필요한 비용이 추가되게 된다.

Android의 경우 비활성 토큰이 270일 동안 활동이 없으면 FCM에서 만료된 것으로 간주한다. 토큰이 만료되면 FCM은 토큰을 유효하지 않은 것으로 표시하고 토큰으로의 전송을 거부한다. iOS와 같은 다른 플랫폼의 경우 FCM은 기본 푸시 서비스(예: APNs)를 사용한다. APNs는 270일 비활성 상태를 기준으로 한 토큰 만료가 적용되지 않기에, 토큰을 최신 상태로 유지하고 비활성 등록 토큰을 삭제하는 것이 좋다.

등록 토큰 검색 및 저장

그렇기에 앱을 처음 시작할 때 이 토큰을 검색해 타임스탬프와 함께 앱 서버에 저장하는 것이 좋다. 물론, 이 타임스탬프는 FCM SDK에서 제공하지 않기에, 서버에서 구현해야 한다.

또한 토큰이 변경될 때마다 타임스탬프를 업데이트하는 것이 중요하다.

• 새 기기에서 앱 복원
• 사용자가 앱 제거 또는 재설치
• 사용자가 앱 데이터 소거
• FCM에서 기존 토큰이 만료된 후 앱이 다시 활성화

토큰 최신 상태 유지 및 비활성 토큰 삭제

토큰이 최신 상태인지 비활성 상태인지를 판단해 토큰을 처리하는 것은 기준을 정해둬야 한다.

기본적으로 FCM은 앱 인스턴스가 한 달 동안 연결되지 않은 경우 토큰을 비활성 상태로 간주한다. 1개월이 지난 토큰은 비활성 기기일 가능성이 높으며 그 외의 활성 기기는 토큰을 갱신했을 것이기 떄문이다.

그렇기에 FCM에서 잘못된 토큰 응답을 감지하고 유효하지 않거나 만료된 등록 토큰을 시스템에서 삭제해 이에 대응하도록 관리해야 한다.

HTTP v1 API를 사용하면 다음과 같은 오류 메시지가 전송 요청이 잘못된 토큰이나 만료된 토큰을 타겟팅했음을 나타낸다.

• UNREGISTERED(HTTP 404)
• INVALID_ARGUMENT(HTTP 400)

INVALID_ARGUMENT는 메시지 페이로드에 문제가 있는 경우에도 반환될 수 있기에 페이로드가 완전히 유효한 경우에만 잘못된 토큰 신호를 보낸다.

메시지 페이로드가 유효하다고 확신한 상태에서, 타겟팅 된 토큰에 대해서 위와 같은 응답이 오면, 해당 토큰은 더 이상 유효한 상태가 아니므로 해당 레코드를 삭제하는 것이 안전하다.

정기적으로 토큰 업데이트

서버에서 모든 등록 토큰을 주기적으로 검색 및 업데이트하는 것이 좋다.

참고 Firebase FCM 등록 토큰 관리를 위한 권장사항  |  Firebase Cloud Messaging

웹 개발 모드에서의 테스트 mov -> gif 변환으로 인한 느림 주의

참고 자료

• Firebase Admin SDK 설정

개발 환경에서 진행한 성능 최적화로, 운영 환경보다 성능이 떨어질 수 있습니다.

페이지 라우팅(navigation) 지연

데모데이로 캠퍼들이 서비스를 사용하며 개선할 사항들에 대해 정리해줬는데, 그 중 하나가 페이지 라우팅이 오래 걸린다는 점이었다.

현재 상황 파악

우리는 웹소켓 장애 대응을 위해 sentry를 적용한 상태다. 마침 sentry에서 성능에 관련된 대시보드를 제공하기 때문에, 얼마나 지연되는지 평균을 찾아볼 수 있었다.

그 중 한 페이지를 사진으로 찍어왔다.

OPERATION 이라고 적힌 부분에서 어떤 타입에 대한 분석인지를 확인할 수 있다. 나는 라우팅과 관련된 사항을 개선하고자 하므로, navigation 이라고 적힌 부분을 보면 된다.

사진상에는 대부분이 navgation 이라고 적혀있으니 위 사진을 토대로 분석을 해보자.

• Operation (navigation vs pageload):
  • navigation: 사용자가 앱 내에서 링크를 클릭해 페이지를 이동할 때 걸린 시간(Client-side routing). 유저 피드백인 "페이지 이동 시 지연"과 직접적으로 관련된 수치
  • pageload: 브라우저에 URL을 직접 입력하거나 새로고침했을 때, 전체 리소스를 처음부터 읽어오는 시간
• AVG DURATION: 해당 페이지로 이동할 때 걸린 평균 시간
• P95 DURATION: 전체 사용자 중 상위 5%(가장 느린 케이스)가 경험한 시간

1. 가장 심각한 지점: /group/:groupId/post/:draftId (pageload)

• 평균 2.48s, P95는 4.21s나 걸리고 있다. 공동 작성 드래프트 페이지 인데, 초기 로딩 시 무거운 스크립트나 대량의 데이터를 가져오고 있을 가능성이 높다.

1. 병목 현상이 의심되는 지점: /group/:groupId (navigation)
   • 단순 페이지 이동임에도 평균 810.54ms, P95는 2.09s이다. 보통 부드러운 웹 경험을 위해 navigation은 200~300ms 이내를 지향하는데, 2초 가량 지연된다면 유저는 확실히 답답함을 느낄 가능성이 크다.

전체적으로 훑어봐도, navigation에서의 지연이 발생하고 있음을 파악할 수 있다. 이제 이에 대한 원인을 알아보자.

원인 분석

일단 가장 많은 유저가 접하게 될 루트 경로인 / 을 확인해봤다.

눈에 띄는 구간은

• 613.99ms이나 걸리는 / 경로 GET 요청
• API 요청
• next-auth 세션 관리

이렇게 3개로 분류할 수 있으며, 불필요한 직렬 요청과 인증 과정이 중복되어 병목이 발생하고 있다.

1. 무거운 인증 및 세션 확인 절차

가장 큰 막대 그래프를 차지하는 부분이 인증 관련 로직이다.

• POST /api/auth/callback/credentials 와 그 아래의 POST /v1/auth/excahnge 가 전체 로딩 시간의 상당 부분을 점유하고 있다.
• 페이지에 진입할 때마다 세션을 다시 확인하려는 과정이 서버 사이드에서 발생해서 라우팅 지연을 유발하고 있는 것으로 추측된다.

2. 미들웨어 및 서버 사이드 처리 지연

• http.server - GET / 내부에서 페이지 컴포넌트를 해석하고 빌드하는 과정이 약 613.99ms 정도 소요되고 있다.
• 서버 컴포넌트가 렌더링되기 전에, 필요한 데이터를 모두 가져올 때까지 브라우저가 응답을 받지 못하고 대기하고 있음을 의미한다.

2번에서 새로 알게 된 사실이 있다.

next.js app 라우터 구조와 서버 컴포넌트 라우팅 지연 관계

서버 컴포넌트와 라우팅 지연이 next.js app 라우터 구조에서 깊은 연관이 있다는 것이다.

일반적인 React 프로젝트(CSR)에서는 클릭하면 즉시 페이지가 바뀌게 된다. 그 다음, 페이지 내부에서 API를 호출하게 되기 때문에 데이터 로드에 대한 유저 피드백을 고려하게 된다.

하지만 Next.js 서버 컴포넌트에서는 서버에서 데이터를 다 가져온 뒤에 완성된 결과물인 RSC payload를 브라우저로 보낸다.

즉, 서버 컴포넌트에서의 api 패칭 처리와 같은 데이터 로드가 끝날 때까지 서버는 브라우저에 응답을 주지 않는다. 이때 유저는 클릭했지만 아무 변화가 없으니, 라우팅 자체가 안되고 지연되고 있다고 느끼게 되는 것이다.

서버 컴포넌트에서의 API 처리가 왜 라우팅에까지 영향을 주는것인지 이해가 안됐었는데, 바로 고개를 끄덕이게 됐다.

사실, 모든 서버 컴포넌트 페이지에서 이런식으로 동작하도록 코드를 적어놔서 이 부분만 수정해도 많이 개선될 것 같다.

개선 과정

일단 각 문제를 어떻게 개선할 수 있을지를 정리해보자.

1. 인증 로직 최적화 사실, 이미 인증 로직은 한 번 최적화 과정을 거쳤다.

next-auth로 세션을 관리하고 api 호출시에 세션이 필요해 api 호출시마다 매번 세션을 조회하도록 로직을 작성했었다.

그랬더니, 모든 api 호출마다 네트워크 탭에서 세션을 조회하는 api가 호출되고 있는걸 확인했다. 그래서 이는 메모리로 캐싱처리해서, 5분 동안은 캐싱된 데이터를 사용하도록 로직을 수정해주었다.

그럼에도 부족한 것으로 파악이 되니, 캐싱 시간을 5분에서 10분으로 늘리는 것으로 타협을 보려고 한다. 우리 서비스는 15분이 백엔드 토큰 만료시간이기 때문에, 이보다는 적은 시간으로 캐시 만료 시간을 정해두는게 안정성 측면에서 좋을 것으로 생각했다.

추가로, 해당 메인 페이지(/)가 로그인 후 세션을 저장하는 로직이 포함되어 있는 페이지와 연관되어 있어서 인증 관련 시간이 많이 소요된 것으로 파악된다.

2. Suspense를 통한 스트리밍 도입 서버 컴포넌트에서 hydration 처리만 해주고 suspense를 적용하지 않았다. 그래서 데이터 패칭이 완료될 때까지 페이지 이동 없이 지연되고 있던 문제이다.

Suspense 를 사용해서 레이아웃을 먼저 보여주고, 데이터가 필요한 부분만 로딩 상태를 보여주는 방식으로 UX를 개선할 수 있을 것 같다.

또한, 서버 컴포넌트에서 데이터를 클라이언트로 내려주겠다고 queryClient.setQueryData 를 해주고 있다. tanstack query의 장점을 살리려면 prefetchQuery 를 사용해서 서버에서 미리 캐싱하는게 정석적일 것 같다.

setQueryData vs prefetchQuery

setQueryData 는 캐시에 데이터를 강제 주입하는거라 Tanstack Query가 이 데이터가 언제 패칭됐는지, 아직 유효한지 알 수 없다.

const queryClient = new QueryClient();

await queryClient.prefetchQuery({
  queryKey: ['records', 'preview', selectedDate, 'personal'],
  queryFn: () => getCachedRecordPreviewList(selectedDate),
});

현재 코드는 Page 메인 함수 안에 들어있어서, 데이터가 다 오기 전까지 지금처럼 라우팅이 지연되는 문제가 발생한다.

데이터 패칭 로직을 메인 페이지 밖으로 옮겨서, 데이터가 없어도 일단 페이지 레이아웃부터 보여주도록 수정해야 한다.

// 현재
export default async function HomePage() {
  // 여기서 await를 해버리면, 데이터가 올 때까지 아래 리턴문(HTML)은 브라우저에 전송되지 않음
  const [data1, data2] = await Promise.all([fetch1, fetch2]); 

  return <Layout>{/* 데이터 사용 */}</Layout>;
}

// 수정 방법
export default function HomePage() {
  return (
    <Layout>
      <WeekCalendar /> {/* 얘는 데이터가 필요 없으니 브라우저에 즉시 뜸 */}

      <Suspense fallback={<HomeSkeleton />}>
        {/* await는 이 안에서 수행됨 */}
        <HomeContent /> 
      </Suspense>
    </Layout>
  );
}

// 별도 파일 혹은 같은 파일 아래에 작성
async function HomeContent() {
  // 여기서 await를 하더라도 HomePage는 이미 브라우저에 전달된 상태
  const [data1, data2] = await Promise.all([fetch1, fetch2]); 
  return <RecordList data={data1} />;
}

이런식으로 서버 컴포넌트 로직을 모두 수정해주자.

메인 페이지 라우팅 지연 성능 문제 performance로 파악

performance 탭에서 녹화 기능을 사용해 라우팅에 얼마나 걸리는지, 혹은 오래 걸리는 작업은 없는지를 파악하고 있었는데 프로필 페이지에서 메인 페이지로 이동하니까 이동하기 직전에 저렇게 long task가 길게 잡혔다.

앞의 빨간 Long task는 프로파일링할 때의 오버헤드라서 제외했다.

Call tree를 분석해보면:

• Run microtasks → handleResult → dispatchSetState → React 렌더링 작업
• 대부분이 React의 state 업데이트와 커밋 작업에 소비됨

이건 메인 페이지로 라우팅할 때 React가 새 페이지를 렌더링하면서 메인 스레드를 블로킹하는 문제이다.

주요 문제

아래 파일들은 모두 위 사진인 메인 페이지(/)에서 사용하는 컴포넌트들이다.

RecordList - 블록 레이아웃 계산

RecordList.tsx를 보면

{(() => {
  // 블록을 row별로 그룹화
  const rowMap = new Map<number, Block[]>();
  record.blocks.forEach((block) => { ... });

  const sortedRows = Array.from(rowMap.entries()).sort(...);

  return sortedRows.map(([rowNumber, blocks]) => {
    const sortedBlocks = blocks.sort(...);
    const hasFullWidth = sortedBlocks.some(...);
    // ...
  });
})()}

문제: 각 기록마다 매번 새로운 Map 생성 → 정렬 → 필터링을 반복한다. 기록이 10개면 이 작업이 10번 반복되고, 메인 스레드를 블로킹하게 된다.

WeekCalendar - 초기 렌더링 시 router.replace

// WeekCalendar.tsx
useEffect(() => {
  if (!dateParam) {
    const today = formatDateISO();
    router.replace(`/?date=${today}`);
  }
}, [dateParam, router]);

문제: 페이지 로드 시 URL에 date 파라미터가 없으면 router.replace를 호출해서 추가 렌더링이 발생한다.

framer-motion의 애니메이션

주간 달력을 표현하는 컴포넌트에서의 문제인데,

AnimatePresence + motion.div + drag 기능이 초기 렌더링 시 많은 이벤트 리스너를 등록한다.

문제 사항 최적화 적용

RecordList 블록 레이아웃 계산 최적화

블록 정렬 로직을 별도 함수로 분리하고 useMemo로 감싼다.

// 각 기록의 블록을 useMemo로 최적화
const sortedRowsMap = useMemo(() => {
  return records.map(record => {
    const rowMap = new Map<number, Block[]>();
    record.blocks.forEach((block) => {
      const row = block.layout.row;
      if (!rowMap.has(row)) rowMap.set(row, []);
      rowMap.get(row)!.push(block);
    });

    return Array.from(rowMap.entries()).sort(([a], [b]) => a - b);
  });
}, [records]);

• 각 기록을 RecordItem 컴포넌트로 분리
• 블록 정렬 로직을 useMemo로 감싸서 불필요한 재계산 방지
• React.memo로 컴포넌트 메모이제이션

효과: 이전에는 각 기록마다 매번 Map 생성 → 정렬을 반복했지만, 이제는 블록이 변경될 때만 계산

서버에서 날짜 파라미터 기본값 설정 및 초기 날짜 파라미터 설정 제거

서버 컴포넌트가 이미 날짜를 설정하고 있으니, WeekCalendar의 useEffect를 제거한다. 또한, 초기엔 날짜 파라미터가 url 상에 없으니 굳이 억지로 추가해 서버 컴포넌트가 두 번 실행되지 않도록 한다.

• 클라이언트 useEffect에서 router.replace 제거
• 서버 컴포넌트에서의 redirect 제거

효과: 초기 렌더링 시 불필요한 추가 렌더링 제거

BlockContent를 React.memo로 감싸기

RecordList.tsx의 BlockContent를 memo 처리하면 불필요한 리렌더링을 방지할 수 있다.

• BlockContent와 ImageBlock 컴포넌트를 React.memo로 감싸기
• props가 변경되지 않으면 리렌더링 스킵

효과: 블록 개수만큼 리렌더링 절감

최적화 후 결과

175.7ms → 134.9ms로 Run microtasks 활동에 대한 작업 시간을 줄였다.

프로필 페이지 성능 최적화

메인 페이지에서 프로필 페이지로 이동할 때도 performance를 돌려봤다.

아래 사진은 프로필 페이지인 마이페이지다.

Timer fired는 Effect 실행 시간이다.

프로필 페이지에선 통계 자료를 보여주도록 되어 있는데, 이에 대한 useEffect 실행에 의한 것이라 판단했다.

<div className={cn(
  'overflow-hidden transition-all duration-300 ease-in-out',
  isChartVisible ? 'max-h-300 opacity-100' : 'max-h-0 opacity-0',
)}>
  <MonthlyUsageChart />  // 항상 렌더링됨
  <PlaceDashboard />
  <EmotionDashboard />
</div>

문제: display: none이 아니라 max-h-0로 숨기고 있어서, 차트가 항상 렌더링되고 있다.

즉, CSS로만 숨기고 있어서 차트가 항상 렌더링되고, useEffect 등이 모두 실행되는 문제이다.

이를 필요할 때만 렌더링되도록 해 불필요한 useEffect 실행을 막아주자

{isChartVisible && (  // 필요할 때만 렌더링
  <div className="...">
    <MonthlyUsageChart />
    <PlaceDashboard />
    <EmotionDashboard />
  </div>
)}

결과적으론, 해당 문제에 대한 long task가 사라졌다.

그 외 최적화한 사항

함께 기록함에서 기록 추가 버튼 클릭 시 지연

함께 기록함 페이지에서, 하단 네비게이션바의 + 버튼을 클릭하면 어떤 그룹에 기록을 추가할 것인지 묻는 drawer가 표시된다.

그런데 이 drawer가 표시되는 데 시간이 꽤 걸리길래, performance로 측정해봤다.

클릭 이벤트가 처리되는 데 시간이 꽤 걸리는 것으로 보인다.

/shared 페이지에서 + 버튼 클릭 시 GroupSelectDrawer가 열리는데, 이때 groups 데이터를 enabled: isGroupSelectOpen으로 조건부로만 패치하고 있어서 지연이 발생한다.

해결 방법: /shared 페이지에서는 drawer가 열리기 전에 미리 데이터를 prefetch하도록 수정

데이터 패치는 /shared 페이지에서 불러오는 데이터와 동일하기 때문에, 캐시된 데이터를 사용하게 된다.

그렇기에 빠르게 데이터를 불러올 수 있게 되에 위 사진처럼 265.6ms → 102.0ms로 이벤트 처리 시간을 줄일 수 있었다.

수정 전 사진과 조금 형태가 다른데, 캐시된 데이터를 사용하게 되어서 빨리 뜰까봐 페이지 이동과 동시에 바로 drawer가 뜨도록 인터렉션을 걸어봤다.

라우팅 지연이 심했던 /group/:groupId 경로 개선

sentry에서 확인했을 때, draft 페이지 다음으로 지연이 심했던 페이지가 특정 그룹 내부 페이지로 이동할 때였다.

그래서 함께 기록함에서 그룹 페이지로 이동할 때의 performance를 측정해봤다.

Suspense 를 적용하기 전보다는 라우팅 지연이 개선되긴 했지만, 그럼에도 지연되는 부분이 존재했다.

페이지를 이동한 뒤에는 Timer fired 문제가, 이동 전 함께 기록함에서는 forced reflow 문제가 발생하는 것으로 파악이 된다.

코드를 확인한 결과,

1. Forced reflow: /shared 페이지의 RecordCard들이 memo 없이 매번 재렌더링되며, 각 카드의 AssetImage가 layout recalculation을 유발
2. Timer fired: 그룹 페이지의 MonthRecords도 동일한 문제

여기서 Timer fired를 조금 더 자세히 적자면,

1. 그룹 페이지로 라우팅 후 React가 다음 작업을 예약
   • 새 컴포넌트 마운트
   • useEffect 훅 실행
   • 상태 업데이트 처리
   • 렌더링
2. 많은 컴포넌트들이 동시에 렌더링되면서
   • MonthRecords 컴포넌트의 여러 RecordCard들
   • 각 카드의 AssetImage 로딩
   • GalleryDrawer (항상 렌더링되고 있었음)

즉, 리렌더링 문제로 파악을 해서 주요 컴포넌트들을 React.memo로 최적화를 진행했다.

그리고 memo를 적용해줘도 props가 자꾸 바뀌면 memo가 작동하지 않기 때문에, 이 부분도 같이 확인해줬다. (props 인라인 함수)

그래서 불필요하게 바뀌는 props도 callback으로 최적화를 시켜줬다.

결과는 다음 사진들과 같다.

Timer fired는 163.3ms → 65.8ms로, forced reflow와 연관된 작업은 375.7ms → 171.3ms로 개선됐다.

그리고 직접 라우팅을 할 때도 개선하기 전보다 이동이 빨라진게 느껴졌다.

그룹 프로필 수정 페이지 지연

그룹 프로필 수정 페이지에 개인 프로필을 설정할 수 있는 수정 페이지가 존재한다. 해당 페이지로 라우팅할 때, 지연이 발생하는 것을 확인해서 이 부분도 같이 측정해봤다.

Call tree 보단 Bottom-up이 원인을 파악하기에 더 수월한 것 같아서 사진을 바꿔봤다.

코드를 확인했을 때, 매번 인라인 함수로 멤버 리스트를 생성하고 있어서 리렌더링 문제가 발생한걸로 추측되었다.

그래서 이 인라인 함수들을 모두 분리해주는 등 최적화 작업을 진행해줬다.

이전/이후 전체 시간을 찍고 내부 시간들을 찍어야 하는데 까먹는다..

가장 눈에 띄었던 Layout 작업이 143.1ms → 101.6ms로 개선된 것을 확인할 수 있었다.

작성 페이지 라우팅 지연

가장 지연이 심했던 작성 페이지를 개선해볼까 한다.

Layout과 Recalculate style에 지연이 발생하고 있음을 파악할 수 있다. 여기도 비슷하게 인라인 함수를 많이 사용하고 있는걸 코드상에서 파악을 해서 똑같이 수정해줬다.

long task가 사라졌다…

인라인 함수 수정과 메모이제이션만 적용해줬는데 개선이 된걸 보고, 컴포넌트에 넘겨줄 때 인라인 함수가 얼마나 안좋은지 알게 된 것 같다.

똑같은 Layout은 173.9ms → 31.7ms, Recalculate style은 14.4ms → 7.7ms로 줄었다.

그 외 다른 것들도 조금씩 감소된걸 확인할 수 있다.

마무리

라우팅 지연 최적화 작업은 사실 2주? 정도 된 작업이다. 다른 최적화 작업을 진행하느라 정리를 제대로 못해서 한 번에 정리해서 적어봤다.

애초에 작업하면서 찍어놓고 정리한 것도 이해하면서 읽기 편한 상태가 아니었어서 정리를 한 뒤에도 조금 가독성이 떨어지는 것 같다.

이번 작업을 하면서 깨달은 것은, 인라인 함수는 리렌더링이 될 때 새로 생성되기 때문에 props로 해당 함수를 전달받는 컴포넌트가 매번 리렌더링 된다는 것이다.

그렇기에 인라인 함수로 자식 컴포넌트에게 전달하기 보단, useCallback으로 감싸거나 인라인이 아닌 함수화해서 해당 함수를 전달하는 방식을 선택해야 한다는 것이다.

그리고 컴포넌트를 렌더링하는 영역인 return 함수 안에는 계산 로직이 들어가지 않도록 하는게 마찬가지로 리렌더링 이슈 개선에 좋다는 것도 알게 된 것 같다.

이 최적화 작업에 대한 PR이 이미 머지된 상태인데, 아직 이전과 비교할만한 아직 데이터가 쌓이지 않아서 전후 비교를 하지 못하고 있다.

스토어 출시를 목표로 하고 있으니, 이후에 쌓인 데이터로 전후 비교를 할 수 있지 않을까 싶다!

mov -> gif를 했는데, 영상이 느리게 실행됩니다.

API 중복 호출 문제

영상처럼 버튼을 여러 번 연속해서 클릭할 때, 클릭한 횟수만큼 api 요청이 가는 문제가 있음을 발견했다.

그래서 중복되는 데이터가 생기게 되며, 이로 인해 유저에게 혼란을 줄 수 있다.

get 요청의 경우 react query key에 맞춰 캐시되도록 했기 때문에, get을 제외한 메소드에 대한 api 중복 호출 문제를 해결하기로 했다.

해결 방법 탐색

API 중복 호출 문제를 해결하기 위한 방법은 세 가지 정도가 있다.

1. debounce
2. throttling
3. tanstack query isPending 활용

처음에는 1, 2번 중에서 선택하려고 했다. POST나 DELETE와 같은 mutate 요청의 경우 API 응답이 왔다고 해도 그 응답에 맞는 처리를 하기까지 시간이 소요될 수 있다.

예를 들어 정상 응답을 받은 후에 페이지 이동이 필요하다면 라우팅을 준비하는 시간이 소요될 수 있다. 그 시간동안은 기존의 페이지에 머물게 되는 것이다.

그러면 유저 입장에선 API를 재호출할 수 있는 환경이 마련되면서 중복된 요청이 발생하게 될 것이라고 생각했다.

하지만 무턱대고 나 혼자만의 생각으로 바로 적용하기 보단, 조금 더 찾아보고 나은 선택을 하는게 좋을 것 같았다.

그렇게 아래의 블로그를 발견했다. React에서 중복호출(aka. 따닥)을 막는 완벽한 방법

블로그에서 말하는 API 중복 호출 중 debounce에 대한 내용은 다음과 같다.

아래는 블로그 내용

debounce 를 활용한 방식은 해피 케이스에는 문제가 없을 것입니다. 여기서 고민이 되는 부분은 waitMS 를 얼마로 설정할 것이냐 입니다. API 는 보통 1초 안에 끝나니까 1초로? 여유롭게 3초로? 이런 직관으로 정할 순 없겠죠. API latency는 서버, DB 상황에 따라서 언제나 달라질 수 있습니다. 이를 고정한다는 것은 엄밀하지 않은 사고입니다.

debounce 를 사용하면, 2가지 케이스가 발생한다는 것을 알 수 있습니다.

• api latency < debounce wait
• api latency > debounce wait

1번 케이스부터 보겠습니다. api가 빠르게 응답이 온다면, 보통의 경우에 큰 문제가 없습니다. 문제가 없는 경우는, API 가 성공했을 때입니다. API 가 성공해서 다음 유저 플로우를 타게 된다면, button disabled 시간(debounce wait - api latency)이 존재해도 문제가 되지 않습니다.

API 가 실패하면 어떻게 될까요? 일정 시간(debounce wait - api latency) 만큼, 사용자는 버튼을 다시 누르지 못 합니다. 그러므로 중복호출을 막기 위한 목적으로 함부로 debounce wait 를 길게 해서는 안 됩니다.

2번 케이스를 보겠습니다. api latency 가 더 길다면, 정말로 문제 입니다. debounce wait 가 끝난다면, 다시 clickable 한 상태가 되고, 서버에 중복호출을 할 수 있습니다. 이때는 서버에서 중복호출을 막고 있길 기도해야겠지요.

정리하자면, api latency 과 debounce wait 가 차이가 있기 때문에, debounce로 완벽한 중복호출을 막는 것은 본질적으로 불가능하다는 것입니다. throttle 도 마찬가지 논리이므로 생략합니다.

그럼 debounce, throttle 의 목적은 무엇일까요? 이들은 “중복호출”을 막기 위함이 아니라, “과도한 호출” 을 막기 위함입니다. 검색, 광클이 가능한 버튼 (게임 아이템 주기 등), 스크롤 이벤트 제어 등에 쓰입니다. 이를 중복 호출 방지에 쓰는 것은 적절하지 않습니다.

이 내용을 읽고 너무나도 맞는 말이라 설득을 당해버렸다. debounce와 throttle은 정해둔 시간이 적절하지 않으면 오히려 UX에 악영향을 줄 수 있다.

그래서 다른 방법을 선택하려고 했는데, 블로그에서는 useRef를 활용한 isLoading 관리 방법으로 API 중복 호출을 막도록 했다.

하지만 나는 공통 유틸 함수를 사용하고 있고, 이를 각 API마다 하나 하나 적용하기란 불필요한 비용이 소모될 것이라고 생각했다.

그래서 비슷한 방법인 공통 유틸 함수(mutate)에서 isPending을 활용해 API 중복 호출을 막도록 하고자 했다.

API 중복 호출 제거하기

이를 위한 방법은 간단하다.

tanstack query의 mutate를 사용하는 곳에서 isPending 상태일 경우에는 api를 호출하지 않도록 하는 것이다.

우리 팀은 코드 일관성과 편의를 위해 공통된 곳에서 mutate를 호출해 사용하고 있다.

// useApi.ts
/**
 * POST 요청을 위한 훅
 * @example
 * const { mutate, isPending } = useApiPost('/users', {
 *   onSuccess: (data) => console.log(data),
 * });
 * mutate({ name: 'John' });
 */
export function useApiPost<
  TData = unknown,
  TVariables = Record<string, unknown>,
>(
  endpoint: string,
  options?: UseApiMutationOptions<TData, TVariables> & {
    invalidateKeys?: QueryKey[];
  },
  sendCookie?: boolean,
  headers?: Record<string, string>,
) {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: async (variables: TVariables) => {
      const response = await post<TData>(
        endpoint,
        variables as Record<string, unknown>,
        { headers },
        sendCookie,
      );

      // 에러 응답 처리 (토큰 재발급은 fetchApi에서 자동 처리됨)
      if (!response.success) {
        throw createApiError(response);
      }

      return response;
    },
    onSuccess: (data, variables, context, mutationContext) => {
      if (options?.invalidateKeys) {
        options.invalidateKeys.forEach((key) => {
          queryClient.invalidateQueries({ queryKey: key });
        });
      }
      options?.onSuccess?.(data, variables, context, mutationContext);
    },
    ...options,
  });
}

위와 같이 각 HTTP 메소드별로 유틸함수를 만들어 이를 호출해 사용하고 있다. 그러니 이 공통 유틸 함수만 수정하면 다른 api 로직에 모두 적용이 된다.

여기에 isPending 동안 mutate 호출을 무시하는 가드를 추가하자.

mutate 호출 무시 가드 추가하기

// useApi.ts
/**
 * isPending 중 중복 호출을 방지하는 mutate 가드
 * 버튼 더블 클릭 등으로 인한 중복 API 요청 방지
 */
function withPendingGuard<TData, TError, TVariables, TContext>(
  mutation: UseMutationResult<TData, TError, TVariables, TContext>,
) {
  return {
    ...mutation,
    mutate: (...args: Parameters<typeof mutation.mutate>) => {
      if (mutation.isPending) return;
      mutation.mutate(...args);
    },
  };
}

이렇게 mutation.isPending 이 true 일 경우 return 해주어 실행되지 않도록 해주었다.

그리고 이를 다음처럼 감싸주면 된다.

// useApi.ts
return withPendingGuard(
    useMutation({
            ...

이렇게만 적용하고 다시 테스트해봤다.

api 요청의 응답은 하나만 전달되어 데이터가 하나만 생성된 것을 확인할 수 있다. 생성 요청 api인 post 도 하나만 전달되었다.

그런데 눈에 띄는 요청이 있었다. 바로 add 라는 이름의 post 요청인데, 이것도 중복 호출되는 것을 막고자 했다.

먼저, 왜 중복 호출되는지에 대해 알아봤다.

스크립트 중복 요청

분석 결과, 두 개의 Server Action이 동시에 호출되고 있었다.

// useCreateRecord.ts
const invalidateQuery = async (groupId?: string) => {
  await Promise.all([refreshRecordData(), refreshHomeData()]); // ← 2개 동시 호출
  ...
};

이는 next.js의 server action 동작 방식 때문이다.

server action은 현재 페이지 url로 post 요청을 보낸다. 그러니 /add 페이지에서 server action을 호출하면 네트워크에서 POST /add 로 표시된다.

Promise.all 로 server action을 동시에 호출하면

POST /add  ← refreshRecordData() Server Action
POST /add  ← refreshHomeData()  Server Action

두 개의 다른 server action이지만 url이 같아서 네트워크 탭에 add 요청이 2번 나타나게 되는 것이다.

실제로는 next action 헤더로 구분되는 서로 다른 요청이다. 문제는 아니지만, 불필요한 이중 요청이라고 생각했다.

위 두 server action은 페이지 단위로 캐시를 지우고자 사용했다.

// revalidate.ts
'use server';

import { revalidatePath } from 'next/cache';

export async function refreshHomeData() {
  revalidatePath('/', 'page');
}

export async function refreshRecordData() {
  revalidatePath('/my', 'layout');
}

export async function refreshGroupData(groupId: string) {
  revalidatePath(`/group/${groupId}`, 'layout');
}

export async function refreshSharedData() {
  revalidatePath('/shared');
}

이렇게 서버 단에서 캐시를 지우게 할 수도 있기에, 나는 빠르면서 한 번에 캐시를 무효화하기 위한 방법으로 사용하고 있었다.

이를 호출하는 server action들을 하나로 합치면 POST 요청이 1번으로 줄어들게 된다.

export async function refreshRecordAndHomeData() {
  revalidatePath('/', 'page');
  revalidatePath('/my', 'layout');
}

두 revalidatePath 를 호출하는 함수를 추가하고, 이를 사용하도록 수정해줬다.

이전의 add POST 중복 호출이 사라진 것을 볼 수 있다.

fetch timeout 걸기

네트워크 환경이 불안정한 유저의 경우 요청이 무한정 대기 상태에 빠져 UI가 프리징되는 현상이 발생할 수 있다.

따라서 API 호출 최적화와 네트워크 타임아웃 전략을 도입해 애플리케이션의 견고함을 높이는 작업을 추가로 해주고자 했다.

우리 팀은 HTTP 메소드에 대한 유틸 함수를 따로 둬서 사용하고 있다. 공통된 유틸 함수만을 사용해서 코드 일관성을 유지하기 위함이다.

그래서 해당 유틸 함수에 타임아웃에 대한 로직을 추가해줬다.

// api.ts
async function fetchWithRetry<T>(
  url: string,
  fetchOptions: RequestInit,
  attempt: number,
  maxRetries: number,
  retryDelay: number,
  skipAuth: boolean,
  timeout: number,
) {
  const controller = timeout > 0 ? new AbortController() : undefined;
  const timeoutId = controller
    ? setTimeout(() => controller.abort(), timeout)
    : undefined;

  try {
    const response = await fetch(url, {
      ...fetchOptions,
      signal: controller?.signal,
    });

    clearTimeout(timeoutId);
    ...

이렇게 타임아웃을 위해 AbortController 를 사용하도록 수정해줬다.

그리고 error 가 발생한다면 타임아웃에 대한 에러인지를 판단해주는 코드도 추가해준다.

  // api.ts
  ...
  } catch (error) {
    clearTimeout(timeoutId);

    const err = error instanceof Error ? error : new Error('unknown error');

    // 타임아웃(AbortError) - 재시도 없이 즉시 반환
    if (err.name === 'AbortError') {
      return {
        success: false,
        data: null,
        error: {
          code: 'TIMEOUT',
          message: '요청 시간이 초과되었습니다.',
          details: {},
        },
      };
    }

    ...

AbortController : 하나 이상의 웹 요청을 취소할 수 있게 해주는 인터페이스 AbortController.abort()로 DOM 요청이 완료되기 전에 취소한다. 이를 통해 fetch 요청, 모든 응답 Body 소비, 스트림을 취소할 수 있다.

fetch 요청을 시작할 때, 요청의 옵션 객체 내부에 AbortSignal 옵션({signal})을 전달한다. 신호와 컨트롤러를 fetch 요청과 관계짓고, AbortController.abort() 를 호출해 이를 취소할 수 있게 한다.

AbortController 에 대한 공식문서 예제는 다음과 같다.

var controller = new AbortController();
var signal = controller.signal;

var downloadBtn = document.querySelector('.download');
var abortBtn = document.querySelector('.abort');

downloadBtn.addEventListener('click', fetchVideo);

abortBtn.addEventListener('click', function() {
  controller.abort();
  console.log('Download aborted');
});

function fetchVideo() {
  ...
  fetch(url, {signal}).then(function(response) {
    ...
  }).catch(function(e) {
    reports.textContent = 'Download error: ' + e.message;
  })
}

모든 브라우저에서 지원하기에 호환성도 좋다.

그리고 그 유틸 함수를 가지고 tanstack query를 사용하고 있기 때문에, tanstack query의 전역 에러 핸들러에서 이 타임아웃 작업을 진행해주면 될 것이라 생각했다.

// provider.tsx
export default function Providers({ children }: { children: React.ReactNode }) {
  // 렌더마다 새 QueryClient 생성 방지 (중요)
  const [queryClient] = useState(
    () =>
      new QueryClient({
        queryCache: new QueryCache({
          onError: (error, query) => {
            if (query.meta?.silent) return;
            if ((error as ApiError)?.code === 'TIMEOUT') {
              toast.error('요청 시간이 초과되었습니다.', {
                description: '네트워크 연결을 확인하고 다시 시도해 주세요.',
              });
              return;
            }
            const message = getErrorMessage(error);
            toast.error(message);
          },
        }),
        mutationCache: new MutationCache({
          onError: (error, variables, context, mutation) => {
            if (mutation.meta?.silent) return;
            if ((error as ApiError)?.code === 'TIMEOUT') {
              toast.error('요청 시간이 초과되었습니다.', {
                description: '네트워크 연결을 확인하고 다시 시도해 주세요.',
              });
              return;
            }
            const message = getErrorMessage(error);
            toast.error(message);
          },
        }),
        defaultOptions: {

현재는 10초로 타임아웃 시간을 지정해놨는데, 실제 fetch 요청 시간에 맞춰서 천천히 수정해야할 것 같다.

이미지를 불러올 때 다음의 과정을 통해 화면에 출력되게 된다.

1. 서버로부터 이미지 id 가져오기 (1 fetch)
2. 이미지 id로 스토리지로부터 이미지 경로 가져오기 (1 fetch)
3. 브라우저가 이미지 경로로 다운받기
4. 화면에 출력

이 과정이 각 이미지가 모두 실행되게 되어 이미지가 많은 경우 메인 스레드를 블로킹하게 되어 인터렉션이 막히는 문제가 발생했다.

그러니 화면에 표시될 이미지 로드를 최적화해 메인 스레드 블로킹 현상을 막고, 더욱 빠르게 유저에게 이미지를 보여줄 수 있도록 하는 작업이 필요하다.

추가로, sentry로 에러를 확인하고 있는데, 이미지 때문에 N + 1 문제가 발생하고 있는걸 확인해 개선이 필요함이 더욱 확실해졌다.

레이아웃과 커밋 단계에서 Long Task가 잡히는 것은 "브라우저가 화면을 그리느라 너무 바빠서 클릭을 무시한다"는 뜻

1. Nextjs Image 컴포넌트를 제대로 활용하지 못한 문제

우리는 서버로부터 이미지 관리를 분리시켰다. 스토리지에서 이미지 데이터를 관리하고, 이를 프론트에서 직접 받아와 화면에 표시한다.

스토리지로부터 받아온 경로를 그대로 사용하면 에러가 발생

스토리지로부터 받아온 이미지를 Image 컴포넌트를 사용해 출력하고자 했는데, 자꾸 에러가 발생했다.

에러가 발생하면서 이미지 자체가 로드되지 않았다. 그래서 다음의 속성을 추가해서 스토리지로부터 받아온 이미지 경로를 그대로 사용하도록 했다.

unoptimized={true}

<Image
 src={imageSrc}
 unoptimized={true}
 alt={alt}
 className={className}
 {...props}
/>

이미지 로드시 에러가 발생한 이유에 대해 정리하고 넘어가자.

먼저, Next.js가 Image 컴포넌트를 통해 이미지를 로드하고 최적화하는 방식은 다음과 같다.

1. Next.js 서버가 원본 이미지 주소로 접속한다.
2. 그리고 서버가 원본을 다운받아 브라우저 크기에 맞게 리사이징 및 WebP 변환을 시도한다.
3. 변환된 이미지를 사용자에게 전달한다.

하지만 외부 스토리지 이미지는 보안상의 이유로 Next.js가 함부로 접근할 수 없다.

만약 next.config.js 에 해당 도메인을 허용해주지 않으면, Nextjs 서버는 신뢰할 수 없는 출처의 이미지를 내가 대신 최적화해줄 수 없다며 에러를 내뱉는다.

하지만 우리는 이러한 문제를 unoptimized={true} 속성을 붙여서 해결했다. 이는 위의 Next.js 서버가 이미지를 최적화하는 과정을 건너뛰고, 원본 스토리지 URL로 직접 연결하기 때문에 해결된 것이다.

즉, unoptimized={true} 속성이 포함되어 있으면 이미지 로드시 성능에 영향을 준다.

그래서 먼저 이 문제를 해결하고자 했다. 이미지 최적화 작업을 진행하도록 하는 것만으로도 성능에 큰 도움이 줄 것이라고 생각했다.

next.config.ts 파일을 확인해보니, remotePattern 은 설정되어 있었다.

images: {
    remotePatterns: [
      ...imageDomains.map((host) => ({
        protocol: 'https' as const,
        hostname: host,
      })),
      ...
      {
        protocol: 'https',
        hostname: 'kr.object.ncloudstorage.com',
        pathname: '/**',
      },
    ],
  },

그럼에도 이미지 로드시 에러가 나는 이유를 찾아보니, 다음의 경우에도 문제가 발생한다고 한다.

• 버킷의 visibility가 public으로 되어있지 않으면, next.js 서버가 이미지를 가져와 리사이징하는 등의 작업이 불가능하다.

그러 만약 외부 스토리지를 사용하는데, 이미지 로드 에러가 발생한다면 다음 두가지를 체크해보면 된다.

• 버킷의 visibility가 public으로 되어있는가?
• next.config.js에 remotePatterns 로 스토리지 경로가 추가되어 있는가?

나의 경우는 ncp로 사용할 때는 remotePatterns 를 적용했음에도 이미지 로드시 에러가 발생했다.

그런데 OCI로 바꾸면서 이미지 로드 에러가 사라졌다.

아마 NCP로 동작할 때는 버킷의 visibility가 public이 아닌 값으로 설정되어 있던 것 같다는 추측을 해본다.

(OCI로 바꾸면서 이전의 NCP 서버 및 스토리지는 바로 삭제해버려 확인이 불가능하다.)

그래서 unoptimized 속성을 제거해줬는데, 그럼에도 webP가 아닌 png 와 같은 content-type 그대로 출력이 됐다.

스토리지로부터 받아오는 이미지가 아닌 경우는 webP로 잘 나오고 있는데, 스토리지로부터 받아오는 이미지만 최적화가 안되는 것 같았다.

webP가 아닌 content-type 그대로 다운받아 출력되는 문제

이는 pre-signed URL의 TTL(300초)이 Next.js 이미지 최적화 캐시와 충돌하고 있어 발생한 문제였다.

문제 흐름:

1. 브라우저가 /_next/image?url=<presigned-url>&w=... 요청
2. Next.js 서버가 presigned URL로 원본 이미지를 fetch
3. 그런데 presigned URL이 만료(300초)됐거나, 이미 캐시된 /_next/image 응답이 없으면 → MinIO 403 반환 → 최적화 실패 → 원본 URL로 리다이렉트
4. 브라우저가 MinIO에서 직접 PNG를 받아옴

Pre-signed URL = "미리 서명된 URL"

일반적으로 S3/MinIO 같은 오브젝트 스토리지는 비공개(private) 이다. 아무나 접근하면 안 되니까.

그런데 특정 파일을 일시적으로 공개해야 할 때, 서버가 "이 URL은 내가 허가한 거야" 라고 서명(signature)을 URL에 담아서 발급해주는 방식이 pre-signed URL이다.

이에 대한 해결 방법은 크게 두 가지이다.

• API proxy 라우트 Next.js에 /api/media-image/[id] 라우트를 만들어서 안정적인 URL을 <Image src>에 넘기는 방식. presigned URL 만료 문제 자체가 없어지고 Next.js 캐시도 제대로 작동한다.
• read용 TTL 늘리기 업로드 presigned URL은 300초가 맞지만, 조회용 URL은 훨씬 길어도 된다.

나는 이 두 방법 중에서 첫 번째 방법인 API proxy 라우트 방법을 채택했다.

가장 큰 이유는 캐시 효율이다.

pre-signed url 은 발급받을 때마다 쿼리 파라미터가 계속 바뀐다. next.js 이미지 최적화 서버는 src 문자열 전체를 캐시 키로 사용하는데, url이 매번 바뀌면 서버는 이를 완전히 새로운 이미지로 인식하게 되어 매번 새로 다운받고 실행시키게 된다.

/api/media-image/[id] 는 변하지 않는 정적 url이다. 이 방식을 쓰면 next.js 서버가 이미지를 한 번만 최적화하고 이후에는 캐시된 데이터를 즉시 반환할 수 있어서, 서버 부하가 줄어들게 될 것이다.

그리고 pre-signed url을 클라이언트에 그대로 노출시키기보단, /api/media-image/[id] 가 캡슐화 역할을 해서 안전하게 실행시키는게 나을 것이라고 생각했다.

그리고 TTL이 짧은 URL은 브라우저가 캐싱을 꺼리게 만들기 때문에, TTL을 손대기보단 라우트를 추가해 캐싱이 잘 동작하도록 하는게 더 효율적이라고 생각했다.

즉, pre-signed url의 휘발성 문제를 해결하면서도 next.js와 브라우저가 이미지를 오래 캐싱할 수 있는 환경을 만들기 위해서 API proxy 방식을 채택했다.

그래서 라우트 파일을 아래와 같이 추가해줬다.

// src/app/api/media-image/[id]/route.ts
import { auth } from '@/auth';
import { NextResponse } from 'next/server';
import sharp from 'sharp';

const backendUrl =
  process.env.NODE_ENV === 'production'
    ? process.env.NEXT_PUBLIC_PRODUCTION_API_URL
    : 'http://localhost:4000';

export async function GET(
  _request: Request,
  { params }: { params: Promise<{ id: string }> },
) {
  const { id } = await params;

  const session = await auth();
  if (!session?.accessToken) {
    return new NextResponse(null, { status: 401 });
  }

  // 백엔드에서 presigned URL 가져오기
  const urlRes = await fetch(`${backendUrl}/v1/media/${id}/url`, {
    headers: { Authorization: `Bearer ${session.accessToken}` },
  });

  if (!urlRes.ok) {
    return new NextResponse(null, { status: urlRes.status });
  }

  const body = await urlRes.json();
  const presignedUrl: string | undefined = body?.data?.url;

  if (!presignedUrl) {
    return new NextResponse(null, { status: 404 });
  }

  // presigned URL에서 원본 이미지 가져오기
  const imageRes = await fetch(presignedUrl);
  if (!imageRes.ok) {
    return new NextResponse(null, { status: imageRes.status });
  }

  const originalBuffer = Buffer.from(await imageRes.arrayBuffer());

  // WebP로 변환
  const webpBuffer = await sharp(originalBuffer).webp({ quality: 85 }).toBuffer();

  return new NextResponse(new Uint8Array(webpBuffer), {
    headers: {
      'Content-Type': 'image/webp',
      // assetId는 불변(새 파일 = 새 UUID)이므로 1년 캐시
      'Cache-Control': 'public, max-age=31536000, immutable',
    },
  });
}

흐름은 다음과 같다.

1. 브라우저 요청
2. auth 인증 확인
3. 백엔드에서 presigned url 가져오기
4. MinIO에서 원본 이미지 가져오기
5. sharp로 WebP로 변환
6. Cache-Control: immutable, 1년 캐시

sharp 라이브러리? Next.js는 기본적으로 이미지를 최적화할 때 내부적으로 squoosh 라는 라이브러리를 사용한다. 하지만 이는 JS 기반이라 속도가 느리고 기능이 제한적이다. Next.js는 sharp가 설치되어 있으면, 자동으로 이를 감지해 모든 이미지 최적화 작업(리사이징, webp 변환 등)을 sharp 에게 맡긴다.

sharp 는 C++로 작성된 libvips 라이브러리를 사용하기 때문에, 일반적인 이미지 처리 도구보다 빠르고 메모리 소모가 적다.

• 포맷 변환(webp/avif): 사용자가 png나 jpg 원본을 요청해도, 서버에서 실시간으로 sharp 를 거쳐 용량이 훨씬 작은 webp로 바꿔서 내보낸다.
• 다이나믹 리사이징: 브라우저 크기에 맞춰서 이미지를 깎아준다.

그리고 기존의 AssetImage.tsx 의 imageSrc 를 위의 라우트 경로로 수정해줬다.

// url prop이 있거나 로컬/외부 URL이면 그대로, 아니면 proxy 라우트 사용
  const imageSrc =
    url ||
    (isLocalPath || isAlreadyUrl ? assetId : `/api/media-image/${assetId}`);

  ...

  // proxy 라우트는 이미 WebP로 변환해서 반환하므로 _next/image 최적화 불필요
  const isProxyUrl = !!imageSrc?.startsWith('/api/media-image/');

  return (
    <Image
      src={imageSrc}
      alt={alt}
      className={className}
      unoptimized={isProxyUrl}
      onError={() => setHasError(true)}
      {...props}
    />
  );

• useMediaResolveSingle 제거해줬다.
  • 기존처럼 클라이언트에서 URL을 미리 resolve할 필요가 없어졌다.
• proxy URL은 unoptimized={true} 하도록 해줬다.
  • 이미 WebP 타입이므로 /_next/image 재최적화 불필요하다.

전체 흐름은 다음과 같다.

• 이전: 브라우저 → /api/media/[id]/url → presigned URL → MinIO (PNG/..) → /_next/image 최적화 실패
• 이후: 브라우저 → /api/media-image/[id] → 서버에서 변환 → WebP 응답 (1년 캐시)

개선 결과 및 효과

결과적으론 이미 불러온 이미지의 경우 다른 페이지에서 같은 이미지를 사용할 때 불필요한 네트워크 요청이 사라졌다.

또한, 초기에 이미지를 불러올 때도 content-type 그대로 다운받아 출력하는 것에서 webp로 변환해 최적화된 이미지를 출력하는 것으로 수정되었다.

2. 여러 이미지를 불러올 때의 N + 1 문제

위에서 next.js의 Image 컴포넌트를 활용하는 것으로 n + 1 문제는 부분적으로는 어느정도 개선했다고 볼 수 있다.

// 변경 전 n + 1 문제
[브라우저 JS 메인 스레드]
useMediaResolveMulti 실행
  ├─ fetch("/v1/media/id1/url") → presigned URL1 → 브라우저 이미지 다운로드
  ├─ fetch("/v1/media/id2/url") → presigned URL2 → 브라우저 이미지 다운로드
  └─ fetch("/v1/media/id3/url") → presigned URL3 → 브라우저 이미지 다운로드

이때 js fetch 가 메인 스레드에서 n번 실행되면서 인터렉션을 차단한다.

// 변경 후
[브라우저 JS 메인 스레드]
proxyUrls = mediaIds.map(id => `/api/media-image/${id}`)  ← 동기, fetch 없음
<Image src="/api/media-image/id1" />  ← 브라우저 네트워크 스택 처리 (JS 아님)
<Image src="/api/media-image/id2" />
<Image src="/api/media-image/id3" />

[서버 (Next.js)]
/api/media-image/id1 → fetch presigned URL → fetch 원본 → WebP 반환
/api/media-image/id2 → fetch presigned URL → fetch 원본 → WebP 반환
/api/media-image/id3 → fetch presigned URL → fetch 원본 → WebP 반환

수정 후에는 fetch 가 메인 스레드에서 서버로 옮겨졌기 때문에, 메인 스레드 블로킹 현상은 어느정도 개선 되었다고 볼 수 있다.

또한 캐시처리도 되었기 때문에, 초기 로드시에만 문제가 발생하고 이후론 발생하지 않을 문제이다.

추가로 Image 컴포넌트는 기본적으로 lazy loading을 하기 때문에, 스크롤로 화면에 출력해야 할 때 로드되기 때문에 한 번에 다 요청하지는 않는다.

하지만 서버 측에서의 이미지 요청 자체는 여전히 n번 발생하고 있기 때문에, 추가 개선이 필요하다.

서버 N + 1 요청 개선 배경 파악

먼저, 현재 상황의 문제점을 파악해보자. 30개가 동시 요청되면 서버에서:

• auth() × 30
• 백엔드 presigned URL 조회 × 30
• 스토리지 이미지 다운로드 × 30
• sharp WebP 변환 × 30 (CPU 집약적)

이게 여러 사용자에게 동시에 발생하면 서버 부하가 발생할 수 있다.

근본적인 n번 요청을 줄이기 위해선 mediaId 배열 → presigned Url 배열을 반환하는 batch 엔드포인트가 있어야 proxy route에서 1번 요청으로 처리할 수 있다.

그리고 우리 백엔드 팀원이 해당 엔트포인트를 이미 만들어두신 상태이다.

기존엔 단건 url 요청 엔드포인트를 사용하고 있었기 때문에, 이 여러 url 요청 엔드포인트로 수정하면 될 것이라고 판단했다.

그러니 서버 컴포넌트에서 사용해 SSR 시 presigned URL을 1번에 batch 조회하고 resolvedUrls로 내려주면, proxy route를 거치지 않고 직접 이미지를 서빙할 수 있을 것이다.

하지만 presigned url 만료(300초) 문제가 남아 있어서, hybrid 방식으로 개선하는게 안정적일 것이라고 생각했다.

• SSR 시: getMediaUrlsServer로 batch 조회 → resolvedUrls에 담아 전달 → 빠른 초기 렌더링
• 만료 후: proxy URL(/api/media-image/${id})로 fallback → 1년 캐시

개선이 필요한 페이지 SSR 컴포넌트 수정하기

이미지 조회 최적화가 필요한 페이지는 어떤게 있을지를 생각해봤다.

• 기록 리스트 출력 페이지(/my 하위, /group 하위, /shared, /)

이 외는 그리 많은 이미지를 출력하지 않기에, 부분적으로 개선해주면 될 것이라 판단했다.

서버 컴포넌트에서 데이터를 미리 prefetch 하도록 했기 때문에, 이를 활용하는 방법으로 가져가고자 했다.

그래서 prefetch 로 데이터를 먼저 로드한 뒤, 해당 데이터를 통해 이미지 url을 한 번의 api 요청으로 가져와 캐시를 갱신하는 방법을 떠올렸다.

prefetchQuery → 캐시에 레코드 데이터 저장
     ↓
getQueryData  → 캐시에서 데이터 읽기
     ↓
getMediaUrlsServer(allMediaIds)  → 백엔드 1번 호출로 URL 배치 조회
     ↓
setQueryData  → resolvedUrls 주입한 데이터로 캐시 갱신
     ↓
dehydrate → HydrationBoundary → 클라이언트 캐시 복원
     ↓
useSuspenseQuery/useQuery → 캐시 히트, resolvedUrls 있음 → proxy 호출 없이 바로 렌더링

그래서 이 로직대로 block에서 이미지 경로를 추출하는 유틸 함수와 해당 이미지 경로로 한 번에 batch api 요청을 보내는 유틸 함수를 만들어 사용해봤다.

그런데, 이미지가 출력되는 곳에서 위에서 설정해줬던 Image 최적화 로직이 실행되지 않았다. content-type 그대로 다운받아 출력되는 문제가 발생했다.

문제를 파악한 결과로는 방금 추가한 batch 조회 때문이었다.

getMediaUrlsServer가 반환하는 건 스토리지의 presigned URL (원본 PNG/JPEG)이다. resolvedUrls에 이걸 주입하면 브라우저가 proxy route를 우회해서 원본 파일을 직접 다운로드하게 된다.

resolvedUrls에 presigned URL 주입됨
     ↓
BlockContent: resolvedUrls.length > 0 → presigned URL 사용
     ↓
브라우저가 스토리지 직접 접근 → 원본 PNG
(proxy route 호출 안 함 → WebP 변환 없음)

그래서 기존의 로직도 실행되면서 batch 처리된 데이터도 활용할 수 있는 로직을 생각해봤는데, presigned url 특성상 캐시가 망가지게 되는 문제가 발생함을 파악했다.

방문 1: /_next/image?url=https://...?X-Amz-Date=20260302T120000Z&X-Amz-Signature=abc...
          → 캐시 저장 (키 = URL1)

방문 2: /_next/image?url=https://...?X-Amz-Date=20260302T130000Z&X-Amz-Signature=xyz...
          → 캐시 미스 (새 presigned URL → 다른 키)
          → 매번 새로 fetch + WebP 변환

presigned url은 요청할 때마다 서명이 달라지므로 /_next/image 캐시가 항상 미스된다. 그렇게 되면 매번 새로운 이미지로 인식해 캐시를 생성하지 못하고 매번 변환 연산을 수행하게 된다.

한 번의 batch 처리로 이미지를 로드할 수는 있지만, 캐시 처리가 되지 않는다면 매번 새로운 이미지를 다운받아 출력하는 과정이 필요하게 되니 오히려 성능에 안좋아진다.

결론적으론 presigned url + webp를 동시에 구현해도 캐시 효율이 현재 현재 proxy 방식보다 낮아지게 되면서 성능에도 영향을 받게 된다.

결과 및 정리

그래서 나는 batch로 pre-signed url을 미리 가져오는 방식 대신, 이미지 고유 id를 기반으로 하는 API proxy 경로(/api/media-image/[id])를 그대로 유지하는 방향을 선택했다.

• /api/media-image/[id] 는 시간이 지나도 변하지 않는 정적 url이다.
• next.js 캐시 시스템은 이 id르르 사용해 한 번 변환된 webp 이미지를 영구적으로 보관할 수 있다.
• 하지만 pre-signed url은 매번 캐시 미스를 유발해 최적화의 의미를 퇴색시킨다.

처음 우려했던 1번의 id 조회 → 1번의 경로 조회 문제는 id 자체를 이미지 활용함으로써 해결된다.

즉, src="/api/media-image/123" 처럼 id를 경로에 직접 포함하면, 별도의 경로 조회 api 호출 없이도 브라우저가 즉시 이미지를 요청할 수 있다.

매 요청마다 sharp 가 새롭게 webp를 생성하는 것보단, 한 번 생성된 캐시를 서빙하는게 성능 면에서 훨씬 유리하다고 판단했다.

결론적으론, 나는 네트워크 요청 횟수를 줄이기보단 요청당 효율에 집중하는 것으로 이미지 로드 최적화 작업을 마무리하기로 했다.

변경 전

[브라우저 JS 메인 스레드]

1. 서버 → assetId 수신
2. useMediaResolveMulti(assetId) → GET /v1/media/${assetId}/url → presigned URL (N번 fetch, 메인 스레드 블로킹)
3. <Image src={presignedUrl} unoptimized />
4. 브라우저 → 스토리지 직접 다운로드 → PNG 원본
5. 화면 출력 (PNG)

변경 후

[브라우저 JS 메인 스레드]

1. 서버 → assetId 수신
2. proxyUrls = assetIds.map(id => '/api/media-image/${id}') ← 동기, fetch 없음
3. <Image src="/api/media-image/${id}" unoptimized />

[브라우저 네트워크 스택 - JS 블로킹 없음]

4. GET /api/media-image/${id}

   ↓

   [Next.js Route Handler - 서버]
5. auth() 확인
6. GET /v1/media/${id}/url → presigned URL (서버-서버, 브라우저 모름)
7. presigned URL로 스토리지 이미지 fetch
8. sharp로 WebP 변환
9. Cache-Control: immutable, max-age=31536000 헤더와 함께 반환

[브라우저] 10. WebP 수신 → 1년간 HTTP 캐시 저장 11. 화면 출력 (WebP)

재방문 시: 4. GET /api/media-image/${id} → 브라우저 캐시 히트 → 요청 없음

이 상태에서 추가 성능 문제가 발생하면, 그때 다른 방법을 고려해보는게 좋을 것 같다. 아직 프론트 배포를 새로 하지 않은 상태라, 이후에 배포까지 진행하면 테스트를 다시 진행해볼 계획이다.

제가 vivaldi라는 브라우저를 사용하고 있어서 주소창에 다운 아이콘이 뜨지 않더라고요. 그래서 어떻게 다운하는지 좀 헤맸는데, 다양한 브라우저에서 지원 가능한 상태인지 추후 검증해보면 좋을 것 같습니다.

그리고 브라우저에 의존하지 않고 웹으로 접속하면 사이트 안에 앱 다운하기가 있으면 더 직관적이고 좋을 것 같습니다.

브라우저마다 install 안내창이 다르게 뜬다는 것은 몰랐기 때문에, 수정이 필요해보였다.

다운하지 않은 유저에겐 웹 상단에 설치하기 버튼 혹은 설치 방법 안내 메시지를 두는게 좋을 것 같아서, 그대로 적용해보려고 한다.

유저에게 설치 안내 배너 띄워주기

먼저, 유저 입장에서 봤을 때 웹앱을 설치할 수 있는지조차 모르는 경우가 많을 것 같았다. 보통 주소창에 뜨는 아이콘들은 잘 보지 않기 때문이다.

그래서 다음을 고려해줬다.

• 서비스 상단에 배너로 이 웹은 앱으로 설치가 가능함을 알리기
• 설치하고 싶지 않은 유저를 위해, 배너 닫기 기능 지원하기
• 배너를 클릭하면 설치 창이 뜨도록 하기

첫 번째로 UI 적인 배너는 다음처럼 만들었다.

배너를 굳이 닫지 않아도 서비스 이용에 불편함이 없도록, fix로 두지 않고 스크롤을 내렸을 때 헤더에 의해 가려지게 했다.

설치 안내창을 지원하지 않는 브라우저 고려하기

이 문제를 나만 고민하는 것은 아니라고 생각하고, 인터넷을 찾아봤다.

그러다 beforeinstallprompt 를 알게 되었고, 이를 사용하면 될 것 같았다.

beforeinstallprompt

MDN 공식문서

beforeinstallprompt 이벤트는 브라우저가 웹사이트를 프로그레시브 웹앱(PWA)로 설치할 수 있음을 감지했을 때 발생한다.

• 이벤트가 발생하는 정확한 시점은 보장되지 않지만, 일반적으로 페이지 로드 시에 발생한다고 한다.
• 웹 앱이 브라우저에게 제공하는 일반적인 UI 대신, 자체 앱 내 UI를 통해 사용자에게 앱 설치를 유도하고자 할 때 사용한다.

사용자가 앱 내의 설치 UI를 사용해서 앱을 설치할 때, 앱 내 설치 UI는 prompt() 로 BeforeInstallPromptEvent 를 호출해 설치 프롬프트를 표시한다.

addEventListener("beforeinstallprompt", (event) => { })

onbeforeinstallprompt = (event) => { }

• BeforeInstallPromptEvent.platforms

이벤트가 발생한 플랫폼을 나타내는 문자열 배열을 반환한다.

사용자에게 ‘웹’ 또는 ‘플레이’와 같은 버전 선택지를 제공해 사용자가 웹 버전 또는 안드로이드 버전 중에서 선택할 수 있도록 한다.

• BeforeInstallPromptEvent.userChoice

앱 설치를 요청받았을 때 사용자가 선택한 내용을 설명하는 객체를 반환한다.

• BeforeInstallPromptEvent.prompt()

앱을 설치할지 사용자에게 묻는 메시지를 표시한다.

<button id="install" hidden>Install</button>

let installPrompt = null;
const installButton = document.querySelector("#install");

window.addEventListener("beforeinstallprompt", (event) => {
  event.preventDefault();
  installPrompt = event;
  installButton.removeAttribute("hidden");
});

버튼을 클릭하면 앱의 설치 버튼이 나타난다.

하지만, 이 이벤트를 지원하지 않는 브라우저가 있기 때문에 지원하지 않는 브라우저도 함께 고려해줘야 한다.

그래서 두 경우로 나눠서 지원하기로 했다.

• 이벤트를 지원하는 경우 브라우저 기본 설치 안내창 띄우기
• 이벤트를 지원하지 않는 경우 모달로 어떻게 설치하는지 방법 띄우기

배너 클릭하면 설치 안내창 혹은 모달로 방법 알려주기

나는 웹의 상단에 표시되는 배너를 클릭하면 동작되게 하고자 했다.

그러기 위해선, root layout에 배너를 띄워줘야 한다.

// src/app/layout.tsx

return (
  ...
  <ThemeColorSetter />
      <div className="flex flex-col min-h-screen w-full mx-auto shadow-2xl max-w-4xl relative transition-colors duration-300 dark:bg-[#121212] dark:text-white bg-white text-itta-black">
        <PWAInstallBanner />
        <ConditionalHeader />
        ...

이렇게 하고 배너 컴포넌트를 만들어보자.

먼저, 이 서비스가 설치한 앱으로 표시되는건지, 웹으로 표시되고 있는 것인지를 판단해야 한다.

  // src/components/PWAInstallBanner.tsx
  useEffect(() => {
    // 이미 설치되었는지 확인
    if (window.matchMedia('(display-mode: standalone)').matches) {
      requestAnimationFrame(() => {
        setIsInstalled(true);
      });
      return;
    }

    // 배너를 닫은 적이 있는지 확인
    const dismissedUntil = localStorage.getItem('pwa-banner-dismissed-until');
    if (dismissedUntil && Date.now() < parseInt(dismissedUntil)) {
      return;
    }

    // beforeinstallprompt 이벤트 리스너
    const handler = (e: Event) => {
      e.preventDefault();
      setDeferredPrompt(e as BeforeInstallPromptEvent);
      setShowBanner(true);
    };

    window.addEventListener('beforeinstallprompt', handler);

    // beforeinstallprompt를 지원하지 않는 브라우저
    // (Safari, Vivaldi 등) - 바로 배너 표시
    const timeout = setTimeout(() => {
      if (!deferredPrompt) {
        setShowBanner(true);
      }
    }, 1000);

    return () => {
      window.removeEventListener('beforeinstallprompt', handler);
      clearTimeout(timeout);
    };
  }, [deferredPrompt]);

나는 pwa를 standalone으로 설정해줬기 때문에, matchMedia 를 standalone 으로 파악해줬다.

일치하는게 있다면 설치한 앱으로 실행시키고 있는 것이니, 배너를 보여줄 필요가 없다. 그렇지 않다면, 만약 유저가 배너를 닫았는지를 localStorage 로 판단해준다.

나는 하루를 기준으로 배너를 숨겨주기로 했다. 나머지는 beforeinstallprompt 이벤트를 등록하고 언마운트시에 해제해주는 로직이다.

const timeout = setTimeout(() => {
      if (!deferredPrompt) {
        setShowBanner(true);
      }
    }, 1000);

이 부분은 safari나 vivaldi와 같은 브라우저는 beforeinstallprompt를 지원하지 않기에, 모달을 띄워주기 위한 상태 업데이트 로직이다.

  // src/components/PWAInstallBanner.tsx
  const handleInstallClick = async () => {
    // Chrome/Edge 등에서 기본 프롬프트 지원하는 경우
    if (deferredPrompt) {
      try {
        await deferredPrompt.prompt();
        const { outcome } = await deferredPrompt.userChoice;

        if (outcome === 'accepted') {
          setIsInstalled(true);
        }

        setShowBanner(false);
        setDeferredPrompt(null);
      } catch (error) {
        console.error('PWA 설치 실패:', error);
      }
    } else {
      // 프롬프트를 지원하지 않는 브라우저 (Safari, Vivaldi 등)
      // 커스텀 안내 모달 표시
      setShowInstructions(true);
    }
  };

유저가 배너를 클릭하게 되면 프롬프트를 지원하는 브라우저에선 기본 설치 안내창을 띄워주도록 했다.

그렇지 않다면 설치 안내 모달을 띄워주도록 한다.

  // src/components/PWAInstallBanner.tsx
  const handleClose = () => {
    setShowBanner(false);
    // 1일 동안 배너 숨김
    const dismissedUntil = Date.now() + 1 * 24 * 60 * 60 * 1000;
    localStorage.setItem(
      'pwa-banner-dismissed-until',
      dismissedUntil.toString(),
    );
  };

  if (isInstalled || !showBanner) {
    return null;
  }

배너를 닫고자 할 때는 localStorage에 시간과 함께 저장해준다.

// src/components/PWAInstallBanner.tsx
// 브라우저 감지
  const userAgent = typeof navigator !== 'undefined' ? navigator.userAgent : '';
  const isIOS = /iPad|iPhone|iPod/.test(userAgent);
  const isSafari = /Safari/.test(userAgent) && !/Chrome/.test(userAgent);
  const isMacOS = /Macintosh|MacIntel|MacPPC|Mac68K/.test(userAgent);

브라우저마다 다르게 안내창을 띄워야 하므로, 브라우저를 알아내야 한다.

navigator 에서 userAgent 로 파악이 가능하길래, 이를 활용해줬다.

MDN 공식문서 - navigator.userAgent

맥북과 같은 노트북/데스크탑은 아이폰과 설치 방법이 달라서 다르게 지원하기 위해 ios, safars, macos를 구분해줬다.

마지막으로 렌더링할 부분(컴포넌트)를 작성해주면 된다. 이는 프로젝트마다 다를 것이니 다루지 않겠다!

참고 자료

• https://velog.io/@votogether2023/프로그레시브-웹-앱PWA이란-인앱-설치를-묻는-화면-구현하기-feat.beforeinstallprompt
• https://developer.mozilla.org/en-US/docs/Web/API/Window/beforeinstallprompt_event
• https://developer.mozilla.org/en-US/docs/Web/API/Navigator/userAgent

그렇기에 우리 팀은 웹 기반이면서 어플로도 변환할 수 있는 pwa를 사용해 웹앱을 지원하기로 했다.

pwa web-app을 지원하는 과정과 그 안에서 고민했던 점들을 정리해봤다.

Next.js를 사용해 PWA 구축하기

PWA: progressive web application

PWA는 웹 애플리케이션의 접근성과 활용성을 갖추면서, 네이티브 모바일 앱의 기능과 사용자 경험을 제공한다.

다음과 같은 이점이 있다.

• 앱 스토어 승인을 기다릴 필요 없이 즉시 업데이트 배포 가능
• 단일 코드베이스로 크로스 플랫폼 애플리케이션 개발
• 홈 화면 설치 및 푸시 알림과 같은 네이티브 앱과 유사한 기능 제공

1. 웹 애플리케이션 manifest, viewport/metadata 생성

Next.js는 App Router를 사용해 웹앱 매니페스트를 생성하는 기능을 기본적으로 제공한다.

app/manifest.ts 또는 app/manifest.json 파일을 만들어서 웹앱 설정을 할 수 있다.

// app/manifest.ts
import type { MetadataRoute } from 'next'

export default function manifest(): MetadataRoute.Manifest {
  return {
    name: 'Next.js PWA',
    short_name: 'NextPWA',
    description: 'A Progressive Web App built with Next.js',
    start_url: '/',
    display: 'standalone',
    background_color: '#ffffff',
    theme_color: '#000000',
    icons: [
      {
        src: '/icon-192x192.png',
        sizes: '192x192',
        type: 'image/png',
      },
      {
        src: '/icon-512x512.png',
        sizes: '512x512',
        type: 'image/png',
      },
    ],
  }
}

• display: 웹 애플리케이션의 기본 표시 모드 지정. 표시 모드는 운영체제 컨텍스트 내에서 앱이 실행될 때 사용자에게 표시되는 브라우저 UI의 범위를 결정
  • fullscreen: 브라우저 UI 요소를 숨기고 사용 가능한 전체 화면 영역을 활용해 앱을 연다. 브라우저 컨트롤어 보이지 않고, 전체 화면을 차지해 완벽한 몰입형 게임 환경을 제공하는 게임 앱에 사용할 수 있다.
  • standalone: 앱을 마치 독립형 네이티브 앱처럼 보이도록 연다. 앱이 별도의 창으로 표시되고 앱 실행기에 자체 아이콘이 포함된다. 브라우저는 URL 표시줄과 같은 UI 요소를 제외하지만 상태 표시줄과 같은 다른 UI 요소는 포함할 수 있다. (브라우저의 URL 표시줄은 없지만 기기의 배터리와 알림 상태 표시줄은 그대로 표시)
  • minimal-ui: 앱을 독립 실행형 앱처럼 열되, 탐색을 위한 최소한의 UI 요소만 표시. 일반적으로 뒤로, 앞으로, 새로고침과 같은 탐색 컨트롤과 앱 URL을 표시하는 기능이 포함된다.
  • brower: 앱을 플랫폼별 링크 열기 규칙에 따라 일반 브라우저 탭 또는 새 창에서 연다. display 모드가 지정되지 않은 경우 이 값이 기본값.
• background_color: 앱의 창 배경색
  • 앱의 스타일시트가 로드되기 전에 애플리케이션 창에 표시되는 색상을 정의한다. 즉, 스타일시트가 로드되기 전에 나타나므로, 애플리케이션 스타일시트의 CSS 속성 색상 값과 동일하게 설정해야 시각적 전환이 원활해진다.

Next.js 13버전부턴 Metadata API가 나오면서 <head> 태그를 건드리지 않아도 됐다. layout.tsx 나 page.tsx 에서 metadata 객체만 내보내면 Next.js가 빌드 및 런타임 시점에 알아서 최적화된 <head> 태그를 구성해준다.

Next.js 13버전 이전까지는 위처럼 meta 태그를 직접 넣어줘야 했는데, 13버전 이후부턴 meta 객체만 선언해주면 된다.

추가로 14버전부터는 metadata 객체 안에 있던 themeColor, viewport 같은 속성들이 별도의 viewport 객체로 분리되었다.

그래서 두 객체를 같이 작성해줘야 한다.

// src/app/layout.tsx
export const viewport: Viewport = {
  width: 'device-width',
  initialScale: 1,
  minimumScale: 1,
  viewportFit: 'cover',
};

export const metadata: Metadata = {
  title: {
    default: '잇다-',
    template: '%s - 잇다-',
  },
  description: '기억과 맥락을 이어주는 기록 서비스',
  manifest: '/manifest.webmanifest',
  icons: {
    icon: '/web-app-icon-192x192.png',
    apple: '/apple-icon.png',
  },
};

export default function RootLayout({
...

viewport/metadata vs manifest.ts

여기서, metadata/viewport랑 manifest.ts랑 무슨 차이가 있는걸까?

metadata/ viewport 는 브라우저(탭)을 위한 것이고, manifest.ts 는 설치될 앱을 위한 것이다.

• viewport: ‘이 화면을 모바일 크기에 맞춰서 그려줘’, ‘주소창 색은 이걸로 해줘' 같은 실시간으로 브라우저 창에 명령을 내리기 위해 사용
• metadata: ‘이 페이지의 제목은 XX야’, ‘검색 결과에 어떻게 나와야 헤’와 같은 SEO와 공유 시 미리보기(openGraph)를 담당

위 두 사항은 페이지를 이동할 때마다 바뀔 수 있다.

• manifest.ts: 사용자가 ‘홈 화면에 추가’ 버튼을 눌러서 앱을 설치할 때만 주로 참조되는 파일

‘설치된 후 앱 아이콘 모양은?’, ‘앱을 켰을 때 가로모드로 고정할까?’, ‘스플래시 화면 배경색은 뭐야?’와 같은 앱의 설정 내용을 결정한다.

한 번 설치되면 잘 바뀌지 않는 앱의 정체성을 규정하고, 브라우저 탭 안에서 돌아갈 때는 manifest 의 설정보다 HTML 헤더의 metadata 설정이 우선순위를 갖는 경우가 많다.

둘 중 하나만 있으면 사용자 경험이 어딘가 깨지게 되기에, 웹앱을 지원하기 위해선 둘 모두 설정하는 것이 중요하다.

유저의 입장에서 봤을 때, 다음의 시나리오를 생각하면 된다.

1. 카톡으로 링크 공유: 이때 드는 제목과 사진은 metadata 가 결정
2. 브라우저로 접속 중: 주소창 색상이 바뀌는 건 viewport 의 themeColor 덕분
3. 홈 화면에 추가: 이때 폰에 생기는 아이콘 모양과 이름은 manifest 에서 가져옴
4. 설치된 앱 실행: 이때 뜨는 스플래시 화면과 앱 전송 UI는 manifest 설정 값

여기까지 해주면 웹앱 설치와 설정은 끝났다.

하지만 테마를 지원한다면, 테마에 맞춰 앱의 주소창 배경색을 동적으로 수정시켜줘야 한다.

테마에 맞춰 앱의 창 배경색 설정하기

나는 다크모드/라이트모드를 지원하고 있으며, 유저가 지정한 테마에 맞춰 창 배경색을 지정하고 싶었다.

manifest.ts 는 빌드 타임에 생성되기 때문에, 런타임에 유저가 버튼을 눌러 바꾸는 tailwind의 테마 상태를 실시간으로 반영하기는 어렵다.

브라우저와 OS 수준에서 지원하는 시스템 테마 설정을 활용하거나, HTML Meta Tag를 병용해서 다크모드/라이트모드에 대응하는 방법이 있다.

layout.tsx 나 index.html 에 다음의 코드를 추가해준다.

<head>
  <meta name="theme-color" content="#ffffff" media="(prefers-color-scheme: light)">
  <meta name="theme-color" content="#0f172a" media="(prefers-color-scheme: dark)">
</head>

하지만 Next.js 13버전부턴 Metadata API가 나오면서 <head> 태그를 건드리지 않아도 됐다. layout.tsx 나 page.tsx 에서 metadata 객체만 내보내면 Next.js가 빌드 및 런타임 시점에 알아서 최적화된 <head> 태그를 구성해준다.

즉, 위에서 설정한 부분은 그대로 가져가면 된다.

우리는 metadata 를 통해서 head에 추가된 저 meta 태그를 동적으로 수정해주면 된다.

테마를 지원한다면, 테마 토글 버튼이 있을테니 그 부분은 넘어가고 어떻게 주소창 배경색을 바꾸는지만 정리하겠다.

metadata 는 매 페이지마다 다르게 html에 들어가기 때문에, 전역적으로 테마를 알아내서 적용시켜줘야 한다.

그러니, layout.tsx 파일에서 테마를 설정하는 컴포넌트를 추가해주자.

// src/app/layout.tsx
import ThemeColorSetter from '@/components/ThemeColorSetter';

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  ...
  <body
    className={`${notoSans.variable} antialiased relative`}
    suppressHydrationWarning
  >
    <Script
      src={`https://maps.googleapis.com/maps/api/js?key=${process.env.NEXT_PUBLIC_GOOGLE_MAPS_API_KEY}&libraries=places`}
      strategy="beforeInteractive"
    >
    <Providers>
      <MswLoader />
      <ThemeProvider
        attribute="class"
        enableSystem={true}
        defaultTheme="system"
      >
        <ThemeColorSetter /> <- 여기!
        ...

이제 ThemeColorSetter 컴포넌트를 만들어주자.

// src/components/ThemeColorSetter.tsx
'use client';

import { useTheme } from 'next-themes';
import { useEffect, useState } from 'react';

export default function ThemeColorSetter() {
  const { resolvedTheme } = useTheme();
  const [mounted, setMounted] = useState(false);

  useEffect(() => {
    // React 19의 cascading renders 에러 방지를 위한 지연 처리
    const raId = requestAnimationFrame(() => {
      setMounted(true);
    });
    return () => cancelAnimationFrame(raId);
  }, []);

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

    const color = resolvedTheme === 'dark' ? '#121212' : '#ffffff';
    const metaThemeColors = document.querySelectorAll(
      'meta[name="theme-color"]',
    );

    if (metaThemeColors.length > 0) {
      metaThemeColors.forEach((meta) => {
        if (meta.getAttribute('content') !== color) {
          meta.setAttribute('content', color);
        }
      });
    } else {
      const meta = document.createElement('meta');
      meta.name = 'theme-color';
      meta.content = color;
      document.head.appendChild(meta);
    }
  }, [resolvedTheme, mounted]);

  return null;
}

위처럼 동적으로 meta 태그의 속성을 바꿔줘야 한다.

마운트가 되기 전에는 meta 태그에 접근했을 때 undefined 가 뜰 수 있기 때문에, 안전하게 수정되도록 마운트 후에 수정되도록 해주었다.

이제 동적으로 주소창도 테마 색상을 바꾸는 것은 끝났다. 하지만 한 가지 더 고려해줘야 하는게 있다.

테마 색상은 localStorage 에서 테마 색상을 꺼내오는 로직이기 때문에, 앱 실행과 테마 값을 불러오는 그 사이 지연시간이 있다.

그 동안은 manifest 에서 설정해준 색상으로 주소창 색상이 결정된다. 유저는 설정한 테마 색상이 아닌 다른 테마 색상이 나왔다가 바뀌는 모습을 지켜보게 된다.

마지막으로 이를 보완해보자.

앱 로딩시에도 테마 색상이 적용되도록 수정

현재 문제인건 ThemeColorSetter 는 클라이언트 컴포넌트이기 때문에, 브라우저가 HTML 파일을 내려받고 자바스크립트를 해석해서 실행하기 전까지는 주소창이 어떤 색이어야 할지 모르는 상태이다.

그래서 Next.js가 기본으로 렌더링한 초기값이 잠깐 보였다가 자바스크립트가 실행된 후에야 색이 바뀌는 것이다.

이를 해결하기 위해 자바스크립트가 로드되길 기다리지 않고, HTML이 읽히자마자 즉시 실행되는 인라인 스크립트를 삽입해야 한다.

layout.tsx 의 <head> 안에 테마를 확인하고 즉시 메타 태그를 수정하는 스크립트를 넣으면 해결된다.

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="ko" suppressHydrationWarning>
      <head>
        {/* 테마 깜빡임을 방지하기 위한 인라인 스크립트 */}
        <script
          dangerouslySetInnerHTML={{
            __html: `
              (function() {
                try {
                  const theme = localStorage.getItem('theme');
                  const supportDarkMode = window.matchMedia('(prefers-color-scheme: dark)').matches;
                  const isDark = theme === 'dark' || (theme === 'system' && supportDarkMode) || (!theme && supportDarkMode);
                  const color = isDark ? '#121212' : '#ffffff';

                  // 메타 태그 생성 또는 수정
                  let meta = document.querySelector('meta[name="theme-color"]');
                  if (!meta) {
                    meta = document.createElement('meta');
                    meta.name = 'theme-color';
                    document.head.appendChild(meta);
                  }
                  meta.setAttribute('content', color);

                  // 시스템 배경색과 일치시키기 위해 <html> 클래스도 미리 제어
                  if (isDark) {
                    document.documentElement.classList.add('dark');
                  } else {
                    document.documentElement.classList.remove('dark');
                  }
                } catch (e) {}
              })();
            `,
          }}
        />
      </head>
      <body className="...">
        {/* ... 기존 내용 */}
      </body>
    </html>
  );
}

body 가 렌더링되기 전, 즉 HTML 헤더를 읽는 즈시 스크립트가 실행되기 때문에 컴포넌트가 마운트될 때가지 기다릴 필요가 없다.

성능적으론 짧은 순수 자바스크립트이기 때문에, 성능 저하 거의 없이 문제를 해결할 수 있다.

pwa를 지원하면서 유저가 어떻게 이 웹을 다운받아 어플로 사용할 수 있는지 모를 수도 있다. 이를 위해서 브라우저별로 어떻게 다운받는지를 알려주기 위해 추가 작업을 진행했다. 이에 대해서는 다음 포스트에서 다룬다.

참고 자료

• Next.js 공식문서 ‘Next.js를 사용하여 프로그레시브 웹 애플리케이션(PWA)을 구축하는 방법’
• MDN 공식문서
• https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/categories
• https://realfavicongenerator.net/your-favicon-is-ready

그룹 프로젝트를 진행하면서 하이드레이션 에러를 정말 많이 마주했는데, 어떤 문제이고 어떻게 해결하는지를 정리하면 나중에 보기 편할 것이라 생각해서 정리해봤다.

서버와 클라이언트의 렌더링 불일치

서버 사이드에서 받은 HTML이 클라이언트 사이드에서 렌더링한 HTML이 다를 때 hydration 에러가 발생하게 된다.

하이드레이션(hydration)

Next.js 공식문서: React가 서버에서 미리 렌더링된 HTML을 이벤트 핸들러를 연결하여 완전한 상호작용 애플리케이션으로 변환하는 단계입니다.

1. 서버 사이드 렌더링: 서버에서 HTML 생성 후 클라이언트에 전송하는 과정
2. 클라이언트 사이드 하이드레이션: 클라이언트 측에서 React가 이 HTML을 받아서 DOM을 분석하고 이를 기반으로 virtual DOM을 생성, 이벤트 핸들러 추가 등의 작업을 수행하는 과정

하이드레이션은 SEO에 친화적이며 초기 로딩 속도를 줄여 사용자에게 빠르게 웹페이지를 제공할 수 있다는 장점이 있다.

하이드레이션 에러의 일반적인 원인

• HTML 태그의 잘못된 중첩
• 렌더링 로직에서 typeof window !== 'undefined 사용
• 렌더링 로직에서 브라우저 전용 API (ex localStorage) 사용
• 렌더링 로직에서 Date() 생성자와 같은 시간 API 사용

hydration mismatch 해결 방법

• useEffect 로 클라이언트에서만 실행하도록 설정

보통은 하이드레이션 에러를 해결하기 위해 useEffect 를 사용한다. 마운트된 이후 작업을 하도록 렌더링을 지연시키는 것이다.

import { useState, useEffect } from 'react'

export default function App() {
  const [isClient, setIsClient] = useState(false)

  useEffect(() => {
    setIsClient(true)
  }, [])

  return <h1>{isClient ? 'This is never prerendered' : 'Prerendered'}</h1>
}

하지만 useEffect 는 마운트 즉시 호출되는 훅이 아니기 때문에 DOM에 마운트 된 후 임의의 시간이 지나 호출된다.

그래서 useEffect 로 hydration mismatch를 해결하게 되면 일부 UI가 깜빡거리는 현상을 마주하게 될 수 있다.

• 특정 컴포넌트에서 SSR 비활성화

동적 import로 컴포넌트를 불러올 때, SSR을 비활성화해 하이드레이션 불일치 문제를 방지할 수 있다.

import dynamic from 'next/dynamic'

const NoSSR = dynamic(() => import('../components/no-ssr'), { ssr: false })

export default function Page() {
  return (
    <div>
      <NoSSR />
    </div>
  )
}

• suppressHydrationWarning

React에서 제공하는 플래그로, hydration mismatch에 따른 에러를 무시하게 해준다(억제 해준다.)

텍스트 콘텐츠로 인해 발생하게 된 하이드레이션 불일치 문제를 억제해준다.

<html lang="en" suppressHydrationWarning={true}>

Next.js 공식문서에서 너무 자주 사용하지 말라는 말이 있었기에, 불가피하게 서버와 클라이언트 간에 콘텐츠가 달라지는 경우만 사용해야한다.

• 현재 시간 표시: 서버 시간과 클라이언트 사용자 시간이 다를 때
• 브라우저 고유 정보: localStorage 의 데이터를 기반으로 초기 UI가 결정될 때
• 랜덤 숫자: Math.random() 을 초기 렌더링에 사용할 때

이유는 성능, UX, 잠재적 버그와 직결되기 때문이다.

suppressHydrationWarning 은 근본적인 원인을 해결하는 것이 아니라 경고만 끄는 것이다.

만약 불일치가 복잡한 DOM 구조에서 발생하면, React가 실제 DOM을 다시 맞추는 과정에서 기존 HTML을 다 날리고 처음부터 다시 렌더링해야 할 수도 있다.

이 경우 경고는 안뜨지만, 실제로는 보이지 않는 성능 저하가 계속 발생하게 되는 셈이다.

또한 공식문서에 따르면 해당 요소 바로 아래 텍스트나 속성에만 적용되기 때문에 만약 깊은 자식 컴포넌트까지 불일치가 전파되고 있다면, 최상위 태그에 플래그를 달아도 하위 요소에서 발생하는 모든 문제를 완벽하게 방어해주지 못한다.

즉, 사용한다고 해서 모든 하이드레이션 불일치 문제가 해결되는 것은 아니다.

참고 자료

• https://velog.io/@page1597/하이드레이션-불일치-경고
• https://medium.com/@jiwoochoics/어쩔-수-없는-hydration-mismatch를-useeffect없이-해결하기-c984c9120f9b
• https://nextjs.org/docs/messages/react-hydration-error

네부캠 그룹 프로젝트 마감 기한이 빡빡해서, 포스팅할 시간이 없었다. 지금부터 조금씩 정리했던 내용들을 포스팅하려고 한다.

우리 팀은 '잇다-' 라는 서비스를 만들고 있다. github

개인의 기록을 넘어, 함께 만드는 추억을 위한 기록 서비스

기록 어플은 시중에 나와있는 서비스가 정말 많다. 나는 그 많은 서비스 중에서 유저의 유입을 고려한다면 디자인이 가장 중요하다고 생각했다.

나만 봐도, 디자인이 별로면 아무리 기능이 뛰어나도 바로 삭제한다. 그래서 디자인적으로 고민을 많이 했고, 다크 모드를 많이 사용하는 사람으로서 다크모드도 넣는게 좋을 것 같았다.

그래서 이번엔 다크모드를 지원하는 과정을 포스팅하려고 한다.

배경

tailwind에서 다크/라이트 모드를 제공하는 방법은 간단하다. class 에 dark:* 로 다크모드일 때의 스타일을 지정해주면 된다.

<span className="dark:text-gray-200 text-itta-black">
  다크 모드
</span>

그리고 다크 모드로 제공하고자 할 때는 html 태그의 class 에 dark 를 추가해주면 된다.

<html lang="ko" className="dark">

html 태그에 해당 class가 존재하냐에 따라 테마를 다르게 지원할 수 있다. 물론 tailwind 버전에 맞게 class로 테마를 설정하는 코드를 작성해줘야 할 수도 있다.

@import "tailwindcss";
@custom-variant dark (&:where(.dark, .dark *));

이 부분은 공식문서를 참고하면 좋을 것 같다.

여기에서 고려해줘야 할 부분이 있다. 매번 html 태그에 dark 를 수동으로 추가해줄 순 없기 때문에, 스크립트를 작성해줘야 한다.

유저가 어떤 페이지에 접근하는지 알 수 없기 때문에, 모든 페이지를 고려해 테마 설정은 Context API 를 주로 사용한다.

또한 새로고침을 해도 테마가 유지되어야 하기에 localStorage 와 같은 스토리지에 테마 값을 저장한다.

테마가 적용되는 흐름은 다음과 같다. (next 기준)

• 서버: HTML을 생성
• 브라우저: HTML 로드
  • React hydration
  • Context에서 localStorage 읽음
  • 테마 적용

이 과정에서 문제가 발생하게 된다.

HTML 로드와 테마 적용 사이에 시간차가 발생하면서 화면이 깜빡이게 된다. 네트워크 지연 혹은 성능이 좋지 않은 디바이스에선 더 두드러질 것이다.

이 문제를 해결하는 방법 중 하나는 blocking script 를 사용하는 것이다.

    <html>
      <head>
        <script dangerouslySetInnerHTML={{
          __html: `
            (function() {
              try {
                const theme = localStorage.getItem('theme');
                if (theme === 'dark') {
                  document.documentElement.classList.add('dark');
                }
              } catch (e) {}
            })();
          `
        }} />
      </head>
      <body>
        <ThemeProvider> {/* Context API */}
          {children}
        </ThemeProvider>
      </body>
    </html>

blocking script 는 React가 로딩되기 전, HTML 파싱 중 즉시 실행되며 React hydration을 기다리지 않는다.

그렇기에 <html> 태그에 바로 dark 클래스를 추가할 수 있어 깜빡임 문제를 개선할 수 있다.

직접 구현하는 것도 충분히 가능하지만, blocking script 로직과 여러 예외 처리를 직접 작성해줘야 한다.

또한 localStorage 에서 값을 가져오고 저장하는 로직도 추가로 작성해줘야 한다.

이런 번거로움을 줄이고자 next 테마를 설정하도록 지원해주는 라이브러리가 있는데, 그게 next-themes 이다. 번들 사이즈도 약 1.5kB로 작기 때문에, 시간과 안정성 측면에서 활용하는게 좋을 것 같다고 판단했다.

출처

next-themes

Next.js에서 다크모드를 비롯한 테마 변경을 쉽게 구현할 수 있도록 하는 라이브러리

클라이언트 측에서 localStorage 또는 class 속성을 사용해 테마를 적용하고 유지하도록 지원한다.

주요 기능 및 이점

• useTheme() 훅을 사용해 테마를 간편하게 변경할 수 있음
• 사용자가 선택한 테마를 localStorage로 유지
• class 기반 테마를 지원해 tailwindCSS를 활용할 때 유용
• system 옵션을 사용해 사용자의 OS 테마 설정에 따라 자동으로 테마가 적용되도록 할 수 있음

사용법

참고자료

pnpm install next-themes

이제 layout에서 ThemeProvider 를 사용할 수 있으며, 이를 통해서 서비스 전체의 테마 색상을 변경할 수 있다.

ThemeProvider 는 서버 컴포넌트가 아닌 클라이언트 컴포넌트이다. 하지만 Provider 하위의 모든 컴포넌트가 CSR로 바뀌는 것은 아니다. 서버에서 ThemeProvider 포함 전체 HTML을 SSR에서 생성하고, 브라우저에서 해당 HTML을 받아 hydration 과정을 거치게 된다.

layout.tsx 파일을 다음과 같이 수정해준다.

import { ThemeProvider } from  "next-themes" ; 

export  default  function  RootLayout ( { 
  children, 
}: Readonly<{ 
  children: React.ReactNode; 
}> ) { 
  return ( 
    <html lang = "en" suppressHydrationWarning> 
      <body className = {`${ geistSans.variable} antialiased`}> 
        <ThemeProvider attribute="class" enableSystem={true} defaultTheme="system">
           {children} 
        </ThemeProvider > 
      </body > 
    </html >
   ); 
}

suppressHydrationWarning 속성을 추가하지 않으면 next-themes element가 업데이트될 때 경고가 표시된다.

서버 컴포넌트 환경에서 클라이언트가 테마를 결정하며 속성을 바꿀 때 발생하는 불일치 경고를 해결하기 위함이다.

특히 다크 모드처럼 클라이언트에서만 확정되는 값이 HTML 속성(class)에 반영될 때 자주 발생

한 단계 깊이까지만 적용되기 때문에, 다른 element의 hydration 경고는 차단하지 않는다.

• enableSystem={true}
  • 사용자의 운영 체제를 자동으로 감지할 수 있다. 사용자가 시스템을 다크 모드 또는 라이트 모드로 설정한 경우, next-themes 가 테마를 시스템 설정에 맞게 조정한다.
• defaultTheme="system"
  • 사용자 시스템에 설정된 테마가 기본 테마로 사용됨을 나타낸다. 다른 테마가 지정되지 않은 경우, 기본적으로 시스템 테마를 사용한다.
• attribute="class"
  • 테마 정보를 HTML의 어떤 속성(attribute)에 기록할지 결정한다.
  • next-themes 가 테마를 바꿀 때마다 <html> 태그에 <html class="dark"> 또는 <html class="light"> 를 자동으로 넣어준다.

테마에 맞는 적절한 색상을 지정하고 싶을 땐 .global.css 파일을 적절히 수정하면 된다.

나는 class 로 테마를 수정하므로 다음과 같이 설정해줬다. (기본)

@custom-variant dark (&:is(.dark *));

이제 테마를 변경하는 토글 버튼을 추가하자

import { useTheme } from 'next-themes';
import { cn } from '@/lib/utils';
import { useState, useEffect } from 'react';

export default function Setting() {
  const router = useRouter();
  const { theme, setTheme, resolvedTheme } = useTheme();
  const [mounted, setMounted] = useState(false);

  useEffect(() => {
    // React 19의 cascading renders 에러 방지를 위한 지연 처리
    const raId = requestAnimationFrame(() => {
      setMounted(true);
    });
    return () => cancelAnimationFrame(raId);
  }, []);

  // Hydration 불일치를 방지하기 위해 마운트되기 전에는 아무것도 렌더링하지 않음
  if (!mounted) {
    return null;
  }

  const toggleDarkMode = () => {
    setTheme(theme === 'dark' ? 'light' : 'dark');
  };

  const currentTheme = resolvedTheme;

  return (
    <div className="flex items-center justify-between">
      <div className="flex items-center gap-3">
        <div className="p-2 rounded-lg transition-colors dark:bg-purple-500/10 dark:text-purple-400 bg-yellow-50 text-yellow-500">
          {currentTheme === 'dark' ? (
            <Moon className="w-4 h-4" />
          ) : (
            <Sun className="w-4 h-4" />
          )}
        </div>
        <span className="text-sm font-bold dark:text-gray-200 text-itta-black">
          다크 모드
        </span>
      </div>
      <button
        onClick={toggleDarkMode}
        className={cn(
          'cursor-pointer w-11 h-6 rounded-full relative transition-all duration-300',
          !mounted
            ? 'bg-gray-200'
            : currentTheme === 'dark'
              ? 'bg-purple-500'
              : 'bg-gray-200',
        )}
      >
        <div
          className={cn(
            'absolute top-1 left-1 w-4 h-4 bg-white rounded-full transition-transform duration-300 ease-in-out',
            mounted && currentTheme === 'dark' && 'translate-x-5',
          )}
        />
      </button>
    </div>
  )

• useTheme
  • next-themes 에서 제공하는 훅을 통해서 현재 테마 상태(theme )를 읽고, 원하는 테마로 변경(setTheme )할 수 있다.
• mounted 상태 관리 (hydration 에러 방지)
  • 서버 렌더링 시의 테마와 클라이언트에서 실제로 적용되는 테마가 다를 수 있는데, 이로 인한 hydration 불일치를 방지하기 위해 클라이언트 마운트 이후에만 UI를 렌더링하도록 한다.
• react19 대응 및 무한 루프 방지
  • useEffect 안에서 동기적으로 setState() 를 호출하면, 렌더링 → effect → setState → 리렌더링 되는 반복 루프 가능성 때문에 경고를 보여준다.
  • 이를 방지하기 위해 requestAnimationframe 을 활용해 마운트 후 상태 업데이트 다음 repaint 직전으로 지연시켜주었다.

setTimeout과 requestAnimationframe

결과

디자인을 수정하기 전에 찍었던 영상이라 현재 배포 버전과 레이아웃이 다른 부분이 있다.

mov -> gif 변환하면서 영상이 많이 느려졌다.

참고 자료

• https://velog.io/@maruru301/SpennyTIL-2-Next.js-다크모드-설정-next-themes
• https://medium.com/@kevstrosky/theme-colors-with-tailwind-css-v4-0-and-next-themes-dark-light-custom-mode-36dca1e20419
• https://bundlephobia.com/package/next-themes@0.4.6

다른 팀 프로젝트를 리팩토링하면서 한 성능개선 작업을 정리했습니다.

성능 개선시 활용되는 브라우저 도구들은 다음과 같다.

• performance(성능): 웹 애플리케이션의 런타임 성능을 기록하고 분석할 수 있는 탭
• profiler(프로파일러): React 개발자 도구의 일부로, React 컴포넌트의 렌더링 성능을 프로파일링한다.

profiler를 통해 컴포넌트 렌더링 횟수와 성능을 측정하고, performance로 메인 스레드 사용량을 알 수 있다.

Performance tab

웹 페이지의 로딩 성능, 렌더링 성능, 스크립트 실행 성능 등을 측정하고 분석하는데 사용된다.

네트워크, CPU, FPS 등을 측정할 수 있다.

녹화 버튼을 통해 특정 인터렉션 혹은 기능에 대한 성능을 측정해보면, 위의 사진처럼 표시된다.

위 사진은 Main Timeline 인데, 주로 웹사이트의 메인 스레드를 가리킨다.

이 메인 스레드에서 Javascript의 실행, 스타일 계산, 레이아웃 생성 등 웹사이트의 주요 동작들이 처리된다.

메인 스레드에서 얼마나 시간을 소요하는지를 확인할 수 있다.

Main 영역에서 소요되는 시간이 50ms를 초과하면 긴 작업으로 판단해 빨간색 태그를 붙여준다.

Profiler tab

profiler 기능은 react-dom 16.5 이상의 개발자 모드에서 지원한다. 프로덕션 프로파일링도 지원하는데, 다른 방법을 사용해야 한다.

조금 지난 문서이긴 한데, 공식문서에서 설명을 해주고 있다.

기본적으로 React는 두 단계로 작동한다.

1. 렌더링 단계: DOM에 어떤 변경이 필요한지 결정하며, 호출한 render 후 결과를 이전 렌더링 결과와 비교한다.
2. 커밋 단계: React가 변경사항을 적용하는 단계.(React DOM 노드 삽입, 업데이트, 제거) 여기서 componentDidMount , componentDidUpdate 와 같은 라이프사이클을 호출한다.

드래그 리렌더링 성능 개선

profiler로 리렌더 상태를 확인하고자 했다.

리렌더 성능에 가장 큰 부분을 차지할 기능은 윈도우 drag & drop이기 때문에, 이 부분을 살펴봤다.

4개의 윈도우를 띄우고 윈도우를 이동시켜봤다. 움직이는 윈도우 뿐만 아니라, 화면에 표시된 모든 윈도우들이 모두 함께 리렌더되고 있었다.

물론 바탕 화면(WallPaper)도 마찬가지였다.

여기서 바의 색상은 함수 실행의 시간을 의미한다.

• 초록색: 렌더링 시간이 짧고 최적 (성능에 큰 영향을 미치지 않는다.)
• 주황색: 렌더링 시간이 상대적으로 길고 최적화가 필요하다. 성능 저하의 원인이 될 수 있다.
• 노란색: 주황색보다는 덜 심각하지만 여전히 시간이 소요되는 구간
• 회색: 리렌더링이 발생하지 않았다는 의미
• 회색 빗금바: 다시 렌더링되지 않은 컴포넌트

performance도 돌려봤다.

가장 큰 부분을 차지하는건 Event: mousedown 처리였다.

이벤트 처리와 관련 작업에 소요된 총 시간이 103.2ms로 Long Task 로 분류되었다.

그리고 내부를 확인해 보면 Function call 이 많은 시간을 차지했는데, 이 Function call 은 주로 React의 업데이트(렌더링, 커밋 등) 또는 데이터 처리와 관련된 작업이다.

run 작업도 보면, 함수 호출 내부에서 불필요하게 많은 컴포넌트가 리렌더링 되거나 복잡한 계산이 동기적으로 이루어졌을 가능성이 높다. 사실 console 출력도 동기적으로 이루어지기 때문에 콘솔 출력이 많아지면 성능에도 영향을 줄 수 있다.

위 performance와 profiler를 통해 마우스 이벤트에 대한 후속 작업에 리소스가 많이 쓰인다는걸 알았으니 이를 개선해보자.

현재 프로젝트는 마우스 이벤트는 리렌더에 직접적인 영향을 주고 있다. 그리고 리렌더 후 서버에 API 요청을 보내 처리한다.

가장 영향이 클 윈도우 리렌더링 이슈를 개선해볼까 한다.

원인 분석

profiler 사진의 오른쪽 사이드바를 보면, What caused this update? 를 볼 수 있다. 이 렌더링의 원인이 무엇인지를 알려주는데, WallPaper 때문이라고 한다.

그렇다면 WallPaper 컴포넌트를 살펴보자.

// wallpaper.tsx
const {
    windowList,
    handleFetchClose,
    handleFetchOpen,
    handleMove,
    handleResize,
    handleFocus,
    handleHide,
    handleShow,
  } = useWindowManager(isBoot);

이렇게 window 와 관련된 함수와 데이터를 상위 컴포넌트인 WallPaper 컴포넌트에서 관리해 내려주고 있었다.

그래서 window의 상태(위치)가 바뀔 때마다 windowList 가 재생성되면서 wallpaper가 함께 리렌더 되던 것이다.

wallpaper가 리렌더되면서 자식 컴포넌트도 같이 리렌더링되는 문제였다. 이전 팀은 전역 상태를 거의 사용하지 않고 지역 상태 위주로 상태들을 관리해줬다.

그렇기에 상위에서 상태를 관리하고, 이를 자식으로 props drilling으로 전달해주고 있었다.

이로 인해 발생한 리렌더링 문제인데, 대부분이 custom hook으로 상태가 관리되고 있었기에 이를 어떻게 개선할지 고민이 됐다.

최대한 코드를 많이 안건들고 싶었는데, 윈도우에 대한 상태를 다른 컴포넌트들로 props drilling 없이 전달하기 위해선 전역 상태로 관리해주는 방법밖에 없었다.

싱글톤도 생각해봤는데, 상태가 불변성을 제공하지 않으면 리렌더가 필요한 곳이 렌더링이 안되는 문제가 발생하기 때문에 subscribe, publish를 만들어줘야 한다.

전역 상태가 그 역할을 대신 해주는데, 굳이 그래야 하나? 라는 생각이 들었다. 거기다 다음 할 일이 또 있었기 때문에 그리 많은 시간을 투자하지 못한다는 점도 컸다.

그래서 빠르게 작업할 수 있는 전역 상태를 활용해 window를 관리해주는걸로 결정했다.

마침 다른 팀원이 zustand 로 전역 상태를 관리하도록 해줘서, 그대로 zustand를 사용하기로 했다.

window 상태들 추리기

전역으로 윈도우 상태를 관리하기로 했으니, 윈도우 상태값들이 어떤게 있는지를 정리해야 한다.

export interface Window {
  id: number;
  title: string;
  x: number;
  y: number;
  z: number;
  width: number;
  height: number;
  isHidden: boolean;
}

마침 type으로 정의된 윈도우가 있고, windowList 도 이 타입들로 관리되고 있어서 그대로 사용하면 될 것 같았다.

이 타입들을 가지고 useWindowStore 를 만들어주고, 상태를 사용하는 컴포넌트에서 호출해주도록 했다.

  // wallpaper.tsx
  const {
    windowList,
    handleFetchClose,
    handleFetchOpen,
    handleMove,
    handleResize,
    handleFocus,
    handleHide,
    handleShow,
  } = useWindowManager(isBoot);

useWindowManager 훅에서 상태 업데이트와 관련 핸들러를 모두 다루고 있어서 분리 실행하기 어려웠다.

useWindowManager 는 내부 로직이 다음과 같이 나뉘어진다.

• sse 데이터 전달받기 및 window 업데이트
• window 이벤트 핸들러

이를 관련 비즈니스 로직별로 훅을 분리하기로 했다.

• useWindowState : sse 데이터 전달 및 전달받은 데이터로 window 업데이트
• useWindowActions : window 관련 이벤트 핸들러 관리

이후 해당 훅이 필요한 컴포넌트에서 직접 호출해주도록 하고, props drilling을 최소화해주었다.

// wallpaper.tsx
{isBoot && (
  <WindowManager
    isBoot={isBoot}
  />
)}
{isBoot && (
  <TaskBar
    onRestart={onRestart}
    onShutdown={onShutdown}
  />
)}

마지막으로 윈도우 내부에서 출력되는 어플리케이션을 메모이제이션 시켜주었다.

리렌더링 확인해봤을 때, Memo 컴포넌트와 FileList 컴포넌트가 실행됐는데, 변경된 상태가 없음에도 리렌더링이 발생하고 있었다.

그리고 이를 살펴보니 사이드바에 적힌 원인은 부모가 리렌더되어 리렌더되었다는 것이었다.

그래서 윈도우 내부에서 실행되는 어플리케이션 컴포넌트에 모두 React.memo 를 적용시켜줬다.

결과

before와 동일하게 가장 높게 측정된 부분을 가져왔다.

저 IconButton 굉장히 마음에 안드는데, memo를 적용했음에도 결과가 똑같아서 그냥 제거하고 그대로 뒀다.

profiler 기준 render time이 107.5ms로 측정되던 렌더링 시간을 9.2ms로 줄였다. before, after 모두 측정 시 가장 높은 값을 가져온 것이며, 약 91% 개선시켰다.

performance도 돌려봤다.

확실히 Long Task가 사라진걸 확인할 수 있다.

그리고 똑같이 position API가 요청될 때의 mousedown 이벤트의 내부 작업을 확인해보면, Fucntion call 이 97.7ms → 43.4ms로 약 55% 개선된 것을 확인할 수 있다.

그래서 이를 개선했던 과정을 담아봤다.

SVG 아이콘 통합

svg sprite와 vite svg 컴포넌트 중 어떤걸 사용할까 고민하다, 일단 비교를 해봤다.

1. svg sprite

HTTP 요청 수가 1개(sprite 파일)이며 이후엔 캐싱되기 때문에 네트워크 요청이 줄어든다는 점이 장점이다.

하지만 파일 크기가 커질 수록 느려지기 때문에 성능 이슈가 발생할 수 있다. 또한 스타일링이 fill 과 stroke 로 직접 svg로 제어하거나, currentColor 로 설정해두고 tailwind로 수정이 가능하다.

2. vite svg 컴포넌트화

svg 파일을 import 해서 컴포넌트처럼 사용할 수 있지만, 플러그인에 의존한다.

HTTP 요청 수는 0개(번들에 포함돼서)이며 코드 분할이 가능하다는 장점이 있다. 또한 초기 로드시 필요한 아이콘만 로드하기 때문에 빠르다.

컴포넌트처럼 사용되기 때문에, 스타일링도 props나 css-in-js 등으로 직접 제어할 수 있다.

아이콘 통합 방법 결정

비교는 해봤지만, 사실 아이콘이 18개 정도이고 더 추가될 가능성이 없기 때문에 성능상 두 방법은 차이가 없다고 봐도 된다.

스타일링도 코드를 보면 딱히 해주고 있는게 없고 img 태그로 넣어주기만 해서 굳이 필요 없다.

그래서 어떻게 아이콘들을 불러오는지를 확인해봤다.

// memo/utils/icons.ts
import bin from "@/assets/bin.svg";
import post from "@/assets/post.svg";
import search from "@/assets/search.svg";
import bulb from "@/assets/bulb.svg";
import onoff from "@/assets/onoff.svg";

import bold from "@/assets/bold.svg";
import italic from "@/assets/italic.svg";
import strike from "@/assets/strike.svg";
import code from "@/assets/code.svg";
import h1 from "@/assets/h1.svg";
import h2 from "@/assets/h2.svg";
import h3 from "@/assets/h3.svg";
import bulletlist from "@/assets/bulletlist.svg";
import numberlist from "@/assets/numberlist.svg";

export const icons = {
  bin,
  post,
  search,
  bulb,
  onoff,
};

export const mark = {
  bold,
  italic,
  strike,
  code,
  h1,
  h2,
  h3,
  bulletlist,
  numberlist,
};

메모장에서 사용하는 아이콘들을 한 파일로 묶어 export해 사용하고 있었다.

이 방식이 vite svg 컴포넌트와 비슷해서 코드를 최대한 많이 안건들기 위해 vite 플러그인을 활용하기로 결정했다.

vite-plugin-svgr 적용하기

1. vite 플러그인 사용을 위해 vite-plugin-svgr 을 install 해준다.
2. vite.config.ts 파일에 plugins로 다음을 추가해준다.

plugins: [
    svgr({
      svgrOptions: {
        icon: true,
      },
    }),
    ...

3. 타입스크립트가 vite-plugin-svgr 이 제공하는 타입을 인식하도록 다음을 추가해준다.

// vite-env.d.ts
/// <reference types="vite-plugin-svgr/client" />

vite-plugin-svgr 은 import Logo from './logo.svg?react' 같은 식으로 svg를 react 컴포넌트로 로딩할 수 있게 해준다. 그런데 타입스크립트는 *.svg?react 형식을 기본적으로 모르기 때문에 컴파일 에러를 낸다.

그래서 vite-plugin-svgr 은 자기 타입 선언을 제공하고 있는데, 그게 바로 vite-plugin-svgr/client 다.

이 타입을 참조하면 타입스크립트가 *.svg?react 는 리액트 컴포넌트라는걸 알게 된다.

먼저, 현재 svg 파일을 그대로 import 하고 있는데, vite svg 컴포넌트로 사용할 때 기존 코드처럼 import하면 createElement("data:image/svg+xml,...") 으로 컴포넌트를 생성하려고 해 에러를 내뿜는다. 경로 뒤에 ?react 를 붙여줘야 한다.

svg 파일을 그대로 import 하게 되면 문자열 경로로 import 된다.

Uncaught InvalidCharacterError: Failed to execute 'createElement' on 'Document': The tag name provided ('data:image/svg+xml,%3c?

그냥 붙이면 해당 경로(?react)는 존재하지 않다고 파일 내에서 에러를 내뿜기 때문에, 타입 선언을 해준다.

// svg.d.ts
declare module "*.svg?react" {
  import * as React from "react";
  const ReactComponent: React.FC<React.SVGProps<SVGSVGElement>>;
  export default ReactComponent;
}

그리고 타입스크립트가 이 타입을 해석할 수 있도록 tsconfig 파일도 수정해준다.

// tsconfig.app.json
"include": ["src", "svg.d.ts"]

그리고 경로를 수정해 기존 방법과 똑같이 객체로 아이콘을 모아준다.

// components/common/icon/iconMap.ts
import BinIcon from "@/assets/bin.svg?react";
...

export const IconMap = {
  leftLine: LeftLineIcon,
  power: PowerIcon,
  rightLine: RightLineIcon,
  setting: SettingIcon,
  system: SystemIcon,
  ...
}

export type IconName = keyof typeof IconMap;

이 아이콘을 편하게 사용하기 위해 아이콘 컴포넌트를 만들어줬다.

// components/common/icon/icon.tsx
const Icon = ({ name, size = 24, className = "" }: IconProps) => {
  const IconComponent = IconMap[name];

  return (
    <IconComponent
      width={size}
      height={size}
      className={cn("inline-block", className)}
    />
  );
};

사용할 때는 아래처럼 사용해주면 된다.

<Icon name="bin" size={17} />

기존 코드와 비교

// 수정 전
import { icons } from "./utils/icons";

<img src={icons.bin} alt="delete" width={17} height={17} />

수정 전: 자산(Asset)으로 처리 (다수 HTTP 요청)

작동 방식: 수정 전 코드는 import bin from "@/assets/bin.svg";와 같이 SVG 파일을 불러왔을 때, 번들러가 이를 자산(Asset) 파일로 간주하고 해당 파일의 경로(URL 문자열)를 JavaScript 변수에 할당.

네트워크 결과: 이 경로 문자열을 React 컴포넌트가 <img> 태그 등으로 사용하면, 브라우저는 해당 URL로 새로운 HTTP 요청을 보내 SVG 파일을 다운로드. 아이콘이 18개면 18개의 HTTP 요청이 네트워크 탭에 하나하나 찍혔던 것.

하나의 객체로 export하고 여러 파일에서 이 객체를 import하여 사용하기 때문에, 객체를 import하는 모든 파일에서 사용 여부와 관계없이 객체에 담긴 모든 아이콘이 함께 로드된다.

// 수정 후
import Icon from "@/components/common/icon/icon";

<Icon name="bin" size={17} />

수정 후: 컴포넌트(Component)로 처리 (단일 JS 번들)

작동 방식: vite-plugin-svgr 플러그인과 ?react 또는 { ReactComponent } 임포트 구문을 사용하면서 모든 SVG 파일은 더 이상 단순한 자산이 아님.

플러그인은 SVG 파일의 XML 내용을 읽어 들임.

이 내용을 <svg>...</svg>를 반환하는 React 컴포넌트 함수로 변환.

이 변환된 JavaScript 코드가 메인 애플리케이션의 JavaScript 번들 파일 안에 통째로 삽입(Inlining)됨.

네트워크 결과: 브라우저는 여전히 JavaScript 번들 파일(예: index.js 또는 app.js)을 다운로드하지만, 그 안에 이미 18개 아이콘의 코드가 포함되어 있음. 따라서 별도로 SVG 파일을 다운로드하기 위한 HTTP 요청이 발생하지 않음.

IconMap.ts에 모든 아이콘이 묶여 있지만, 이 맵은 오직 Icon.tsx 컴포넌트 한 곳에서만 참조된다. 따라서 Icon.tsx 파일을 사용하지 않는 다른 모듈이나 컴포넌트들은 번들링 시 아이콘 코드 전체가 포함되지 않는다.

참고 자료

https://velog.io/@mari/React-Vite-svgr-setup https://breathof.tistory.com/311 https://www.npmjs.com/package/vite-plugin-svgr

새로고침시 브라우저 이벤트가 발생하게 된다. 새로고침에 의한 이벤트는 beforeunload 와 unload 가 있는데, beforeunload 는 unload 하기 전, 사용자에게 새로고침을 할 것인지 경고 혹은 알리는데 주로 사용한다.

unload 는 새로고침 되기 직전에 발생하는 이벤트이다.

사용자가 직접 새로고침한 것이기에 의도된 것이라고 판단하고 beforeunload 는 고려하지 않기로 했다. 그래서 unload 이벤트에 서버로 shutdown API를 요청해 클라이언트와 서버의 시스템 상태를 동기화시키도록 로직을 작성해줬다.

새로고침은 모든 Page 컴포넌트에서 발생할 수 있는거기에 App.tsx 파일에 이벤트를 등록해주었다.

  const { updateSystemState } = useSystemStateStore();
  const { mutate: shutdownMutate } = useApi<ShutdownResponse>(
    systemAPI.shutdown,
    {
      onSuccess: () => {
        updateSystemState(SYSTEM_MODE.SHUTDOWN);
      },
      onError: (res) => {
        updateSystemState(SYSTEM_MODE.ERROR);
      },
    },
  );

  useEffect(() => {
    const unloadFunc = async () => {
      await shutdownMutate()
    };

    window.addEventListener('unload', unloadFunc);
    return () => {
      window.removeEventListener('unload', unloadFunc);
    };
  }, []);

하지만 unloadFunc 함수는 실행이 되지만 shutdownMutate 함수가 정상적으로 실행되지 않았고, console로 API 요청 후 출력까지 해봤지만 console도 실행되지 않았다.

문제 발생 이유

브라우저 환경에서 unload 이벤트가 발생하면 브라우저는 현재 페이지를 즉시 unload 하고 새 페이지 로드를 시작한다.

여기서 unload 이벤트는 동기적이며, unload 핸들러가 실행되더라도 브라우저가 이 핸들러가 완전히 종료될때까지 기다려주지 않는다.

즉, 페이지 unload 작업이 매우 빠르게 진행된다.

그런데 핸들러 안에서 비동기적으로 시간이 소요되는 로직을 호출하고, 작업이 종료되기 전에 페이지가 unload 되면서 이후의 console이 출력되지도, 정상적으로 요청이 처리되지도 않은 것이다.

문제 해결

하지만 나는 브라우저가 페이지를 닫기 전에 서버에 데이터를 보내야 하고, 비동기 로직을 await 하는걸 기다려주지 않는다.

그렇기에 unload 이벤트에 핸들러를 등록하는 것 대신, 브라우저가 직접 요청을 처리할 수 있는 방법을 찾아야 한다.

이를 알아보다 navigator 에서 제공해주는 sendBeacon() 이라는 메소드를 알아냈다.

MDN

navigator.sendBeacon() 메서드는 적은 양의 데이터를 포함하는 HTTP POST 요청을 비동기적으로 웹 서버에 보냅니다.

딱 나한테 필요한 기능!

서버로부터 응답을 받아야 하면 fetch 의 keepalive 를 true 로 설정한 걸 사용하라고 한다. 나한텐 필요없다.

sendBeacon(url)
sendBeacon(url, data)

• url : data를 받을 서버의 URL, 상대 주소와 절대 주소 모두 가능하다
• data : ArrayBuffer , TypedArray, DataView, Blob , 문자열 또는 객체 리터럴, FormData, URLSearchParams 등 전송할 데이터를 담은 객체

성공적으로 사용자 에이전트가 전송할 data를 대기열에 추가하면 true 를 반환하고, 아니라면 false 를 반환한다.

사용자 에이전트? 사용자를 대표하는 컴퓨터 프로그램으로, 웹 맥락에선 브라우저를 의미한다.

설명을 보면 분석 정보나 진단 데이터를 서버에 보내기 위한 목적으로 만들었다고 한다. 하지만? 사용하기 편하고 적절한 대안이니 상황에 따라 사용 가능

원래는 unload 이벤트 발생 시 브라우저가 정상적으로 비동기 요청을 전송할 수 있도록 지원했다고 한다.

하지만 이는 다음 페이지로의 탐색 속도가 저하되기 때문에, 사용자는 새로운 페이지가 느리다고 느끼게 되는 것이다. 이 UX를 개선하기 위해 고안된 메소드라고 한다.

(사실 unload 이벤트에 비동기 로직을 작성하는건 굉장히 좋지 않다고 적혀있다.)

장점은 다음과 같다고 설명한다.

• 데이터가 안정적으로 전송됨
• 비동기적임
• 다음 페이지에 영향을 끼치지 않음

이제 어떤 목적으로 이 메소드가 만들어졌고, 어떤 이점이 있는지에 대해 알았으니 적용해보자.

  const unloadFunc = async () => {
    const shutdownPayload = JSON.stringify({ reason: 'window_unload' });
    const blob = new Blob([shutdownPayload], { type: 'application/json' });

    // sendBeacon을 사용하여 API 요청을 브라우저에 위임
    const success = navigator.sendBeacon('/api/system/shutdown', blob);

    if (success) {
      console.log('Shutdown request successfully initiated via sendBeacon.');
    } else {
      console.log('Failed to initiate sendBeacon request.');
    }

    // sendBeacon은 비차단이므로 다음 코드는 즉시 실행되지만,
    // API 응답을 기다리지 않으므로 로그아웃 성공/실패 여부를 알 수 없다.
    console.log('dhfh (sendBeacon started)');
  };

  useEffect(() => {
    window.addEventListener('unload', unloadFunc);
    return () => {
      window.removeEventListener('unload', unloadFunc);
    };
  }, []);

전달할 수 있는 데이터 중 알고 있는 타입이 Blob 였기에 이를 사용했다.

이렇게 작성하고 실행해봤더니, 정상적으로 처리된걸 확인했다.

네트워크 탭으로 확인할 땐 Type ping으로 cancled 상태의 요청만 보였는데, 이건 실패했다는건 아니고 sendBeacon 은 성능에 영향을 주지 않도록 백그라운드에서 실행되기 때문에 ping 이나 other 등을 분류되는게 일반적이라고 한다.

그리고 ping 은 매우 낮은 우선순위로 처리되기 때문에 브라우저 개발자 도구가 이를 완전히 추적하지 못했다는 것으로 해석할 수 있다.

확실하게 처리됐는지 확인하고자 한다면, 서버 로그를 확인하는걸 추천한다!

이전 프로젝트를 진행하면서, 팀원이 lint 에러를 수정하지 못하고 push를 해서 수정된 코드를 pull 받은 팀원이 해결해야 하는 문제가 있었습니다.

그리고 prettier가 버그로 인해 동작하지 않았을 때 (IDE or 특정 폴더에서는 동작하지 않는 등) push를 해서 다른 팀원이 pull로 코드를 받았을 때 파일의 모든 부분이 변경되는 문제점도 있었습니다.

이 문제들을 해결하기 위해 husky + lint-staged를 설정하기로 결정했습니다. 설정 후엔 위의 문제들이 해결되고, 깜빡하고 넘어갔던 lint 에러도 해결이 되어 배포시 발생했던 lint 오류도 훨씬 줄어들었습니다.

이번 그룹 스프린트에서도 협업이기에 비슷한 문제가 발생할 경우를 대비해 husky + lint-staged 를 설정하기로 했습니다.

먼저, 모노레포로 프로젝트가 설정되어 있기에 이를 고려해 진행했습니다.

- app/
   |- frontend/
   |- bacnend/

설치하기

husky는 깃의 특정 이벤트가 발생할 때 자동으로 원하는 스크립트를 실행할 수 있게 해주는 역할을 합니다.

공식 문서 설치가이드를 통해 husky를 각 패키지 매니저로 설치할 수 있습니다.

저희는 pnpm 을 사용하고 있기에, 다음의 명령어를 입력해 설치 및 초기화했습니다.

pnpm install -D husky lint-staged -w

-w 는 pnpm의 모노레포 환경 보호 기능을 끄기 위해서 추가한 옵션입니다. pnpm을 사용하면 루트 디렉토리는 워크스페이스의 중앙 관리 지점입니다.

pnpm install -D husky lint-staged 를 루트에서 실행하면, pnpm은 이 의존성이 모든 서브 프로젝트에서 사용될지, 아니면 루트에서 관리되는 도구로만 사용될지 명확하지 않다고 판단합니다.

그렇기에 이 의존성을 워크스페이스 루트에 추가하는 것이 의도한 것이라면 -w 플래그를 사용해 명시적으로 알려달라고 요청합니다.

 ERR_PNPM_ADDING_TO_ROOT  Running this command will add the dependency to the workspace root, which might not be what you want - if you really meant it, make it explicit by running this command again with the -w flag (or --workspace-root). If you don't want to see this warning anymore, you may set the ignore-workspace-root-check setting to true.

위의 문제를 해결하기 위해 -w 옵션으로 의도한 것이라는걸 알려주는 것입니다.

이제 초기화를 시키기 위해 다음의 명령어를 입력합니다.

pnpm exec husky install

위의 명령어를 입력하면 루트 폴더에 .husky 폴더가 생기는 것을 볼 수 있습니다.

설정하기

이제 커밋을 하게 될 때 자동으로 lint와 prettier가 작동되도록 설정해야 합니다.

husky 가 버전이 업그레이드되면서 CLI로 pre-commit 훅을 설정하는 방식이 DEPRECATED 되었습니다.

그렇기에 직접 pre-commit 파일에 접근해서 코드를 작성해주어야 합니다.

다음과 같이 작성해주었습니다.

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

pnpm exec lint-staged

• #!/usr/bin/env sh : 이 파일이 쉘 스크립트임을 선언하고, 시스템 환경 변수를 사용해 sh 인터프리터로 실행되도록 지정합니다.
• . "$(dirname -- "$0")/_/husky.sh" : husky가 제공하는 실행 환경을 불러와 훅을 실행할 준비를 합니다. husky가 올바른 환경에서 실행되도록 보장하는 필수 초기화 코드입니다.
• pnpm exec lint-staged : 스테이징된 파일만 검사하고 수정하는 lint-staged 도구를 실행합니다.

husky만 적용하면 변경된 파일뿐만 아니라 모든 파일에 대해 매번 수행을 하기 때문에 시간이 오래걸리며 불필요한 작업이 수행되게 됩니다.

lint-staged는 이 문제를 해결해줍니다. 커밋하기 전에 변경된 파일에 대해서만 린트와 포맷팅 작업을 수행하도록 트리거합니다.

lint-staged 를 설정해주었으니, package.json에 lint-staged 가 실제로 어떤 파일을 검사하고 어떤 명령을 실행할지에 대한 규칙을 정의하는 블록을 작성해주어야 합니다.

  // package.json
  "lint-staged": {
    "app/frontend/**/*.{js,jsx,ts,tsx}": [
      "pnpm exec eslint --fix --cwd app/frontend",
      "pnpm exec prettier --write"
    ],
    "app/backend/**/*.{js,ts}": [
      "pnpm exec eslint --fix --cwd app/backend",
      "pnpm exec prettier --write"
    ],
    "*.{json,css,md,yaml,yml}": [
      "pnpm exec prettier --write"
    ]
  },

위의 "lint-staged" 를 추가해줍니다.

저희는 app/frontend 와 app/backend 로 분리했기에 위처럼 작성해주었습니다. 각 팀의 폴더 구조에 맞게 작성해주시면 됩니다.

이제 커밋을 하게 될 때마다 린트와 포맷팅 작업을 수행하게 됩니다.

(브랜치 이름은 오타가 맞습니다 ㅎㅎ..)

여기서 경고 메시지가 보입니다.

husky - DEPRECATED

Please remove the following two lines from .husky/pre-commit:

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

They WILL FAIL in v10.0.0

이는 husky가 v10에서 스크립트 실행 방식이 변경될 예정임을 미리 알려주는 단순 경고 메시지입니다.

husky 버전이 올라가면서 스크립트 실행 환경을 초기화하는 방식을 더 단순화하고 있기에 알려주는 경고 메시지입니다.

아직은 v9이기 때문에 안전하지만, v10으로 변경될 때 지원을 중단할 예정이며 문제가 발생할 수 있으니 미리 삭제하라고 권장합니다. (안바꿔도 됩니다! v10으로 업그레이드 할 계획이 없다면)

메시지는 pre-commit 에서 설정한 . "$(dirname -- "$0")/_/husky.sh" 명령어를 없애라고 합니다.

#!/usr/bin/env sh

pnpm exec lint-staged

위처럼 pre-commit 을 바꿔 다시 커밋을 날려보면 lint-staged가 동작하지 않습니다!

v10 버전부터 제거해야하는거고, 현재 husky 버전(v9.1.7)에서는 이 줄이 필수적인 초기화 코드이기 때문이다.

그러니, 다시 붙이자….

XML은 데이터를 정의하는 규칙을 제공하는 마크업 언어이다. 다른 프로그래밍 언어와 달리 XML은 자체적으로 컴퓨팅 작업을 수행할 수 없다.

대신, 구조적 데이터 관리를 위해 모든 프로그래밍 언어 또는 소프트웨어를 구현할 수 있다.

주로 서로 다른 시스템 간에 데이터를 교환할 때 사용하며, 구조 표현용 마크업 언어이다.

자유롭게 태그를 정의할 수 있으며, 계층 구조를 가진다.

<?xml version="1.0" encoding="UTF-8"?>
<bookstore>
  <book category="cooking">
    <title lang="en">Everyday Italian</title>
    <author>Giada De Laurentiis</author>
    <year>2005</year>
    <price>30.00</price>
  </book>
  <book category="children">
    <title lang="en">Harry Potter</title>
    <author>J K. Rowling</author>
    <year>2005</year>
    <price>29.99</price>
  </book>
  <book category="web">
    <title lang="en">Learning XML</title>
    <author>Erik T. Ray</author>
    <year>2003</year>
    <price>39.95</price>
  </book>
</bookstore>

XML과 HTML의 차이

예시만 보면 XML과 HTML은 동일한 것 같다.

HTML 과 XML 은 애플리케이션 개발과 웹 개발에서 널리 사용되는 두 가지 마크업 언어이다.

이름은 비슷하지만, 사용 사례는 다르다.

HTML 은 주로 애플리케이션의 UI를 개발하는 데 사용된다. 웹 사이트 또는 애플리케이션에서 볼 수 있는 텍스트, 이미지, 버튼, 확인한 및 드롭다운 상자를 렌더링한다.

반면, XML 의 주요 목적은 데이터 교환 및 전송이다. 기계와 사람이 모두 읽을 수 있는 형식으로 데이터를 인코딩한다.

즉, XML 은 데이터가 무엇인지 설명하는 반면, HTML 은 데이터를 최종 사용자에게 표시하는 방법을 결정한다.

또한 XML은 사용자가 태그를 직접 정의할 수 있으며 자유롭게 만들 수 있다. 즉, 데이터의 의미와 구조가 중요하다.

반면 HTML은 미리 정의된 태그만 사용해야 하며, 데이터의 의미는 중요하지 않다.

왜 HTML로는 안될까?

근본적인 차이로 인해 HTML로는 XML이 표현하고자 하는 의미 있는 데이터 표현이 불가하다.

아래와 같은 XML 데이터가 있다고 하자.

<order>
  <customer>수연</customer>
  <item>노트북</item>
  <price>1200000</price>
</order>

이 데이터는 주문 정보라는 의미를 정확히 담고 있다.

이를 HTML로 표현하면 다음과 같을 것이다.

<div>
  <div>수연</div>
  <div>노트북</div>
  <div>1200000</div>
</div>

그저 박스(div )만 있을 뿐, 어떤 것을 의미하는지 알 수 없다.

이 외에도 HTML 은 사람이 화면으로 보는 용도이며 XML 은 앱 ↔ 서버, 회사 ↔ 회사 간의 데이터 교환 용도라는 차이로 데이터 교환에 적합하지 않다.

실제 예시론, 항공사 시스템 ↔ 여행사 시스템 ↔ 결제 시스템 사이에서의 데이터 교환을 들 수 있다.

항공편 정보, 승객 정보, 가격 등을 XML 을 통해 데이터를 교환한다.

XML 로 데이터를 전송해 서로가 데이터의 의미를 정확히 알 수 있다.

HTML과 XML을 사용해야 하는 경우

HTML은 프레젠테이션 언어로 알려진 일종의 마크업이다. HTML 을 사용해 웹 페이지와 클라이언트 측 애플리케이션을 만들 수 있다.

일반적으로 스타일 지정을 위한 CSS와 동적 동작을 위한 JS와 결합된다.

반대로 두 애플리케이션 또는 시스템 간의 데이터 교환에는 XML 을 사용한다. 동일한 형식을 이해하기 위해 애플리케이션에서는 XML 파일의 내용을 정의하는 XML 스키마 를 공유했다.

XML 은 여전히 널리 사용되고 있지만, 데이터 교환을 위한 또 다른 방법인 JSON 으로의 경량 데이터 포맷은 빠른 파싱으로 인해 더 많이 사용되고 있다.

XML과 JSON

데이터 교환을 위한 목적으로 사용한다면, JSON 도 있지 않나?

그렇다! 이전엔 XML 을 주로 사용했지만, JSON 이 구문이 더 간결하고 빠르며 쓰고 읽기가 쉬워 오늘날은 JSON 을 더 많이 쓰는 추세다.

// xml 버전
<user>
  <id>1</id>
  <name>Suyeon</name>
  <email>suyeon@example.com</email>
  <skills>
    <skill>JavaScript</skill>
    <skill>React</skill>
  </skills>
</user>

// json 버전
{
  "user": {
    "id": 1,
    "name": "Suyeon",
    "email": "suyeon@example.com",
    "skills": ["JavaScript", "React"]
  }
}

XML 은 데이터를 기계가 읽을 수 있는 방식으로 저장하는 데 중점을 두므로, 복잡한 데이터의 오류를 검사하는 데 있어서 JSON 보다 더 효율적이다.

또한 더욱 발전된 도구와 라이브러리를 갖추고 있어서 레거시 시스템에서 더 잘 작동할 수 있다.

반면, JSON 은 데이터 교환을 목적으로 설계되었으며 더 간단하고 간결한 형식을 제공한다. 또한 성능과 통신 속도를 향상시킨다.

JSON 은 일반적으로 API, 모바일 앱 및 데이터 스토리지에 더 적합하며, XML 은 데이터 교환이 필요한 복잡한 문서 구조에 더 적합하다.

한마디로, JSON의 장점은 파일 크기가 작아 네트워크 전송 속도가 빠르며 파싱 속도가 빠르며 메모리 효율적이다.

하지만 태그가 없어 데이터의 의미 표현에 약하며, 매우 복잡한 계층 구조나 혼합 콘텐츠 표현엔 부적합하다.

XML은 사용자 정의 태그가 가능해 산업별 표준에 적합하며, DTD, XSD를 통한 강력한 검증이 가능하다.

하지만 문법이 복잡하며 가독성이 떨어지며, 파싱 속도가 느려서 클라이언트 리소스가 부담된다.

JSON보다 파일 크기도 크기 때문에, 네트워크 전송 속도도 비교적 느리다.

Well-formed XML

Well-formed XML 이란, XML 문서가 문법적으로 정확한 형태를 만족하는 것을 말한다.

즉, XML의 규칙을 모두 만족하는 것을 말한다.

XML의 규칙은 다음과 같다.

1. 모든 XML 요소는 닫는 태그를 가지고 있어야 한다.
2. 태그는 열린 순서대로 닫혀야 한다.
3. 반드시 하나의 루트 엘리먼트만 존재한다.
4. XML 태그는 대소문자를 구분한다.
5. 모든 XML 요소는 적절하게 중첩되어야 한다.
6. 모든 XML 문서는 루트 요소를 가지고 있어야 한다.
7. 속성값은 항상 따옴표로 묶어야 한다.
8. 빈 요소는 반드시 /> 로 끝나야 한다.
9. 모든 시작 태그는 하나의 마침태그를 가지고 있어야 한다.
10. 주석은 <!-- 로 시작해서 --> 로 끝난다.

이 외에도 다양한 규칙이 존재한다. 이러한 XML 문법만 잘 지켜지면 Well-formed XML 이라고 할 수 있다.

이에 대한 검증 방식으론 파서(parser)를 이용한 검증과 온라인 XML 검증 도구를 사용하는 등의 방식이 있다.

XML 파서는 XML 문서를 문법에 맞게 작성했는지 검증하거나, XML 문서를 다른 애플리케이션에서 사용할 수 있는 문서로 변환하는 소프트웨어를 통틀어서 말한다.

XML 파서

파서의 종류는 크게 3가지로 나눈다.

1. 문법적인 오류만 검사하는 파서

일반적으로 브라우저에 내장된 파서이다. XML 문서를 출력시 자동으로 문법적인 오류를 검사한다.

문법만 맞으면 통과된다.

익스플로러, 크롬, 사파리 같은 브라우저에도 XML 파서가 내장되어 있다.

2. 유효한 문서인지 검사하는 파서

문서가 DTD 또는 XSD 스키마를 준수하는지를 확인한다.

태그와 속성이 스키마 정의와 일치하는지, 속성의 값 타입이 올바른지, 요소의 순서와 반복 조건이 일치한지 등을 검사한다.

즉, 문법 검사(well-formed)는 기본이며, 이에 유효성 검사가 추가된다.

최근 대부분의 브라우저는 XML 파서 기능을 포함하고 있어 별도 설치가 필요없다.

3. XML 문서를 다른 형태의 문서로 변형해 주는 파서

기존의 XML 문서를 WML, HTML 같은 형태의 문서 구조로 변형하고 출력해준다.

DOM 기반의 파서

DOM 기반의 파서는 DOM API를 사용한다. 문법 검사와 필요시 유효성 검사도 한다.

파싱 후 트리 구조를 생성하기 때문에, 자식, 부모, 형제 등 관계를 쉽게 탐색/수정할 수 있다.

DOM API를 사용하면 DOM 노드로 접근해 XML 문서 데이터를 변경할 수 있다.

브라우저의 내장 XMl 파서가 DOM 기반의 파서이다.

가상 환경은 물리적으로 한 대의 컴퓨터 안에서 여러 개의 독립된 컴퓨터(시스템)을 가상으로 만들어 사용하는 기술이다.

가상 환경을 만드는 것은 시대가 변하면서 변화했다.

애플리케이션 실행 환경의 변화

애플리케이션 실행 환경의 변화는 3단계로 나눠진다.

전통적인 환경에서의 배포(On-premise)에서 가상 환경에서의 배포(Virtual Machine)로, 또 컨테이너의 배포(Container)로 이어진다.

전통적인 환경에서의 배포(On-premise)

초기의 개발 환경은 물리적 서버에서 애플리케이션을 실행하였다.

이 방법은 물리적 서버 애플리케이션의 변경 사항을 쉽게 적용할 수 없고, 물리적 서버를 유지 관리하는데도 비용이 많이 들었다.

가상 환경에서의 배포(Virtual Machine)

물리적 환경에 대한 솔루션으로 가상화가 도입되었다.

단일한 물리적 서버의 CPU에서 여러 대의 가상머신(VM)을 실행할 수 있게 되었다.

이러한 가상화를 사용하게 되면 애플리케이션 간의 격리를 할 수 있고, 상호 간의 보안 환경도 유지할 수 있다.

• Host OS(호스트 OS): 실제 물리 하드웨어와 운영체제를 가진 PC나 서버
• Gest OS(게스트 OS): 하이퍼바이저 위에서 동작하는 가상머신의 운영체제로, 물리적 자원을 간접적으로 할당받아 시스템처럼 동작

하이퍼바이저란, 물리 하드웨어와 가상 머신 사이에서 자원을 중재하는 소프트웨어 레이어다.

서로 다른 OS를 동시에 구동할 수 있으며, 한 VM이 다른 VM에 직접적인 영향을 주지 않기 때문에 보안과 안정성이 높다는 장점이 있다.

하지만, Gest OS 전체를 구동하므로 무겁고, 부팅 시간이 길다.

또한 VM 이미지는 용량이 크며 메모리, CPU 자원을 많이 사용한다.

컨테이너로의 배포(Container)

컨테이너는 위의 가상머신과 유사하지만 컨테이너에는 자체 파일 시스템, CPU 공유, 메모리, 프로세스 공간 등이 있다.

기본 인프라에서 분리되기 때문에 클라우드 및 OS 배포 전반에 걸쳐 이식 가능하다.

VM처럼 운영체제를 통째로 띄우지 않고, 호스트 OS의 커널을 공유하여 애플리케이션만 격리하는 방식이다.

이로 인해 훨씬 가볍고 빠른 가상 환경을 제공한다.

이러한 이유로 현재는 컨테이너로 배포하는 환경이 주를 이루고 있다

실제로는 호스트 커널을 함께 쓰지만, 각 컨테이너마다 프로세스와 네트워크, 파일 시스템이 독립된 것처럼 보인다.

VM에 비해 훨씬 빠른 시작과 종료가 가능하며, 적은 자원으로도 다수의 애플리케이션 운영이 가능하다.

또한 애플리케이션별로 격리된 환경을 쉽게 만들 수 있다는 장점이 있다.

하지만 호스트 커널을 공유하기 때문에 보안 격리는 VM보다 취약할 수 있으며, 서로 다른 OS를 동시에 쓰기엔 커널 호환성 문제로 어렵다는 단점이 있다.

Docker

컨테이너 기술을 쉽고 간편하게 쓸 수 있도록 만들어진 오픈소스 플랫폼으로 Docker 가 표준처럼 널리 사용된다.

애플리케이션의 실행에 필요한 환경을 하나의 이미지로 모아두고, 그 이미지를 사용하여 다양한 환경에서 애플리케이션 실행 환경을 구축 및 운영하기 위한 오픈소스 가상화 플랫폼이다.

컨테이너는 프로세스 단위의 격리 환경을 조성하고 있어, 상호 간의 의존도를 낮추어 준다.

또한 VM에 비해 사이즈가 작아서 배포가 빠르고 성능 손실이 거의 없다.

쿠버네티스(Kubernetes)

도커의 등장으로 컨테이너 기반 배포 방식이 보편화되고, 많은 서비스들이 도커라이징 되어 이미지로 관리되기 시작했다.

점점 이미지가 많아지면서, 관리해야할 컨테이너와 서버들 또한 많아지게 되었다.

이 말은, 엔지니어가 할 일이 많아졌다는 말이다.

컨테이너들의 관리를 자동화할 도구(컨테이너 오케스트레이션 툴 )의 필요성이 대두되고, 비로소 컨테이너 오케스트레이션의 춘추전국시대가 열리게 된다.

많은 컨테이너 오케스트레이션 도구가 있음에도 불구하고, 현재는 쿠버네티스가 컨테이너 오케스트레이션들의 사실상 표준으로 자리매김하게 되었다.

• 대규모 컨테이너를 관리했던 구글의 노하우와 강력한 확장성
• 마이크로소프트, RedHat, IBM 등 수많은 기업의 참여

당근 인턴 면접에서, 새로고침 없이 페이지를 이동하는 라우팅 구현 문제가 라이브 코딩에서 나왔다. 이때, pushState로 url을 넣어주면 새로고침 되지 않는다는 것만 기억나서, 라이브 코딩은 망하고 면접 보는 도중에 계속 상태…상태…상태…만 얘기했던 기억이 있다. 그래서 이번 기회에 history API와 SPA 클라이언트 라우팅을 공부해 정리해봤다.

History API란

history 전역 객체를 통해 브라우저 세션 히스토리에 대한 접근을 제공한다.

사용자의 방문 기록을 앞뒤로 탐색하고, 방문 기록 스택의 내용을 조작할 수 있다.

메인 스레드의 전역 객체인 window 를 사용할 수 있는 곳에서만 활용 가능한 API이기 때문에, 메인 스레드에서 동작하지 않는 Worker 와 같은 곳에서는 접근할 수 없다.

• pushState : 세션 히스토리에 새로운 URL 상태를 쌓는다.
• replaceState: 세션 히스토리에 새로운 URL을 쌓지 않고, 현재 URL을 대체한다.

실제로는 화면 이동이 일어나지 않지만, 히스토리에는 URL 스택이 쌓이고, 현재 URL을 바꿔줄 수 있다.

이를 활용해 실제론 페이지 이동(페이지 이동시 발생하는 새로고침 없이)을 하지 않고, URL에 따른 화면을 다시 그릴 수 있다.

즉, history API를 활용해 SPA를 구현하는 것이 가능하며, 우리가 흔히 사용하는 router 가 history API를 기반으로 한다.

history 프로퍼티

• length: history 스택에 쌓인 페이지 수를 의미한다. 현재 3개의 페이지가 스택에 담겨있는 모습이다.

• scrollRestoration: 스크롤 복원에 대한 프로퍼티

  • auto: 사용자가 스크롤한 페이지의 위치가 복원된다.

  • manual: 페이지의 위치가 복원되지 않는다. 사용자가 직접 스크롤하여 해당 위치로 이동해야 한다.

    history.scrollrestoration = "manual";
    
    const scrollRestoration = history.scrollRestoration;
    if(scrollRestoration === 'manual') {
    console.log('scroll location is not restored');
    }

• state: pushState 와 replaceState 함수의 첫 번째 인자로 전달할 값이 저장된다.

    history.pushSate(state, title, url);
  
    history.pushState({scrollY: window.scrollY}, '', '/new-page');
  
    // 이후 popstate 이벤트에서 사용 가능
    window.addEventListener('popstate', (event) => {
      console.log(event.state); // {scrollY: ...}
    });

  • state: 개발자가 임의로 넣을 수 있는 객체 데이터 초기값은 null이며, 추가 정보를 저장하고자 할 때 사용한다. pushState, replaceState를 써야만 값이 들어간다.

  • title: 현재는 거의 무시되며, 대부분의 브라우저가 사용하지 않는다.

  • url: 바뀔 주소

SPA에서의 scrollRestoration

여기서 velog로 실제로 스크롤 위치가 저장되는지 scrollRestoration 을 테스트해봤다.

하지만 다음 게시글로 넘어갔다 돌아와도 스크롤 위치가 고정되지 않고, 최상단으로 이동했다.

알아보니, SPA 특성상 기본 브라우저 동작이 비활성화 되어 있기 때문이라 한다.

페이지 전환이 실제로는 URL만 바뀌고, 콘텐츠는 자바스크립트가 동적으로 교체하기 때문에 브라우저는 페이지 이동이라고 인식하지 못하고, 스크롤 위치 복원도 자동으로 동작하지 않는다고 한다.

MPA 기준으론 별도로 조작하지 않으면 기본적으로 이전 페이지의 스크롤 위치를 기억하고 복원한다.

하지만 여기서 이해되지 않는 부분이 있다.

‘history 스택이 변하는게 결국은 페이지 이동을 했다는 것을 의미하니까, 결국 똑같은거 아닌가?’

정확히 보면, 브라우저의 history 스택에 새로운 항목이 추가된다고 해서 브라우저가 ‘페이지 전환’으로 인식하는 것은 아니다.

pushState, replaceState 로 history 스택에 새로운 entry가 추가된다. 이때 URL은 바뀌지만, 브라우저가 이를 새로운 페이지를 요청해 로딩했다고 인식하지는 않는다.

단순히 주소와 상태만 바뀌었다고 본다. 브라우저가 ‘페이지 전환’으로 인식하는 경우는 다음과 같다.

• 새로운 문서를 요청해, 전체 페이지를 다시 그리는 경우 <a href=”/page2”> 클릭 시 서버에 새 HTML 요청

이때만 기본적으로 이전 페이지의 스크롤 위치를 기억하고, 뒤로 가기 시 복원한다.

React Router, Next.js, Vue Router 같은 클라이언트 라우팅 라이브러리들은 pushSate 를 사용해 URL만 변경한다.

그렇기에 기본적으론 스크롤 복원이 자동으로 되지 않는 것이며, 개발자가 직접 처리해야 한다.

history 관리 메소드

history.pushState(state, title, url)

url은 세션 히스토리에 새로 push할 URL 값이다.

a 태그를 클릭하거나 location.href 로 URL을 변경하는 것과는 달리, 이 URL이 변경된다고 해서 화면이 리로드되지 않는다.

말 그대로, URL만 바뀌게 된다.

history.replaceState(state, title, url)

기본적으로 pushState와 같다.

다른 점은, 히스토리에 새 URL 상태를 쌓지 않고, 현재 URL을 넣어준 url 값으로 대체한다.

history 스택 이동 메소드

history.back();
history.go(-1);

위는 모두 방문 기록의 뒤로 이동하는 방법이다. 브라우저 도구 모음에서 [뒤로 가기] 버튼을 클릭한 것과 동일하다.

history.forward();
history.go(1);

위는 모두 방문 기록의 앞으로 이동하는 방법이다. 브라우저 도구 모음에서 [앞으로 가기] 버튼을 클릭한 것과 동일하다.

history.go(2);
history.go(-2);

방문 기록의 특정 지점으로 이동하고자 한다면, 위처럼 현재 위치에 대한 상대 위치로 식별되는 특정 페이지로 로드하면 된다. 현재 위치는 0 이다.

history.go(0);
history.go();

위는 현재 페이지를 새로고침하는 방법이다.

history.length();

스택의 사이즈를 통해 페이지 수를 확인할 수 있다.

PopStateEvent

브라우저에서 페이지를 이동하게 되면 popstate 라는 이벤트가 발생한다.

history.pushState() 또는 history.replaceState() 를 호출하는 것만으로는 popstate 이벤트가 트리거되지 않는다.

이벤트는 history.back() , history.forward() 와 같은 뒤로, 또는 앞으로 가기 버튼을 클릭하는 것과 같은 브라우저 동작을 수행하거나 JavaScript에서 popstate 를 호출할 때 트리거된다.

pushState, replaceState에서 popstate 이벤트가 발생하지 않는 이유

history entry가 실제로 변경될 때 발생한다고 하는데, pushState, replaceState로 entry가 변경된 것인거 아닌가?

라는 생각이 들었다. 이에 대한 답은 다음과 같다.

히스토리 스택 내에서 ‘기존 entry 간에 이동(스택 간 이동)’을 한 경우에만 popstate 이벤트가 발생한다고 한다.

• pushState는 url을 변경하긴 하지만, 기존 entry 간의 이동이 아닌, 새 entry를 추가하고 그 entry가 활성화되는 것이기 때문에 이벤트가 발생하지 않는 것이다.

이 과정은 새로운 페이지를 불러온 게 아니라, 자바스크립트가 페이지 상태를 바꾼 것일 뿐이기 때문에 이벤트는 발생하지 않는다.

• replaceState는 현재 entry를 교체하는 것이므로, 히스토리 내에서 이동이 전혀 일어나지 않는다.

현재 활성화된 history entry를 교체하는(현재 entry를 덮어쓰는) 동작만을 하기 때문에 이벤트가 발생하지 않는 것이다.

history API로 클라이언트 SPA 라우팅 구현해보기

SPA는 페이지를 이동할 때마다 새로고침되지 않는다.

history의 pushState 를 사용해 URL만 바꾸고 해당 URL에 맞는 컴포넌트를 렌더링시키는 것이다.

주요 아이디어는 다음과 같다.

• URL이 변경될 때마다 컴포넌트 교체
• history.pushState() 를 사용해 URL만 바꾸고 페이지를 새로 고치지 않음
• popstate 이벤트를 이용해 앞/뒤로 가기 대응

1. React로 구현해보기

import React, { useEffect, useMemo, useState } from 'react';

const routes = [
  { path: /^\/$/, component: () => <h2>홈 페이지</h2> },
  { path: /^\/about$/, component: () => <h2>소개 페이지</h2> },
  { path: /^\/contact$/, component: () => <h2>연락처 페이지</h2> },
  {
    path: /^\post\/(\d+)$/,
    component: (params) => <h2>포스트 ID: {params[1]} 페이지</h2>,
  },
];

export default function App() {
  const [currentPath, setCurrentPath] = useState(window.location.pathname);

  useEffect(() => {
    const onPopState = () => {
      setCurrentPath(window.location.pathname);
    };

    window.addEventListener('popstate', onPopState);
    return () => {
      window.removeEventListener('popstate', onPopState);
    };
  }, []);

  const navigate = (path) => {
    // state, title, url
    window.history.pushState({}, '', path);
    setCurrentPath(path);
  };

  // 리렌더링을 고려하여 useMemo로 감싸줌
  const MatchedComponent = useMemo(() => {
    let component = () => <h2>404 페이지를 찾을 수 없습니다.</h2>;

    routes.some((route) => {
      const match = currentPath.match(route.path);
      if (match) {
        component = () => route.component(match);
        return true;
      }
      return false;
    });

    return component;
  }, [currentPath]);

  return (
    <div className="p-4 space-y-4">
      <nav className="space-x-4">
        <button
          type="button"
          onClick={() => navigate('/')}
          className="text-blue-500 underline"
        >
          홈
        </button>
        <button
          type="button"
          onClick={() => navigate('/about')}
          className="text-blue-500 underline"
        >
          소개
        </button>
        <button
          type="button"
          onClick={() => navigate('/contact')}
          className="text-blue-500 underline"
        >
          연락처
        </button>
        <button
          type="button"
          onClick={() => navigate('/post/123')}
          className="text-blue-500 underline"
        >
          포스트 123
        </button>
        <button
          type="button"
          onClick={() => navigate('/post/456')}
          className="text-blue-500 underline"
        >
          포스트 456
        </button>
      </nav>
      <hr />
      <MatchedComponent />
    </div>
  );
}

2. 순수 자바스크립트로 라우터 모듈 구현해보기

const routes = [
  { path: /^\/$/, component: () => '<h2>홈 페이지</h2>' },
  { path: /^\/about$/, component: () => '<h2>소개 페이지</h2>' },
  { path: /^\/contact$/, component: () => '<h2>연락처 페이지</h2>' },
  {
    path: /^\/post\/(\d+)$/,
    component: (params) => `<h2>포스트 ID: ${params[1]} 페이지</h2>`,
  },
];

function matchRoute(pathname) {
  let matchedComponent = null;

  routes.some((route) => {
    const match = pathname.match(route.path);
    if (match) {
      matchedComponent = route.component(match);
      return true;
    }
    return false;
  });

  return matchedComponent || '<h2>404 페이지를 찾을 수 없습니다.</h2>';
}

function render(html) {
  document.getElementById('app').innerHTML = html;
}

function navigate(path) {
  window.history.pushState({}, '', path);
  const html = matchRoute(path);
  render(html);
}

// popstate 이벤트 (뒤/앞으로 가기)
window.addEventListener('popstate', () => {
  const html = matchRoute(window.location.pathname);
  render(html);
});

// 초기 렌더링
const html = matchRoute(window.location.pathname);
render(html);

컴파일 언어, 정적 타입 언어

자바스크립트는 동적 타입의 언어로 런타임에서 오류를 발견하고, 타입스크립트는 정적 타입의 컴파일 언어로 코드 작성 단계에서 타입을 체크해 오류를 확인할 수 있고, 미리 타입을 결정하기 때문에 실행속도가 빠르다.

하지만 코드 작성 시 매번 타입을 결정해야 하기 때문에 번거롭고 코드량이 증가하며 컴파일 시간이 오래 걸린다는 단점이 있다.

자바스크립트 superset

자바스크립트 기본 문법에 타입스크립트 문법을 추가한 언어이다. 따라서 유효한 자바스크립트로 작성한 코드는 확장자를 .js 에서 .ts 로 변경하고, 타입스크립트로 컴파일해 변환할 수 있다.

객체지향 프로그래밍 지원

ES6을 포함하여 class, instance, 상속, 모듈 등과 같은 객체지향 프로그래밍 패턴을 제공한다.

타입스크립트를 고려해야 하는 이유

높은 수준의 코드 탐색과 디버깅

타입스크립트는 코드에 목적을 명시하고, 목적에 맞지 않는 타입의 변수나 함수들에서 에러를 발생시켜 버그를 사전에 제거한다. 또한, 코드 자동완성이나 실행 전 피드백을 제공하여 작업과 동시에 디버깅이 가능해 생산성을 높일 수 있다.

자바스크립트 호환

타입스크립트는 자바스크립트와 100% 호환된다. 따라서 프론트엔드 또는 백엔드 어디든 자바스크립트를 사용할 수 있는 곳이라면 타입스크립트도 쓸 수 있다. 타입스크립트는 앱과 웹을 구현하는 자바스크립트와 동일한 용도로 사용가능하며 서버 단에서 개발이 이루어지는 복잡한 대형 프로젝트에서도 빛을 발한다.

강력한 생태계

타입스크립트는 그리 오래되지 않은 언어임에도 강력한 생태계를 가지고 있다. 대부분의 라이브러리들이 타입스크립트를 지원하며 마이크로소프트의 비주얼 스튜디오 코드를 비롯해 각종 에디터가 타입스크립트 관련 기능과 플러그인을 지원한다.

점진적 전환 가능

기존의 자바스크립트 프로젝트를 타입스크립트로 전환하는데 부담이 있다면, 추가 기능이나 특정 기능에만 타입스크립트를 도입함으로써 프로젝트를 점진적으로 전환할 수 있다.

자바스크립트에 주석을 추가하는 것에서부터 시작해 시간이 지남에 따라 코드베이스가 완전히 바뀌도록 준비 시간을 가질 수 있다. 프로젝트의 규모가 크고 복잡할 수록, 유지보수가 중요한 장기 프로젝트일 수록 타입스크립트의 이점이 부각된다.

타입스크립트 장/단점

코드 작성시 매번 타입을 결정해야해서 번거롭고 코드량이 증가하며 컴파일 시간이 오래걸린다는 단점이 있다. 장점은 자바스크립트와 100% 호환되며, 코드에 목적을 명시하고 목적에 맞지않는 타입의 변수나 함수들에서 에러를 발생시켜 버그를 사전에 제거하고, 작업과 동시에 디버깅이 가능해 생산성을 높일 수 있다는 점이다.

제네릭, 맵드 타입,조건부 타입 등의 타입 조작 기능을 이용해 실무에서 자주 사용되는 타입을 만들어 놓은 것

맵드 타입 기반의 유틸리티 타입

맵드 타입 기존에 정의되어 있는 타입을 새로운 타입으로 변환해 주는 문법을 의미한다. 마치 map() API 함수를 타입에 적용한 것과 같은 효과를 가진다.

Partial

특정 객체 타입의 모든 프로퍼티를 선택적 프로퍼티로 바꿔주는 타입

interface Post {
  title: string;
  tags: strng[];
  content: string;
  thumbnailURL?: string;
}

type Partial<T> = {
  [key in keyof T]? T[key];
}

const draft: Partial<Post> = {
  title: '',
  content: '',
}

Required

특정 객체 타입의 모든 프로퍼티를 필수 프로퍼티로 바꿔주는 타입

interface Post {
  title: string;
  tags: string[];
  content: string;
  thumbnailURL?: string;
}

type Required<T> = {
  [key in keyof T]-?: T[key];
}

const withThumbnailPost: Required<Post> = {
  title: '',
  tags: '',
  content: '',
  thumbnailURL: '',
}

Readonly

특정 객체의 타입에서 모든 프로퍼티를 읽기 전용 프로퍼티로 만들어주는 타입

interface Post {
  title: string;
  tags: string[];
  content: string;
  thumbnailURL?:string;
}

type Readonly<T> = {
  readonly [key in keyof T]: T[key];
}

const readonlyPost: Readonly<Post> = {
  title: '',
  tags: '',
  content: '',
}

Pick

Pick<T, K> 객체 타입으로부터 특정 프로퍼티만 딱 골라내는 타입

interface Post {
  title: string;
  tags: string[];
  content: string;
  thumbnailURL?: string;
}

type Pick<T, K extends keyof T> = {
  [key in K]: T[key];
}

const lagacyPost: Pick<Post, 'title' | 'content'> = {
  title: '옛날 글',
  content: '옛날 컨텐츠',
}

Omit

Omit<T, K> 객체 타입으로부터 특정 프로퍼티를 제거하는 타입

interface Post {
  title: string;
  tags: string[];
  content: string;
  thumbnailURL?: string;
}

type Omit<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>>;

const noTitlePost: Omit<Post, 'title'> = {
  content: '',
  tags: [],
  thumbnailURL: '',
}

Record

Record<K, V> 객체 타입을 만들어주는 타입

interface Post {
  title: string;
  tags: string[];
  content: string;
  thumbnailURL?:string;
}

type Record<K extends keyof any, V> = {
  [key in K]: V;
}

type Thumnail = Record<'large' | 'medium' | 'small', {url: string}>;
//type ThumnailRegacy = {
//    large: { url: string };
//    medium: { url: string };
//    small: { url: string };
//    watch: { url: string };
//}

조건부 타입 기반 유틸리티 타입

Exclude

Exclude<T, U> T에서 U를 제거하는 타입

type Exclude<T, U> = T extends U ? never : T;

type A = Exclude<string | boolean, boolean>;
// 1. Exclude<string, boolean>
// 2, Exclude<boolean, boolean>
// 3. string | never
// 4. string

Extract

Extract<T, U> T에서 U를 추출하는 타입

type Extract<T, U> = T extends U ? T : never;
type B = Extract<string | boolean, boolean>
// 1. Extract<string, boolean>
// 2. Extract<boolean, boolean>
// 3. boolean

ReturnType

ReturnType<T> 함수의 반환값 타입을 추출하는 타입

type ReturnType<T extends (...args: any) => any> = T extends (...args: any) => infer R ? R : never;

function funcA() {
  return 'hello';
}

function funcB() {
  return 10;
}

type ReturnA = ReturnType<typeof funcA>
type ReturnB = ReturnType<typeof funcB>