Doo

2025 FE CONF

Hyeong Nim — Sat, 23 Aug 2025 23:05:30 +0900

작년에 비해 축소된 스폰서 규모와 사은품에서 현재의 경제 상황을 엿볼 수 있었습니다. 그럼에도 불구하고, 1년 동안의 고민과 경험을 공유하려는 발표자들, 그리고 새로운 지식에 목마른 참가자들의 열기로 컨퍼런스는 붐볐습니다.

이번 컨퍼런스에서 가장 기대했던 세션은 '모노레포 절망편'이었습니다. 현재 저희 팀이 모노레포 도입을 고려 중이라 더욱 관심이 갔습니다. 과거에 모노레포를 사용하며 겪었던 불편함과 현재의 장점(패키지 공유, CI/CD 간소화) 사이에서 고민하던 저에게 큰 도움이 될 세션이었습니다.

아쉬운 점도 있었습니다. 유명 연사들이 많지 않았고, 일부 세션은 기대만큼 깊이 있는 내용이 아니었습니다. 하지만 개발자로서의 경험이 쌓일수록 작은 인사이트 하나가 서비스 설계에 큰 영향을 준다는 것을 알기에, 이번 컨퍼런스도 분명 의미 있는 시간이었습니다.

전반적으로 아쉬움과 기대가 교차했던 자리였지만, 동료 개발자들과 함께 고민을 나누고 배우는 소중한 경험이었습니다.
제가 들었던 각 세션에 대한 자세한 내용은 아래 있습니다.

스벨트를 통해 리액트 더 잘 이해하기

'memo'를 지울 결심 : React Compiler가 제안하는 미래

중요하지만 긴급하지 않은 일, 그럼에도 계획해야 하는 웹 접근성

음성 인터페이스 개발에서 DX 향상하기: 모델 비교부터 직관적인 인터페이스 설계

1년에 10억 원을 절약한, 강남언니의 SEO 웹 전략 공개

TanStack Query 너머를 향해! 쿼리를 라우트까지 전파시키기

모노레포 절망편, 14개 레포로 부활하기까지 걸린 1년

[정리] React Server Components는 단지 “서버에서 돌리는 컴포넌트”가 아닙니다

Hyeong Nim — Mon, 14 Jul 2025 22:52:51 +0900

처음 React Server Components(RSC)를 접했을 때는 그저 SSR(서버사이드 렌더링)의 새 버전 정도로 생각했습니다.
하지만 최근 Dan Abramov의 글을 읽고 나서야 그 생각이 완전히 바뀌었습니다.

RSC는 단순한 기능이 아니라, 자바스크립트 모듈 시스템의 본질을 다시 바라보게 만드는 프로그래밍 모델이었습니다.

모듈 시스템은 사람을 위한 것입니다

컴퓨터는 모듈을 알지 못합니다. 컴퓨터는 실행 가능한 하나의 프로그램을 필요로 할 뿐이죠.
모듈은 사람이 코드를 더 쉽게 작성하고 이해하기 위해 만든 추상화입니다.

모듈은 다음을 가능하게 합니다:

복잡한 프로그램을 파일 단위로 나눌 수 있게 하고
코드 중 일부만 외부에 노출할 수 있게 하며
동일한 코드를 여러 곳에서 재사용할 수 있게 합니다

JavaScript에서는 이를 import, export 키워드를 통해 구현합니다.
중요한 건 이 키워드들이 실행 시점에 실제로 어떤 의미를 갖느냐입니다.

JavaScript의 import 는 “복사 붙여넣기”가 아닙니다

보통 import는 외부 코드를 “불러오는” 것이라 생각하지만, C의 #include처럼 단순한 복사 개념은 아닙니다.
JavaScript 모듈 시스템은 모듈을 싱글턴(Singleton)으로 처리합니다.
즉, 동일한 모듈이 여러 곳에서 불러와지더라도 실행은 단 한 번만 발생합니다.
이 덕분에 각 모듈은 자신의 내부 상태를 안전하게 유지할 수 있으며, 전체 프로그램은 효율적인 구조로 구성됩니다.

문제는 “두 개의 환경”이 등장할 때 시작됩니다

지금까지 설명한 모듈 시스템은 단일 런타임(예: 브라우저 또는 Node.js)을 전제로 합니다.
하지만 실제 웹 애플리케이션은 백엔드와 프런트엔드라는 두 환경에 걸쳐 실행됩니다.
이 두 환경은 각자 독립적인 모듈 시스템을 갖고 있고, 서로의 메모리에 접근하지 못합니다.
그럼에도 불구하고, 우리는 종종 두 환경 간에 코드를 공유하고 싶어 합니다. 예컨대 유틸 함수, 밸리데이터, 모델 타입 등.

공유하고 싶은 코드 vs 공유하면 안 되는 코드

공유는 쉬워 보입니다. 그냥 같은 파일을 양쪽에서 import 하면 되니까요. 하지만 문제는 “공유하면 안 되는 코드”가 섞여 있을 때 생깁니다. 예를 들어 fs.readFileSync 같은 Node.js 전용 API를 사용한 코드가 프런트엔드에 포함되면, 런타임 오류가 발생합니다.
더 심각한 경우는 서버 비밀 정보가 클라이언트 번들에 그대로 노출되는 경우입니다.

이때 필요한 것이 server-only, client-only 같은 독약(Poison Pill)입니다

이런 문제를 사전에 방지하기 위해, RSC는 특정 모듈이 어느 환경에서만 실행되어야 하는지를 명시적으로 선언할 수 있는 도구를 제공합니다.

// secrets.js
import 'server-only';

export const SECRET = '1234';

이 코드는 프런트엔드 번들에 포함되려 할 경우 빌드 에러를 일으킵니다. 즉, RSC는 “코드 위치”를 결정하지 않지만, “어디에 포함되어선 안 되는지”를 선언적으로 제어할 수 있게 해줍니다.

이 철학은 단순하지만 강력합니다: 잘못된 실행 환경으로의 침투를 예방하려면, 애초에 포함 자체를 막아라.

‘use client’, ‘use server’는 실행 위치를 “바꾸는” 게 아닙니다

많은 개발자들이 'use client'를 컴포넌트 실행 위치를 지정하는 태그라고 오해합니다. 하지만 이 지시어들은 프런트엔드와 백엔드 모듈 시스템 사이의 “문(Door)”을 여는 역할을 합니다.

즉, 'use client'가 선언된 모듈은 서버 코드에서 직접 실행되는 것이 아니라, React가 해당 함수를 스크립트 태그로 프런트엔드에 전달하고 연결할 수 있도록 만듭니다.

// ClientButton.tsx
'use client';
export function sayHello() {
  alert('Hi!');
}

// ServerPage.tsx
import { sayHello } from './ClientButton';

export function Page() {
  return <button onClick={sayHello}>눌러보세요</button>;
}

하나의 프로그램, 두 개의 실행 환경

React Server Components는 이 모든 흐름을 통합합니다.

각 환경은 독립적인 모듈 시스템을 유지합니다.
일반 모듈은 자유롭게 공유되며, 실행 위치는 현재 컨텍스트에 따라 자동 결정됩니다.
특정 환경에만 존재해야 하는 모듈은 server-only, client-only로 제한합니다.
다른 환경의 코드를 참조하고 싶을 땐, 'use client', 'use server'로 문을 엽니다.

결과적으로 RSC는 “하나의 프로그램이 두 환경에서 실행되는 구조”를 안전하고 명확하게 지원하는 모델을 제공합니다.

마무리하며

React Server Components는 “SSR보다 빠른 렌더링”이라는 기능적 개선만을 위한 기술이 아닙니다. 이는 우리가 프런트엔드와 백엔드가 나뉘어 있다는 전통적 사고방식에서 벗어나, “하나의 모듈 시스템이 두 환경에 걸쳐 작동하는 구조”를 어떻게 만들 것인가라는 질문에 대한 실질적인 해답입니다.

프런트와 백을 나누는 것이 아니라, “의도된 실행 위치를 명확히 표현할 수 있는 언어 체계”를 만든 것입니다.
그 언어가 바로 RSC이고, 그 문법이 use client, server-only입니다.

원문 & 참조

https://overreacted.io/how-imports-work-in-rsc/

How Imports Work in RSC — overreacted

A layered module system.

overreacted.io

https://nodejs.org/api/packages.html#conditional-exports

Modules: Packages | Node.js v24.4.0 Documentation

Modules: Packages# Introduction# A package is a folder tree described by a package.json file. The package consists of the folder containing the package.json file and all subfolders until the next folder containing another package.json file, or a folder nam

nodejs.org

Next.js 프로젝트의 SEO 최적화 전략

Hyeong Nim — Sat, 17 May 2025 12:58:45 +0900

안녕하세요, 이번 포스트에서는 Next.js 프로젝트에서 활용할 수 있는 효과적인 SEO 최적화 전략에 대해 이야기해보려고 합니다. 검색 엔진 최적화(SEO)는웹사이트의 가시성을 높이고 유기적 트래픽을 증가시키는 중요한 요소입니다. 특히 네이버와 같은 국내 검색 엔진에서의 노출은 모든 웹 서비스에 매우 중요하죠.

1. 이미지 `alt` 속성 최적화

일반적인 문제점

많은 프로젝트에서 배너 이미지의 alt 속성이 '배너01', '배너02'와 같이 의미 없게 설정되어 있어 SEO에 부정적 영향을 주고 있습니다. 이미지를 검색 결과에 노출하기 위해서는 더 효과적인 방법이 필요합니다.

의미 있는 키워드(예: 제품 카테고리, 제품 특징)로 alt 텍스트를 구성하는 것이 검색엔진 노출에 유리합니다.
SEO 우선순위: <title>, <h1>, URL 일치도, 키워드 밀도, alt, meta, 사용자 체류 시간 등이 복합적으로 작용합니다.
키워드는 페이지 내 여러 위치에서 자연스럽게 반복 노출되는 것이 중요합니다.

// 개선 전
<img src="/banner-image.jpg" alt="배너01" />

// 개선 후
<img src="/banner-image.jpg" alt="신규 제품 출시 기념 프로모션" />

2. 구조화 데이터 위치 및 적용 전략

최적화 방향

모든 페이지에 공통으로 구조화 데이터를 삽입하는 것보다 콘텐츠 목적에 맞는 페이지별 맞춤 삽입이 SEO에 더 유리합니다.
홈페이지, 제품 페이지, 콘텐츠 페이지 등 각각의 목적에 맞는 구조화 데이터를 적용해야 합니다.

효과적인 구현 방법

효율적인 방법: 각 페이지 컴포넌트에서 목적에 맞는 구조화 데이터 적용
지양해야 할 방법: Layout.tsx 같은 공통 컴포넌트에서 모든 페이지에 동일한 구조화 데이터 적용

페이지별 추천 구조화 데이터

상품/제품 페이지
- BreadcrumbList: 사이트 내 현재 페이지 위치 표시
- Product: 제품 정보 구조화
- AggregateRating: 평점 정보
- Review: 리뷰 정보
- ItemList: 이미지 슬라이드용
콘텐츠 페이지
- Article: 일반 콘텐츠 구조화
- HowTo: 프로세스를 보여주는 콘텐츠
홈페이지
- ItemList: 제품/콘텐츠 목록 구조화
- WebSite: 사이트 정보 구조화
- Organization: 조직 정보 구조화

// 예: 제품 페이지의 구조화 데이터 적용
export default function ProductDetail({ product }) {
  return (
    <>
      <script
        type="application/ld+json"
        dangerouslySetInnerHTML={{
          __html: JSON.stringify({
            "@context": "https://schema.org",
            "@type": "Product",
            "name": product.name,
            "image": product.imageUrl,
            "description": product.description,
            "offers": {
              "@type": "Offer",
              "price": product.price,
              "priceCurrency": "KRW"
            }
          })
        }}
      />

      {/* 페이지 콘텐츠 */}
    </>
  );
}

3. Heading 구조 최적화

Heading 태그의 중요성

Heading 태그는 페이지의 구조와 콘텐츠의 계층을 나타내는 중요한 요소입니다.
검색엔진은 Heading 태그를 통해 페이지의 주요 주제와 콘텐츠를 파악합니다.
특히 <h1> 태그는 페이지의 주요 주제를 나타내는 가장 중요한 요소입니다.

효과적인 Heading 구조 설계

핵심 키워드를 명확하게 전달하는 간단한 구조가 효과적입니다.
마케팅 문구나 부가 정보는 하위 Heading 태그에 배치하는 것이 좋습니다.
검색엔진이 이해하기 쉽도록 논리적인 계층 구조를 만드는 것이 중요합니다.

// 일반적인 예시
<h1>무선 이어버드</h1>
<h2>신제품 출시 기념 특별 할인</h2>

4. SSR 적용 영역 확대

SEO 관점에서의 SSR 중요성

네이버 등 국내 검색엔진은 CSR(클라이언트 사이드 렌더링) 영역의 콘텐츠를 잘 인식하지 못하는 경향이 있습니다.
SSR(서버 사이드 렌더링) 처리를 통해 사이트 신뢰도 향상 + 키워드 노출 + 콘텐츠 인덱싱이 가능합니다.

효과적인 SSR 적용 전략

핵심 콘텐츠, 제품 정보, 리뷰 등은 SSR로 처리하여 검색엔진이 인식할 수 있도록 합니다.
단기 프로모션, 광고성 정보는 CSR로 처리하여 검색 결과에 지속적으로 노출되는 것을 방지합니다.

// 프로모션 영역을 클라이언트 컴포넌트로 분리
'use client'
export default function PromotionBanner() {
  // 프로모션 관련 렌더링 로직
}

// 핵심 콘텐츠는 서버 컴포넌트로 구현
export default function MainContent({ content }) {
  return (
    <div>
      <h1>{content.title}</h1>
      <p>{content.description}</p>
      {/* 주요 콘텐츠 정보 */}
    </div>
  );
}

5. `generateMetadata` 기능 활용

Next.js 13 이상에서는 generateMetadata 함수를 사용하여 각 페이지별로 동적 메타데이터를 생성할 수 있습니다.

활용 방법

페이지마다 적절한 title과 meta description을 동적으로 설정
핵심 키워드를 포함한 메타데이터를 구성하여 검색 엔진 최적화

// pages/[slug]/page.jsx
export async function generateMetadata({ params }) {
  // 데이터 가져오기
  const pageData = await fetchPageData(params.slug);

  return {
    title: pageData.title,
    description: pageData.summary,
    openGraph: {
      title: pageData.title,
      description: pageData.summary,
      images: [{ url: pageData.imageUrl }],
    },
  };
}

export default function ContentPage({ params }) {
  // 페이지 컴포넌트 내용
}

최적화 팁

메타 description은 150-160자 내외로 핵심 정보를 담아 작성
타이틀에는 중요 키워드를 앞쪽에 배치
메타데이터를 키워드로 과도하게 채우는 것은 오히려 역효과

결론

Next.js에서 SEO를 최적화하는 것은 지속적인 개선이 필요한 과정입니다. 이 포스트에서 소개한 기법들은 어떤 Next.js 프로젝트에도 적용할 수 있는 범용적인 전략입니다. 특히 한국 시장에서는 네이버 검색엔진에 최적화하는 것이 중요하며, SSR을 적극 활용하고 구조화 데이터를 적절히 적용하는 것이 핵심입니다.

위 전략들을 적용하면 웹사이트의 검색 엔진 노출과 유기적 트래픽 증가에 긍정적인 효과가 있을 것입니다. 프론트엔드 개발자라면 SEO 최적화에 대한 이해가 프로젝트 성공에 큰 도움이 됩니다.

Apollo Client Refetch 구조 개선하기: SSE 알림과 Error 핸들링까지

Hyeong Nim — Mon, 28 Apr 2025 16:46:00 +0900

이번 포스트에서는 Apollo Client를 사용하면서 Refetch를 효율적으로 구성하고, 실시간 알림을 SSE(Server-Sent Events)로 처리하는 방법을 소개합니다. 그리고 그 과정에서 고민했던 ErrorLink, ErrorPolicy 설정, 그리고 Subscription을 사용하지 않은 이유까지 함께 정리합니다.

기존 문제

우리는 Hasura GraphQL을 메인 API 서버로 사용하고 있었습니다.
그런데 서비스 도중 실시간 데이터 갱신이 필요한 순간이 생겼고, 이를 해결하기 위해 "알림 시스템"을 구축해야 했습니다.

처음에는 Hasura의 Subscription 기능을 고려했지만,
비용과 복잡성, 운영 안정성 문제로 Subscription이 아니라 SSE를 이용해 별도 알림 서버를 구축하기로 결정했습니다.

SSE를 통해 알림 수신 및 Refetch 처리

SSE로 알림 메시지를 수신하면, 특정 도메인 그룹에 따라 필요한 데이터를 Refetch하는 구조를 설계했습니다.
여기서 가장 중요한 부분은, 어떤 Query Document를 Refetch할지 명시하지 않아도,
연관 도메인만 지정해서 자동으로 Refetch가 일어나는 구조를 만든 것입니다.

Refetch Link 구조

context: { refetchable: true, refetchGroups: [...] }
➔ Query에 이런 형태로 context를 설정합니다.
Mutation 성공 시 ➔ client.context.refetchGroup 값을 읽어와서 관련된 Query들을 자동으로 Refetch합니다.

덕분에 개발자가 직접 Query Document를 일일이 지정하지 않아도, 도메인 기준으로만 관리하는 깔끔한 구조를 만들 수 있었습니다.

Refetch 도중 발생한 에러 문제

처음에는 이 구조가 잘 작동했지만, 특정 상황에서 문제가 발생했습니다.

예를 들어,

어떤 데이터가 서버에서 삭제되었는데,
SSE 알림을 받아서 Refetch를 시도했을 때,
이미 삭제된 데이터를 다시 요청하게 되면서 404 Not Found 에러가 발생했습니다.

이 에러는 Suspense Query 환경에서는 심각했습니다.

Suspense 사용 중 문제가 된 이유

Suspense 기반 Query는 네트워크 에러를 내부적으로 다시 던져버립니다.
그 결과, 화면이 깨지거나, Not Found 페이지가 의도치 않게 노출되는 문제가 생겼습니다.

결국, 이런 상황에서는 Suspense Query가 적합하지 않다는 결론을 내렸습니다.

해결 방법

Suspense를 제거하고, 일반 useQuery로 전환했습니다.
Apollo의 ErrorPolicy를 all로 변경했습니다.

이렇게 하면, Query 중 일부 필드에 에러가 발생해도 전체 데이터가 undefined로 되지 않고, 가능한 데이터는 유지한 채 에러 정보를 받을 수 있습니다.

ErrorPolicy: 왜 all을 선택했을까?

Apollo Client의 ErrorPolicy는 세 가지 옵션이 있습니다.

none: 에러가 발생하면 아무것도 반환하지 않음.
ignore: 에러를 무시하고 데이터를 반환.
all: 에러와 데이터를 모두 반환.

우리는 all을 선택했습니다. 이유는 다음과 같습니다.

SSE 알림으로 데이터 갱신 중 404 에러가 발생할 수 있기 때문입니다.
그러나 전체 페이지를 깨뜨리고 싶지 않았습니다.
사용자는 이미 가지고 있던 정상 데이터를 보고, 추가적으로 에러 메시지만 참고하면 됩니다.

에러를 감싸면서도 앱 전체 안정성을 지키는 선택이었습니다.

왜 Subscription을 사용하지 않았을까?

Hasura는 WebSocket 기반 Subscription 기능을 제공합니다.
그런데 우리는 Subscription 대신 별도 SSE 서버를 사용하기로 결정했습니다.

그 이유는 다음과 같습니다.

1. 운영 복잡성 최소화

Hasura에 직접 SSE 기능을 추가하거나, Subscription을 확장하려면 커스터마이징이 필요합니다.
이는 서버를 무겁게 만들고, 추후 버전 관리나 운영에서 문제가 될 수 있습니다.

2. 모든 개발자에게 Hasura가 편한 것은 아니다

Hasura는 추상화가 잘 되어 있지만, 커스텀 이벤트나 세밀한 제어가 필요한 경우에는 오히려 불편할 수 있습니다.
별도 서버를 두면 더 자유롭게 이벤트를 발행하고 관리할 수 있었습니다.

3. 버전 업그레이드 리스크

Hasura를 업그레이드하려면 마이그레이션 작업이 필요할 수 있고, 이는 운영 리스크를 키웁니다.
우리는 빠르게 실시간 알림을 구축해야 했기 때문에, 기존 Hasura를 건드리지 않는 쪽을 택했습니다.

4. SSE의 장점

SSE는 HTTP 기반으로 간단하게 구축할 수 있습니다.
서버 리소스를 적게 소모하며, 로드밸런서 설정도 간단합니다.
실시간 알림처럼 단방향 이벤트 전송에 매우 적합합니다.

결국 우리는 Hasura를 메인 API 서버로 유지하면서,
별도 SSE 서버를 운영하여 실시간 알림과 데이터 Refetch를 효율적으로 관리하는 아키텍처를 완성했습니다.

마무리

이번 구조 개선을 통해 우리는

알림 수신 ➔ 관련 도메인만 지정하여 Refetch
일부 에러 발생시에도 전체 서비스는 유지
서버 확장과 운영 리스크 최소화

이 세 가지를 모두 달성할 수 있었습니다.

퍼포먼스 최적화(Next.js App Router)

Hyeong Nim — Mon, 28 Apr 2025 16:09:47 +0900

배경: FSD(Feature-Sliced Design) + Barrel Files

초기 설계는 Feature-Sliced Design (FSD)를 따랐습니다. Feature 단위로 독립성과 가독성을 확보하기 위해, 권장된 가이드에 따라 Barrel Files를 도입했습니다. 하지만 Feature 단위에서 내보내는 Public Index의 양이 많아지면서 필요 없는 코드까지 묶여서 파일이 무거워졌습니다.

결국: 아래와 같이 퍼포먼스에 이슈가 생겼고 Barrel Files를 걷어내기로 했습니다.

초기 로딩 부하 증가
SEO Core Web Vitals 점수 하락

문제 진단: 구조적 성능 병목

과적축된 정적 Public API
SSR이 필요하지 않은 컴포넌트에 Code Splitting이 되어 있지 않아 초기 렌더링 부하

평균 LCP 2.1초, Performance Score 75.88로 UX 관점에서 ‘명백한 이탈 위험 구간’이었습니다.

해결 전략: 구조 레벨부터 리셋

1. Barrel Files 제거 → 명시적 Import

모든 컴포넌트를 개별 import로 변경해, 필요할 때만 필요한 코드만 가져오도록 구조 재설계.

// Before
import { Dialog, Tooltip, Dropdown } from '@/components/common';

// After
import Dialog from '@/components/common/Dialog';
import Tooltip from '@/components/common/Tooltip';
import Dropdown from '@/components/common/Dropdown';

모노레포 패키지의 경우 필요 컴포넌트만 번들링을 통한 트리쉐이킹 100% 활성화
모노레포 앱의 경우 필요한 컴포넌트를 직접 import 하도록 변경
코드 의존성 명확화

2. 초기 렌더링과 무관한 컴포넌트는 Dynamic Import + SSR False

import dynamic from 'next/dynamic';

const Dialog = dynamic(() => import('@/components/common/Dialog'), { ssr: false });

Dialog, Modal, Tooltip 등 인터랙티브 컴포넌트 및 번들사이즈에 방해되는 컴포넌트는 꼭 필요하지 않다면 초기 렌더링 제외
HTML 크기 축소 → Time to First Byte(TTFB) 개선
Core Web Vitals(LCP, FCP) 직접 개선
데이터가 무거운데 자주 방문하는 페이지의 데이터의 경우 FetchPolicy를 'cache-first'로 두어 FCP 개선 (단, 인증을 확인 하기 위해 별도 인증 정보 호출을 'network-only'로 통신)

성과

항목	개선 전	개선 후	변화율
평균 LCP	2.10초	0.68초	▲ 약 67.6% 개선
Performance Score	75.88	90.12	▲ 약 18.8% 개선
페이지당 평균 파일 크기	7.97 kB	6.15 kB	▼ 22.8% 감소
페이지당 First Load JS	745.88 kB	583.27 kB	▼ 21.8% 감소

✅ LCP 0.7초 이하
✅ Performance 90점 이상
✅ 체감 로딩 속도 “즉시 반응” 수준

Next.js App Router에서 prefetch 전략

Hyeong Nim — Mon, 28 Apr 2025 12:37:28 +0900

최근 프로젝트에서는 Next.js의 App Router를 기반으로 웹사이트를 개발했습니다.
이 사이트는 다음과 같은 특징을 가지고 있었습니다:

모든 페이지가 로그인 필수
모든 경로가 dynamic route (export const dynamic ='force-dynamic')

초기에는 prefetch에 대해 깊게 고려하지 않고, 기본 <Link>만 사용했습니다.
하지만 시간이 지날수록 성능 이슈를 체감하게 되었고, prefetch 전략을 개선하여 사이트를 훨씬 최적화할 수 있었습니다.

오늘은 그 경험을 정리해보려고 합니다.

프로젝트의 초기 상황

Next.js App Router는 <Link>를 사용할 때 기본적으로 prefetch를 수행합니다.
이 때 prefetch는 별도의 API 호출을 발생시키는 것이 아니라, Server Component의 결과물(Flight Response) 을 미리 받아오는 형태입니다.

Network 패널에서 보면 /project/[id], /approval/[id] 같은 dynamic route로 Server Component를 다운로드 받는 요청만 발생하고 별도 fetch API 요청이나 데이터 호출은 발생하지 않았습니다.

또한, 브라우저의 Network Connection 관점에서도 SSE나 websocket 같은 지속적인 연결은 관찰되지 않았습니다.

요약하면,
prefetch가 별도 API 트래픽을 증가시키진 않았지만,
dynamic route가 많은 환경에서는 불필요한 Server Component 다운로드로 네트워크 비용이 커지고 있었습니다.

무슨 문제가 있었을까?

사이트의 특성상:

하나의 페이지에 수십~수백 개의 dynamic 링크가 등장하는 경우가 많았고, 각 링크가 개별적으로 prefetch되면서 필요하지 않은 Server Component까지 대량으로 다운로드하는 상황이 발생했습니다.

결국 이런 문제가 나타났습니다:

페이지 이동을 하지 않아도 브라우저 네트워크에 부하
렌더링과 리소스 소모가 불필요하게 증가
실제로 이동하려는 순간보다 먼저 대량의 데이터를 받아 메모리 사용량이 증가
특히 모바일 네트워크 환경에서는 체감 속도가 급격히 느려짐

Prefetch 전략 수립

문제를 인식한 후, 다음과 같은 전략을 세웠습니다.

1. 기본 prefetch 끄기

우선, <Link> 컴포넌트에 기본 prefetch를 끄기 시작했습니다.

<Link href={`/project/${project.id}`} prefetch={false}>
  {project.name}
</Link>

사용자가 직접 클릭하거나 명확한 액션을 취하기 전까지는 prefetch를 수행하지 않게 했습니다.

2. 명시적 prefetch 적용

필요한 경우에만 prefetch를 수동으로 트리거했습니다.
예를 들어 사용자가 해당 링크를 hover하거나 focus했을 때 prefetch를 실행합니다.

"use client";
import { useRouter } from '@shared/navigation';

export default function ProjectItem({ id, name }: { id: string, name: string }) {
  const router = useRouter();

  const handleMouseEnter = () => {
    router.prefetch(`/project/${id}`);
  };

  return (
    <Link href={`/project/${id}`} prefetch={false} onMouseEnter={handleMouseEnter}>
      {name}
    </Link>
  );
}

이렇게 하면:

사용자가 실제로 접근할 가능성이 높은 링크만 prefetch
네트워크와 브라우저 메모리 사용을 최소화
결과적으로 성능이 훨씬 가벼워졌습니다.

적용 이후 결과

Prefetch 전략을 개선한 후, 다음과 같은 긍정적인 변화를 경험할 수 있었습니다.

항목	변경 전	변경 후
다운로드하는 데이터 양	많음 (불필요한 Server Component 다운로드)	필요한 것만 최소 다운로드
네트워크 대역폭 사용량	높음	감소
페이지 렌더링 속도	느림 (특히 리스트 많은 화면)	빨라짐
모바일 체감 속도	느림	개선

특히, dynamic route가 많은 환경에서는 prefetch 제어만으로 체감 속도가 개선되었습니다.

결론

Next.js App Router는 기본적으로 prefetch 기능을 제공합니다.
이는 사용자 경험을 빠르게 만드는 강력한 무기이지만,

dynamic route가 많고, 로그인 세션이 필요한 사이트에서는
prefetch를 무조건 사용하는 것이 오히려 네트워크, 메모리 부하를 키울 수 있습니다.

따라서:

언제 prefetch를 수행할지
언제 prefetch를 제한할지

명확한 전략을 세우는 것이 필수입니다.

Next.js에서 next/image를 사용하는 이유와 optimize 설정에 대한 고민

Hyeong Nim — Mon, 28 Apr 2025 11:51:10 +0900

Next.js를 사용하면서 많은 사람들이 자연스럽게 선택하는 컴포넌트가 있습니다. 바로 next/image입니다.
이미지 관리를 자동화해주고 성능 최적화까지 해주니, 정말 매력적인 기능이죠.
하지만 실제 운영 환경에서는 이 next/image가 예상치 못한 문제를 일으킬 수도 있습니다.
특히 optimize: true 설정을 사용할 때 주의해야 할 점들이 있었습니다.

오늘은 제가 이 문제를 고민했던 경험을 바탕으로, 왜 next/image를 쓰는지, 그리고 optimize 설정을 현명하게 다루는 방법까지 정리해보려고 합니다.

왜 next/image를 사용하는가?

먼저, next/image가 제공하는 장점은 정말 강력합니다.

자동 최적화 (Optimization)
요청하는 디바이스에 맞게 이미지를 리사이즈하거나, WebP, AVIF 같은 최신 포맷으로 변환하여 최적화된 이미지를 전송해줍니다. 결과적으로 페이지 로딩 속도가 크게 향상됩니다.
지연 로딩 (Lazy Loading)
사용자가 화면에 스크롤하기 전까지 이미지를 로딩하지 않습니다. 이로 인해 초기 로딩이 가벼워지고, LCP(Largest Contentful Paint) 같은 웹 퍼포먼스 지표도 좋아집니다.
Placeholder 지원 (Blur-up)
이미지를 로딩하는 동안 흐릿한 미리보기 이미지를 제공하여, 사용자 경험(UX)을 부드럽게 만듭니다.
Responsive srcset 자동 생성
다양한 디바이스 해상도에 맞게 자동으로 srcset을 생성합니다. 고해상도 디스플레이(iPhone, 4K 모니터 등)에서도 선명한 이미지를 제공할 수 있습니다.
레이아웃 안정성 확보
height와 width를 명시적으로 지정하게 함으로써 레이아웃 시프트(CLS)를 방지합니다.

이 모든 기능을 별도 설정 없이, 단순히 next/image를 사용하기만 하면 얻을 수 있다는 점은 정말 매력적이었습니다.

optimize: true의 그림자

하지만 optimize: true 설정을 켜고 운영해보면서 몇 가지 중요한 문제를 발견했습니다.

next/image는 optimize가 활성화되었을 때, 서버에서 다음 작업을 수행합니다.

원본 이미지를 메모리에 올림
리사이징
포맷 변환 (WebP, AVIF 등)
압축(quality 조정)

이 과정은 CPU와 메모리 자원을 상당히 많이 소모합니다. 특히 다음과 같은 상황에서는 위험이 커집니다.

고해상도 원본 이미지를 처리할 때
동시에 많은 이미지 최적화 요청이 들어올 때
서버 메모리가 충분하지 않은 경우

이미지 한 장 최적화에 5~10배의 메모리 사용이 발생할 수 있고, 이게 겹치면 서버 메모리가 터지면서 OOM(Out of Memory) 크래시가 발생할 수 있습니다.

실제로 대규모 트래픽을 처리하는 서비스나, 이미지가 많은 서비스에서는 optimize가 켜진 상태로 서버를 운영하면 메모리 부족 문제를 경험하는 경우가 적지 않습니다.

그렇다면 어떻게 해야 할까?

저는 다음과 같은 방향으로 해결책을 고민했습니다.

1. 외부 이미지 최적화 서비스 사용

next/image는 자체 최적화(optimize)를 끄고(optimize: false) 대신 외부 최적화 서비스를 연결할 수 있습니다.

대표적으로:

Vercel의 Image Optimization
Cloudflare Images
Imgix
ImageKit

이런 서비스는 고성능으로 이미지 최적화를 해주고, 글로벌 CDN에 캐싱까지 해주기 때문에 서버 부하를 거의 0에 가깝게 만들 수 있습니다.

// next.config.js
module.exports = {
  images: {
    loader: 'imgix', // 또는 'cloudinary', 'custom' 등
    path: 'https://your-image-service.com/',
  },
};

이렇게 설정하면 Next.js 서버는 최적화 작업을 하지 않고, 외부 서비스를 통해 최적화된 이미지를 바로 서빙합니다.

2. 서버 메모리 확장

가장 단순한 방법은 서버 사양을 올리는 것입니다. 메모리와 CPU를 확장하면 어느 정도 최적화 부하를 견딜 수 있습니다.
하지만 이 방법은 비용이 기하급수적으로 증가할 수 있어 장기적인 해결책으로는 추천하지 않습니다.

3. 이미지 사전 최적화 (Preprocessing)

빌드 시점이나 업로드 시점에 미리 이미지를 최적화해두고, 운영 서버에서는 가공 없이 바로 서빙하는 방법입니다.
예를 들면, CMS에 이미지를 업로드할 때 sharp 같은 라이브러리로 미리 리사이징/압축을 걸어두는 식입니다.

결론

next/image는 현대 프론트엔드 개발자에게 정말 강력한 도구입니다.
특히 자동 최적화 기능(optimize)은 페이지 속도 개선과 사용자 경험 향상에 큰 도움이 됩니다.

하지만,
optimize: true는 서버에 적지 않은 부담을 준다는 것을 반드시 기억해야 합니다.

작은 프로젝트, 저트래픽 서비스 → 그냥 optimize를 켜고 쓰는 것도 OK
중대형 서비스, 고트래픽 사이트 → optimize를 끄고 외부 이미지 최적화 서비스를 고려해야 합니다.

실시간 데이터 갱신을 위한 SSE(Server-Sent Events)와 WebWorker 활용기

Hyeong Nim — Mon, 28 Apr 2025 11:45:32 +0900

프로젝트를 진행하면서, 전자결재 시스템과 같은 상태 기반 데이터를 실시간으로 갱신해야 하는 요구사항이 생겼습니다. 예를 들면, 사용자가 요청한 결재가 승인되거나 거절될 때 그 상태가 즉시 화면에 반영되어야 했습니다.
이를 위해 저희는 여러 기술적 대안을 고민했고, 최종적으로 Server-Sent Events(SSE) 를 사용하기로 결정했습니다.

왜 WebSocket이 아닌 SSE를 선택했을까?

처음에는 자연스럽게 WebSocket을 떠올렸습니다. WebSocket은 양방향 통신이 가능하고, 대규모 실시간 애플리케이션(예: 채팅 서비스)에서는 훌륭한 선택이 될 수 있습니다. 하지만 우리의 경우는 조금 달랐습니다.

서버 → 클라이언트 방향의 알림만 필요했습니다. (ex: 결재 상태 변경 알림)
클라이언트가 서버에 실시간으로 메시지를 보낼 필요는 없었습니다.
WebSocket을 사용하면 연결 유지 및 관리 비용이 더 높아지고, 구현 복잡도가 증가합니다.

즉, 단방향 스트리밍만 필요한 상황이었기 때문에, 더 가볍고 간단한 SSE(Server-Sent Events) 가 딱 맞는 선택이었습니다.

SSE 사용 시 고려한 점

SSE는 본질적으로 HTTP 기반이기 때문에 연결이 끊어질 수 있습니다. 특히 다음과 같은 상황을 고려해야 했습니다.

사용자의 네트워크가 일시적으로 끊겼다가 복구되는 경우
브라우저가 일시적으로 리소스를 중단하거나 복구하는 경우
서버 측 유지 관리나 네트워크 이슈로 인해 세션이 끊기는 경우

이런 상황을 대비해 다음과 같은 정책을 수립했습니다.

재시도 주기(retry interval) : 기본적으로 연결이 끊어진 경우 3초 후 재시도를 하도록 설정했습니다.
최대 재시도 횟수 : 무한히 재시도하지 않도록, 최대 10회까지 재시도 후 실패로 처리했습니다.
서버가 retry 값을 명시적으로 내려주는 경우 그 값을 반영하여 유연하게 재시도 간격을 조정할 수 있도록 했습니다.

이렇게 함으로써 네트워크 환경이 불안정한 상황에서도 사용자가 자연스럽게 서비스를 이용할 수 있도록 했습니다.

메인 스레드 부하를 줄이기 위해 WebWorker 활용

SSE는 기본적으로 브라우저의 메인 스레드에서 실행됩니다. 하지만 다음과 같은 문제가 발생할 수 있었습니다.

사용자가 페이지를 이동하거나 다른 작업을 수행할 때, 메인 스레드에서 SSE 연결 관리 로직이 잠깐 멈추거나 딜레이 되는 현상
그로 인해 사용성 저하나 예상치 못한 오류 발생 가능성

이를 방지하기 위해 WebWorker를 도입했습니다.

SSE 연결 및 이벤트 수신 로직을 WebWorker 내부에서 실행하도록 했습니다.
메인 스레드는 UI 렌더링과 사용자 입력 처리에만 집중할 수 있게 했습니다.
Worker는 SSE 연결 상태를 모니터링하고, 메시지가 오면 메인 스레드로 전달(postMessage)하는 구조로 구현했습니다.

덕분에 사용자 경험(UX)이 매우 부드럽게 유지되었고, 특히 모바일 환경에서도 네비게이션 중 끊김 없이 실시간 알림이 잘 동작하는 결과를 얻을 수 있었습니다.

마치며

이번 경험을 통해 단방향 실시간 갱신이 필요한 경우 SSE를 적극 고려해볼 수 있다는 확신을 얻었습니다. 또한, 브라우저 메인 스레드를 가볍게 유지하고 안정적인 실시간 연결을 유지하기 위해 WebWorker를 통한 비동기 처리가 얼마나 중요한지도 다시 한번 체감할 수 있었습니다.

JSON-Patch: 대규모 JSON 관리를 위한 효율적인 도구

Hyeong Nim — Wed, 22 Jan 2025 17:27:34 +0900

현대의 소프트웨어 개발 환경에서는 대규모 JSON 데이터를 관리하고 동기화하는 일이 빈번합니다. 특히 OpenAPI와 같은 API 명세서를 다룰 때, 각 버전 간의 변경 사항을 추적하고 효율적으로 관리하는 것이 중요합니다. 이런 작업을 위해 JSON-Patch는 매우 유용한 도구로 자리 잡고 있습니다. 이번 글에서는 JSON-Patch란 무엇인지, 그리고 제가 경험한 사례를 통해 이를 어떻게 효과적으로 활용할 수 있는지 공유하고자 합니다.

JSON-Patch란 무엇인가?

JSON-Patch는 JSON 문서의 특정 부분을 추가, 삭제, 변경, 교체할 수 있도록 설계된 경량화된 표준입니다. RFC 6902로 정의된 이 표준은 다음과 같은 특징을 가지고 있습니다:

작은 크기: 변경 사항만을 포함하기 때문에 네트워크 사용량을 최소화합니다.
구조화된 형식: 명령(operation)과 경로(path)를 기반으로 JSON 데이터를 수정합니다.
범용성: 다양한 언어와 프레임워크에서 사용 가능합니다.

JSON-Patch는 기본적으로 아래와 같은 6가지 연산자를 지원합니다:

add: 새로운 값을 추가합니다.
remove: 값을 제거합니다.
replace: 값을 교체합니다.
move: 값을 다른 위치로 이동합니다.
copy: 값을 복사합니다.
test: 특정 경로의 값이 예상한 값과 일치하는지 확인합니다.

다음은 간단한 예제입니다:

[
  { "op": "replace", "path": "/name", "value": "John Doe" },
  { "op": "add", "path": "/age", "value": 30 },
  { "op": "remove", "path": "/address" }
]

JSON-Patch와 OpenAPI: 실전 사례

최근에 OpenAPI 명세서를 커스터마이징할 일이 있었습니다. Swagger 문서를 받고 이를 클라이언트 사이드에서 수정해야 하는 상황이었는데, 이때 json-joy/lib/json-patch 라이브러리를 활용했습니다. 이 라이브러리는 JSON-Patch 표준을 구현한 강력한 도구로, 변경 사항을 효율적으로 관리할 수 있도록 도와줍니다.

OpenAPISpecification 클래스 설계

응집도를 높이기 위해 OpenAPISpecification이라는 클래스를 설계했습니다. 이 클래스는 Swagger 문서와 JSON-Patch를 다룰 수 있는 다양한 메서드를 제공합니다:

compare(spec1, spec2): 두 개의 명세서를 비교하여 차이를 반환합니다.
diff(): 현재 명세서와 다른 버전의 차이를 계산합니다.
get(path): 특정 경로의 값을 가져옵니다.
update(patch): JSON-Patch를 적용하여 명세서를 업데이트합니다.

특히, 이 클래스는 다음과 같은 방식으로 활용되었습니다:

명세서 버전 관리: 변경 사항을 JSON-Patch 형태로 기록하여, 이전 버전과의 차이를 명확히 확인하고 필요한 경우 쉽게 롤백할 수 있었습니다.
자동화된 업데이트: 클라이언트 애플리케이션에서 Swagger 명세서를 동적으로 수정해야 할 때, update 메서드를 통해 간단히 JSON-Patch를 적용할 수 있었습니다. 예를 들어, 특정 API 경로의 설명을 수정하거나 새로운 필드를 추가하는 작업이 수월해졌습니다.
테스트 및 검증: compare 메서드를 활용하여 명세서 간의 변경 사항을 검증하고, 누락된 수정 사항이나 예상치 못한 변경을 쉽게 발견할 수 있었습니다. 이를 통해 배포 전에 변경 사항의 안전성을 높일 수 있었습니다.

아래는 이를 활용한 주요 시나리오 중 하나입니다:

// 명세서 간의 차이점 확인
const spec1 = { paths: { "/users": { get: { description: "Get users" } } } };
const spec2 = { paths: { "/users": { get: { description: "Retrieve users list" } } } };

const openAPISpec = new OpenAPISpecification(spec1);
const patch = openAPISpec.diff(spec2);
console.log(patch);
// 결과: [ { op: 'replace', path: '/paths/users/get/description', value: 'Retrieve users list' } ]

// JSON-Patch를 적용하여 명세서 업데이트
openAPISpec.update(patch);
console.log(openAPISpec.spec);
// 업데이트된 명세서 출력

4. 팀 협업 향상: 프론트엔드와 백엔드 개발자 간에 명확한 통신 규칙을 정의하고, 서로 JSON-Patch를 주고받으며 효율적으로 대규모 JSON 데이터를 관리할 수 있었습니다. 예를 들어, 백엔드에서는 Spring 기반 라이브러리를 사용해 클라이언트가 보낸 패치를 적용하고, 클라이언트는 이를 UI에 실시간 반영했습니다.

JSON-Patch의 장점

효율성: 변경 사항만 처리하기 때문에 대규모 데이터 관리에 적합합니다.
유연성: 다양한 언어와 플랫폼에서 사용할 수 있습니다.
협업 향상: 클라이언트와 서버 간의 명확한 통신 규칙을 설정할 수 있습니다.

마무리

JSON-Patch는 단순하면서도 강력한 도구로, 특히 대규모 JSON 데이터를 다루는 환경에서 효율성을 극대화할 수 있습니다. 제가 경험한 OpenAPI 명세서 커스터마이징 사례는 이를 잘 보여주는 예입니다. 만약 JSON 데이터를 효과적으로 관리하고 싶은 개발자라면 JSON-Patch를 적극적으로 활용해 보시길 권장합니다.

더 나아가, 이러한 사례를 통해 데이터 관리의 효율성을 높이고, 팀 간 협업을 강화할 수 있는 방법을 고민해 보세요. 이 글이 JSON-Patch를 활용하고자 하는 개발자들에게 작은 영감이 되길 바랍니다.

KeycloakJs를 이용한 다중 계정 전환 Web Component개발기

Hyeong Nim — Wed, 22 Jan 2025 12:28:53 +0900

프로젝트 개요

다수의 사내 서비스에 공통으로 사용할 수 있는 다중 계정 전환 컴포넌트를 10일 이내에 개발해야 했습니다.
Keycloak에 대한 사전 지식이 없는 상태였으며, 관리자 권한도 없이 백엔드 인증 담당자와의 협업만으로 진행해야 했습니다.

이 프로젝트의 주요 목표는 다음 두 가지였습니다.

호스트 서비스로부터 완전히 독립된 형태로 제작 (스타일 및 스크립트 충돌 방지)
SSO 또는 인증(Keycloak)에 대한 이해가 없는 개발자도 쉽게 사용할 수 있도록 구현

컴포넌트 요구사항

개발 과정에서 기능은 점진적으로 확장되었으며, 최종 요구사항은 다음과 같습니다.

프로필 이미지 표시
hover 시 유저 정보 표시
click 시 유저 정보 + 계정 리스트 + 계정 전환 모달
전체 로그아웃 기능
계정 전환/로그아웃 시 다른 탭에 알림 Dialog 노출
display: none 상태에서도 모달 동작 유지
client_id, redirect_uri 등의 파라미터 동적 주입 가능
계정 전환 시 prompt, select_account query parameter 포함

프로젝트 디자인

lit-element-starter-ts 기반으로 프로젝트 구성
주요 컴포넌트: modal, popover, sso-profile, sso-userinfo-popover, sso-userinfo-modal
<script>를 통해 import한 뒤 <sso-profile />로 사용 가능
Typescript/React 사용자 지원을 위한 .d.ts 제공
환경변수는 <script id="...">{...}</script> 태그를 통해 전달, 내부적으로 기본값과 병합하여 사용
Popover 위치 계산은 Floating UI 활용
모달은 Shadow DOM 외부(document.body)에 렌더링하여 독립성 확보
Web Component 스타일링 문제 해결을 위해 모든 요소에 part 제공
Rollup을 통해 UMD, ESM 빌드 및 단일 파일 번들 제공

이슈

1. keycloak에 대해 익숙하지 않음

keyCloack을 init할 때 login-required, check-sso를 선택할 수 있는데 모든 서비스는 로그인이 됐다고 가정하고 Sso만 검증할 수 있는 check-sso를 사용해야 했습니다. check-sso의 기본 동작을 이해하고 있지 않아 동작 방식을 이해해야 했고 시간이 소요됐습니다.

await keycloak.init({
    onLoad: 'check-sso',
    silentCheckSsoRedirectUri: `${location.origin}/silent-check-sso.html`
});

check-sso는 iframe을 만들어 계정 전환, 로그아웃이 됐을 때 이벤트를 받아야 하는데 silent-check-sso.html을 만들고 아래 내용과 같은 형태를 담으라고 적혀있었습니다 (keycloak adapter 링크). 인증이 됐다면, keycloak 서버에서 받은 token을 전달해주는 역할이라고 하지만 전체적인 흐름이 없었기에 이해하는데 어려움이 있었습니다.

<html><body><script>parent.postMessage(location.href, location.origin)</script></body></html>

로그아웃이 발생했을 때 onAuthLogout으로 이벤트를 받을 수 있는데, 이 때 로그아웃이 아닌 계정전환을 하더라도 1번 계정은 로그아웃되고 2번 계정이 로그인 됐다면 이벤트가 발생하여 어떤 Alert를 띄울지 판단하는데 해당 기능이 필요했습니다.
KeycloakJs에서는 별도의 checkSso를 제공하지 않았고, 이를 해결하기 위해 customAdapter를 만들게 되었습니다.

await keycloak.init({
    ...,
    adapter: MyKeycloakAdapter,
});

결과론적으로 onAuthLogout시에 필요한 this.MyKecloakAdapter.checkSso()를 호출했고 그 내부 로직에는 CheckSso에 사용되는 KeycloakJs코드를 복붙하여 수정하여 사용했습니다. 생각보다 JS파일 자체는 작았고, 아래 부분이 필요하여 조건문 중 필요한 부분만 사용했습니다. (ResponseMode에 fragment와 query가 있었고 fragment 부분만 남겨두거나 등등)

   var checkSsoSilently = function() {
                var ifrm = document.createElement("iframe");
                var src = kc.createLoginUrl({prompt: 'none', redirectUri: kc.silentCheckSsoRedirectUri});
                ifrm.setAttribute("src", src);
                ifrm.setAttribute("title", "keycloak-silent-check-sso");
                ifrm.style.display = "none";
                document.body.appendChild(ifrm);

                var messageCallback = function(event) {
                    if (event.origin !== window.location.origin || ifrm.contentWindow !== event.source) {
                        return;
                    }

                    var oauth = parseCallback(event.data);
                    processCallback(oauth, initPromise);

                    document.body.removeChild(ifrm);
                    window.removeEventListener("message", messageCallback);
                };

                window.addEventListener("message", messageCallback);
            };

    function parseCallback(url) {
        var oauth = parseCallbackUrl(url);
        if (!oauth) {
            return;
        }

        var oauthState = callbackStorage.get(oauth.state);

        if (oauthState) {
            oauth.valid = true;
            oauth.redirectUri = oauthState.redirectUri;
            oauth.storedNonce = oauthState.nonce;
            oauth.prompt = oauthState.prompt;
            oauth.pkceCodeVerifier = oauthState.pkceCodeVerifier;
        }

        return oauth;
    }

    function parseCallbackUrl(url) {
        var supportedParams;
        switch (kc.flow) {
            case 'standard':
                supportedParams = ['code', 'state', 'session_state', 'kc_action_status'];
                break;
            case 'implicit':
                supportedParams = ['access_token', 'token_type', 'id_token', 'state', 'session_state', 'expires_in', 'kc_action_status'];
                break;
            case 'hybrid':
                supportedParams = ['access_token', 'token_type', 'id_token', 'code', 'state', 'session_state', 'expires_in', 'kc_action_status'];
                break;
        }

        supportedParams.push('error');
        supportedParams.push('error_description');
        supportedParams.push('error_uri');

        var queryIndex = url.indexOf('?');
        var fragmentIndex = url.indexOf('#');

        var newUrl;
        var parsed;

        if (kc.responseMode === 'query' && queryIndex !== -1) {
            newUrl = url.substring(0, queryIndex);
            parsed = parseCallbackParams(url.substring(queryIndex + 1, fragmentIndex !== -1 ? fragmentIndex : url.length), supportedParams);
            if (parsed.paramsString !== '') {
                newUrl += '?' + parsed.paramsString;
            }
            if (fragmentIndex !== -1) {
                newUrl += url.substring(fragmentIndex);
            }
        } else if (kc.responseMode === 'fragment' && fragmentIndex !== -1) {
            newUrl = url.substring(0, fragmentIndex);
            parsed = parseCallbackParams(url.substring(fragmentIndex + 1), supportedParams);
            if (parsed.paramsString !== '') {
                newUrl += '#' + parsed.paramsString;
            }
        }

        if (parsed && parsed.oauthParams) {
            if (kc.flow === 'standard' || kc.flow === 'hybrid') {
                if ((parsed.oauthParams.code || parsed.oauthParams.error) && parsed.oauthParams.state) {
                    parsed.oauthParams.newUrl = newUrl;
                    return parsed.oauthParams;
                }
            } else if (kc.flow === 'implicit') {
                if ((parsed.oauthParams.access_token || parsed.oauthParams.error) && parsed.oauthParams.state) {
                    parsed.oauthParams.newUrl = newUrl;
                    return parsed.oauthParams;
                }
            }
        }
    }

    function parseCallbackParams(paramsString, supportedParams) {
        var p = paramsString.split('&');
        var result = {
            paramsString: '',
            oauthParams: {}
        };
        for (var i = 0; i < p.length; i++) {
            var split = p[i].indexOf("=");
            var key = p[i].slice(0, split);
            if (supportedParams.indexOf(key) !== -1) {
                result.oauthParams[key] = p[i].slice(split + 1);
            } else {
                if (result.paramsString !== '') {
                    result.paramsString += '&';
                }
                result.paramsString += p[i];
            }
        }
        return result;
    }

2. Cross origin 문제

개발 중에는 silent-check-sso.html의 orgin이 기존 localhost에 동일하게 serving하고 있었지만 배포 이후 특정 URL에서 서빙하다보니 메시지가 정상적으로 받아지지 않았습니다. 디버깅을 위해 브라우저 디버기을 했고 이벤트 리스너에서 받은 message의 event.data가 token이 아닌 알 수 없는 내용이 왔고 postMessage가 정상적으로 되지 않고 있다고 생각했습니다.
그리고 해결을 위해 아래와 같이 targetOrigin을 *로 변경하였습니다.

<html><body><script>parent.postMessage(location.href, '*')</script></body></html>

둘째로 keyCloak.init({onLoad: 'check-sso'})를 할 때 checkSsoSliently()를 호출했는데,

  var checkSsoSilently = function() {
                var ifrm = document.createElement("iframe");
                var src = kc.createLoginUrl({prompt: 'none', redirectUri: kc.silentCheckSsoRedirectUri});
                ifrm.setAttribute("src", src);
                ifrm.setAttribute("title", "keycloak-silent-check-sso");
                ifrm.style.display = "none";
                document.body.appendChild(ifrm);

                var messageCallback = function(event) {

                    if (event.origin !== window.location.origin || ifrm.contentWindow !== event.source) {
                       return;
                    }

		// logic

이벤트를 받았을 때 event.origin과 window.location.origin이 동일하지 않아 init을 할 수 없었습니다. pnpm patch를 통해 'event.origin !== window.location.origin' 부분만 'kc.silentCheckSsoRedirectUri.includes(event.origin)'으로 변경하여 checkSilentSsoRedirectUri로부터 event.origin이 왔는지 검증하는 로직으로 변경하였습니다.

3. End of Thrid-party cookies

몇몇 브라우저에서 SameSite 정책으로 인해 CheckSso를 확인할 수 없었습니다. 크롬에서 작업을 끝난 후에 다른 브라우저를 확인했을 때 아래와 같이 modern browser에서 iframe과 cookie에 강하게 의존하여 동작하지 않았습니다. SameSite가 아닌 경우에도 이용할 수 있는 방법을 찾았지만 Chrome 또한 2025년 상반기에 해당 기능을 block할 계획을 갖고 있다고 발표했고 만들고 나서 아래와 같은 정보를 알게되었습니다.

일부 브라우저의 최신 버전에서는 Chrome의 SameSite나 완전히 차단된 타사 쿠키와 같이 타사가 사용자를 추적하지 못하도록 다양한 쿠키 정책이 적용됩니다. 이러한 정책은 시간이 지남에 따라 더 제한적이 될 가능성이 높으며 다른 브라우저에서도 채택될 것입니다. 결국 타사 컨텍스트의 쿠키는 브라우저에서 완전히 지원되지 않고 차단될 수 있습니다. 결과적으로 영향을 받는 어댑터 기능은 궁극적으로 더 이상 지원되지 않을 수 있습니다."SameSite=Lax by Default" 정책이 있는 브라우저SSL/TLS 연결이 Keycloak 측과 애플리케이션 측에 구성된 경우 모든 기능이 지원됩니다. 예를 들어, Chrome은 버전 84부터 영향을 받습니다.타사 쿠키가 차단된 브라우저Silent는 check-sso 지원되지 않으며 기본적으로 일반(비침묵)으로 돌아갑니다 . 이 동작은 메서드 에 전달된 옵션을 check-sso설정하여 변경할 수 있습니다 . 이 경우 제한적인 브라우저 동작이 감지되면 완전히 비활성화됩니다.Regular check-sso도 영향을 받습니다. Session Status iframe이 지원되지 않으므로 어댑터가 초기화될 때 Keycloak으로 추가 리디렉션을 수행하여 사용자의 로그인 상태를 확인해야 합니다. 이 확인은 iframe을 사용하여 사용자가 로그인했는지 여부를 알려주고 리디렉션은 사용자가 로그아웃한 경우에만 수행되는 표준 동작과 다릅니다.

Google은 2024년에 모든 Chrome 사용자를 대상으로 타사 쿠키를 종료할 예정이며, Safari에서는 이미 기본적으로 비활성화되어 있습니다. 이것이 당신에게 어떤 영향을 미치는지 살펴보겠습니다.
우선, ID 서버와 앱이 동일한 루트 도메인을 공유하는 경우 영향을 받지 않습니다.
예를 들어, 다음과 같은 경우: 귀하의 앱은 www.example.com 또는 dashboard.example.com에 호스팅됩니다.예를 들어 Keycloak와 같은 귀하의 ID 서버는 auth.example.com에 호스팅됩니다.
당신은 영향을 받지 않습니다 ✅. 실제로 www.example.com, dashboard.example.com 및 auth.example.com은 모두 동일한 루트 도메인인 example.com을 공유합니다. 반면에, 당신이 다음의 경우에 있다면:
귀하의 앱은 www.examples.com 또는 dashboard.example.com에 호스팅됩니다.귀하의 ID 서버는 auth.sowhere-else.com에 호스팅됩니다.

참조

https://unpkg.com/browse/keycloak-js@19.0.1/dist/keycloak.mjs

UNPKG - keycloak-js

unpkg.com

https://www.keycloak.org/securing-apps/javascript-adapter#_modern_browsers

Keycloak JavaScript adapter - Keycloak

In some situations, you may need to run the adapter in environments that are not supported by default, such as Capacitor. To use the JavasScript client in these environments, you can pass a custom adapter. For example, a third-party library could provide s

www.keycloak.org

https://docs.oidc-spa.dev/resources/end-of-third-party-cookies

End of third-party cookies | OIDC SPA

Resources End of third-party cookies TL;DR; It's mostly inconsequential. Google is ending third-party cookies for all Chrome users in 2024 and are already disabled by default in Safari. Let's see how it might affect you. First of all, if your identity s

docs.oidc-spa.dev

Doo