분명 로그를 확인해 보니 비밀번호를 틀려서 발생한 에러였는데, 왜 화면에는 세션 만료가 떴을까요? 범인은 바로 과거의 저였습니다. 😂

개발자인 저는 F12를 눌러 Network 탭을 보면 그만이지만, 사용자는 제가 띄워준 토스트 알림 하나에 의지해 서비스를 이용합니다. 엉성했던 에러 처리가 사용자를 얼마나 혼란스럽게 만들었는지 반성하며, 이를 구조적으로 개선한 과정을 공유해 봅니다.

1. 문제의 시작 : "401은 다 세션만료?"

사실 처음부터 이랬던 건 아니었습니다. 원래는 로그인/비밀번호 에러만 각각 처리하고 있었는데요. 어느 날 "로그인 상태인데 삭제나 수정이 안된다"는 피드백을 받게 됩니다. 원인은 세션 만료였죠.

그래서 급하게 "401 Unauthorized 에러가 오면 전역적으로 잡아서 세션 만료로 처리하고 재로그인을 시키자!"라고 수정을 해뒀습니다. 문제를 고치려다 다른 문제를 만든 실화

🛑 기존 방식의 문제점들

• 일반화의 오류 : 비밀번호가 틀려도 401, 토큰이 없어도 401... 다 똑같이 "세션 만료"라고 퉁처버렸습니다.
• 노가다 하드코딩 : API마다 응답 형식이 제각각이라 프론트에서 "등록 실패", "수정 실패" 메시지를 매번 하드코딩해서 띄웠습니다.
• 불친절한 정보 : 특히 인사 정보 입력할 때 중복 데이터가 있으면 "뭐가 중복인지"를 안 알려주니 사용자는 답답할 노릇이었죠.

2. 백엔드 : 에러에도 '이름'을 붙여주자 (FastAPI)

먼저 백엔드에서 내려주는 에러 응답 규격부터 통일했습니다. 프론트가 에러의 정체를 바로 알 수 있게 errorCode를 심어준 것입니다.

# 공통 에러 응답 양식
return JSONResponse(
    status_code=409,
    content={
        "success": False, 
        "errorCode" : "DB_DUPLICATE_ENTRY",
        "message": "이미 등록된 정보(주민번호 등)가 존재합니다.", 
        "data": None
    },
)

그리고 모든 API마다 try-except를 쓸 순 없으니, main.py에서 전역적으로 에러를 잡아내도록 만들었다. (파이썬이 아직 낯설지만 적응 중입니다! 🐍)

@app.exception_handler(IntegrityError)
async def integrity_exception_handler(request: Request, exc: IntegrityError):
    logger.error(f"DB Integrity Error: {exc.orig}") 
    return JSONResponse(
        status_code=409,
        content={
            "success": False,
            "errorCode": "DB_DUPLICATE_ENTRY",
            "message": "이미 등록된 정보가 존재합니다.",
            "data": None
        }
    )

3. 프론트엔드 : "너 무슨 에러니" (Axios Interceptor)

이제 프론트에서는 Axios 인터셉터를 활용해 errorCode에 따라 똑똑하게 대응합니다. 무조건 로그인 모달을 띄우는 게 아니라, 상황을 먼저 파악하는 거죠.

✅ 개선된 인터셉터 로직

api.interceptors.response.use(
  (response) => response,
  (error) => {
    const { response } = error;

    if (response && response.status === 401) {
      const errorCode = response.data?.errorCode;

      // 1. 아이디/비밀번호 자체가 틀린 경우 (진짜 로그인 실패)
      if (errorCode?.startsWith("AUTH_INVALID_CREDENTIALS")) {
        toast.error("아이디 또는 비밀번호를 다시 확인해주세요.");
      } 
      // 2. 진짜 세션이 만료되었거나 토큰이 없는 경우 (재로그인 필요)
      else {
        toast.error("세션이 만료되었습니다. 다시 로그인해주세요.");
        useModal.getState().openModal("login"); // Zustand로 로그인 모달 짠!
      }
      return new Promise(() => {}); 
    }
    return Promise.reject(error);
  }
);

4. 마치며 : 대충 하지 말자.

사실 개발할 때는 기능 구현이 급해서 에러 처리를 뒤로 미루기 쉽습니다. 하지만 피드백을 받을 때마다 느끼는 건, 사용자에게 가장 친절해야 할 순간이 바로 에러가 발생한 순간이라는 점이에요.

요즘 AI 덕분에 코딩 속도는 엄청 빨라졌지만, 이런 디테일한 사용자 경험과 테스트를 챙기는 건 결국 개발자의 몫인 것 같습니다.

SSE 사용법 자세히 보기 (MDN) SSE는 Server-Sent Events로, 서버에서 클라이언트로 단방향 이벤트 스트림을 전송하는 기술이다.

🔍 언제 사용하면 좋을까?

웹에서 실시간 통신을 구현할 때는 주로 아래 3가지 방식을 고려한다. 상황에 맞게 선택하는 것이 중요하다.

📌 Polling (폴링)

2~3초마다 주기적으로 서버에 요청을 보내는 방식이다.

• 구현은 가장 간단하지만, 불필요한 요청이 반복되어 서버 부담이 큼
• 정달 간단한 구현, 테스트할 때 사용하자.

📌 WebSocket (웹소켓)

최초 한 번만 HTTP 요청으로 연결을 맺은 후, 쌍방향 통신을 지속적으로 유지한다.

• 단점은 초기 설정이나 구현이 복잡하다는 점
• 채팅, 실시간 협업 등 클라이언트-서버 간 상호작용이 많을 때 사용하자.

📌 SSE (Server-Sent Events)

HTTP 기반의 단방향 통신 방식으로, 서버에서 클라이언트로만 데이터 전송이 가능하다.

• 웹소켓보다 구현이 간단하고, 브라우저에서 자동 재연결 처리도 수월하다.
• 알림, 단순한 실시간 업데이트 등에 사용하자.

📎 나의 경험:

무인매장 관리 시스템에서 실시간 알림을 구현할 때 SSE를 사용한 경험이 있다. 이번 프로젝트에서도 읽지 않은 메시지 수를 실시간으로 업데이트 하기 위해 SSE를 선택했다.

EventSource

브라우저에서 기본적으로 제공하는 EventSource 객체를 이용해 서버와 SSE 연결을 할 수 있다.

  eventSource = new EventSource(
    `${process.env.VUE_APP_API_BASE_URL}/sse/subscribe?token=${token}`
  );

  eventSource.addEventListener("unread-count", (event) => {
    try {
      const data = JSON.parse(event.data);
      callback(data);
      console.log("unread-count 이벤트 data:", data);
    } catch (error) {
      console.error("SSE unread-count 데이터 파싱 에러", error);
    }
  });

  eventSource.onerror = (error) => {
    console.error("SSE 연결 오류", error);
    disconnectSSE();
  };

⚠️ 알아야 할 점

• EventSource는 GET 메서드만 지원하고, 헤더 설정이 불가능하다.
• 위 코드처럼 쿼리스트링으로 토큰을 넘기는 방식은 보안상 안전하지 않을 수 있다. (URL 로그에 토큰이 노출될 수 있음)

Event-source-polyfill

EventSource와 사용법은 거의 동일하나 헤더를 직접 추가할 수 있는 라이브러리이다. 그래서 나는 이 라이브러리로 헤더에 token을 보내는 방법으로 수정했다.

✅ 설치

npm install event-source-polyfill

✅ 적용 코드

import { EventSourcePolyfill } from "event-source-polyfill";

  eventSource = new EventSourcePolyfill(
    `${process.env.VUE_APP_API_BASE_URL}/sse/subscribe`,
    {
      headers: {
        Authorization: `Bearer ${token}`,
      },
      withCredentials: true,
    }
  );

🖥️ 서버(Spring Boot)도 함께 수정

기존에는 @RequestParams으로 토큰을 받았다면, 이제는 @RequestHeader로 헤더를 받아 처리한다.

    // MediaType.TEXT_EVENT_STREAM_VALUE : SSE를 위한 HTTP 응답 타입 설정 이다.
    // 이걸 설정하면 프론트가 sse 스트림이라고 인식할 수 있다.
    @GetMapping(value = "/subscribe", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public SseEmitter subscribe(@RequestHeader("Authorization") String authorizationHeader){
        String token = authorizationHeader.replace("Bearer ", "");

        Claims claims = Jwts.parserBuilder()
                .setSigningKey(secretKey)
                .build()
                .parseClaimsJws(token)
                .getBody();

        String email = claims.getSubject();
        System.out.println(email + " SSE 구독 연결됨");
        return sseService.subscribe(email);
    }

MediaType.TEXT_EVENT_STREAM_VALUE을 지정하면 프론트가 스트림을 응답으로 인식할 수 있다.

🔍 연결 확인 방법

개발자 도구(F12) → Network 탭에서 연결 상태 및 메시지를 확인할 수 있다. (물론 서버 로그로도 확인 가능)

1. subscribe 요청 확인

2. Headers : 인증 헤더 포함 여부, 상태코드(200/401) 확인

3. Response : 실시간 전달되는 메시지 스트림 확인

프로젝트 개요

배포 링크: MBTI 프로필 테스트

• ⏱ 개발 기간: 2025.06.13 ~ 2025.06.14 (2일)
• 🛠 기술 스택 : Next.js, TypeScript, Tailwind CSS

주요 기능

1. MBTI 테스트 진행

• 총 12개의 현실 기반 질문
• 각 질문마다 2개의 선택지 제공
• 선택지마다 성향(MBTI 지표) 매핑 → 최종 유형 계산

2. 결과 페이지

• 16가지 MBTI 유형별로 구성된 개성 있는 결과 제공
• 속마음, 좋아하는 것, 극혐 포인트 등 현실 기반 항목 포함
• SNS 공유 가능

3. 이미지는… GPT가 만들어줬습니다. 😇

🖼 OG 이미지도 직접 설정해봤습니다!

이번 프로젝트에선 처음으로 OG Image(Open Graph Image) 설정도 적용해봤습니다. SNS나 링크에서 썸네일 미리보기 이미지가 자동으로 뜨도록 한 건데, Next.j의 metadata에 이미지랑 title 정보를 설정했습니다.

export const metadata: Metadata = {
  title: "MBTI 테스트",
  description: "팩폭과 귀여움 사이, 당신의 성향은?",
  openGraph: {
    title: "MBTI 테스트",
    description: "팩폭과 귀여움 사이, 당신의 성향은?",
    images: [
      {
        url: "https://mbti-test-app-iota.vercel.app/og-image.png",
        width: 1200,
        height: 630,
        alt: "MBTI 썸네일",
      },
    ],
    type: "website",
  },
  twitter: {
    card: "summary_large_image",
  },
};

• public/og-image.png에 이미지 파일을 두고, 위처럼 메타 정보에 등록
• 어렵진 않았지만, 썸네일이 이런 설정으로 보인다는걸 알게 돼서 신기했음

⚡️ 성능 개선은 이거 하나만 ..

사실 큰 기능이 없는 단순 테스트 앱이라 성능 이슈는 없겠지 싶었는데, Lighthouse를 돌려보니… LCP가 19초 상세 정보를 보니 텍스트에 적용된 웹폰트가 늦게 렌더링되는 게 원인이었다.

폰트가 다운로드될 때까지 텍스트가 렌더링되지 않아서 지연 발생

@font-face {
    font-family: "Ownglyph_Seung_Hoon-Rg";
    src: url("https://fastly.jsdelivr.net/gh/projectnoonnu/2408@1.0/Ownglyph_Seung_Hoon-Rg.woff2") format("woff2");
    font-weight: normal;
    font-style: normal;
    font-display: swap; // 이거 추가 !
}

font-display: swap이란? : 폰트가 로딩되기 전에 기본 시스템 폰트로 먼저 렌더링하고, 웹폰트가 도착하면 그때 바꿔치기하는 방식

이거 하나만 추가하고 다시 측정해보니

LCP 1.2초, 성능 점수 75점 -> 100점 덕분에 웹폰트가 렌더링을 막는 방식과 폰트 최적화에 대해 제대로 이해할 수 있었다.

😊 짧은 회고

친구들이랑 일상에서 주고받던 대화를 그대로 질문으로 정리해서 빠르게 기획하고, 구현하고, 테스트해볼 수 있어서 재밌었다. Next.js로 만든 토이 프로젝트는 이번이 두 번째인데, 할수록 너무 편하고 좋다! 이번 프로젝트를 통해 App Router, Zustand, OG 이미지 설정 같은 기능도
직접 써보면서 훨씬 익숙해질 수 있었던 2일이었다. ☺️😊

🔗 GitHub

👉 GitHub 바로가기

프로젝트 생성부터

간단히 로그인 → 프로젝트 생성 가능 (무료 버전이면 2개까지만 만들 수 있고, 3개부터는 기존 프로젝트를 삭제하거나 중지해야 함) 나는 안 쓰는 거 중지시키고 새 프로젝트 생성해서 쓰는 중 👇

설치 및 초기 설정

npm install @prisma/client
npx prisma init

위 명령어로 Prisma를 초기화하면 schema.prisma 파일이 생성되고, DB 종류도 PostgreSQL로 자동 세팅된다.

Supabase 라이브러리도 설치해주자

npm install @supabase/supabase-js

🔌 Supabase 연결

Supabase 연결을 위해 .env 파일에 URL을 설정해야 한다. URL은 Supabase 페이지 상단의 Connect에서 찾을 수 있다.

Transaction pooler (pgbouncer) 와 Session pooler를 사용

DATABASE_URL="postgresql://postgres.<project-id>:<password>@<host>.supabase.com:6543/postgres?pgbouncer=true"
DIRECT_URL="postgresql://postgres.<project-id>:<password>@<host>.supabase.com:5432/postgres"

📌 DATABASE_URL은 트랜잭션 풀링(pgbouncer)용, 📌 DIRECT_URL은 직접 연결용 (migrate 등 내부 작업에 필요)

❓ 왜 이렇게 나눠야 할까?

처음엔 DATABASE_URL에 Direct connection만 지정했는데 오류 발생 그래서 Transaction pooler로 바꾸니까 오류는 안 나는데 아무 반응이 없음 ㅠ 여기저기 구글링하다가 이 블로그에서 해결방법을 찾았다!! (역시 구글링최고)

GPT한테 물어보니까 요렇게 정리해줌:

• Supabase는 기본적으로 트랜잭션 풀링(pgbouncer)을 사용해서 확장성 있게 운영함
• 근데 Prisma는 pgbouncer 모드에서 DDL 작업이 안됨
• 그래서 직접 연결용으로 directUrl도 같이 써야 함

그래서 schema.prisma도 아래와 같이 지정해야 한다 👇

datasource db {
provider = "postgresql"
url      = env("DATABASE_URL")  // pgbouncer (운영용)
directUrl = env("DIRECT_URL")   // 직접 연결 (migrate 등 내부 사용)
}

✅ 마이그레이션 & 확인

npx prisma migrate dev --name init 위 명령어로 정상 연결 여부 확인 가능하고, npx prisma studio로 테이블 구조와 데이터도 바로 확인 가능하다.

Supabase에서도 확인 가능!

마무리

여기까지 정리 완료! Supabase에서 소셜 로그인도 지원한다고 하니까, 그 기능도 다음에 써봐야지 :)

1차 개발 당시, 스터디 카드 리스트를 무한 스크롤 방식으로 먼저 구현했다. 하지만 실제 배로 후, 초기 진입 속도나 리스트 로딩 속도가 느리다고 체감했다. 그래서 useMemo, useCallback을 부모 컴포넌트인 StudyList와 자식 컴포넌트인 StudyCard에 골고루 적용해봤다.

그런데.. 메모제이션이 전혀 적용되지 않았다.

무한스크롤이 발생하거나, 필터링 조건이 바뀌거나, 새로운 스터디가 등록될 때마다 자식 컴포넌트까지 전부 재렌더링되면서, useMemo로 감싼 로직(today, 모집 마감 여부 등)도 매번 다시 실행되었다.

• 카드 수가 적을 때는 눈에 띄지 않지만,
• 카드 수가 많아지면 점점 느려질 수밖에 없는 구조다.

2️⃣ 성능 측정: 무한 스크롤 기준

실제 카드 수를 500개 이상으로 늘려주고, Chrome Devtools Profiler로 렌더링 속도를 측정했다.

• 무한스크롤 시, 카드 하나 렌더링에 약 2.4ms ~ 4.1ms 소요됨
• 누적되는 DOM 구조로 인해, 스크롤이 길어질수록 성능 저하

3️⃣ 개념 정리: 가상화 vs 무한스크롤

4️⃣ react-window 도입

가상화를 위해 react-window을 사용했다. TypeScript 사용 시 타입 설치도 필요하다:

npm install react-window
npm install @types/react-window

Grid 컴포넌트 적용 예시

          <Grid
            columnCount={columnCount}
            columnWidth={cardWidth + 18}
            height={700} // 뷰포트 높이(px), 조정 가능
            rowCount={Math.ceil(studies.length / columnCount)}
            rowHeight={cardHeight + 24}
            width={gridWidth}
            onItemsRendered={({ visibleRowStopIndex }) => {
              const lastVisibleIndex = (visibleRowStopIndex + 1) * columnCount;
              if (
                hasMore &&
                !loading &&
                lastVisibleIndex >= studies.length - columnCount
              ) {
                fetchStudies();
              }
            }}
          >
            {({ columnIndex, rowIndex, style }) => {
              const idx = rowIndex * columnCount + columnIndex;
              if (idx >= studies.length) return null;
              return (
                <div
                  style={{
                    ...style,
                    left: (style.left as number) + 12 / 2, // 양 옆 gap/2씩
                    top: (style.top as number) + 12 / 2,
                    width: cardWidth,
                    height: cardHeight,
                  }}
                >
                  <StudyCard key={studies[idx].id} study={studies[idx]} />
                </div>
              );
            }}
          </Grid>

• height와 width: 뷰포트 크기
• rowCount, columnCount: 카드 개수에 맞게 계산
• onItemsRendered: 스크롤 끝 감지 후 fetch 호출 나는 반응형 대응을 위해 window.innerWidth를 기준으로 카드 가로 폭, 열 수 등을 계산해서 반영했다.

5️⃣ 가상화 적용 후 성능 측정

같은 조건에서 다시 Profiler 측정하기

• 카드 하나당 1.4ms ~ 1.9ms로 렌더링 시간 감소
• 첫 렌더링 시 뷰포트에 맞춰 18개만 렌더링
• 이후 스크롤 시 6개씩 동적으로 교체
• F12 개발자 도구로 html 확인시 18개만 계속 렌더링됨

렌더링 성능이 약 2배 이상 개선되었고 전체 카드 수와 무관하게 일정한 성능 유지 가능해짐

가상화 적용하기 쉬웠는데 렌더링 시간이 바로 감소돼서 좋았다. 실제 사용자 경험을 고려하면 성능과 UX 모두 잡을 수 있는 조합이라고 느꼈다. 👍

처음 Lighthouse 기준 LCP가 2,560ms로 빨간세모 판정을 받았다. 원인을 추적해보니,로딩 페이지의 이미지가 너무 커서 주요 컨텐츠로 잡히고 있었고, 이로 인해 렌더링이 더 지연되고 있었다.

✅ 1단계 : PNG → WebP 변환

기존 Groupie.png은 1.5MB로 너무 무거웠다. webp을 사용하면 훨씬 가볍고 최적화에 유리하기에, 아래처럼 변환을 진행했다.

# macOS에서 cwebp 설치
brew install webp

# PNG를 WebP로 변환 (품질 80%)
cwebp -q 80 public/Groupie.png -o public/Groupie.webp

• 파일 크기: 1.5MB → 28KB
• LCP: 2,560ms → 2,090ms → 포맷만 바꿨을 뿐인데도 500ms 가까이 개선되었다.

✅ 2단계 : fill → width/height로 변경

fill 속성을 사용하면 브라우저가 이미지 크기를 렌더링 시점에 계산하게 되므로, LCP 지연의 원이 될 수 있다. 그래서 width/height 속성을 명시해 불필요한 계산을 줄이고자 했다.

• LCP는 이미지 최적화 이후에도 다른 리팩토링 작업들 덕분에 자연스럽게 2,090ms → 1,680ms까지 개선되었고,

• 여기에 width/height를 적용하면서 최종적으로 1,380ms까지 줄일 수 있었다.

  항목	최적화 전	중간 단계	최종
  LCP	2,560ms 🔺	1,680ms ⚠️	1,380ms ✅
  Load Delay	1,610ms (63%)	860ms (51%)	690ms (50%)
  TTFB	810ms (31%)	630ms (37%)	630ms (46%)

📌 정리

• ✅ WebP로 포맷 최적화
• ✅ Image 크기 명시
• ✅ LCP 기준 '나쁨' → '양호' 개선 성공

프론트 상태관리 도구라고 하면 Context API, Redux, Zustand 등 여러 가지가 있다. 사실 이번 Groupie 사이드 프로젝트 전까지만 해도 난 상태관리 도구 없이 useState만 쓰던 초짜였다.

특강에서 면접 때 상태관리 도구 왜 썼는지 물어보니까 공부해두라는 얘기를 들었다. 찾아보니 최근앤 Zustand가 가볍고 쓰기도 편해서 자주 쓰이는 것 같았다. (내피셜)

프로젝트를 진행하면서 처음에느 로그인/회원가입 모달 상태에 zustand를 도입했고, 최근에는 스터디 필터링 가능에 zustand를 적용했다. 적용하면서 "아 이때 전역 상태관리를 써야 하구나"하고 감이 잡혔다.

언제 Zustand를 쓰는 게 맞을까?

1. props drilling이 심해질 때

• 부모 → 자식 → 자식의 자식까지 계속 props를 넘겨야 하는 경우
• 그냥 전역으로 관리하자! (그럼 부모든, 자식이든 쉽게 사용 가능하니까)

2. 여러 컴포넌트가 같은 상태를 공유해야 할 때

• 로그인 모달 : 헤더, 페이지 등 여러 곳에서 모달을 열고 닫기
• 필터 버튼 : StudyFilterBar, StudyList 등에서 같은 필터 상태 사용

3. 비동기/복잡한 상태 (캐싱, optimisic UI, 토스트)

• 상태가 복잡하거나 서버와 연동되는 로직이 많을 때
• 토스트 알림, optimistic UI, 캐싱, 뷰 카운트 등

❌ 굳이 안 써도 되는 경우

• 한 컴포넌트 또는 한 계층에서만 쓸 때 → useState나 useReducer면 충분
• 괜히 다 전역으로 올리면 코드가 복잡해짐

Context API는 왜 안 썼을까?

처음에는 Context API를 쓸까 했지만, page.tsx에 필터 버튼만 있는 게 아니라 인기글 컴포넌트, 스터디 리스트도 함께 있어서 <Context.Provider>로 감싸는 구조가 애매했다.

결국 단순 상태 공유와 빠른 반응성을 위해 zustand를 선택했다.

사용 방법 (기본)

📌 공식 데모 사이트 바로가기 →

1. 설치

   npm install zustand

2. 스토어 생성 (예: modalStore.ts) 보통 store폴더를 만들어 그 안에 스토어 파일을 관리한다. 파일명은 xxxStore.ts처럼 작성하는 경우가 많다.

   // store/modalStore.ts
   import { create } from "zustand";
   

type ModalType = "login" | "signup" | null;

// zustand로 전역 모달 스토어 만들기 interface ModalStore { openModal: ModalType; open: (type: ModalType) => void; close: () => void; }

export const useModalStore = create((set) => ({ openModal: null, open: (type) => set({ openModal: type }), close: () => set({ openModal: null }), }));

> 여기서 `interface`는 스토어의 상태와 메서드 구조를 정의하는 역할
`create()`함수는 zustand의 핵심 함수로, 스토어를 실제로 생성한다.

---
3. 스토어 사용하기 (컴포넌트에서 호출)
다른 컴포넌트에서 사용할 때는 `useModalStore()`훅을 호출하면 된다.
```ts
// 예: 로그인 폼에서 모달 닫기
import { useModalStore } from "@/store/modalStore";

export default function LoginForm() {
  const { close } = useModalStore();

  return (
    <button onClick={close}>
      닫기
    </button>
  );
}

이렇게 하면 모달을 여는 컴포넌트, 닫는 컴포넌트가 다른 위치에 있어도 상태를 공유할 수 있다!

❓ 궁금했던 점

기술 스택에 zustand가 있다면 모든 상태를 zustand로 써야 하나?

굳이?

• 전역 상태가 필요한 경우 zustand 쓰면 된다.
• 단일 컴포넌트에서만 쓰는 상태는 useState가 더 직관적이고 성능도 좋음.

예전 발주 페이지에서도 zustand로 전체 상태를 묶었다가, 셀렉트 버튼 상태는 useState로 되돌린 적이 있다. 지금 생각하면, 거기서는 zustand를 쓰지 않아도 됐던 것 같다. 상태 공유가 진짜 필요한가? 를 먼저 고민하는 게 중요하다는 걸 이번에 체감할 수 있었다.

한 줄 요약

여러 컴포넌트가 공유해야 하거나, 비동기/복잡한 상태일 때 zustand! 그 외엔 useState

Vercel 배포중 아래와 같은 에러를 만났다. 로그를 보니 react-markdown에서 문제가 발생한 건 알 수 있었다.

./node_modules/@uiw/react-markdown-preview/node_modules/react-markdown/lib/complex-types.ts:25:21
Type error: Cannot find namespace 'JSX'a

구글링을 통해 관련된 GitHub 이슈를 찾아볼 수 있었다. 답변들을 보니 JSX를 React.JSX로 바꿔야 한다는 내용이 많았다❗️

원인 분석

React 19와 최신 TypeScript에서는 JSX 네임스페이스를 더이상 전역으로 제공해 주지 않고 대신 React.JSX를 사용해야 한다. 그러나 일부 라이브러리에서는 여전히 전역 JSX를 참조하고 있어서 문제가 발생한 것이다.

해결 방법

1. 라이브러리 업데이트 관련 라이브러리들을 최신 버전으로 업데이트 하자.

npm install react-markdown@latest @uiw/react-markdown-preview@latest

• react-markdown-preview 와 그 내부 react-markdown 을 React 19 호환 버전(전역 JSX 참조를 없앤 버전)으로 업데이트

2. 글로벌 타입 선언 추가 계속해서 에러가 발생한다면,프로젝트 루트에 global.d.ts 파일을 생성하고 아래 내용을 추가하기

// ./global.d.ts
import React from "react";

declare global {
  namespace JSX {
    // React 18+의 JSX.Element
    type Element = React.ReactElement;

    // 모든 태그 이름을 any로 허용
    interface IntrinsicElements {
      [elemName: string]: any;
    }
  }
}

이렇게 하면, 전역 JSX 네임스페이스를 임시로 복원할 수 있다.

참고자료

• styled-components 이슈 #4359
• react-markdown 이슈 #877

마무리

나는 라이브러리 업데이트와 글로벌 타입 선언을 모두 적용했다. 그 결과 에러가 사라졌지만, 아마 라이브러리 업데이트가 근본적인 해결책인 거 같다!

Type error: Type '{ params: { id: string; }; }' does not satisfy the constraint 'PageProps'.

위와 같은 타입 에러를 만났다.

문제 상황

문제가 난 코드는 아래와 같다. 코드상 오류는 없었는데 배포하니 타입에러가 났다.

export default async function StudyDetailPage({
  params,
}: {
  params: { id: string };
}) {
  const { id } = params;
  // ...
}

구글링으로 답변을 찾아보니 Next.js 15부터는 params와 searchParams가 비동기(Promise) 로 변경되었기 때문에 위 코드는 타입 에러를 발생시킨다.

해결 방법

params를 Promise로 타입 지정하고 await를 통해 값을 받아야 한다.

type StudyDetailPageProps = {
  params: Promise<{ id: string }>;
};

export default async function StudyDetailPage({
  params,
}: StudyDetailPageProps) {
  const { id } = await params;
  // ...
}

왜 바뀌었을까? (Next.js 15 기준)

1. 성능 최적화 → 라우트 파라미터를 필요할 때만 불러오도록 지연 로딩 가능
2. 스트리밍 지원 → Partial Prerendering(PPR)이나 스트리밍 렌더링과 더 잘 통합됨
3. 서버 컴포넌트와의 일관성 → 서버 컴포넌트가 기본적으로 async 함수이므로, params도 일관되게 비동기로 일치

참고한 답변

같은 에러를 겪는 다른 사람의 질문이 스택오버플로우에 있었다! ▶ Stackoverflow 링크

마무리

이렇게 수정하니 해당 에러는 해결됐고... 물론 다른 에러가 나긴 했지만 ㅜ 어쨌든 중요한 건! 👉 Next.js 15에서는 params도 Promise로 받자!

npm run dev로 서버를 띄운 후, 첫 페이지 진입 시 찍히는 로그창을 보니

• GET /study: 2436ms
• GET /api/studies: 1366ms 응답 속도가 꽤 느렸다. 물론 실행할 때마다 수치는 조금씩 달라지긴 하지만, 느리다는 건 변한없었다.

특히 쿼리문을 보니 불필요한 데이터까지 모두 select해서 들고오고 있었다. /study에서는 스터디 리스트를, /api/studies에서는 인기글 리스트를 select하고 있는 상황에서 두 쿼리문을 개선해 보았다.

✂️ 첫 번째 개선: 필요한 필드만 select

Prisma의 select옵션으로 필요한 필드만 지정해서 가져오도록 수정했다.

 const studies = await prisma.study.findMany({
      where,
      select: {
        id: true,
        title: true,
        category: true,
        startDate: true,
        createdAt: true,
        scrap: true,
        content: true,
        author: {
          select: {
            id: true,
            nickname: true,
            profileImage: true,
          },
        },
        _count: {
          select: {
            comments: true, // 댓글 개수만 필요하면 이렇게
          },
        },
      },
      orderBy: { createdAt: "desc" },
      ...(cursor && {
        cursor: { id: cursor },
        skip: 1, // cursor 제외
      }),
      take,
    });

결과

• /study: 2436ms → 2105ms (약 331ms 감소, 14% 개선)
• /api/studies: 1366ms → 1115ms (약 251ms 감소, 18% 개선)

🔍 두 번째 개선: 인덱스 추가

추가적으로 스크랩과 조회수 기준으로 인기글을 정렬할 때, 게시글별로 댓글을 가져올때, 더 빠르게 쿼리를 처리하기 위해 자주 조회되는 필드에 인덱스를 추가했다.

*인덱스는 DB에서의 책 목차 같은 역할이다. * 검색하거나 정렬할 필드에 인덱스를 걸어두면, 전체를 다 뒤짖 않고 필요한 데이터만 바로 찾아갈 수 있다.

// Study 테이블
 @@index([scrap(sort: Desc), views(sort: Desc), createdAt(sort: Desc)], name: "idx_study_performance")

이건 아래와 같은 순서로 정렬할떄 최적화된다.

• "scrap 내림차순 → 그 안에서 views 내림차순 → 그 안에서 createdAt 내림차순" 쿼리에서도 orderBy에 이 세 필드를 같은 순서로 명시해줘야 인덱스가 적용된다.

  orderBy: [
  { scrap: "desc" },
  { views: "desc" },
  { createdAt: "desc" },
  ]
  

// Comment 테이블 @@index([studyId], name: "idx_comment_study_id")

이건 댓글 테이블에서 특정 스터디에 달린 댓글 목록을 빠르게 조회할 때 사용된다. (WHERE studyId = 'xxx')


### 결과
- `/study`: 2105ms → 2198ms (정렬 기준 적용 이후에도 속도 유지됨)
- `/api/studies`: 1115ms → 1040ms (댓글 많은 글도 속도 차이 거의 없음)


---
## 전체 성능 변화 요약
| API            | 변경 전   | 변경 후   | 감소량    | 개선율   |
| -------------- | ------ | ------ | ------ | ----- |
| `/study`       | 2436ms | 2198ms | -238ms | 약 10% |
| `/api/studies` | 1366ms | 1040ms | -326ms | 약 24% |

실행할때마다 수치가 다르긴 하지만, DB쿼리 개선후에 속도가 빨라진 건 느껴졌다.

---
## 😺 배운점
API 속도가 느리면 일단 **백엔드 쿼리를 먼저 확인해보는 게 기본**이라는 것을 느꼈다. 특히 Supabase 덕분에 터미널에 쿼리문이 잘 찍혀서 디버깅하기 훨씬 좋았던 것 같다.
- 필요한 데이터만 `select` 해오기
- 자주 조회되는 조건은 `index` 걸기
- join이나 count연산 주의하기

Minimize main-thread work가 6.7초로, 첫 페이지 열자마자 메인스레드가 할 일이 너무 많이 상태였다. JS 파일이 많고, 데이터도 엄청 불러오고 렌더링도 많아지니까 그런거 같았다. 근데 나는 컴포넌트도 잘 쪼개고, use client도 최대한 줄이면서 서버 컴포넌트로 잘 써놨어서 더이상 구조적으로 쪼갤 건 없었다. 그래서 결국 남은 문제는:

첫 페이지에서 너무 많은 걸 보여주고 있었던 게 문제였다.

그래서 나는 "지연 로딩"을 적용했다.

지연 로딩은 말 그대로 지연해서 로딩하는 것이다. 필요한 시점이 될 때 그때 가서 객체(컴포넌트)를 가져오는 방식이라고 이해하면 된다.

첫 페이지에서 바로 보여주지 않아도 되는 것은 지연로딩으로 메인스레드의 부담을 줄이는 방법

예를 들어 내 사이트에서는

• 로그인 / 마이페이지 버튼 헤더에 바로 보여야 하니까 지연 로딩이 불가능함
• 로그인 / 회원가입 모달 버튼 누르기 전까진 안 보여도 되니까 지연 로딩하기 딱 좋음
• 인기 스터디 슬라이더 스켈레톤 UI가 있어서 처음부터 꼭 보여줄 필요는 없음 → 지연 로딩 적합

로그인 모달 지연 로딩

Next.js에서 동적 import 할 땐 dynamic()을 쓰는데, 이건 클라이언트 컴포넌트에서만 가능하다. 그래서 나는 DynamicmodalWrapper.tsx라는 클라이언트 컴포넌트를 하나 생성했다.

"use client";
import dynamic from "next/dynamic";

// 모달 컴포넌트 동적 import, SSR 비활성화
const LoginSignupModal = dynamic(
  () => import("@/components/auth/LoginSignupModal"),
  { ssr: false }
);

export default function DynamicModalWrapper() {
  return <LoginSignupModal />;
}

여기서 ssr: false는 서버에 렌더링하지 않고 브라우저에만 렌더링하겠다는 뜻이다. 이 모달 컴포넌트는 유저가 버튼을 눌러서 필요한 순간에만 불러오게 되는 것!

✅ 인기 스터디 슬라이더도 지연 로딩

로그인 모달처럼 인기글 슬라이더도 dynamic으로 감쌌다.

const PopularStudySlider = dynamic(() => import("./PopularStudySlider"), {
  ssr: false,
  loading: () => (
    <div className="grid grid-cols-1 md:grid-cols-3  ">
      {Array.from({ length: 1 }).map((_, i) => (
        <PopularCardSkeleton key={i} />
      ))}
    </div>
  ),
});

처음에는 인기글도 지연로딩을 하는게 맞는지 고민했다. 인기글은 빠르게 보여주는게 좋을거 같아서 근데 오히려 지연로딩을 적용하니까 페이지가 더 빨라져서 인기글이 더 빨리 보이는 느낌이 들었다. 아마 전체 페이지가 무거워서 느려지던게 지연로딩으로 조금 분산되니까 나머지가 더 빨리 로딩되는게 아닐까?

추가적으로 loading 옵션을 사용해서 스켈레톤 UI을 보여주면서 사용자 경험을 향상시켰다.

최종결과

이렇게 인기글 슬라이더 + 로그인 모달을 지연 로딩으로 분리하고 나서 다시 성능 측정해봤더니…

Minimize main-thread work
6.7초 → 5.6초로 줄어듦!! 🎉

간단한 지연 로딩으로 1.1초나 줄어들어서 만족스러웠다.

다음편에서는 DB 최적화와 인덱스 추가 등으로 백엔드 응답 속도를 줄인 과정을 정리할 예정임니다.

웹 성능 최적화가 중요한 이유

사용자는 사이트가 느린걸 싫어한다. 로딩이 좀만 길어져도 응 안써. 하고 나감 성능이 낮으면 사용자 이탈률이 높아지고, 검색엔진 최적화(SEO)에도 불리하다. 특히 Next.js는 SSR을 지원하지만, 잘못쓰면 오히려 느려질 수 있다. 그래서 나는 Lighthouse를 통해 성능 병목을 확인하고 직접 개선해보기로 했다.

Lighthouse란?

Lighthouse는 Chrome 브라우저에서 제공하는 웹사이트 품질 분석 도구이다. 성능 점수부터 접근성, SEO, Best Practice까지 알아서 분석해준다.

• Performance : 페이지 로딩 속도, 스크립트 실행 시간 등
• Accessibility : 접근성 문제
• Best Practices : 보안/코딩 관례 준수 여부
• SEO : 검색 최적화 관련 지표

f12 → Lighthouse 탭 → "페이지 로드 분석" 클릭하면 측정 끝!

주요 성능 지표

초기 측정 결과

• Performance: 62점
• Main-thread work: 6.7초
• Script Evaluation: 3,715ms
• Script Parsing & Compilation: 975ms
• Garbage Collection: 467ms

👉 /study(첫 페이지) 진입할 때 너무 느렸음. 인기글 + 전체 게시글 한꺼번에 불러오면서, 중요한 콘텐츠가 늦게 뜨는 문제가 있었음

① Minimize main-thread work : use client 다이어트 use client가 붙은 컴포넌트 중에서 정적 UI만 처리하는 컴포넌트는 서버 컴포넌트로 전환해 메인 스레드의 부담을 줄여보자.

예시: StudyList → StudyCard 분리

• StudyCard

  import React from "react";
  import { formatRelativeTime } from "@/lib/date";
  import {  Study, User } from "@prisma/client";
  

import Image from "next/image"; import { FaBookmark } from "react-icons/fa"; import Link from "next/link";

type StudyType = Study & { author: User; comments: Comment[]; };

interface Props { study: StudyType; isLast: boolean; observerRef: React.RefObject<HTMLDivElement | null>; }

const StudyCard = ({ study, isLast, observerRef }: Props) => { const today = new Date(); today.setHours(0, 0, 0, 0); // 오늘 00:00:00

return ( <Link href={/study/${study.id}} key={study.id}> <div ref={isLast ? observerRef : null} className=" min-h-[200px] group bg-white rounded shadow-sm border border-gray-200 p-6 hover:shadow-lg transition-all duration-300 hover:-translate-y-1" >

      <div className="space-y-2">
        <h3 className="text-lg font-semibold text-gray-900  transition-colors line-clamp-1">
          {study.title}
        </h3>
        <p
          className="text-sm text-gray-600 line-clamp-2 leading-relaxed
              min-h-[48px]"
        >
          {study.content.replace(/[#_*~`>[\]()\-!\n]/g, "").slice(0, 100)}
        </p>
      </div>

      <div className="flex items-center gap-3 text-xs text-gray-500">
        <span>{formatRelativeTime(new Date(study.createdAt))}</span>
        <span>•</span>
        <span>{study._count.comments}개의 댓글</span>
      </div>

      <div className="flex items-center justify-between pt-3 border-t border-gray-100">
        <div className="flex items-center gap-3">
          <div>
            <div className="w-8 h-8 rounded-full overflow-hidden relative">
              <Image
                src={study.author.profileImage ?? "/default-avatar.png"}
                alt="프로필"
                fill
                className="object-cover"
              />
            </div>
          </div>
          <span className="text-sm text-gray-700 font-medium ">
            {study.author.nickname}
          </span>
        </div>
        <div className="flex items-center gap-1 text-red-500">
          <FaBookmark className="text-sm" />

          <span className="text-sm font-medium">{study.scrap}</span>
        </div>
      </div>
    </div>
  </div>
</Link>

그리고 `StudyList.tsx`에서는 이렇게 사용

```ts
import StudyCard from "./StudyCard";

// ...

{studies.map((study, index) => (
  <StudyCard
    key={study.id}
    study={study}
    isLast={index === studies.length - 1}
    observerRef={observerRef}
  />
))}

DATABASE_URL="mysql://root:@localhost:3306/study_cafe"

generator client {
provider = "prisma-client-js"
}

datasource db {
provider = "mysql"
url      = env("DATABASE_URL")
}

model Study {
id        Int      @id @default(autoincrement())
category  String
title     String
content   String
createdAt DateTime @default(now())
}

import { PrismaClient } from "@prisma/client";
const prisma = new PrismaClient();

const studies = await prisma.study.findMany();

import { PrismaClient } from "@prisma/client";

const globalForPrisma = globalThis as unknown as {
  prisma: PrismaClient | undefined;
};

export const prisma = globalForPrisma.prisma ?? new PrismaClient();

if (process.env.NODE_ENV !== "production") {
  globalForPrisma.prisma = prisma;
}

  const likedPosts: ScrapedWithStudy[] = await prisma.scrap.findMany({
    where: { userId },
    include: { study: true },
  });

Hydration failed because the server rendered HTML didn't match the client. As a result this tree will be regenerated on the client. This can happen if a SSR-ed Client Component used: 

<p className="text-gray-600">
   {new Date(comment.createdAt).toLocaleString()}
<p>

new Date().toLocaleString();
// 브라우저가 한국이면 → "2025. 5. 23. 오후 3:10"
// 브라우저가 미국이면 → "5/23/2025, 3:10 PM"
// 서버(Node.js)는? → 서버 OS의 기본 설정 따라감

<p className="text-gray-600">
    {formatRelativeTime(new Date(comment.createdAt))}
</p>

import { format, formatDistanceToNowStrict } from "date-fns";
import { ko } from "date-fns/locale";

export function formatRelativeTime(date: Date) {
  const now = new Date();
  const diffInMs = now.getTime() - date.getTime();
  const diffInSec = diffInMs / 1000;  // 1000ms 여서
  const diffInDay = diffInMs / (1000 * 60 * 60 * 24);

  if (diffInSec < 60) {
    return "방금 전";
  }

  if (diffInDay < 3) {
    return formatDistanceToNowStrict(date, { locale: ko, addSuffix: true });
  }

  return format(date, "yyyy.MM.dd");
}

formatDistanceToNowStrict(date, { locale: ko, addSuffix: true })

import { revalidatePath } from 'next/cache';

revalidatePath('/news'); // /news 페이지 캐시 재검증 요청
revalidatePath('/news', 'layout'); // /news 페이지의 레이아웃까지 재검증

// fetch 시 태그 지정
 const response = await fetch("http://localhost:8080/messages", {
    next : {tags : ['msg']}
  });


// 서버에서 해당 태그 무효화
import { revalidateTag } from 'next/cache';
revalidateTag('msg');

fetch(url, { cache : 'no-store'});

fetch(url, { next: { revalidate: 5 } });

export const revalidate = 5; // 5초 동안 캐시 유지

export const dynamic = "force-dynamic" // 파일 내 어디서든 필요한 모든 데이터를 항상 다 가져옴
export const dynamic = "force-static" // 새로운 데이터를 전혀 가져오지 않게 됨 (캐싱 강조)

import { unstable_noStore } from "next/cache";

unstable_noStore(); // 이 컴포넌트에서의 요청은 캐시 사용 안 함

export function GET(request){
    console.log(request);

    // return Response.json();
    return new Response('Hello');
}

export async function POST(request) {
  const body = await request.json();
  return Response.json({ name: body.name });
}

<NavLink href="/news">News</NavLink>

// components/NavLink.js
'use client';

import Link from "next/link";
import { usePathname } from "next/navigation";

export default function NavLink({ href, children }) {
  const path = usePathname();
  return (
    <Link
      href={href}
      className={path.startsWith(href) ? "active" : undefined}
    >
      {children}
    </Link>
  );
}

// app/meals/loading.js
import classes from "./loading.module.css";

export default function MealsLoadingPage() {
  return <p className={classes.loading}>Fetching meals...</p>;
}

import { Suspense } from "react";
import MealsGrid from "@/components/meals/meals-grid";
import { getMeals } from "@/lib/meals";

async function Meals() {
  const meals = await getMeals();
  return <MealsGrid meals={meals} />;
}

export default function MealsPage() {
  return (
    <>
      <header>...헤더 콘텐츠...</header>
      <main>
        <Suspense fallback={<p>Loading meals...</p>}>
          <Meals />
        </Suspense>
      </main>
    </>
  );
}

import Logo from "./public/images";
 <img src={Logo.src} alt="logo" />

import Logo from "./public/images";
import Image from "next/image";

<Image src={Logo} alt="logo" />

<img alt="logo" loading="lazy" width="1024" height="1024" decoding="async" data-nimg="1" 
srcset="/_next/image?...w=1080&q=75 1x, ...w=2048&q=75 2x" 
src="/_next/image?...w=2048&q=75" style="color: transparent;" />

<Image src={Logo} alt="logo" priority />