1. 문제 상황 (The Problem)

서비스 내에 영상 다운로드 기능을 구현했고, PC 및 일반 모바일 브라우저(Chrome, Safari)에서는 기기 저장소에 파일이 잘 저장되는 것을 확인했습니다. 하지만 카카오톡 인앱 브라우저로 접속했을 때 기이한 현상이 발생했습니다.

• ✅ "다운로드를 시작합니다" -> "다운로드가 완료되었습니다" Toast 메시지는 정상 출력.
• ✅ 개발자 도구상 에러 로그 없음.
• ❌ 하지만 실제 파일은 기기 어디에도 다운로드되지 않음.

사용자 입장에서는 성공했다는데 파일은 없는, 소위 '유령 다운로드' 상태가 된 것이죠.

2. 원인 분석 (Root Cause)

1) 기존 구현 방식: Fetch + Blob

보안을 위해 API 요청 시 인증 헤더(Authorization)를 실어 보내야 했기에, 일반적인 <a> 태그의 href 링크 직접 이동 대신 자바스크립트의 fetch를 사용했습니다.

1. fetch로 바이너리 데이터를 받아옴
2. Blob 객체 생성
3. URL.createObjectURL(blob)로 가상의 URL 생성
4. 임시 <a> 태그를 생성해 click() 이벤트 트리거

2) 인앱 브라우저의 제약

원인은 카카오톡 인앱 브라우저(WebView)의 보안 정책 때문이었습니다. 인앱 브라우저는 보안 및 메모리 관리상의 이유로 스크립트를 통한 Blob 생성 및 a.download 속성을 이용한 다운로드를 차단하거나 정상적으로 처리하지 못하는 경우가 많습니다.

코드는 에러 없이 끝까지 실행되어 Toast는 떴지만, 브라우저 단에서 기기의 파일 시스템으로 접근하는 것을 막아버린 것입니다.

3) 왜 재생(Play)은 가능했나?

영상 재생(<video src="...">)이나 일반적인 데이터 조회 API는 fetch 이후 데이터를 브라우저의 '메모리'상에서만 핸들링하므로 문제가 없었습니다. 오직 "파일 시스템에 저장"하려는 행위만 차단된 것이 핵심이었습니다.

3. 해결 방법 (Solution)

카카오톡 환경에서는 Blob 방식 대신 브라우저 네이티브 다운로드 방식(URL 직접 이동)을 사용하기로 결정했습니다.

STEP 1: 프론트엔드 분기 처리

UserAgent를 체크하여 카카오톡일 경우 fetch 과정을 거치지 않고 window.location.href로 API 엔드포인트에 직접 접근시킵니다.

// src/hooks/use-video-download.ts

const downloadVideo = async (serviceMessageId: number) => {
  const params = new URLSearchParams();
  params.append("serviceMessageId", serviceMessageId.toString());

  // 💡 카카오톡 인앱 브라우저 체크
  const isKakaoTalk = /KAKAOTALK/i.test(navigator.userAgent);

  if (isKakaoTalk) {
    // 카카오톡은 Blob 다운로드가 차단되므로 네이티브 다운로드 유도
    // (이 경우 헤더 대신 쿠키 인증을 활용하게 됨)
    const downloadUrl = `/api/video/download?${params.toString()}`;
    window.location.href = downloadUrl;
    return;
  }

  // 일반 브라우저는 기존 방식 (fetch + Blob) 유지
  // ... fetch 및 Blob 다운로드 로직 수행
};

STEP 2: 백엔드 인증 방식 개선 (핵심)

여기서 난관이 생깁니다. window.location.href로 이동하면 프론트엔드에서 커스텀 헤더(Authorization)를 강제로 욱여넣을 수 없습니다.

이를 해결하기 위해 쿠키(Cookie)를 활용했습니다. 브라우저는 같은 도메인으로 요청을 보낼 때 쿠키를 자동으로 실어 보내기 때문입니다. 백엔드 API가 헤더뿐만 아니라 쿠키도 확인하도록 로직을 수정했습니다.

// src/app/api/video/download/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function GET(request: NextRequest) {
  // 1. 우선 Authorization 헤더 확인 (기존 Blob 방식 대응)
  let authHeader = request.headers.get("Authorization");

  // 2. 헤더가 없으면 쿠키에서 토큰 확인 (카카오톡 직접 링크 이동 대응)
  if (!authHeader) {
    const cookieToken = request.cookies.get("celegram_user_access_token")?.value;
    if (cookieToken) {
      authHeader = `Bearer ${cookieToken}`;
    }
  }

  if (!authHeader) {
    return NextResponse.json({ error: "인증 토큰이 없습니다." }, { status: 401 });
  }

  // ... 이후 인증 통과 시 파일 스트리밍 및 다운로드 로직 실행
}

4. 마치며 (Retrospective)

이번 이슈를 통해 몇 가지 중요한 교훈을 얻었습니다.

1. 인앱 브라우저의 변수: 카카오톡, 라인, 인스타그램 등 인앱 브라우저는 표준 브라우저와 동작이 다를 수 있음을 항상 염두에 두어야 합니다. 특히 '파일 시스템 접근'이나 '팝업 제어'에서 차이가 큽니다.
2. JS 다운로드 vs 네이티브 다운로드: Blob 방식은 헤더 제어가 가능해 세밀한 보안 설정이 가능하지만 호환성 이슈가 있습니다. 반면 location.href는 투박해 보이지만 가장 확실한 호환성을 보장합니다.
3. 유연한 인증 설계: API 설계 시 헤더 인증과 쿠키 인증을 모두 고려하면, 이번처럼 브라우저가 직접 요청을 보내야 하는 제한적인 상황에서도 유연하게 대처할 수 있습니다. (단, 쿠키 사용 시 httpOnly, Secure 등 보안 설정은 필수!)

1. 문제 상황 (The Problem)

• Chrome (PC): 영상이 정상적으로 재생됨.
• Safari (Mac/iOS) 및 Chrome (iOS): 영상이 재생되지 않고 무한 로딩되거나 403 Forbidden 에러 발생.

💡 참고: iOS 환경에서는 Chrome 브라우저 역시 Safari와 동일한 WebKit 엔진을 강제로 사용하기 때문에 Safari와 동일한 에러가 발생합니다.

2. 원인 분석 (Root Cause)

1차 원인: Iframe과 모바일 정책

초기에는 Vimeo 플레이어를 iframe으로 임베드하여 사용하고 있었습니다. 하지만 iOS Safari는 iframe 내의 미디어 자동 재생이나 쿠키(서드파티 쿠키) 공유에 매우 엄격한 정책을 가지고 있습니다. 이로 인해 토큰 인증이 제대로 이루어지지 않거나 브라우저 정책에 의해 차단되었습니다.

2차 원인 (핵심): CORS와 Authorization 헤더

모바일 호환성을 위해 iframe을 제거하고 HTML5 <video> 태그를 사용하여 직접 API를 호출하려고 했으나, 더 복잡한 문제가 발생했습니다.

기존 API 흐름: 클라이언트 → 백엔드 API (/video/play, Auth 헤더 포함) → 302 리다이렉트 → Vimeo CDN

• Chrome의 동작: 리다이렉트 시 Authorization 헤더를 적절히 처리하거나, Cross-Origin 리다이렉트를 유연하게 허용합니다.
• Safari의 동작: 리다이렉트를 따라갈 때 Authorization 헤더를 그대로 유지하여 Vimeo CDN으로 보냅니다. 하지만 Vimeo CDN은 타 도메인의 인증 헤더를 허용하지 않기 때문에(Access-Control-Allow-Headers 미포함), CORS Preflight가 실패하거나 403 Forbidden을 반환하게 됩니다.

🚨 콘솔 에러 메시지:

Request header field Authorization is not allowed by Access-Control-Allow-Headers.

3. 시도했던 방법 (Attempted Solutions)

❌ 시도 1: Iframe → Video 태그 교체

• 접근: 모바일 호환성을 위해 iframe을 걷어내고 <video> 태그로 변경.
• 결과 (실패): <video> 태그의 src 속성으로는 요청 헤더(Authorization)를 조작할 수 없어 인증 토큰을 보낼 수 없었습니다.

❌ 시도 2: URL 쿼리 파라미터로 토큰 전달

• 접근: 헤더 대신 ?accessToken=... 형태의 쿼리 파라미터로 백엔드에 인증 정보를 전달.
• 결과 (실패): 백엔드에서 인증은 성공하지만, 리다이렉트되는 과정에서 Safari가 Cross-Origin 리다이렉트를 차단하거나 파라미터를 유실시켰습니다.

❌ 시도 3: Client-side Fetch로 최종 URL 획득

• 접근: 클라이언트단에서 자바스크립트 fetch로 먼저 API를 호출하여 리다이렉트된 최종 URL(response.url)을 알아낸 뒤, 그 URL을 <video> 태그에 주입.
• 결과 (실패): Safari는 fetch가 리다이렉트를 따라갈 때도 엄격한 CORS 정책을 적용하여 스크립트단에서 에러가 발생했습니다. (에러: Fetch API cannot load ... due to access control checks)

4. 최종 해결책 (Final Solution)

✨ "Next.js API Route를 이용한 서버 사이드 프록시 (Server-side Proxy)"

브라우저(Safari)의 까다로운 CORS 정책을 우회하기 위해, 클라이언트가 직접 요청하는 대신 서버(Next.js)가 대신 요청을 보내도록 구조를 변경했습니다.

변경된 아키텍처 흐름:

1. Client: 브라우저는 Next.js의 내부 API (/api/video/play)를 호출합니다. (같은 도메인이므로 CORS 문제 발생 X)
2. Next.js Server: 서버 사이드에서 백엔드 API를 호출합니다. 서버 간 통신(Server-to-Server)에는 브라우저의 CORS 정책이 적용되지 않습니다.
3. Next.js Server: 백엔드가 리다이렉트해준 최종 Vimeo CDN URL을 받아옵니다.
4. Client: 서버로부터 최종 URL(순수 CDN 주소)을 응답받아 <video> 태그에 삽입하여 재생합니다.

적용 코드 예시 (Next.js API Route):

// src/app/api/video/play/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function GET(request: NextRequest) {
  // 1. 서버 사이드에서 백엔드 호출 (CORS 제약 없음)
  const response = await fetch(`${process.env.BACKEND_API}/video/play?...`, {
    headers: { Authorization: `Bearer ${TOKEN}` },
    redirect: "follow", // 리다이렉트 끝까지 추적
  });

  // 2. 최종 도달한 순수 URL(Vimeo CDN)만 클라이언트에 반환
  return NextResponse.json({ videoUrl: response.url });
}

5. 결론 (Key Takeaway)

1. "Safari는 다르다": Chrome에서 잘 동작한다고 안심해서는 안 됩니다. 특히 Cross-Origin 환경에서의 리다이렉트와 커스텀 헤더(Authorization 등) 처리에 있어서 Safari는 매우 엄격한 보안 기준을 적용합니다.
2. CORS는 브라우저만의 정책이다: CORS(Cross-Origin Resource Sharing) 에러는 오직 '브라우저'가 요청을 보낼 때만 발생합니다. 서버와 서버 간의 통신에는 적용되지 않으므로, 브라우저 정책 때문에 막힐 때는 서버를 프록시(Proxy)로 활용하는 것이 가장 확실하고 우아한 해결책이 될 수 있습니다.

1. 문제 상황

• PC 환경: Chrome, Edge 등 모든 브라우저에서 정상 재생.

• iOS 환경: iPhone의 Safari 및 Chrome에서 영상 영역이 까맣게 나오거나 재생 버튼이 작동하지 않음.

• 특이사항: iOS의 Chrome 역시 Safari와 동일한 WebKit 엔진을 사용하기 때문에 동일한 증상이 발생함.

2. 원인 분석: ITP (Intelligent Tracking Prevention)

문제의 핵심은 iOS와 macOS Safari에 탑재된 ITP(지능형 추적 방지) 기능이었습니다.

왜 재생이 안 되었을까?

• 서드파티 쿠키 차단: Vimeo 플레이어는 iframe 형태로 로드됩니다. 이때 Vimeo는 사용자를 식별하고 재생 상태(세션)를 유지하기 위해 쿠키를 생성하려고 시도합니다.

• 추적자로 간주: Safari의 ITP는 이를 "사용자 추적 행위"로 간주하여 Vimeo가 생성하려는 서드파티 쿠키를 강력하게 차단합니다.

• 권한 획득 실패: 특히 비공개 설정이나 특정 도메인 제한이 걸린 영상의 경우, 사용자를 식별할 수 있는 쿠키가 필수적입니다. 이 쿠키가 차단되니 Vimeo 서버로부터 재생 권한을 얻지 못해 영상이 나오지 않았던 것입니다.

3. 해결 방법: ITP 우회 설정 적용

문제를 해결하기 위해 video-player.tsx 컴포넌트의 Vimeo 로드 로직에 두 가지 설정을 추가했습니다.

A. Do Not Track (dnt=1) 파라미터 추가

Vimeo에게 "우리는 사용자를 추적하지 않을 것이니 추적용 쿠키를 생성하지 마"라고 명시적으로 알려주는 설정입니다.

// src/components/common/video-player.tsx

// 추적 방지 설정을 통해 iOS(ITP) 호환성 향상

const url = new URL(vimeoUrl);
url.searchParams.set("dnt", "1"); 

효과: dnt=1이 설정되면 Vimeo 플레이어는 추적용 쿠키 생성을 시도하지 않습니다. 결과적으로 Safari의 ITP 차단 정책에 걸리지 않게 되어 영상이 정상적으로 로드됩니다.

B. Referrer Policy 변경

Vimeo 영상이 특정 도메인에서만 재생되도록 허용(Domain Whitelist)되어 있는 경우, 요청이 어디서 왔는지 정확히 알려줘야 합니다.

// iframe 태그 속성 추가
referrerPolicy="strict-origin-when-cross-origin"

• 기존: origin (도메인 정보만 보냄)

• 변경: strict-origin-when-cross-origin

이유 : 보안을 유지하면서도 Vimeo 서버가 "우리 서비스 도메인"에서 온 요청임을 정확히 식별할 수 있게 도와줍니다. 이를 통해 도메인 제한이 걸린 영상도 안전하게 재생할 수 있습니다.

4. 마치며

iOS 환경은 보안 및 개인정보 보호 정책이 매우 엄격하기 때문에, 서드파티 서비스를 연동할 때 예상치 못한 이슈가 발생하곤 합니다.

이번 이슈는 ITP의 작동 원리를 이해하고, Vimeo 측에서 제공하는 dnt 옵션을 활용해 해결할 수 있었습니다. 혹시 비슷한 문제를 겪고 계신 프론트엔드 개발자분들께 도움이 되길 바랍니다.

📝 한 줄 요약 "iOS Safari의 ITP 정책으로 인해 차단되는 서드파티 쿠키 문제를 dnt=1 파라미터 추가를 통해 해결하여 영상 재생 호환성을 확보했습니다."

Next.js App Router로 프로젝트를 진행하면서 shadcn/ui의 Carousel 컴포넌트를 사용할 때 겪은 혼란과 그 해결 과정을 공유합니다.

초기 상황

// carousel.tsx - shadcn/ui 컴포넌트
'use client';

export const Carousel = ({ children }) => {
  // ... carousel 로직
}

export const CarouselContent = ({ children }) => {
  // ...
}

export const CarouselItem = ({ children }) => {
  // ...
}

// buy-section.tsx
import { Carousel, CarouselContent, CarouselItem } from '@/components/ui/carousel';

export const BuySection = () => {
  return (
    <Carousel>
      <CarouselContent>
        <CarouselItem>...</CarouselItem>
      </CarouselContent>
    </Carousel>
  );
};

이렇게 코드를 작성했더니 에러가 발생했습니다:

Error: Cannot access displayName.valueOf on the server. 
You cannot dot into a client module from a server component.

첫 번째 의문: carousel.tsx에 이미 'use client'가 있는데, 왜 buy-section.tsx에도 써야 하는 걸까?

💡 핵심 개념: Server Component는 Client Module의 내부를 "들여다볼 수 없다"

1. Next.js의 Server/Client 경계

Server Component → Client Component (O)  // 참조 가능
Server Component → Client Component 내부 export (X)  // 접근 불가

2. 왜 에러가 발생했나?

// Server Component에서:
import { Carousel, CarouselContent, CarouselItem } from '@/components/ui/carousel';

// 이건 사실 이런 의미:
import * as CarouselModule from './carousel';  // Client 모듈

const Carousel = CarouselModule.Carousel;           // ❌ 내부 접근
const CarouselContent = CarouselModule.CarouselContent;  // ❌ 내부 접근
const CarouselItem = CarouselModule.CarouselItem;       // ❌ 내부 접근

Server는 Client 모듈의 여러 export를 개별적으로 사용할 수 없습니다!

3. 실행 환경의 차이

서버 (Node.js 환경)
  ↓
  buy-section.tsx를 실행
  ↓
  <Carousel>를 만나면?
  → "아, 이건 Client Component구나!" ✅
  → Placeholder 생성
  ↓
  <CarouselContent>를 만나면?
  → ❌ "어? 이게 뭐지? carousel.tsx 파일 내부를 봐야 하는데..."
  → ❌ "하지만 이건 Client 모듈이라 내부를 볼 수 없어!"

4. 번들링 관점에서 보기

빌드 시:

Server Bundle (서버용)          Client Bundle (브라우저용)
├─ buy-section.tsx            ├─ carousel.tsx (전체!)
│  └─ Carousel 참조만           │  ├─ Carousel
│     (실제 코드는 X)            │  ├─ CarouselContent
                               │  ├─ CarouselItem
                               │  └─ useEmblaCarousel
                               │  └─ React hooks
                               │  └─ 브라우저 API

Server에서 CarouselContent를 직접 사용하려면 carousel.tsx 파일을 파싱해야 하지만, 이 파일은 브라우저 전용 코드를 포함하고 있어 Server 번들에 넣을 수 없습니다.

🎨 shadcn/ui가 Next.js와 잘 맞는 진짜 이유

처음에는 "Carousel을 쓰는 곳마다 'use client'를 써야 하는데 왜 Next.js랑 잘 맞다고 하지?"라는 의문이 들었습니다.

오해: "모든 것을 Server Component로"가 아닙니다

Next.js의 철학은:

• ✅ 기본은 Server Component
• ✅ 인터랙티브한 부분만 Client Component
• ✅ 적재적소에 사용

Carousel은 당연히 Client Component여야 합니다

// Carousel의 본질
- 사용자가 슬라이드를 넘김 (onClick)
- 애니메이션 (useEffect)
- 현재 위치 추적 (useState)
- 드래그 이벤트 (onDrag)

이런 기능은 브라우저에서만 가능합니다!

실제 번들 크기 비교

Traditional React App (모두 Client):
└─ client.js (2.5MB)
   ├─ React
   ├─ All components
   ├─ All libraries
   └─ Your code

Next.js + shadcn/ui (적재적소):
├─ Server rendered HTML (대부분)
└─ client.js (200KB) ← 90% 감소! 🚀
   └─ Interactive parts만 (Carousel 등)

shadcn/ui의 진짜 장점

다른 UI 라이브러리:

import { Carousel } from 'some-ui-library';
// 라이브러리 내부가 블랙박스
// 최적화 불가능

shadcn/ui:

// 코드를 직접 소유하므로:
// 1. 필요 없는 부분 제거 가능
// 2. Server/Client 경계 조정 가능
// 3. 프로젝트에 맞게 커스터마이징
// 4. 번들 사이즈 최적화 가능

🚀 해결책 1: 섹션 전체를 Client Component로

가장 간단한 해결책:

// buy-section.tsx
'use client';

import { Carousel, CarouselContent, CarouselItem } from '@/components/ui/carousel';

export const BuySection = () => {
  return (
    <div>
      <GuideText /> {/* 같이 Client가 됨 */}
      <GuideText />

      <Carousel>
        <CarouselContent>
          <CarouselItem>...</CarouselItem>
        </CarouselContent>
      </Carousel>
    </div>
  );
};

장점:

• ✅ 간단함
• ✅ 빠른 구현

단점:

• ❌ 섹션 전체가 Client Component
• ❌ 불필요한 JavaScript 번들 증가

🎯 해결책 2: Carousel 부분만 Client Component로 분리 (최적화)

더 나은 방법은 필요한 부분만 Client Component로 분리하는 것입니다.

Step 1: 범용적인 MobileCarousel 컴포넌트 생성

// components/common/mobile-carousel.tsx
'use client';

import { Carousel, CarouselContent, CarouselItem, type CarouselApi } from '@/components/ui/carousel';
import { ReactNode, Children } from 'react';
import type { EmblaOptionsType } from 'embla-carousel';

interface MobileCarouselProps {
  children: ReactNode;
  itemClassName?: string;
  contentClassName?: string;
  carouselClassName?: string;
  setApi?: (api: CarouselApi) => void;
  opts?: EmblaOptionsType;
  orientation?: 'horizontal' | 'vertical';
}

export const MobileCarousel = ({
  children,
  itemClassName = 'basis-auto',
  contentClassName = 'md:-ml-6 lg:-ml-6',
  carouselClassName = 'w-full md:hidden lg:hidden',
  setApi,
  opts,
  orientation = 'horizontal'
}: MobileCarouselProps) => {
  const items = Children.toArray(children);

  return (
    <Carousel 
      className={carouselClassName} 
      setApi={setApi} 
      opts={opts} 
      orientation={orientation}
    >
      <CarouselContent className={contentClassName}>
        {items.map((child, index) => (
          <CarouselItem key={index} className={itemClassName}>
            {child}
          </CarouselItem>
        ))}
      </CarouselContent>
    </Carousel>
  );
};

Step 2: Server Component에서 사용

// buy-section.tsx - Server Component! ✅
import { MobileCarousel } from '@/components/common/mobile-carousel';

export const BuySection = () => {
  return (
    <div>
      <GuideText /> {/* Server ✅ */}
      <GuideText /> {/* Server ✅ */}

      {/* Desktop: 정적 그리드 - Server ✅ */}
      <div className="hidden lg:flex">
        {BUY_STEPS.map(step => <StepCard key={step.title} {...step} />)}
      </div>

      {/* Mobile: Carousel - Client (필요한 부분만!) ✅ */}
      <MobileCarousel>
        {BUY_STEPS.map(step => <StepCard key={step.title} {...step} />)}
      </MobileCarousel>
    </div>
  );
};

최적화 효과

Before (전체 Client):
├─ buy-section.tsx (전체)
├─ guide-text.tsx
├─ step-card.tsx
└─ carousel.tsx
Total: ~50-60KB

After (필요한 부분만 Client):
├─ mobile-carousel.tsx (작은 wrapper만)
└─ carousel.tsx
Total: ~20-25KB

💡 약 60% 감소! 🚀

🚨 또 다른 문제: 함수를 prop으로 전달할 수 없다

처음 MobileCarousel을 만들 때 이런 시도를 했습니다:

// buy-section.tsx - Server Component
const BUY_STEPS = [
  {
    icon: StepOneIcon,  // SVG 컴포넌트
    title: 'STEP 01',
    description: '공고'
  }
];

<MobileCarousel steps={BUY_STEPS} />  // ❌ 에러!

Error: Functions cannot be passed directly to Client Components 
unless you explicitly expose it by marking it with "use server".

왜 에러가 발생했을까?

SVG 파일의 정체:

// SVG를 import하면:
import StepOneIcon from '@/assets/about/step1-icon.svg';

// 이건 사실 React 컴포넌트 = 함수입니다!
const StepOneIcon = (props) => {
  return (
    <svg width="24" height="24" {...props}>
      <path d="M..." />
    </svg>
  );
};

문제의 원인:

// Server → Client로 전송하려는 내용:
{
  steps: [
    { 
      icon: function StepOneIcon(props) {  // ❌ 함수를 직렬화할 수 없음!
        return <svg>...</svg>
      }
    }
  ]
}

Server → Client 경계에서 전달 가능한 것들

// ❌ 전달 불가능
const MyComponent = () => { /* ... */ };  // 함수
const handler = () => {};                  // 함수
const icon = SomeIcon;                     // React Component (함수)

<ClientComp 
  component={MyComponent}  // ❌ 
  onClick={handler}        // ❌
  icon={icon}              // ❌
/>

// ✅ 전달 가능
const data = { title: "Hi", count: 10 };  // 직렬화 가능한 데이터
const text = "Hello";                      // 문자열
const jsx = <Icon />;                      // 렌더링된 React Element

<ClientComp 
  data={data}        // ✅ 
  text={text}        // ✅
>
  <Icon />           {/* ✅ children으로 전달 */}
</ClientComp>

💡 해결책: Composition Pattern

// ❌ Before: 함수를 prop으로 전달
const steps = [{ icon: StepOneIcon }];
<MobileCarousel steps={steps} />

// ✅ After: children으로 렌더링된 Element 전달
<MobileCarousel>
  {steps.map(step => {
    const Icon = step.icon;  // Server에서 함수 사용
    return (
      <div key={step.title}>
        <StepCard>
          <Icon />  {/* Server에서 렌더링 → Element로 전달 */}
        </StepCard>
      </div>
    );
  })}
</MobileCarousel>

전달 과정

1. 서버 실행:
   Server Component가 실행됨
   ↓
   const Icon = StepOneIcon;
   <Icon />  ← 서버에서 실행, JSX로 변환
   ↓
   결과: { type: 'svg', props: {...} }  ← 직렬화 가능한 객체

2. 네트워크 전송:
   JSON으로 직렬화
   ↓
   {"type":"svg","props":{...}}  ← 문자열

3. 클라이언트 수신:
   브라우저가 받음
   ↓
   React가 렌더링

🤔 그런데 원래 intro 페이지는 왜 에러가 안 났지?

흥미로운 발견: 원래 intro/page.tsx는 'use client' 없이도 Carousel을 사용하고 있었습니다.

// intro/page.tsx - 'use client' 없음 (Server Component)
<Carousel className="w-full pl-4 md:pl-6 lg:hidden">
  <CarouselContent className="md:-ml-6">
    {ABOUT_DATA.map((item) => (
      <CarouselItem key={item.id} className="basis-auto">
        <div>...</div>
      </CarouselItem>
    ))}
  </CarouselContent>
</Carousel>

왜 작동했을까?

JSX는 "함수 호출"이 아니라 "객체"입니다

// 이렇게 쓰면:
<CarouselItem className="basis-auto">
  <div>Hello</div>
</CarouselItem>

// 실제로는 이렇게 변환됩니다:
React.createElement(CarouselItem, { className: "basis-auto" }, 
  React.createElement("div", {}, "Hello")
)

// 결과는 "객체"입니다:
{
  type: CarouselItem,  // 함수 참조
  props: { className: "basis-auto", children: {...} }
}

Server가 하는 일:

• 컴포넌트를 "실행"하지 않습니다
• "어떤 컴포넌트를 써야 하는지" 참조만 전달합니다
• Next.js가 내부적으로 컴포넌트 참조를 ID로 변환합니다

// Server에서:
<Carousel>
  <CarouselContent>
    <div>Hello</div>
  </CarouselContent>
</Carousel>

// ↓ Next.js가 변환

// Client로 전송:
{
  "type": "ClientComponent#carousel-123",     // ← 참조 ID
  "props": {
    "children": {
      "type": "ClientComponent#carousel-124", // ← 참조 ID
      "props": {
        "children": { "type": "div", "props": { "children": "Hello" } }
      }
    }
  }
}

📊 패턴 비교표

🎯 최종 아키텍처

프로젝트 전체 구조

src/
├─ components/
│  └─ common/
│     └─ mobile-carousel.tsx  🎨 범용 컴포넌트 (Client)
│
├─ app/
   ├─ about/
   │  ├─ intro/
   │  │  └─ page.tsx  ✅ Server Component
   │  │
   │  └─ collection-guide/
   │     └─ _sections/
   │        ├─ donation-section.tsx  ✅ Server Component
   │        └─ buy-section.tsx       ✅ Server Component
   │
   └─ _sections/
      ├─ activity-section.tsx   🔵 Client (애니메이션 필요)
      ├─ highlight-section.tsx  🔵 Client (애니메이션 필요)
      └─ timeline-section.tsx   🔵 Client (애니메이션 필요)

사용 예시

간단한 케이스:

// Server Component
<MobileCarousel>
  {items.map(item => <Card key={item.id}>{item.name}</Card>)}
</MobileCarousel>

고급 케이스 (API 제어):

// Client Component
'use client';

const [api, setApi] = useState<CarouselApi>();
const [current, setCurrent] = useState(0);

<MobileCarousel 
  setApi={setApi}
  opts={{ loop: true, align: 'center' }}
  orientation="vertical"
>
  {items.map(item => <Card key={item.id}>{item}</Card>)}
</MobileCarousel>

{/* 점 표시기 */}
<div>
  {items.map((_, i) => (
    <button 
      className={i === current ? 'active' : ''}
      onClick={() => api?.scrollTo(i)}
    />
  ))}
</div>

💡 핵심 요약

1. Server/Client 경계 규칙

✅ Server Component → Client Component (children 패턴)
❌ Server Component → Client Component 내부 exports
❌ Server Component → Client Component (함수 prop)
✅ Server Component → Client Component (직렬화 가능한 데이터 prop)

2. 전달 가능한 것

• ✅ 문자열, 숫자, 객체, 배열 (직렬화 가능)
• ✅ React Elements (<Component /> 형태)
• ❌ 함수, 클래스, Symbol

3. SVG = 함수 = 전달 불가

// ❌ 이렇게 하지 말고:
<ClientComp icon={IconSvg} />

// ✅ 이렇게 하세요:
<ClientComp>
  <IconSvg />
</ClientComp>

4. shadcn/ui + Next.js = 완벽한 조합

• 인터랙티브한 부분만 Client Component
• 나머지 80-90%는 Server Component
• 코드를 직접 소유해서 최적화 가능
• 번들 크기 최소화

🚀 결론

Next.js App Router의 Server/Client Component 경계를 이해하는 것은 처음에는 복잡해 보이지만, 핵심 원칙을 이해하면:

1. 적재적소에 Client Component 사용: 인터랙션이 필요한 부분만
2. Composition Pattern 활용: 함수 대신 children으로 전달
3. 범용 컴포넌트 추상화: MobileCarousel처럼 재사용 가능하게

이런 패턴을 따르면 성능이 뛰어나고 유지보수가 쉬운 Next.js 애플리케이션을 만들 수 있습니다!

최종 결과:

• ✅ 코드 재사용 극대화
• ✅ 번들 크기 60% 감소
• ✅ 일관된 UX
• ✅ Server Component 최대 활용

참고 자료:

• Next.js App Router 공식 문서
• React Server Components
• shadcn/ui

프론트엔드에서 FormData로 배열을 전송할 때, 같은 프로젝트 내에서도 다양한 방식이 혼재되어 있었습니다:

// 방식 1: JSON.stringify
formData.append('deleteTimelines', JSON.stringify([1, 2, 3]));

// 방식 2: forEach ([] 없음)
dto.deletedResourceIds.forEach(id => {
  formData.append('deletedResourceIds', id.toString());
});

// 방식 3: forEach + []
dto.deletedFileIds.forEach(id => {
  formData.append('deletedFileIds[]', id.toString());
});

특히 타임라인 API에서 deleteTimelines[]를 deleteTimelines로 변경하니 제대로 작동했는데, 왜 그런지 궁금했습니다.

🔍 핵심 원리

1. FormData의 본질적 한계

FormData는 키-값 쌍만 전송할 수 있습니다. 배열을 표현하는 표준 방법이 없습니다.

// 실제 HTTP 전송 형태
Content-Disposition: form-data; name="ids"
value="1"

2. 백엔드 파싱 동작 방식

같은 키에 값이 몇 개 append 되었는지에 따라 결과가 달라집니다:

3. [] 표기법의 역할

formData.append('deletedFileIds[]', '1');

[]는 단순한 명시가 아니라, 실제로 키 이름의 일부입니다!

HTTP 전송: name="deletedFileIds[]"

NestJS/Multer 파싱: "[] 패턴 발견! 배열로 변환해야겠다"
                   → deletedFileIds = ["1"]

💡 세 가지 전송 방식 비교

방식 1: JSON.stringify

// 프론트엔드
formData.append('deleteTimelines', JSON.stringify([1, 2, 3]));

// 백엔드 DTO
@Transform(({ value }) => (typeof value === 'string' ? JSON.parse(value) : value))
deleteTimelines?: number[];

// 결과: ✅ 항상 배열로 파싱

장점:

• ✅ 값이 1개든 여러 개든 항상 안전
• ✅ 복잡한 객체 배열도 전송 가능
• ✅ 코드가 간결

단점:

• ⚠️ 백엔드에서 JSON 파싱 필요

방식 2: forEach ([] 없음)

// 프론트엔드
dto.deletedResourceIds.forEach(id => {
  formData.append('deletedResourceIds', id.toString());
});

// 백엔드: 자동 배열 변환 (여러 값일 때만)

장점:

• ✅ 백엔드에서 자동 파싱 (여러 값일 때)

단점:

• ❌ 값이 1개일 때 문자열로 인식되어 에러!
• ❌ 단순 값(숫자/문자열)만 가능

방식 3: forEach + []

// 프론트엔드
dto.deletedFileIds.forEach(id => {
  formData.append('deletedFileIds[]', id.toString());
});

// 백엔드: [] 패턴 인식 → 무조건 배열로 변환

장점:

• ✅ 값이 1개든 여러 개든 항상 배열로 보장
• ✅ 백엔드에서 자동 파싱

단점:

• ❌ 단순 값만 가능 (객체 배열 불가)
• ⚠️ 프로젝트마다 지원 여부 다름

🎯 실제 사례 분석

타임라인 API (JSON.stringify 통일)

formData.append('timelines', JSON.stringify(dto.timelines));           // 객체 배열
formData.append('addTimelines', JSON.stringify(dto.addTimelines));     // 객체 배열
formData.append('updateTimelines', JSON.stringify(dto.updateTimelines)); // 객체 배열
formData.append('deleteTimelines', JSON.stringify(dto.deleteTimelines)); // 숫자 배열

왜 모두 JSON.stringify를 사용?

• ✅ API 내부 일관성 (모든 배열을 같은 방식으로)
• ✅ 객체 배열 전송 필수 (timelines, addTimelines, updateTimelines)
• ✅ 백엔드 파싱 로직 통일

공지사항 API (forEach + [] 사용)

// 파일 업로드 ([] 없음)
dto.files.forEach(file => {
  formData.append('files', file);  // Multer가 자동 처리
});

// 숫자 배열 ([] 있음)
dto.deletedFileIds.forEach(id => {
  formData.append('deletedFileIds[]', id.toString());
});

왜 deletedFileIds[]에만 [] 사용?

• ✅ 파일은 Multer가 자동으로 배열 처리
• ✅ 숫자 ID는 명시적으로 배열임을 표시해야 함
• ✅ 값이 1개일 때도 배열로 보장 (엣지 케이스 방지)

🔧 백엔드 코드 분석

NestJS의 @Transform 데코레이터

@Transform(({ value }) => (typeof value === 'string' ? JSON.parse(value) : value))
deletedFileIds?: number[];

이 코드의 의미:

1. 문자열이 오면 → JSON.parse() 실행 (JSON.stringify로 보낸 경우)
2. 배열이 오면 → 그대로 사용 (forEach + []로 보낸 경우)

시나리오별 동작:

// Case 1: JSON.stringify
formData.append('ids', JSON.stringify([1,2,3]));
// value = "[1,2,3]" (문자열)
// JSON.parse("[1,2,3]") → [1,2,3] ✅

// Case 2: forEach + []
formData.append('ids[]', '1');
// value = ["1"] (배열)
// 그대로 통과 → ["1"] ✅

// Case 3: forEach (값 1개, [] 없음)
formData.append('ids', '1');
// value = "1" (문자열)
// JSON.parse("1") → 1 ❌ (배열 아님!)

📋 선택 가이드

JSON.stringify를 사용해야 할 때:

✅ 객체 배열을 전송할 때

formData.append('items', JSON.stringify([
  { id: 1, name: 'A' },
  { id: 2, name: 'B' }
]));

✅ API 내 다른 배열들도 JSON.stringify를 쓸 때 (일관성)

✅ 복잡한 중첩 구조를 전송할 때

forEach + []를 사용해야 할 때:

✅ 단순 값(숫자/문자열) 배열만 전송할 때

✅ 백엔드가 [] 패턴을 명시적으로 요구할 때

✅ 값이 1개일 수도 있는 경우 (엣지 케이스 방지)

forEach ([] 없음)를 사용할 때:

⚠️ File 객체 (Multer가 자동 처리)

⚠️ 항상 2개 이상의 값이 보장될 때

⚠️ 백엔드가 관대하게 파싱할 때 (권장하지 않음)

🎓 핵심 교훈

1. Swagger만으로는 부족하다

// Swagger에서는 똑같이 보임
{
  "deleteTimelines": {
    "type": "array",
    "items": { "type": "number" }
  }
}

하지만 실제 FormData 전송 방식은 다릅니다:

• deleteTimelines: "[1,2,3]" (JSON 문자열)
• deletedFileIds[]: 1, deletedFileIds[]: 2 ([] 패턴)

2. API 내부 일관성이 중요하다

같은 API 내에서는 통일된 방식을 사용하는 게 좋습니다:

// ✅ 좋은 예: 모두 JSON.stringify
formData.append('add', JSON.stringify([...]));
formData.append('update', JSON.stringify([...]));
formData.append('delete', JSON.stringify([...]));

// ❌ 나쁜 예: 혼재
formData.append('add', JSON.stringify([...]));
formData.append('update', JSON.stringify([...]));
arr.forEach(id => formData.append('delete[]', id)); // 혼자 다름

3. 백엔드와의 협의가 필수

프론트엔드만 바꾸면 작동하지 않습니다. 백엔드 DTO 설계를 먼저 확인하세요:

// 백엔드 Request DTO를 확인!
@Transform(({ value }) => ...)
deleteIds?: number[];

4. 엣지 케이스를 고려하라

"값이 1개만 삭제할 때" 같은 시나리오를 테스트하세요. 많은 버그가 여기서 발생합니다.

🚀 실전 권장사항

새 API 개발 시:

1. 백엔드와 먼저 협의: JSON vs forEach 방식 결정
2. 일관성 유지: 같은 API는 같은 방식으로
3. 문서화: 주석으로 이유 명시

   // 배열 형태로 전송하기 위해 [] 표기법 사용
   formData.append('deletedFileIds[]', id.toString());

기존 코드 유지보수 시:

1. 현재 방식 확인: 백엔드 DTO와 프론트엔드 코드 모두
2. 테스트: 값이 1개일 때, 여러 개일 때 모두 테스트
3. 함부로 바꾸지 않기: 이미 작동하면 그대로 두기

통일을 원한다면:

1. 팀 컨벤션 문서 작성
2. 백엔드 팀과 협의 (가장 중요!)
3. 새 API부터 적용
4. 점진적 마이그레이션 (여유 있을 때)

📚 요약

결론: API의 특성에 맞게 선택하되, 일관성을 유지하자!

• 브라우저: Chrome 114 (MacBook Pro M2)
• 프로젝트: Next.js 14 + React-Konva 기반 Canvas 에디터
• 측정 코드: handleTransformEnd 이벤트마다 performance.now()로 처리 시간(ms) 로깅
• 반복 횟수: 10회씩 평균 값 여러 번 실행 → 평균 계산

// CanvasElementsRender.tsx (핵심 부분)
const handleTransformEnd = (id: string, e: Konva.KonvaEventObject<Event>) => {
  const start = performance.now();

  // … updateElement 로직, batchDraw() 호출 …

  const end = performance.now();
  durationsRef.current.push(end - start);

  if (durationsRef.current.length >= 10) {
    const sum = durationsRef.current.reduce((a, b) => a + b, 0);
    const avg = sum / durationsRef.current.length;
    console.log(`[perf] transform 평균: ${avg.toFixed(2)} ms (samples: 10)`);
    durationsRef.current = [];
  }
};

📝 측정 결과

• batchDraw만 적용: 3.49 → 2.70ms ⇒ 약 22.75% 감소

• useCallback 추가 시: 2.70 → 1.71ms ⇒ 약 32% 추가 개선

• 전체 최적화 효과: 3.49 → 1.71ms ⇒ 총 51.06% 성능 향상

📸 캡쳐 스냅샷

1) ❌ 비최적화 버전 (3.49ms 평균)

2) ✅ batchDraw()만 적용 (2.70ms 평균)

3) ✅ useCallback + batchDraw() 적용 (1.71ms 평균)

🎯 정리 및 결론

1. 불필요한 리렌더링 방지: useCallback으로 핸들러 메모이제이션 적용

2. 불필요한 redraw 최소화: batchDraw()로 최적화된 그리기 처리

3. 상태 변경 최소화: 매 이벤트마다 상태를 직접 변경하지 않고 필요한 순간에만 반영

📌 이 최적화를 통해 평균 처리 시간이 3.49ms → 1.71ms, 약 51% 감소 복잡한 캔버스 조작에서도 부드럽고 반응성 높은 UX 개선

unno 프로젝트에서 명함을 이미지로 저장할 때, 다음과 같은 경로로 Supabase Storage에 PNG 파일을 저장하도록 설계하였다.

const fileName = `${label}_${lastSlug}_img.png`;
const filePath = `${userId}/${lastSlug}/${fileName}`;

즉, 하나의 slug에 대해 front_img.png, back_img.png 같은 고정된 경로에 저장되는 구조다.

정상 케이스

• 최초 저장 시에는 문제없이 잘 작동한다.

문제 발생

같은 slug로 다시 저장(즉, 이미지 덮어쓰기)하면 다음 문제가 발생했다:

• Supabase에는 새로운 이미지로 덮어쓰기가 되었음에도,
• 브라우저에서는 이전 이미지가 계속 캐시된 채로 보임
• 강력 새로고침 (Cmd+Shift+R)을 해야만 새로운 이미지가 반영됨

현상 요약

원인: Supabase의 CDN 캐싱 구조

Supabase는 Cloudflare 기반 CDN을 통해 전 세계에 분산된 이미지 서버를 제공한다.

출처: Supabase Smart CDN 소개

캐시가 동작하는 방식 요약

1. 사용자가 업로드한 이미지가 Supabase Storage에 저장된다.

2. Supabase는 이를 Cloudflare CDN에 자동 복제(Cache) 한다.

3. 이후 동일한 URL 요청이 들어오면 CDN에서 캐시된 이미지를 반환한다.

4. 즉, 원본이 변경되어도, 캐시가 만료되기 전까지는 이전 이미지가 계속 반환된다.

참고 문서: Supabase Smart CDN 공식 문서

해결 방법

1. 쿼리 스트링을 활용한 Cache Busting

const timestamp = new Date().getTime();
const imageUrl = `https://.../cards/${fileName}?v=${timestamp}`;

• Supabase는 URL 쿼리를 무시하고 동일한 리소스를 반환하지만,

• 브라우저는 ?v=12345678이 붙은 걸 새 파일로 취급하며 캐시를 우회한다.

2. 파일명을 아예 새로 생성

const fileName = `${label}_${lastSlug}_${Date.now()}_img.png`;

• 경로 자체를 변경함으로써 캐시를 완전히 피할 수 있다.

• 다만 기존 파일을 수동으로 정리해줘야 하고, 저장소 관리가 복잡해질 수 있다.

3. Supabase에서 캐시 TTL 조정은 불가능

• 현재는 사용자가 TTL(Time To Live) 값을 설정하거나 purge(강제 초기화)하는 기능은 제공되지 않는다.

• Smart CDN은 Pro 요금제에서만 자동 무효화를 제공하며, Free 요금제에서는 직접 우회 처리를 해야 한다.

결론

• Supabase Storage는 CDN 기반이라 이미지 덮어쓰기가 바로 반영되지 않는다.
• 쿼리 스트링을 붙이는 방식의 캐시 무효화가 가장 간단하고 안전한 해결책이다.
• 이미지 URL을 클라이언트에서 불러올 때 ?v=${timestamp}를 함께 붙이자

unno 프로젝트에서 사용자가 이미지를 업로드하면 해당 파일은 Supabase Storage에 저장된다. 이후 명함을 새로 만들 때도 기존에 업로드한 이미지들을 재사용할 수 있도록 DB에 저장된 이미지 URL을 기반으로 캔버스(Stage)에 추가하는 구조로 설계했다.

하지만, 캔버스에서 Stage.toBlob()을 통해 이미지를 저장하려고 할 때, 일부 이미지가 포함된 Stage에서 Blob 변환이 실패하는 문제가 발생했다.

문제 발생: toBlob이 null을 반환함

export const uploadStageImage = async (
  stage: Konva.Stage,
  userId: string,
  lastSlug: string,
  label: 'front' | 'back'
): Promise<string> => {
  const blob: Blob = await new Promise<Blob>((resolve, reject) => {
    stage.toBlob({
      mimeType: 'image/png',
      pixelRatio: 2,
      callback: (b: Blob | null) => {
        if (b) resolve(b);
        else reject(new Error('Konva.toBlob 반환값이 null입니다.'));
      },
    });
  });

  const fileName = `${label}_${lastSlug}_img.png`;
  const filePath = `${userId}/${lastSlug}/${fileName}`;

  return uploadToSupabaseStorage('cards', filePath, blob);
};

의도

• Konva.Stage를 이미지로 변환하여 Supabase에 업로드하고, 해당 public URL을 반환

현상

• 특정 이미지가 포함된 Stage에서는 toBlob() 결과가 null로 반환됨

상황 비교

업로드 직후 캔버스에 추가된 이미지

{
  "previewUrl": "blob:http://localhost:3000/...",
  "height": 98.54,
  ...
}

• 로컬 Blob URL이므로 보안 제약 없이 사용 가능

DB에서 가져온 Supabase 이미지 URL

{
  "previewUrl": "https://your-project.supabase.co/storage/v1/object/public/uploadimg/...",
  "height": 84.23,
  ...
}

• Supabase의 도메인이 다른 origin이기 때문에 브라우저 보안 정책에 의해 문제가 발생

원인 분석

이 문제의 본질은 CORS (Cross-Origin Resource Sharing) 정책 때문이다.

• 브라우저는 다른 origin의 이미지를 <canvas>에 그릴 경우, 해당 canvas를 tainted 상태로 간주한다.

• 이 상태에서는 .toBlob(), .toDataURL() 등 출력 관련 API 사용이 제한된다.

• 특히 Konva.Image는 <img> 태그 기반이므로, 다음 조건이 필요하다:

  • crossOrigin="anonymous" 설정
  • 이미지 서버(Supabase)에서 CORS 헤더 허용

해결 방법

1. Supabase Storage의 CORS 정책 설정

Supabase 프로젝트에서 다음과 같이 CORS 설정을 추가해야 한다

[
  {
    "allowed_origins": ["*"], // 또는 "https://uuno.vercel.app"
    "allowed_methods": ["GET"],
    "allowed_headers": ["*"],
    "max_age": 86400
  }
]

• allowed_origins: 실제 배포 도메인을 등록

• allowed_methods: 최소한 GET은 포함해야 함

2. Konva 이미지 로딩 시 crossOrigin 속성 지정

useImage 훅에서 'anonymous' 옵션을 명시해야 한다.

const [image] = useImage(element.previewUrl, 'anonymous');

element-image-canvas.tsx, element-upload-canvas.tsx 등 모든 이미지 요소 컴포넌트에 이 설정을 추가해야 함

적용 결과

• toBlob()이 안정적으로 Blob 객체를 반환 ✅

• Supabase 이미지가 포함된 canvas도 문제 없이 저장 가능 ✅

• 업로드한 이미지 재활용 시에도 CORS 에러 없이 저장 가능 ✅

마무리 팁

• Supabase Storage에 이미지를 업로드할 때는 반드시 public 폴더에 업로드하고,
• crossOrigin 설정이 누락되면 에러 없이 그냥 null을 반환하기 때문에 에러 처리를 반드시 해야 한다.

무료 Unsplash API는 1시간당 50회 호출 제한이 있어, 다음과 같은 UX 흐름에서 빠르게 한도에 도달하는 문제가 발생했다:

• 🔍 검색어 입력 시 → 실시간 API 호출

• 📜 스크롤 이동 시 → 무한스크롤 기반 추가 호출

⛔ 디바운싱을 적용해도 TanStack Query의 fetchNextPage와 중첩되어 호출량이 급증, 기능이 차단되는 상황이 빈번히 발생했다.

🔧 초기 대응: 서버 측 200장 preload → 클라이언트 필터링

요청 수를 줄이기 위해, 서버에서 4페이지(50장 × 4)의 이미지를 한 번에 받아와 클라이언트에서 필터링하는 구조로 변경했다.

export async function GET() {
  const allImages: UnsplashImage[] = [];

  const pageRequests = Array.from({ length: 4 }, (_, i) =>
    fetch(`${BASE_URL}?page=${i + 1}&per_page=50&client_id=${ACCESS_KEY}`).then((res) => res.json())
  );

  const results = await Promise.all(pageRequests);
  for (const pageData of results) {
    if (Array.isArray(pageData)) allImages.push(...pageData);
  }

  return NextResponse.json(allImages);
}

⚠️ 하지만 두 가지 문제가 발생했다

1. 🔤 한글 검색 정확도 부족 (단순 포함 필터링으로 처리했기 때문)
2. 🖼️ 이미지 탐색성 저하 (제한된 200장 내에서만 탐색 가능)

✅ 최종 해결: 프로덕션 API 승인 → 무한스크롤 + 검색 구조 복구

API 쿼터를 확장(프로덕션 승인)받은 뒤, 다시 검색어 기반 호출과 무한스크롤을 활성화하는 구조로 복구했다.

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url);
  const query = searchParams.get('query') || '';
  const page = Number(searchParams.get('page') || '1');
  const perPage = Number(searchParams.get('per_page') || 20);

  if (page > MAX_UNSPALSH_API_PAGES) {
    return NextResponse.json(
      { error: '요청 페이지 수 제한 초과' },
      { status: 429 }
    );
  }

  const baseURL = query
    ? `https://api.unsplash.com/search/photos`
    : `https://api.unsplash.com/photos`;

  const url =
    `${baseURL}?client_id=${ENV.UNSPLASH_ACCESS_KEY}` +
    `&page=${page}&per_page=${perPage}` +
    (query ? `&query=${encodeURIComponent(query)}` : '');

  const res = await fetch(url, { next: { revalidate: 3600 } });

  if (!res.ok) {
    const errorData = await res.json().catch(() => null);
    return NextResponse.json(
      { error: '이미지 불러오기 실패', details: errorData || res.statusText },
      { status: res.status }
    );
  }

  const json = await res.json();

  return query
    ? NextResponse.json({ results: json.results, total_pages: json.total_pages })
    : NextResponse.json(json);
}

💡 고려 사항 및 결과

• ✅ 검색어 유무에 따라 search/photos 또는 photos API로 자동 분기

• ✅ TanStack Query 기반 무한스크롤 구조에 적합

• ✅ revalidate: 3600을 적용하여 1시간 단위 캐싱으로 서버 부담 최소화

Canvas 기반 편집기를 Konva로 개발하면서 가장 큰 기술적 난관 중 하나는 Canvas 요소와 HTML 요소 간 좌표 차이였다. 사용자가 보는 위치와 실제 Konva Canvas에서 인식하는 위치가 달라 툴바, 입력창 등의 HTML 오버레이가 엉뚱한 위치에 렌더링되는 문제가 반복적으로 발생했다.

이 글에서는 이 좌표 오차가 왜 발생하는지, 그리고 이를 어떻게 해결했는지에 대해 실제 경험을 바탕으로 정리한다.

⚙️ HTML과 Canvas 좌표계 차이의 본질

1. 서로 다른 좌표 단위

• Canvas는 _Canvas 픽셀 좌표계_를, HTML은 _CSS 픽셀 좌표계_를 기준으로 한다.

• 브라우저의 확대/축소나 디바이스의 devicePixelRatio 설정에 따라 좌표 오차가 누적될 수 있다.

2. Konva의 scale 적용 방식

• Konva의 scale은 Canvas 내부 transform으로 적용된다.

• 반면 HTML은 CSS의 transform 속성으로 처리되므로, 서로 다른 좌표 변환 방식을 사용한다.

3. 부모 컨테이너의 padding, border, flex 영향

• Konva <Stage>의 부모 요소에 padding, border, flex 설정이 있으면 좌표 보정이 반드시 필요하다.

4. 스크롤/뷰포트 기준 좌표차

• getClientRect()는 DOM 기준, getAbsolutePosition()은 Konva 내부 기준이다.

• 따라서 스크롤이 있는 페이지에서는 툴바 위치가 어긋나는 원인이 될 수 있다.

🧪 실제 문제 사례: 툴바 위치가 맞지 않던 이유

문제 상황

텍스트나 도형을 클릭하면 요소 하단 중앙에 툴바를 띄우는 구조를 구현 중이었다. 초기에는 getAbsolutePosition()으로 좌표를 받아 다음과 같이 툴바 위치를 설정했다:

const position = node.getAbsolutePosition();
setToolbar({ x: position.x, y: position.y });

그러나 실제 렌더링된 툴바는 완전히 다른 위치에 표시되었다. 이는 getAbsolutePosition()이 scale, 회전, 그룹화 변형을 반영하지 않는 논리 좌표만 반환하기 때문이다.

✅ 해결 방법 : getClientRect() 기반 좌표 계산

보다 정확한 위치 계산을 위해 getClientRect()를 사용한 코드로 교체했다:

const handleUpdateToolbarNode = (node: Konva.Node) => {
  requestAnimationFrame(() => {
    const rect = node.getClientRect();
    setToolbar({
      x: rect.x + rect.width / 2 - (TOOLBAR_WIDTH * zoom) / 2,
      y: rect.y + rect.height + 8,
    });
  });
};

• getClientRect()는 실제 렌더링 기준의 x, y, width, height 정보를 포함한다.

• 이를 기반으로 요소의 하단 중앙에 툴바가 정확히 위치하게 된다.

두 메서드의 비교

1. getAbsolutePosition()

반환값: { x, y } (논리 좌표) 장점: 변형 전 순수 좌표 확인 가능 단점: 스케일, 회전, 그룹 트랜스폼 미반영

2. getClientRect()

반환값: { x, y, width, height } 장점: 실제 렌더링된 bounding box 조회 가능 단점: CSS와 Canvas 스케일 차이에 대한 보정 필요

🔄 Zoom 적용 후 추가 문제와 해결

Zoom 기능을 추가한 이후, 좌표가 또다시 어긋나는 문제가 발생했다. Konva 좌표는 확대된 상태로 계산되므로, HTML 요소는 Zoom을 나누어 보정해야 한다:

const textPosition = textNode.getAbsolutePosition();
const areaPosition = {
  x: textPosition.x / zoom,
  y: textPosition.y / zoom,
};
setupTextareaStyles({ textarea, textNode, areaPosition });

✨ 결론

HTML과 Canvas는 본질적으로 좌표계가 다르다.

이 차이를 정확히 이해하고, getClientRect()와 zoom 보정을 적절히 적용한 결과, 툴바 및 입력창 같은 HTML 오버레이 요소들이 사용자 기준 위치에 정확하게 렌더링되도록 구현할 수 있었다.

이 경험을 통해 좌표계 문제를 단순 보정이 아닌 시스템적 차이로 인식하고 대응하는 사고력을 키울 수 있었다.

에서

최근 작업하던 브랜치에서 파일명을 대문자에서 소문자로 바꾸는 단순한 변경을 진행했다:

• 변경 전: Header.tsx
• 변경 후: header.tsx

그런데 갑자기 GitHub Pull Request(PR)에서 예상치 못한 충돌(conflict) 이 발생했다.

로컬에서 git status는 깨끗한 상태였지만, GitHub에서는 아래와 같은 충돌 메시지가 나타났다:

This branch has conflicts that must be resolved These conflicts are too complex to resolve in the web editor.

더욱 당황스러웠던 점은:

• GitHub의 웹 에디터에서 "Resolve conflicts" 버튼조차 비활성화된 상태.
• 심지어 GitHub 원격 저장소와 로컬 환경 모두에서 이미 파일명은 정상적으로 header.tsx로 적용된 상태였다.

도대체 왜 이런 문제가 발생한 걸까?

🤔 원인 분석

결론부터 말하자면, 이 문제는 macOS의 파일 시스템 특성에서 비롯된 것이다.

✅ macOS의 파일 시스템 특징

macOS의 기본 파일 시스템(HFS+ 또는 APFS)은 대소문자를 구분하지 않는(case-insensitive) 특성을 가진다.

즉, macOS에서는 아래 두 파일을 완전히 동일한 파일로 인식한다:

• ✅ Header.tsx
• ✅ header.tsx

그러나 Git은 내부적으로 파일명을 대소문자까지 엄격하게(case-sensitive) 구분한다.
따라서 대소문자만 변경한 경우, Git이 이를 서로 다른 두 개의 파일로 잘못 인식하게 된다.

🚩 문제의 흐름 요약

• macOS에서는 Header.tsx → header.tsx로 파일 이름만 바꾼 것으로 인식함.
• Git은 두 파일명이 서로 다르다고 생각하여, PR 병합 과정에서 두 개의 서로 다른 파일이 존재한다고 착각함.
• 결과적으로 GitHub PR에서는 충돌(conflict)이 발생하게 됨.

🛠️ 해결 과정 (시도했던 방법들)

❌ 시도했지만 실패한 방법들:

• ✅ 다른 브랜치에서 merge dev를 시도했지만, 충돌로 나타난 파일 자체가 존재하지 않아 실패.
• ✅ git add . && git commit으로 다시 커밋해도 PR 충돌 해결 안됨.
• ✅ git mv header.tsx tmp.tsx 이후 커밋을 하고 다시 git mv tmp.tsx header.tsx 를 하고 커밋을 했지만, macOS는 대소문자 변경만으로는 변경된 것을 인식하지 못해서 실패.
• ✅ git config core.ignorecase false 설정 후 다시 진행했으나, 효과 없음.

🚨 마침내 성공한 최종 해결 방법 (강력 추천 ✅)

위 방법들이 모두 실패한 뒤, 마지막으로 선택한 방법은 오히려 다시 원래 파일명으로 되돌리는 것이었다.

즉, header.tsx → Header.tsx로 다시 바꾸고 커밋했더니 모든 충돌이 해결됐다.

✨ 성공적으로 해결된 절차는 아래와 같다:

1. 터미널에서 명확하게 대문자로 변경 명령 수행

   git mv header.tsx Header.tsx

2. 명확히 커밋 메시지 작성 후 커밋

   git commit -m "fix: rename header.tsx to Header.tsx to fix GitHub PR conflict"

3. 변경 사항을 원격 브랜치에 푸시 git push origin 브랜치명

Next.js 14 프로젝트에서 Konva와 react-konva를 사용하는 법을 정리하려고 한다.

특히 SSR(Server Side Rendering) 환경에서 Konva를 클라이언트 전용으로 설정하는 방법과 react-konva의 버전 호환 문제를 해결해야지 자유롭게 사용이 가능하다.

1. 기본 패키지 설치

pnpm add konva react-konva@18

• Next.js 14는 현재 React 18.x 버전을 사용한다.
• 하지만 react-konva 최신 버전(19.x)은 React 19을 요구하기 때문에 버전을 명시적으로 낮춰서 설치해야 한다.

2. Konva를 사용한 캔버스 컴포넌트 만들기

• Konva를 사용하는 컴포넌트는 Next.js의 서버 환경에서 동작하지 않으므로,
• 반드시 최상단에 "use client";를 붙여 클라이언트 전용 컴포넌트로 설정해야 한다.

4. 클라이언트 전용 컴포넌트로 불러오기

• Konva를 사용하는 컴포넌트는 Next.js의 SSR 환경에서 바로 렌더링되지 않으므로,

• 반드시 dynamic import와 함께 ssr: false 옵션을 사용해야 한다.

import dynamic from "next/dynamic";

const CanvasEditor = dynamic(() => import("@/components/CanvasEditor"), {
  ssr: false,
});

export default function Home() {
  return (
    <div>
      <CanvasEditor />
    </div>
  );
}

5. SSR 환경에서의 canvas 모듈 에러 해결

• Next.js 서버 빌드 시 Konva 내부에서 Node.js의 canvas 모듈을 찾으려고 하면서 에러가 발생할 수 있다.

• 이를 방지하기 위해 프로젝트 루트의 next.config.js에 다음과 같은 Webpack 설정을 추가한다.

/** @type {import('next').NextConfig} */
const nextConfig = {
  webpack: (config, { isServer }) => {
    if (isServer) {
      config.resolve.fallback = {
        ...config.resolve.fallback,
        canvas: false,
      };
    }
    return config;
  },
};

module.exports = nextConfig;

6. 정리

• 사용하는 next 버전과 알맞은 react-konva 설치하기

• dynamic import와 ssr: false로 클라이언트로 불러오기

• next.confing.js에서 webpack 추가

처음 프로젝트를 구상할 때 React-DnD와 React-RnD를 이용해 명함 편집 도구를 구현하는 방식을 택했다. DOM 기반의 편집 방식이 React와의 친화성이 높고, 드래그 앤 드롭과 리사이징 기능을 쉽게 관리할 수 있을 것이라 생각했기 때문이다.

기획 변화와 UX 중심의 고민

하지만 상세하게 기획을 하다보니 조금씩 퀼리티 높은 편집툴을 만드는 방향으로 가게 되었다. 또한 사용자입장에서 생각해보면 보다 정밀하고 고급스러운 편집툴이 훨씬 더 ux적인 측면에서 좋지 않을까라는 생각을 했다.

DOM 기반 방식의 한계

DOM 요소를 기반으로 한 편집 방식은 요소가 많아질수록 성능 저하가 발생할 가능성이 높아진다. DOM 방식은 브라우저의 DOM 트리 구조를 직접 조작하는 방식으로, 각각의 요소가 브라우저에 개별적으로 렌더링되기 때문에 요소가 많아질수록 리플로우(reflow)와 리페인트(repaint) 작업이 빈번해진다.
리플로우는 요소가 추가되거나 스타일이 변경될 때 발생하며, 이 과정에서 브라우저는 전체 레이아웃을 다시 계산해야 하므로 성능 저하가 일어난다. 특히, 빈번한 드래그 앤 드롭, 리사이즈와 같은 실시간 인터랙션이 많아질수록 성능 저하가 더욱 심각해진다.

또한 DOM 방식은 정밀한 그래픽 제어가 어렵다는 단점이 있다. DOM과 CSS를 활용하면 위치 지정과 간단한 변형(transform)이 가능하지만, 세밀한 픽셀 단위의 위치 조정이나 자유로운 형태의 변형(회전, 스큐 등)을 정확하게 구현하는 것이 어렵다. 특히, CSS transform 속성의 한계로 인해 미세한 조정에서 부자연스러운 현상이 발생할 수 있고, 다양한 브라우저에서 일관된 결과를 보장하기도 어렵다.

또한 DOM 구조는 계층적인 HTML 구조를 기반으로 하기 때문에 복잡한 레이어 관리가 까다롭고, z-index 관리가 복잡해지면 유지 보수가 힘들어진다. 더불어 DOM 요소 간의 이벤트 처리가 복잡해질 수 있으며, 이벤트 위임(event delegation) 방식으로 성능 최적화를 진행하더라도 일정 수준 이상의 인터랙션이 발생하면 처리 비용이 증가하게 된다.

이러한 여러 한계점 때문에 DOM 방식이 사용자에게 직관적이고 전문적인 편집 경험을 제공하는 데 적합하지 않다고 판단하게 되었다.

캔버스 기반 기술로의 전환

이러한 문제를 해결하기 위해 캔버스 기반의 Konva.js(미정)를 선택하게 되었다. 캔버스는 픽셀 단위의 정밀한 제어와 고성능 렌더링을 지원하며, 요소의 회전, 레이어 관리 등 복잡한 그래픽 작업에 특화되어 있다. 결과적으로 캔버스를 통해 더욱 전문적인 디자인 툴에 가까운 사용자 경험을 제공할 수 있게 되었다.

포트폴리오 관점에서의 고민과 결정

캔버스로의 전환을 고민하는 과정에서, 포트폴리오로 작성할 내용을 충분히 확보할 수 있을지에 대한 걱정이 있었다. 처음에는 DOM 기반의 DnD 방식이 직접적인 로직과 상태 관리 부분에서 설명할 부분이 많아 포트폴리오로 적합해 보였지만, 실제로 캔버스 방식을 택하고 개발을 진행하게 된다면 노가다적이고 반복적인 로직(상태 관리, 이벤트 처리 등)을 최소화 시킬 수 있다는 장점이 있다. 또한 캔버스 기반의 기술적 특성과 렌더링 최적화, 정밀한 기능 구현 등 더 깊이 있는 기술적 도전과 해결 과정을 제시할 수 있어, 결과적으로 포트폴리오의 퀄리티를 높일 수 있다는 생각을 하게 되었다.

기술 방식 비교

결론

결과적으로 DOM 기반의 React-DnD와 React-RND 방식에서 캔버스 기반의 Konva.js로의 전환을 통해 더 정밀한 제어와 고급스러운 그래픽 기능을 제공할 수 있었다. 캔버스 방식을 통해 개발 과정에서의 반복적이고 복잡한 로직을 간소화하고, UX적으로 우수한 사용자 경험을 실현할 수 있게 되어 포트폴리오의 기술적 완성도와 깊이를 높일 수 있었다.

목표

• 사용자가 드래그 앤 드롭 방식으로 쉽게 명함을 제작
• 제작된 명함을 공유하여 발생하는 다양한 유저 액션(조회, 다운로드, 클릭 등)을 추적해 통계로 제공하는 웹 서비스 구축

핵심 가치

• 사용 편의성이 높은 명함 제작 도구 제공
• 제작된 명함의 활용도 및 반응을 실시간 데이터로 확인 가능

2. 기술 스택

프론트엔드/백엔드

• Next.js 14 (최신 App Router, 서버 액션 등 활용)

데이터베이스 및 인증

• Supabase (DB, Auth, RLS 등)

통계 시각화

• Chart.js (다양한 차트 유형 활용: 라인, 도넛, 바 차트 등)

명함 제작 인터페이스

• 드래그 앤 드롭 방식 (예: react-dnd 등 라이브러리 활용)

3. 서비스 주요 기능

명함 제작 및 편집

사용자는 템플릿 선택 후 에디터에서 드래그 앤 드롭 방식으로 명함 디자인 텍스트, 이미지, 아이콘 등의 요소를 자유롭게 배치하고, 수정 가능

명함 공유: 제작된 명함은 고유 URL(slug)을 통해 공유 공유된 명함은 별도의 페이지에서 일반 사용자에게 노출 데이터 추적 및 통계 분석: 추적 항목: 총 조회수, 고유 방문자, 이미지 저장 횟수, 이메일 클릭 횟수, QR 코드 스캔 횟수, 평균 체류 시간 각 이벤트 발생 시 API 호출을 통해 Supabase에 기록 수집된 데이터는 Chart.js를 통해 관리자 및 명함 소유자 대시보드에서 시각화

4. 페이지 구성 및 역할

   1. 홈페이지 • 서비스 소개, 주요 기능 설명, CTA(템플릿 선택, 로그인/회원가입 등)
   2. 템플릿 리스트 페이지 • 약 12개의 미리 디자인된 명함 템플릿 제공 • 사용자가 템플릿을 선택하면 에디터 페이지로 이동하여 해당 템플릿 기반 명함 제작 시작 • 템플릿은 기본 디자인으로 제공되며, 선택 후 에디터에서 자유롭게 수정 가능
   3. 마이페이지 • 사용자가 제작한 명함들을 한눈에 확인 • 각 명함에 대해 편집, 삭제, 공유 기능 제공
   4. 에디터 페이지 • 드래그 앤 드롭 기반 명함 편집 도구 제공 • 선택한 템플릿을 불러와 수정 또는 새로운 디자인 작업 진행 • 실시간 미리보기와 저장 기능 구현
   5. 명함 상세페이지 • 제작된 명함의 상세 정보 및 디자인 확인 • 명함과 관련된 통계(조회수, 유저 액션 등)를 시각화하여 표시 (Chart.js 활용)
   6. 명함 공유된 페이지 • 외부 사용자들이 공유된 명함을 열람할 수 있는 페이지 • 간편한 명함 뷰 제공 및 해당 명함 관련 이벤트(조회, 체류 시간 등) 기록
   7. 로그인/회원가입 페이지 • 사용자 인증 및 계정 생성 • Supabase Auth 연동을 통한 보안 로그인/회원가입 처리

5. 데이터베이스 설계 및 이벤트 추적 • 주요 테이블 예시: • users: 사용자 계정 정보 저장 • cards: 제작된 명함 정보 (디자인 데이터, 소유자 정보, 고유 slug 등) • card_views 또는 card_events: 명함 조회 및 각종 이벤트(이미지 저장, 이메일 클릭, QR 스캔 등) 기록 • 각 이벤트는 event_type(조회, 저장, 클릭 등), 타임스탬프, 사용자 정보(IP, User-Agent 등)를 포함 • templates: 기본 템플릿 디자인 정보 • 데이터 집계: • 총 조회수/고유 방문자: 각 명함의 접속 로그 분석 • 이미지 저장/이메일 클릭/QR 스캔: 해당 액션 발생 시 API 호출로 이벤트 기록 • 평균 체류 시간: 페이지 입장 및 퇴장 시각을 기록해 평균 계산

6. 사용자 플로우

   1. 사용자 방문 및 템플릿 선택: • 사용자는 홈페이지에서 서비스 소개를 확인한 후, 템플릿 리스트 페이지로 이동 • 12개의 템플릿 중 원하는 디자인 선택
   2. 명함 제작 및 편집: • 선택한 템플릿을 기반으로 에디터에서 드래그 앤 드롭 방식으로 명함 디자인 • 디자인 완료 후 저장, 마이페이지에서 관리
   3. 명함 공유 및 조회: • 제작된 명함은 고유 URL로 생성되어 공유됨 • 다른 사용자는 공유된 페이지를 통해 명함을 확인하고, 이때 각종 유저 액션(조회, 클릭 등)이 기록됨
   4. 통계 확인: • 명함 상세페이지에서 Chart.js를 이용해 각종 이벤트 및 통계 데이터를 시각적으로 확인 • 통계 데이터는 Supabase에서 집계되어 제공
   5. 로그인/회원가입: • 사용자 인증 및 계정 관리를 위해 로그인/회원가입 페이지에서 계정 생성 및 로그인 진행

7. 구현 단계 및 고려 사항 • 프로젝트 초기 세팅: • Next.js 14, TypeScript 환경 구성 • Supabase 프로젝트 설정 및 연동 (.env 파일에 키/URL 저장) • DB 및 인증 설정: • Supabase Dashboard에서 users, cards, card_events 등 테이블 생성 • Supabase Auth를 활용한 사용자 인증 구현 • 프론트엔드 구현: • Next.js App Router를 활용한 각 페이지 구성 • 에디터 페이지의 드래그 앤 드롭 인터페이스 구현 (react-dnd 등 사용) • 명함 상세 및 공유 페이지에서 이벤트 추적 스크립트 구현 • 통계 및 대시보드 구현: • API 라우트 혹은 서버 액션을 통해 Supabase에서 통계 데이터 집계 • Chart.js를 사용한 데이터 시각화 및 대시보드 구성 • 테스트 및 배포: • 각 기능(명함 제작, 공유, 이벤트 기록, 통계 시각화) 단위 테스트 • 최종 배포 전 성능 및 보안 점검 (특히 데이터 추적 및 인증 관련)텍스트

   8. DB

9. 유저 플로우

최근 Next.js 프로젝트를 진행하며 parallel 라우트를 사용한 모달 구현 방법을 적용해 보았다. 기존에 자주 사용했던 State + Portal 방식을 사용하는 모달과 비교하며 느낀 장점과 한계를 정리해보려고 한다.

Parallel 라우트란?

Parallel 라우트는 Next.js에서 제공하는 기능 중 하나로, URL 경로에 영향을 주지 않으면서도 각 컴포넌트를 독립적으로 렌더링할 수 있게 해준다. 특히 로딩이나 에러 상태 관리, 데이터 캐싱 등을 Next.js에서 자동으로 최적화하여 제공한다.

Parallel 라우트가 필요한 이유

1. Route Segment처럼 로딩과 에러 상태 관리 가능

• URL에 영향을 주지 않는 독립적인 컴포넌트에도, 마치 일반적인 Route Segment처럼 loading과 error 상태를 관리할 수 있게 된다.

2. Fetch 캐시 관리 최적화

• 비동기 요청 시 Next.js가 자동으로 fetch 요청을 캐싱해주고 효율적으로 관리한다.

기존(State + Portal) 방식 모달의 장단점

기존의 모달 구현 방식은 React의 State와 React Portal을 이용하여 구현하는 방법이다.

장점

• 구현이 직관적이고 간단함.

• URL에 영향을 미치지 않기 때문에 모달의 상태만으로 간단히 관리할 수 있음.

단점

• 상태 관리 코드가 증가하며 유지보수가 어려워질 수 있음.

• 웹뷰(Android) 환경에서 물리적인 백버튼을 눌렀을 때 추가적인 코드가 필요하여 복잡성 증가.

• 뒤로가기나 페이지 전환 시 모달 상태 관리가 까다로워질 수 있음.

// 기존 방식 모달 예시
const [open, setOpen] = useState(false);

return (
  <>
    <button onClick={() => setOpen(true)}>모달 열기</button>
    {open && ReactDOM.createPortal(
      <div className="modal">
        모달 내용
        <button onClick={() => setOpen(false)}>닫기</button>
      </div>,
      document.getElementById('modal-root')
    )}
  </>
);

Parallel 라우트를 사용한 모달의 장단점

장점

• 별도의 상태 관리 코드가 필요 없으므로 코드가 간결해지고 유지보수가 쉬워진다.

• 브라우저의 뒤로가기 버튼을 이용하여 모달을 자연스럽게 닫을 수 있어 UX 상승

• Next.js에서 fetch 요청을 자동으로 최적화 관리

단점

• 기본적으로 소프트 내비게이션(CSR, router.push 또는 Link 사용)에 적합하며, 하드 내비게이션(새로고침, 직접적인 URL 접근) 처리에는 한계가 있다.

• 중첩된 모달을 구현시, 추가적인 parallel route 슬롯을 만들어야 하는 복잡성이 있다.

// 폴더 구조
app/
├── @modal
│   └── modal
│       └── page.jsx
└── page.jsx

// Parallel 라우트를 이용한 모달 예시
// page.jsx
import Link from 'next/link';

export default function Page() {
  return (
    <>
      <Link href="/@modal/modal" scroll={false}>모달 열기</Link>
    </>
  );
}

// @modal/modal/page.jsx
export default function Modal() {
  return (
    <div className="modal">
      모달 내용
    </div>
  );
}

결론

Parallel 라우트를 이용한 모달 구현은 다음과 같은 경우에 유리하다.

• 간단한 상태 관리와 자연스러운 뒤로가기 처리가 중요한 경우
• 모달이 빈번히 열리고 닫히며, 상태 코드가 복잡해질 수 있는 경우
• Next.js의 fetch 캐싱 기능을 적극적으로 활용하고 싶은 경우

반면, 다음과 같은 상황에서는 기존의 State + Portal 방식이 더 적합하다.

• URL 경로를 절대 변경하지 않고 모달을 처리해야 하는 경우
• 하드 내비게이션(새로고침 등)과 직접적인 URL 접근을 빈번하게 사용하는 경우
• 중첩된 모달을 관리하기 위한 추가적인 parallel 슬롯 관리가 번거로운 경우

프로젝트의 특성과 요구 사항에 따라 적절한 방식을 선택하면 최적의 개발 경험과 사용자 경험을 제공할 수 있을 것이다.

• Next.js의 새로운 기능 중 하나로, 클라이언트 컴포넌트 내부에서 서버로 직접 호출할 수 있는 서버 전용 함수

주요 특징

1. 클라이언트와의 긴밀한 통합

• 클라이언트 컴포넌트 내에서 함수 호출만으로 서버 로직을 실행 가능
• 별도의 API 엔드포인트를 구성할 필요 없이, UI와 밀접하게 연동되는 기능들을 쉽게 구현 가능

2. 보안

• 서버 액션은 서버에서만 실행되기에 민감한 정보가 클라이언트에 노출 방지
• Ex) 폼 제출 시 입력 데이터를 서버에서 직접 처리하여 응답하는 경우

3. 개발 생산성

• 하나의 파일 내에서 클라이언트와 서버 로직을 함께 관리할 수 있기 때문에, 코드 중복을 줄이고 빠른 프로토타이핑이 가능

요약

• UI와 밀접하게 연관된 작업(폼 제출, 간단한 데이터 업데이트 등)
• 클라이언트와 서버 간의 경계를 최소화해 개발하고자 할 때

2. 라우트 핸들러(Route Handler)란?

• Next.js의 파일 기반 라우팅 시스템을 활용하여 API 엔드포인트를 구성하는 방식
• 일반적으로 /app/api 폴더에 파일을 생성해 HTTP 메서드(GET, POST, PUT, DELETE 등)에 따라 서버 사이드 로직을 작성

주요 특징

1. 모듈화된 서버 로직

• UI와 분리된 독립적인 API 엔드포인트를 구성함으로써, 복잡한 비즈니스 로직을 체계적으로 관리 가능
• 파일 기반 라우팅 덕분에 프로젝트의 구조가 명확해질 수 있음
• 즉, 어느 파일이 어떤 역할을 하는지 쉽게 파악 가능

2. 다양한 HTTP 메서드 지원

• 하나의 라우트 파일 내에서 여러 HTTP 메서드를 처리할 수 있어, 복잡한 API 로직이나 다양한 클라이언트 요청을 효과적으로 대응 가능

3. 외부 시스템과의 연동

Next.js 애플리케이션 외부의 다른 서비스(예: 모바일 앱, 다른 웹 애플리케이션)와의 통신에 적합

• RESTful API 서버로서 역할을 수행 가능

** RESTful(Representational State Transfer) : 간결하고 일관된 방식으로 클라이언트와 서버 간의 데이터를 교환할 수 있도록 도와주는 설계 방식

요약

• 독립적인 API 서비스 구축 (여러 클라이언트가 호출할 수 있는 공개 API 제공)
• 복잡한 로직이나 다양한 HTTP 메서드를 필요로 하는 경우
• UI와 서버 로직을 완전히 분리해 관리하고자 할 때

차이점

3. 서버 액션과 라우트 핸들러의 차이점 및 선택 기준

결론

*서버 액션 : *

• UI와 긴밀하게 연동된 간단한 작업을 신속하게 처리하고자 할 때 유용

라우트 핸들러 :

• 독립적인 API를 구성해 외부 시스템과의 통신이나 복잡한 로직을 모듈화하여 관리할 때

Next.js에서는 error.js 파일을 통해서 중첩된 라우트에서 발생하는 예기치 못한 런타임 오류를 처리 할 수 있음 클라이언트 컴포넌트에서는 처리할 방법이 많기 때문에 서버에서 다루는 방법에 대해 작성해보자.

• error.tsx : 특정 경로(페이지)에서 발생한 에러를 처리(재시도 or 홈으로 이동)
• global-error.tsx : 앱 전체에서 발생하는 에러를 전역으로 처리

error.tsx

각 경로에서 에러가 발생하면 해당 경로에 생성된 error.tsx가 자동 렌더링

"use client";

import { useRouter } from "next/navigation";
import { startTransition } from "react";

export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  const { refresh } = useRouter();

  return (
    <div>
      <h2>에러가 발생했습니다</h2>
      <h2>{error.message}</h2>
      <button
        onClick={() =>
          startTransition(() => {
            refresh();
            reset();
          })
        }
      >
        Try again
      </button>
    </div>
  );
}

useRouter()와 startTransition()을 꼭 포함시키기 사용하지 않으면 버튼을 클릭해도 새로고침이 되지 않음

refresh() : 강제 새로고침 startTransition() : 상태 업데이트가 긴급하지 않은 경우, 해당 업데이트를 낮은 우선순위 작업으로 처리(ui 응답성 개선)

global-error.tsx

전역 에러를 처리하기 위한 컴포넌트

'use client';

export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    <html>
      <body>
        <h2>Something went wrong!</h2>
        <button onClick={() => reset()}>Try again</button>
      </body>
    </html>
  );
}

global-error.tsx가 필요한 이유

• error.tsx는 각 경로(폴더)마다 별도로 적용되기에 해당 경로 내에 발생하는 에러만 처리
• 따라서 앱 전체에서 발생하는 예외, 비동기 로직에서 잡히지 않은 에러, 최상단에서 발생한 에러에 대해서는 error.tsx로는 처리 할 수 없음

다크모드를 추가하고 나니 에러 발생

Uncaught Error: Minified React error #418; visit https://react.dev/errors/418 for the full message or use the non-minified dev environment for full errors and additional helpful warnings.

기존코드

"use client";

import { Moon, Sun } from "lucide-react";
import { useTheme } from "next-themes";

const DarkMode = () => {
  const { theme, setTheme } = useTheme();

  return (
    <button
      onClick={() => setTheme(theme === "dark" ? "light" : "dark")}
      className="rounded px-4 py-2"
    >
      {theme === "dark" ? <Sun /> : <Moon />}
    </button>
  );
};

export default DarkMode;

하지만, 초기 렌더링 시 theme 값이 아직 제대로 설정되지 않거나, 서버와 클라이언트 간의 불일치로 인해 에러가 발생

원인

Next-themes는 브라우저에서 사용자의 설정이나 OS 테마에 따라 다크모드를 결정하는데 초기기 랜더링할 때는 theme가 설정되지 않을 수 있음.

해결 방법: 마운트 상태 확인

변경코드

"use client";

import { Moon, Sun } from "lucide-react";
import { useTheme } from "next-themes";
import { useEffect, useState } from "react";

const DarkMode = () => {
  const { theme, setTheme } = useTheme();
  const [mounted, setMounted] = useState(false);

  useEffect(() => {
    setMounted(true);
  }, []);

  if (!mounted) return null;

  return (
    <button
      onClick={() => setTheme(theme === "dark" ? "light" : "dark")}
      className="rounded px-4 py-2"
    >
      {theme === "dark" ? <Sun /> : <Moon />}
    </button>
  );
};

export default DarkMode;

초기에 useState로 mounted를 false로 주고 나서 useEffect로 렌더링이 되면 true로 바꿔줘서 해결

최근 과제를 진행하면서 챔피언 리스트에서 특정 캐릭터의 상세 정보를 확인할 때 발생하는 이미지 로딩 지연 문제를 발견했습니다.

문제 상황

상세 페이지에 들어가면 챔피언의 스킬 정보와 함께 각각의 스킬 이미지가 표시되도록 만들었다. 그런데 일부 챔피언 상세 페이지에서는 스킬 이미지가 바로 로드되는 반면, 다른 페이지에서는 이미지가 1초에서 3초 정도 늦게 나타나는 문제가 있었습니다.

문제 확인

기본 HTML의 <img> 태그와 Next.js의 Next/Image 컴포넌트를 비교

• <img> 태그는 별도의 lazy loading(지연 로딩) 설정이 없기 때문에 브라우저가 페이지 렌더링 시 바로 이미지를 로드

원인

원인 : Next.js의 Next/Image 컴포넌트가 기본적으로 lazy loading(지연 로딩)을 사용하기 때문

Lazy loading이란

• 사용자가 현재 보고 있는 영역에 노출되는 이미지들만 우선 로드
• 나머지는 스크롤 등으로 실제 화면에 나타날 때 로드함으로써 초기 로딩 속도를 개선하는 기법
• 따라서 캐시에 이미지가 없거나 아직 해당 영역에 도달하지 않은 경우, 이미지 로딩이 지연되는 현상이 발생

해결 방안

1. Next/Image 컴포넌트에 priority 속성 사용 (강제 로드)

• 해당 이미지를 초기 로딩 시 우선적으로 로드하도록 지시

2. Next/Image 컴포넌트에 loading="eager" 속성 사용 (강제 로드) lazy loading 대신 이미지를 즉시 강제 로드

   {championDetail.spells.map((spell) => (
        <div key={spell.id} className="flex flex-row items-center space-x-8">
          <div>
            <span>스킬 : {spell.id.slice(-1)}</span>
            <Image
              priority // 1번째 방법
              loading="eager" //2번째 방법
              src={`${SERVER_URL}/cdn/${VERSION}/img/spell/${spell.image.full}`}
              alt={spell.name}
              width={70}
              height={70}
            />
          </div>
          <img
            src={`${SERVER_URL}/cdn/${VERSION}/img/spell/${spell.image.full}`}
          />

Next.js는 페이지 성능을 향상시키기 위해 자동으로 다양한 캐싱 전략을 제공 - 빌드 시점 캐싱 (Full Route Cache) - 요청 시 데이터 캐싱 (Data Cache)

Next.js의 fetch API는 브라우저의 fetch API를 확장한 것이며, 캐싱 전략을 설정할 수 있는 강력한 기능을 제공

1. Full Route Cache (빌드 시점 캐시)

정의: Next.js가 빌드 단계에서 전체 페이지를 렌더링하여 HTML 및 데이터를 미리 캐싱

장점: 동일한 페이지 요청이 올 때 매번 렌더링하지 않고 미리 렌더링된 캐시를 제공하기에 응답 시간이 매우 빠름

특징: - React Server Components를 미리 렌더링하여 결과를 캐싱 - 사용자 요청마다 미리 생성된 페이지 제공 (속도 매우 빠름)

단점: 데이터가 자주 변하는 경우, 실시간 반영이 어려움

2. Data Cache (요청 시점 데이터 캐시)

정의: 데이터 요청 시점에 데이터를 캐싱하여 반복적인 API 호출을 방지하는 방식

효과: 데이터 요청 횟수를 줄여 응답 속도를 높이고, 서버 부하를 줄여줌

예시 (ISR)

// 1시간 동안 캐시된 데이터를 제공, 이후 다시 불러옴
const res = await fetch('https://api.example.com/data', { next: { revalidate: 3600 } });
const data = await res.json();

예시 (SSR)

// 항상 최신 데이터를 요청 (캐시 사용 X)
const res = await fetch('https://api.example.com/data', { cache: 'no-store' });
const data = await res.json();

유용한 캐싱 기능

generateStaticParams()

정적인 페이지들을 빌드 시점에 미리 생성하는 데 사용

// posts의 slug를 이용해 정적 페이지 미리 생성
export async function generateStaticParams() {
  const posts = await fetch('https://.../posts').then((res) => res.json());

  return posts.map((post) => ({
    slug: post.slug,
  }));
}

// params로 전달된 값 사용 가능
export default function Page({ params }) {
  const { slug } = params;
  // ...
}

태그 기반 캐싱 (tags)

특정 데이터를 태그로 식별하여 효율적으로 캐시를 관리

fetch('/api/data', {
  next: {
    tags: ['products'],
  }
});

캐시 무효화 (revalidate)

캐시된 데이터를 주기적으로 갱신하는데 사용 (ISR 방식)

fetch('/api/data', {
  next: {
    revalidate: 60, // 60초마다 데이터 갱신
  }
});