수달 코딩 공장

10주간의 React 스터디를 마무리하며...!

수달군 — Tue, 2 Jun 2026 21:46:05 +0900

10주간의 리액트 중급 스터디를 마무리하며

리액트 중급 스터디가 어느덧 마지막 주차에 도달했다.

처음 스터디를 시작했을 때는 단순히 React와 Next.js를 조금 더 깊게 공부하고, 개인 프로젝트에 적용할 수 있는 실전적인 기술들을 익히는 것이 목표였다. 하지만 10주간의 과정을 지나오면서 느낀 것은, 프론트엔드 개발에서 중요한 것은 단순히 새로운 기술을 많이 아는 것이 아니라는 점이었다.

오히려 더 중요한 것은 어떤 기준으로 코드를 작성할 것인지, 어떤 구조가 유지보수에 유리한지, 그리고 사용자 경험과 개발자 경험을 어떻게 함께 고려할 것인지에 대한 고민이었다.

이번 글에서는 10주간의 스터디를 돌아보며 학습한 내용, 나의 설계 철학, 포트폴리오에 반영할 기술 블로그 방향, 그리고 스터디를 통해 얻은 점과 아쉬운 점을 정리해보려고 한다.

10주 동안 무엇을 배웠나

이번 스터디에서는 React와 Next.js를 중심으로 프론트엔드 개발에 필요한 여러 주제를 다루었다.

초반에는 프로젝트를 시작하기 위한 기본 구조를 잡는 것부터 시작했다. 단순히 페이지를 만들고 컴포넌트를 배치하는 것이 아니라, 프로젝트가 커졌을 때도 관리하기 쉬운 폴더 구조를 어떻게 가져갈지 고민했다. 이 과정에서 Feature-Sliced Design, Layered Architecture와 같은 아키텍처 개념을 학습했고, 기능 단위로 코드를 나누는 방식과 계층별 책임을 분리하는 방식에 대해 생각해볼 수 있었다.

이전에는 폴더 구조를 단순히 components, pages, hooks, utils처럼 나누는 정도로만 생각했다. 하지만 프로젝트 규모가 커질수록 이런 단순한 분류만으로는 코드의 책임을 명확하게 나누기 어렵다는 것을 느꼈다. 어떤 컴포넌트가 공통 컴포넌트인지, 어떤 컴포넌트가 특정 기능에 종속된 컴포넌트인지, API 요청 로직은 어디에 두어야 하는지 등을 기준 없이 작성하면 결국 유지보수가 어려운 구조가 될 수밖에 없었다.

중반에는 상태 관리, API 연동, 에러 핸들링, 스타일링 전략과 같은 실전적인 주제들을 다루었다. 특히 에러 핸들링을 학습하면서 프론트엔드에서 에러를 처리하는 방식이 생각보다 다양하다는 것을 알게 되었다. 단순히 try-catch로 에러를 잡는 것뿐만 아니라, 렌더링 영역에서는 Error Boundary를 사용하고, 서버 상태에서는 React Query의 isError, error 상태를 활용하며, 사용자 액션에서는 토스트 메시지나 모달을 통해 즉각적인 피드백을 제공할 수 있었다.

후반에는 테스트 전략과 코드리뷰, 리팩토링에 대해 다루었다. Vitest와 React Testing Library를 활용해 컴포넌트 테스트와 통합 테스트의 차이를 정리했고, MSW를 활용해 API 요청을 Mocking하는 방법도 학습했다. 테스트는 아직 익숙하지 않은 영역이지만, 단순히 “잘 작동하는지 확인하는 코드”가 아니라 기능의 안정성을 보장하고 리팩토링에 대한 부담을 줄여주는 장치라는 점을 이해할 수 있었다.

코드리뷰와 리팩토링 실습도 의미 있었다. 같은 기능을 구현하더라도 컴포넌트 책임을 어떻게 나누는지, 중복 코드를 어떻게 줄이는지, CSS 구조를 어떻게 정리하는지에 따라 코드의 가독성과 유지보수성이 크게 달라진다는 것을 느꼈다. 결국 좋은 코드는 처음부터 완성되는 것이 아니라, 계속해서 리뷰하고 개선하는 과정 속에서 만들어진다는 생각이 들었다.

기능 구현에서 구조 설계로 관점이 바뀌다

이번 스터디를 하면서 가장 크게 달라진 점은 개발을 바라보는 관점이었다.

예전에는 기능이 정상적으로 동작하면 어느 정도 만족했다. 버튼을 누르면 모달이 열리고, API 요청을 보내면 데이터가 화면에 출력되고, 스타일이 디자인과 비슷하게 맞으면 구현이 끝났다고 생각했다.

하지만 스터디를 진행하면서 단순히 “동작하는 코드”와 “유지보수 가능한 코드”는 다르다는 것을 느꼈다.

동작하는 코드는 지금 당장의 요구사항을 해결할 수 있다. 하지만 기능이 추가되고, 화면이 복잡해지고, API 명세가 바뀌는 순간 코드의 구조가 중요해진다. 컴포넌트가 너무 많은 책임을 가지고 있거나, 상태가 여러 곳에 흩어져 있거나, API 요청 로직과 UI 로직이 뒤섞여 있다면 작은 변경도 어렵게 느껴진다.

그래서 이번 스터디를 통해 “어떻게 구현할까?”보다 먼저 “어떤 구조로 나누어야 할까?”를 고민하게 되었다.

예를 들어 하나의 페이지를 만들 때도 단순히 JSX를 길게 작성하는 것이 아니라, 페이지 컴포넌트, 섹션 컴포넌트, 카드 컴포넌트, 공통 UI 컴포넌트처럼 역할을 나눌 수 있다. API 요청도 컴포넌트 내부에서 직접 처리하기보다 커스텀 훅으로 분리하면 UI와 데이터 로직의 책임을 명확히 나눌 수 있다.

이러한 구조화는 당장은 시간이 더 걸릴 수 있다. 하지만 프로젝트가 커질수록 코드를 이해하고 수정하는 비용을 줄여준다. 결국 좋은 설계는 개발 속도를 늦추는 것이 아니라, 장기적으로 더 안정적인 개발을 가능하게 만드는 기반이라고 생각하게 되었다.

나의 설계 철학 정리

이번 스터디를 통해 나만의 설계 철학도 조금씩 정리할 수 있었다.

첫 번째는 사용자 흐름을 기준으로 기능을 설계하는 것이다.

프론트엔드 개발은 결국 사용자가 직접 마주하는 영역이다. 따라서 개발자의 구현 편의성보다 사용자가 어떤 흐름으로 서비스를 이용하는지가 중요하다. 사용자가 어떤 정보를 먼저 보고, 어떤 행동을 하며, 어떤 피드백을 받아야 하는지를 기준으로 화면과 기능을 설계해야 한다.

예를 들어 검색 기능을 만든다면 단순히 검색창과 결과 목록을 만드는 것으로 끝나지 않는다. 사용자가 검색어를 입력하기 전에는 어떤 안내를 보여줄지, 검색 중에는 어떤 로딩 상태를 보여줄지, 결과가 없을 때는 어떤 메시지를 제공할지, 에러가 발생했을 때는 어떻게 다시 시도할 수 있게 할지까지 함께 고려해야 한다.

두 번째는 변경에 강한 구조를 만드는 것이다.

프로젝트는 처음 설계한 그대로 유지되지 않는다. 기능은 계속 추가되고, 요구사항은 바뀌며, 디자인도 수정된다. 따라서 코드는 변경을 전제로 작성되어야 한다고 생각한다. 이를 위해 컴포넌트의 책임을 명확히 나누고, 반복되는 로직은 커스텀 훅이나 유틸 함수로 분리하며, 특정 페이지에만 필요한 코드와 여러 곳에서 재사용될 수 있는 코드를 구분하는 것이 중요하다.

세 번째는 완벽한 코드보다 개선 가능한 코드를 지향하는 것이다.

처음부터 완벽한 구조를 만드는 것은 어렵다. 오히려 처음부터 너무 과하게 추상화하려고 하면 코드가 더 복잡해질 수도 있다. 그래서 현재 상황에서 가장 적절한 구조를 선택하되, 이후 문제가 발견되면 리팩토링을 통해 점진적으로 개선하는 태도가 중요하다고 생각한다.

이번 스터디에서 코드리뷰와 리팩토링을 경험하며, 좋은 코드는 한 번에 만들어지는 것이 아니라는 점을 다시 느꼈다. 코드를 작성한 뒤 다시 읽어보고, 다른 사람의 피드백을 받고, 더 나은 방식으로 고쳐보는 과정 자체가 개발 실력을 높이는 데 큰 도움이 되었다.

앞으로 포트폴리오는 어떻게 채워나갈 것인가

이번 스터디에서 정리한 내용들은 단순한 학습 기록으로 끝내기보다 포트폴리오에 적극적으로 반영할 수 있다고 생각한다.

포트폴리오를 만들 때 흔히 프로젝트 결과물, 사용 기술, 주요 기능을 중심으로 정리한다.

물론 이것도 중요하지만 프론트엔드 개발자로서 더 잘 보여주어야 하는 것은 “왜 그렇게 만들었는가”라고 생각한다.

예를 들어 단순히 “React Query를 사용했다”고 적는 것보다, 서버 상태와 클라이언트 상태를 분리하기 위해 React Query를 사용했고, 캐싱과 로딩 상태, 에러 상태를 선언적으로 관리하기 위해 적용했다고 설명하는 것이 더 좋다.

또한 “컴포넌트를 분리했다”고 적는 것보다, 페이지 컴포넌트가 너무 많은 책임을 가지지 않도록 섹션 단위와 공통 UI 단위로 컴포넌트를 나누었고, 이를 통해 재사용성과 가독성을 높였다고 정리하는 것이 더 설득력 있다.

기술 블로그도 마찬가지다. 단순히 공부한 개념을 정리하는 글도 의미 있지만, 실제 프로젝트에 적용하면서 어떤 문제를 만났고 어떻게 해결했는지를 함께 정리하면 더 좋은 포트폴리오 자료가 될 수 있다.

이번 스터디에서 작성하거나 정리할 수 있는 기술 블로그 주제는 다음과 같다.

Feature-Sliced Design과 Layered Architecture를 프로젝트에 적용하는 방법
React Query를 활용한 서버 상태 관리 전략
선언적 에러 처리와 명령적 에러 처리의 차이
Error Boundary를 활용한 렌더링 에러 대응
Vitest와 React Testing Library를 활용한 프론트엔드 테스트 전략
MSW를 활용한 API Mocking
실제 프로젝트 코드리뷰와 리팩토링 과정
CSS 구조 개선과 공통 스타일 관리 방식
포트폴리오 프로젝트에서 기술 선택 이유를 정리하는 방법

이러한 글들은 단순히 “공부했다”는 기록이 아니라, 내가 어떤 기준으로 코드를 바라보고 개선하려고 했는지를 보여주는 자료가 될 수 있다. 앞으로 포트폴리오를 정리할 때도 프로젝트 결과 화면만 보여주는 것이 아니라, 문제 상황, 해결 과정, 개선 결과를 함께 담아내고 싶다.

스터디를 통해 얻은 점

이번 스터디의 가장 큰 장점은 혼자 공부할 때보다 더 많은 관점을 얻을 수 있었다는 점이다.

혼자 공부하면 내가 이해한 방식이 맞는지 확인하기 어렵고, 특정 문제를 한 가지 방식으로만 바라보게 되는 경우가 많다. 하지만 스터디에서는 같은 주제에 대해서도 서로 다른 의견을 들을 수 있었고, 다른 사람이 작성한 코드나 정리한 내용을 보며 새로운 관점을 얻을 수 있었다.

특히 코드리뷰 과정에서 많은 것을 느꼈다. 내가 작성한 코드는 익숙하기 때문에 문제점이 잘 보이지 않을 때가 있다. 하지만 다른 사람이 보면 컴포넌트 이름이 애매하거나, 로직이 너무 길거나, 스타일 코드가 반복되는 부분을 더 쉽게 발견할 수 있다. 반대로 다른 사람의 코드를 리뷰하면서 나 역시 좋은 코드와 아쉬운 코드의 차이를 더 구체적으로 생각해볼 수 있었다.

또한 스터디를 통해 꾸준히 글로 정리하는 습관을 만들 수 있었다. 개발을 하면서 배운 내용을 글로 정리하면 단순히 알고 있다고 생각했던 개념도 더 명확하게 이해할 수 있다. 설명하기 위해서는 개념을 구조화해야 하고, 예시를 들어야 하며, 내가 정확히 모르는 부분도 드러나기 때문이다.

아쉬웠던 점과 앞으로의 방향

물론 아쉬운 점도 있었다.

10주 동안 다양한 주제를 다루다 보니, 일부 내용은 깊게 실습하기보다 개념을 이해하는 수준에서 넘어간 부분도 있었다. 특히 테스트 코드 작성, 성능 최적화, 접근성 개선과 같은 주제는 실제 프로젝트에 더 많이 적용해보면서 경험을 쌓아야겠다고 느꼈다.

테스트의 경우 개념은 이해했지만, 아직 프로젝트 전반에 자연스럽게 테스트를 작성하는 습관은 부족하다. 앞으로는 새로운 기능을 만들 때 핵심 로직이나 사용자 플로우를 기준으로 테스트를 함께 작성해보려고 한다.

성능 최적화 역시 단순히 useMemo, useCallback을 사용하는 수준이 아니라, 실제 렌더링 병목을 분석하고 필요한 지점에 적절히 적용하는 경험이 필요하다고 생각한다. 접근성도 마찬가지로, 버튼이나 폼을 만들 때 키보드 접근성, 명확한 라벨, 스크린 리더 대응 등을 더 의식하면서 개발할 필요가 있다.

앞으로는 이번 스터디에서 배운 내용을 개인 프로젝트와 포트폴리오 프로젝트에 직접 반영하려고 한다. 단순히 공부한 내용을 정리하는 것에서 끝나는 것이 아니라, 실제 코드에 적용하고 그 과정을 다시 기술 블로그로 기록하는 방식으로 이어가고 싶다.

마무리

이번 10주간의 리액트 중급 스터디는 단순히 React 관련 기술을 학습한 시간이 아니었다.

기능 구현만을 목표로 하는 것이 아니라, 유지보수 가능한 구조를 고민하고, 사용자 흐름을 기준으로 화면을 설계하며, 에러 처리와 테스트, 리팩토링까지 함께 고려해야 한다는 것을 배웠다.

좋은 프론트엔드 개발자는 단순히 화면을 예쁘게 만드는 사람이 아니라, 사용자가 안정적으로 서비스를 이용할 수 있도록 구조를 설계하고 문제를 개선해나가는 사람이라고 생각한다.

앞으로는 이번 스터디에서 배운 내용을 바탕으로 더 나은 프로젝트를 만들고, 그 과정에서 생긴 고민과 해결 방법을 기술 블로그와 포트폴리오에 꾸준히 정리해나가고자 한다.

아직 부족한 부분은 많지만, 적어도 이번 스터디를 통해 내가 어떤 방향으로 성장해야 하는지는 조금 더 분명해졌다. 이제 중요한 것은 배운 내용을 실제 프로젝트에 적용하고, 계속해서 개선해나가는 것이다.

개인 포트폴리오 페이지를 구현해보자!

수달군 — Sun, 24 May 2026 23:41:26 +0900

Next.js로 기술 블로그 만들기

어느덧 Next.js를 공부한지도 7주차가 되었다.

처음에는 단순히 React에서 한 단계 더 나아가기 위해 Next.js를 공부하기 시작했지만, App Router, Server Component, 파일 기반 라우팅, SEO, 정적 생성 같은 기능들을 하나씩 배우다 보니 이 기술을 활용해서 직접 하나의 프로젝트를 만들어보고 싶다는 생각이 들었다.

그러던 중 단순히 기능을 구현하는 프로젝트가 아니라, 나 자신을 보여줄 수 있는 사이트를 만들어보면 어떨까 하는 생각이 들었다.

지금까지 공부한 내용, 진행했던 프로젝트, 문제를 해결했던 과정, 프론트엔드 개발자로 성장해가는 기록들을 한곳에 모아두면 좋겠다고 생각했다. 기존에는 Tistory에 내용을 정리했지만, Tistory에서는 디자인 수정이 쉽지 않기도 하고, 원하는 글 형식을 제공하지 않아서 아쉽다는 생각이 많이 들었다.

그래서 이번에는 직접 블로그와 포트폴리오를 결합한 기술 블로그 사이트를 만들어보기로 했다.

이 사이트는 단순히 글을 올리는 공간이 아니라, 내가 어떤 기술을 공부하고 있는지, 어떤 프로젝트를 만들어왔는지, 그리고 어떤 문제를 어떻게 해결했는지를 기록하는 공간이 될 예정이다.

또한 Next.js를 공부하면서 배운 개념들을 실제 프로젝트에 적용해보는 실습 공간이기도 하다. App Router 기반의 페이지 구조를 설계하고, Markdown 또는 MDX로 글을 관리하며, 프로젝트 소개 페이지와 기술 글 목록 페이지를 직접 구현해보려고 한다.

이번 프로젝트를 통해 단순히 “Next.js를 공부했다”에서 끝나는 것이 아니라, Next.js를 활용해 실제로 하나의 서비스를 기획하고 구현하는 경험을 쌓아보고자 한다.

프로젝트 개요

Next.js 기반의 기술 블로그 겸 포트폴리오 사이트를 제작하는 개인 프로젝트이다.

블로그에는 프론트엔드 개발을 공부하면서 정리한 기술 글을 작성하고,
포트폴리오 영역에는 지금까지 진행했던 프로젝트들을 정리할 예정이다.
또한 나에 대한 소개를 랜딩페이지에 소개하여 향후 다른 이들에게 개발자인 "나"를 소개할때 사용할 수 있도록 할 것이다.

기술 블로그에서는 다음과 같은 내용을 다룰 계획이다.

React와 TypeScript, Next.js 등의 학습 기록
프로젝트 개발 과정
에러 해결 기록
프론트엔드 테스트와 최적화 경험
개인 프로젝트 회고

포트폴리오 영역에서는 단순히 프로젝트 결과물만 보여주는 것이 아니라, 프로젝트를 만들게 된 이유, 맡은 역할, 사용한 기술, 구현 과정, 문제 해결 경험, 아쉬운 점 등을 함께 정리하려고 한다.

즉, 이 사이트는 나의 학습 기록이자, 프로젝트 아카이브이며, 프론트엔드 개발자로서의 성장 과정을 보여주는 공간이 될 것이다.

왜 블로그와 포트폴리오를 함께 만들었는가

프론트엔드 개발을 공부하다 보면 많은 기술을 접하게 된다.

React, Next.js, TypeScript, Tailwind CSS, 상태 관리, API 연동, 성능 최적화, 테스트 코드 등 배워야 할 내용은 계속 늘어난다. 하지만 공부한 내용을 제대로 정리하지 않으면 시간이 지나면서 잊어버리기 쉽다.

특히 프로젝트를 진행하면서 겪었던 문제 해결 과정은 그 당시에는 치열하게 고민하지만, 기록하지 않으면 나중에 다시 떠올리기 어렵다.

그래서 내가 공부한 내용과 프로젝트 경험을 꾸준히 기록할 수 있는 공간이 필요하다고 느꼈다.

물론 Velog나 Notion 같은 좋은 플랫폼도 있지만, 직접 기술 블로그를 만들면 단순히 글을 쓰는 것 이상의 경험을 얻을 수 있다.

블로그 자체를 하나의 프론트엔드 프로젝트로 바라보고, 페이지 구조, 컴포넌트 설계, 콘텐츠 관리, SEO, 반응형 UI, 배포까지 직접 경험할 수 있기 때문이다.

하지만 기술 블로그만으로는 내가 어떤 프로젝트를 해왔고, 실제로 어떤 문제를 해결했는지 보여주기에는 조금 부족하다고 느꼈다.

반대로 포트폴리오 사이트만 만들면 프로젝트 결과물은 보여줄 수 있지만, 그 과정에서 어떤 고민을 했는지, 어떤 기술을 학습했는지, 어떤 시행착오를 겪었는지는 충분히 담기 어렵다.

그래서 블로그와 포트폴리오를 하나의 사이트 안에 함께 구성하기로 했다.

블로그에서는 학습한 기술과 문제 해결 과정을 기록하고, 포트폴리오에서는 실제 프로젝트 경험을 정리한다. 두 영역이 연결되면 단순한 자기소개 사이트보다 더 입체적으로 나를 보여줄 수 있다고 생각했다.

예를 들어 어떤 프로젝트에서 TanStack Query를 사용했다면, 포트폴리오 페이지에서는 해당 프로젝트에서 어떤 기능에 사용했는지를 설명하고, 블로그 글에서는 TanStack Query를 학습하며 정리한 개념을 더 자세히 다룰 수 있다.

이렇게 구성하면 프로젝트 경험과 기술 학습 기록이 서로 연결되는 구조를 만들 수 있다.

이번 프로젝트를 통해 얻고 싶은 것은 단순히 예쁜 블로그 사이트 하나가 아니다.

내가 배운 기술을 실제로 적용해보고, 그 과정을 다시 글로 정리하면서 기술을 더 깊게 이해하는 것이다.

만들고자 하는 사이트의 방향

이번 기술 블로그는 단순히 글을 나열하는 사이트가 아니라, 방문자가 나의 학습 흐름과 프로젝트 경험을 자연스럽게 볼 수 있는 구조로 만들고자 한다.

메인 페이지에서는 내가 어떤 개발자인지 간단히 소개하고, 최근 작성한 글과 대표 프로젝트를 보여줄 예정이다.

기술 글 목록 페이지에서는 카테고리와 태그를 활용해 글을 쉽게 탐색할 수 있도록 구성하려고 한다.

프로젝트 페이지에서는 지금까지 진행한 프로젝트들을 카드 형태로 보여주고, 상세 페이지에서는 프로젝트의 배경, 구현 과정, 문제 해결 경험을 정리할 계획이다.

전체적인 방향은 다음과 같다.

학습 기록을 체계적으로 정리할 수 있는 블로그
프로젝트 경험을 보여줄 수 있는 포트폴리오
Next.js 학습 내용을 실제로 적용하는 실습 프로젝트
꾸준히 확장 가능한 개인 웹사이트

현재 개발 중인 과정

현재는 기술 블로그의 전체 방향성을 정하고, 실제 구현에 들어가기 전 필요한 구조를 하나씩 잡아가는 단계이다.

처음부터 완성된 블로그를 만들기보다는, 블로그를 구성하는 핵심 기능을 단계별로 나누어 구현하려고 한다.

기술 블로그는 단순히 화면을 예쁘게 만드는 것보다, 글을 어떻게 관리할지, 사용자가 어떻게 글을 탐색할지, 프로젝트 경험을 어떻게 보여줄지에 대한 구조 설계가 중요하다고 생각했다.

그래서 현재는 다음과 같은 흐름으로 개발을 진행하고 있다.

프로젝트 초기 세팅

가장 먼저 Next.js 프로젝트를 생성하고 기본 개발 환경을 구성하고 있다.

이번 프로젝트는 Next.js App Router 기반으로 진행할 예정이다. App Router는 폴더 구조를 기준으로 페이지를 구성할 수 있기 때문에, 블로그처럼 페이지 구조가 명확한 프로젝트에 잘 어울린다고 생각했다.

기본적으로 다음과 같은 페이지 구조를 먼저 잡고 있다.

src/
  app/
    page.tsx
    posts/
      page.tsx
      [slug]/
        page.tsx
    projects/
      page.tsx
      [slug]/
        page.tsx
    about/
      page.tsx

이 구조에서 page.tsx는 메인 페이지, posts/page.tsx는 게시글 목록 페이지, posts/[slug]/page.tsx는 게시글 상세 페이지를 담당한다.

projects 경로는 포트폴리오 역할을 하는 프로젝트 목록과 상세 페이지를 담당하고, about 페이지에서는 나에 대한 소개와 기술 스택, 활동 경험 등을 정리할 계획이다.

처음부터 많은 페이지를 한 번에 구현하기보다는, 메인 페이지와 게시글 목록 페이지를 먼저 만들고 이후 프로젝트 페이지와 소개 페이지를 확장하는 방식으로 진행하고 있다.

UI 구조 설계

초기 세팅 이후에는 블로그의 전체 UI 구조를 설계하고 있다.

기술 블로그는 글을 읽는 경험이 중요하기 때문에 화려한 인터랙션보다는 가독성과 탐색 편의성을 우선으로 두고 있다. 방문자가 블로그에 들어왔을 때 내가 어떤 기술을 공부하고 있는지, 어떤 프로젝트를 진행했는지 빠르게 파악할 수 있어야 한다고 생각했다.

현재 생각하고 있는 기본 레이아웃은 다음과 같다.

공통 레이아웃
- Header
- Main Content
- Footer

메인 페이지
- Hero Section
- 최근 게시글
- 대표 프로젝트
- 관심 기술 스택

게시글 목록 페이지
- 게시글 카드 목록
- 카테고리 필터
- 태그 필터
- 검색 영역

게시글 상세 페이지
- 제목
- 작성일
- 태그
- 본문
- 코드 블록
- 목차

특히 게시글 상세 페이지는 기술 블로그의 핵심이기 때문에 본문 폭, 줄 간격, 제목 크기, 코드 블록 스타일 등을 신경 써서 구성하려고 한다.

기술 글은 일반 글보다 코드 예제와 설명이 많기 때문에, 작은 스타일 차이도 읽는 경험에 큰 영향을 준다고 생각했다.

공통 컴포넌트 개발

블로그에서 반복적으로 사용되는 UI는 공통 컴포넌트로 분리해서 관리할 계획이다.

예를 들어 게시글 카드, 태그, 카테고리 배지, 버튼, 섹션 제목, 레이아웃 컴포넌트 등은 여러 페이지에서 반복해서 사용된다.

현재는 다음과 같은 컴포넌트를 우선적으로 만들려고 한다.

components/
  common/
    Button.tsx
    Badge.tsx
    SectionTitle.tsx

  layout/
    Header.tsx
    Footer.tsx
    Container.tsx

  post/
    PostCard.tsx
    PostList.tsx
    PostTag.tsx
    PostMeta.tsx

  project/
    ProjectCard.tsx
    ProjectList.tsx

컴포넌트를 나누는 기준은 단순히 파일을 많이 만드는 것이 아니라, 각 컴포넌트가 어떤 책임을 가지는지 명확하게 구분하는 것이다.

예를 들어 PostCard는 게시글 하나를 카드 형태로 보여주는 역할만 담당하고, 게시글 목록을 순회하며 렌더링하는 책임은 PostList가 담당하도록 나눌 수 있다.

이렇게 하면 나중에 게시글 카드 디자인을 바꾸거나 목록 정렬 방식을 수정할 때도 영향을 받는 범위를 줄일 수 있다.

콘텐츠 구조 설계

기술 블로그에서 가장 중요한 부분은 글을 어떻게 관리할지이다.

초기에는 Markdown 기반으로 글을 작성하고, 각 글의 상단에 frontmatter를 작성하여 메타데이터를 관리할 계획이다.

예를 들어 게시글은 다음과 같은 구조로 작성할 수 있다.

---
title: "Next.js App Router 이해하기"
description: "Next.js App Router의 기본 구조와 동작 방식을 정리합니다."
category: "Next.js"
tags: ["Next.js", "App Router", "React"]
publishedAt: "2026-05-24"
published: true
---

본문 내용...

여기서 title은 게시글 제목, description은 글 설명, category는 글의 큰 분류, tags는 세부 키워드, publishedAt은 작성일을 의미한다.

이렇게 글 데이터를 구조화해두면 게시글 목록 페이지에서 카드 UI를 만들 때도 사용할 수 있고, 상세 페이지의 SEO 메타데이터에도 활용할 수 있다.

또한 태그와 카테고리를 기반으로 필터링 기능을 구현할 수 있기 때문에, 글이 많아져도 사용자가 원하는 내용을 쉽게 찾을 수 있다.

게시글 목록 페이지 구현 계획

게시글 목록 페이지는 블로그의 중심이 되는 페이지이다.

이 페이지에서는 작성한 글들을 최신순으로 보여주고, 사용자가 카테고리나 태그를 기준으로 원하는 글을 찾을 수 있도록 만들 예정이다.

게시글 카드에는 다음 정보를 표시할 계획이다.

- 게시글 제목
- 게시글 설명
- 작성일
- 카테고리
- 태그 목록
- 예상 읽기 시간

처음에는 전체 게시글을 최신순으로 보여주는 기능부터 구현하고, 이후 검색과 필터 기능을 추가할 예정이다.

검색 기능은 제목과 설명을 기준으로 동작하도록 만들고, 필터 기능은 카테고리와 태그를 기준으로 동작하게 할 계획이다.

예를 들어 사용자가 Next.js 카테고리를 선택하면 Next.js와 관련된 글만 보여주고, React, 성능 최적화, 테스트 같은 태그를 선택하면 해당 태그가 포함된 글만 보여주는 방식이다.

이 기능을 통해 단순한 글 목록이 아니라, 사용자가 원하는 글을 쉽게 찾을 수 있는 블로그를 만들고자 한다.

게시글 상세 페이지 구현 계획

게시글 상세 페이지에서는 Markdown으로 작성한 본문을 실제 페이지로 렌더링한다.

상세 페이지는 단순히 글을 보여주는 화면이 아니라, 기술 글을 읽기 좋은 형태로 가공하는 역할을 해야 한다.

따라서 다음과 같은 요소를 함께 구현할 계획이다.

- 게시글 제목
- 작성일
- 카테고리
- 태그
- 본문 렌더링
- 코드 블록 스타일링
- 목차
- 이전 글 / 다음 글 이동
- 관련 글 추천

특히 코드 블록 스타일링은 기술 블로그에서 중요한 요소라고 생각한다.

프론트엔드 기술 글에는 코드 예제가 자주 들어가기 때문에, 코드가 읽기 어렵다면 글 전체의 가독성이 떨어질 수 있다. 따라서 코드 하이라이팅을 적용하고, 필요하다면 파일명 표시나 복사 버튼도 추가할 계획이다.

또한 글이 길어질 경우를 대비해 목차 기능도 고려하고 있다. 제목 구조를 기준으로 목차를 자동 생성하면 사용자가 글의 전체 흐름을 파악하기 쉬워진다.

프로젝트 페이지 구현 계획

이 블로그는 단순한 기술 글 저장소가 아니라 포트폴리오 역할도 함께 하도록 만들 계획이다.

그래서 별도의 프로젝트 페이지를 만들고, 지금까지 진행한 프로젝트들을 정리하려고 한다.

프로젝트 목록 페이지에서는 각 프로젝트를 카드 형태로 보여준다.

- 프로젝트명
- 한 줄 소개
- 진행 기간
- 맡은 역할
- 사용 기술
- 주요 기능
- GitHub 링크
- 배포 링크

프로젝트 상세 페이지에서는 단순히 결과물을 보여주는 것이 아니라, 프로젝트를 만들게 된 이유와 구현 과정, 문제 해결 경험을 중심으로 작성할 예정이다.

예를 들어 프로젝트 상세 글은 다음과 같은 흐름으로 구성할 수 있다.

- 프로젝트 소개
- 프로젝트를 시작한 이유
- 맡은 역할
- 사용한 기술
- 주요 기능
- 구현 과정
- 문제 해결 경험
- 아쉬운 점
- 개선 방향

이렇게 작성하면 단순히 “이런 프로젝트를 만들었다”에서 끝나는 것이 아니라, 프로젝트를 진행하면서 어떤 고민을 했고 어떤 방식으로 문제를 해결했는지를 보여줄 수 있다.

검색과 필터 기능 계획

블로그에 글이 많아질수록 탐색 기능은 중요해진다.

처음에는 글이 많지 않기 때문에 최신순 목록만으로도 충분할 수 있지만, 장기적으로 기술 글이 쌓이면 원하는 글을 빠르게 찾기 어려워질 수 있다.

그래서 검색과 필터 기능을 초기 설계 단계부터 고려하고 있다.

검색은 다음 기준으로 동작하도록 만들 계획이다.

- 제목 검색
- 설명 검색
- 태그 검색
- 카테고리 검색

필터는 카테고리와 태그를 기준으로 구현할 예정이다.

예를 들어 카테고리는 React, Next.js, TypeScript, CSS, 회고처럼 큰 주제로 나누고, 태그는 App Router, Server Component, Tailwind CSS, TanStack Query처럼 더 세부적인 키워드로 구성할 수 있다.

이렇게 카테고리와 태그를 분리하면 글을 더 체계적으로 관리할 수 있고, 방문자도 관심 있는 주제의 글을 더 쉽게 탐색할 수 있다.

SEO와 메타데이터 설정 계획

기술 블로그는 검색을 통해 유입되는 경우가 많기 때문에 SEO도 함께 고려할 예정이다.

Next.js에서는 각 페이지마다 메타데이터를 설정할 수 있고, 게시글 상세 페이지에서는 글의 제목과 설명을 기반으로 동적인 메타데이터를 생성할 수 있다.

예를 들어 게시글의 frontmatter에 작성한 title과 description을 활용해 페이지의 메타데이터를 구성할 수 있다.

export async function generateMetadata({ params }: Props) {
  const post = getPostBySlug(params.slug);

  return {
    title: post.title,
    description: post.description,
  };
}

이렇게 설정하면 각 게시글마다 다른 제목과 설명을 검색 엔진에 전달할 수 있다.

또한 추후에는 Open Graph 이미지, sitemap, robots.txt도 함께 설정하여 검색과 공유 환경에서 더 자연스럽게 노출되도록 개선할 계획이다.

앞으로의 개발 계획

현재는 블로그의 전체 구조와 핵심 기능을 설계하는 단계이며, 이후에는 다음 순서로 개발을 진행할 계획이다.

Next.js 프로젝트 초기 세팅
공통 레이아웃 구현
메인 페이지 구현
Markdown 게시글 구조 설계
게시글 목록 페이지 구현
게시글 상세 페이지 구현
코드 블록 스타일링 적용
프로젝트 목록 페이지 구현
프로젝트 상세 페이지 구현
검색 및 필터 기능 구현
SEO 메타데이터 설정
반응형 UI 개선
배포

우선은 블로그의 핵심 기능인 게시글 목록과 상세 페이지를 먼저 완성하는 것을 목표로 하고 있다.

그 이후 프로젝트 페이지와 소개 페이지를 추가하고, 검색과 필터 기능을 붙이면서 사용성을 높일 예정이다.

마지막으로 반응형 UI와 SEO를 정리하고 배포까지 진행하면 1차 버전의 기술 블로그가 완성될 것이다.

나만의 블로그를 완성하는 그날까지 화이팅!!

프론트엔드에서 테스트는 어떻게 진행할까?

수달군 — Sun, 24 May 2026 22:06:31 +0900

프론트엔드 테스트는 왜 필요할까?

버튼 하나의 조건을 바꿨는데 모달이 열리지 않을 수 있고, API 응답 구조가 조금 바뀌었는데 리스트가 렌더링되지 않을 수 있습니다. 또는 로그인 여부에 따라 보여야 할 페이지가 잘못 노출될 수도 있습니다.

특히 React 프로젝트에서는 컴포넌트가 많아질수록 상태, props, API, 라우팅, 전역 상태가 복잡하게 연결됩니다. 이때 테스트가 없으면 기능을 수정할 때마다 직접 브라우저를 열고 모든 경우를 손으로 확인해야 합니다.

테스트 코드는 이런 과정을 자동화해 줍니다.

예를 들어 다음과 같은 상황을 코드로 검증할 수 있습니다.

사용자가 검색어를 입력한다.
검색 버튼을 클릭한다.
API 응답이 도착한다.
검색 결과 목록이 화면에 표시된다.

이 흐름이 테스트로 작성되어 있다면, 이후 코드를 리팩토링하더라도 검색 기능이 깨졌는지 빠르게 확인할 수 있습니다.

프론트엔드 테스트의 기본 관점

프론트엔드 테스트에서 중요한 기준은 사용자 관점에서 테스트하는 것입니다.

예를 들어 React 컴포넌트 내부에 isOpen이라는 상태가 있다고 해보겠습니다. 모달이 열렸는지 테스트할 때 isOpen 값이 true인지 직접 확인하는 방식은 좋지 않습니다.

대신 사용자가 실제로 보는 화면을 기준으로 확인하는 것이 좋습니다.

expect(screen.getByText('로그인 정보를 입력해주세요')).toBeInTheDocument();

이 방식은 “모달 상태가 true인가?”를 확인하는 것이 아니라, “사용자 화면에 로그인 안내 문구가 보이는가?”를 확인합니다.

이 차이가 중요합니다. 내부 구현은 언제든 바뀔 수 있지만, 사용자에게 보여야 하는 결과는 유지되어야 하기 때문입니다.

프론트엔드 테스트의 종류

프론트엔드 테스트는 보통 다음과 같이 나눌 수 있습니다.

단위 테스트	함수, 유틸 로직	날짜 포맷, 가격 계산, 배열 필터링
컴포넌트 테스트	개별 UI 컴포넌트	Button, Modal, Input, Card
통합 테스트	여러 컴포넌트와 상태의 연결	검색 폼 + API + 결과 리스트
E2E 테스트	실제 브라우저에서 전체 사용자 흐름	로그인 → 상품 검색 → 결제

각 테스트는 역할이 다릅니다. 모든 것을 하나의 방식으로 테스트하려고 하면 오히려 비효율적입니다.

단위 테스트

단위 테스트는 가장 작은 로직을 검증하는 테스트입니다. 보통 UI보다는 순수 함수나 유틸 함수를 테스트할 때 많이 사용합니다.

예를 들어 날짜를 화면에 보여주기 좋은 형식으로 바꾸는 함수가 있다고 해보겠습니다.

export const formatDate = (date: string) => {
  return date.replaceAll('-', '.');
};

이 함수는 다음과 같이 테스트할 수 있습니다.

import { describe, expect, it } from 'vitest';
import { formatDate } from './formatDate';

describe('formatDate', () => {
  it('날짜 문자열의 하이픈을 점으로 변경한다', () => {
    expect(formatDate('2026-05-19')).toBe('2026.05.19');
  });
});

단위 테스트는 실행 속도가 빠르고, 실패했을 때 원인을 찾기 쉽습니다. 그래서 날짜 변환, 숫자 계산, 필터링, 정렬, 유효성 검사 같은 로직에 적합합니다.

컴포넌트 테스트

컴포넌트 테스트는 React 컴포넌트가 props나 사용자 행동에 따라 올바르게 렌더링되는지 확인합니다.

예를 들어 버튼 컴포넌트가 있다고 해보겠습니다.

type ButtonProps = {
  children: React.ReactNode;
  disabled?: boolean;
  onClick?: () => void;
};

export function Button({ children, disabled, onClick }: ButtonProps) {
  return (
    <button disabled={disabled} onClick={onClick}>
      {children}
    </button>
  );
}

이 컴포넌트는 다음과 같이 테스트할 수 있습니다.

import { render, screen } from '@testing-library/react';
import { describe, expect, it, vi } from 'vitest';
import userEvent from '@testing-library/user-event';
import { Button } from './Button';

describe('Button', () => {
  it('버튼 텍스트를 렌더링한다', () => {
    render(<Button>저장</Button>);

    expect(screen.getByRole('button', { name: '저장' })).toBeInTheDocument();
  });

  it('버튼을 클릭하면 onClick이 호출된다', async () => {
    const user = userEvent.setup();
    const handleClick = vi.fn();

    render(<Button onClick={handleClick}>저장</Button>);

    await user.click(screen.getByRole('button', { name: '저장' }));

    expect(handleClick).toHaveBeenCalled();
  });
});

여기서도 핵심은 button 태그를 직접 찾는 것이 아니라, 사용자가 접근할 수 있는 역할인 button과 이름인 저장을 기준으로 찾는다는 점입니다.

이 방식은 접근성 측면에서도 좋습니다. 테스트하기 쉬운 컴포넌트는 대체로 사용자와 스크린 리더도 접근하기 쉬운 구조를 갖는 경우가 많습니다.

통합 테스트

통합 테스트는 여러 컴포넌트, 상태, API 요청이 함께 동작하는 흐름을 검증합니다.

예를 들어 애니메이션 검색 페이지가 있다고 해보겠습니다. 이 페이지는 검색어 입력 컴포넌트, 검색 버튼, API 요청, 결과 리스트 컴포넌트가 함께 동작합니다.

통합 테스트는 이런 식으로 진행됩니다.

it('검색어를 입력하고 검색하면 결과 목록이 표시된다', async () => {
  const user = userEvent.setup();

  render(<AnimeSearchPage />);

  await user.type(screen.getByPlaceholderText('애니메이션 검색'), 'naruto');
  await user.click(screen.getByRole('button', { name: '검색' }));

  expect(await screen.findByText('Naruto')).toBeInTheDocument();
});

이 테스트는 내부적으로 어떤 state를 사용하는지, API 함수 이름이 무엇인지에 관심을 두지 않습니다.

중요한 것은 사용자가 검색어를 입력하고 검색했을 때 결과가 보이는지입니다.

프론트엔드에서 실제로 가장 가치 있는 테스트는 이런 통합 테스트인 경우가 많습니다. 사용자가 경험하는 흐름을 직접 검증하기 때문입니다.

API가 필요한 테스트는 어떻게 할까?

프론트엔드 테스트에서 API 요청을 실제 서버에 보내는 것은 보통 권장되지 않습니다.

서버 상태나 네트워크 환경에 따라 테스트가 실패할 수 있고, 테스트 데이터가 바뀌면 결과도 흔들릴 수 있기 때문입니다. 그래서 API가 필요한 테스트에서는 보통 Mocking을 사용합니다.

대표적으로 많이 사용하는 도구가 **MSW(Mock Service Worker)**입니다.

MSW는 프론트엔드 코드가 실제 API를 호출하는 것처럼 동작하게 두면서, 테스트 환경에서는 해당 요청을 가로채서 가짜 응답을 반환합니다.

예를 들어 검색 API를 다음과 같이 모킹할 수 있습니다.

import { http, HttpResponse } from 'msw';

export const handlers = [
  http.get('/api/anime/search', () => {
    return HttpResponse.json({
      results: [
        {
          id: 1,
          title: 'Naruto',
        },
      ],
    });
  }),
];

그러면 테스트에서는 실제 서버가 없어도 API 응답을 받은 것처럼 화면을 검증할 수 있습니다.

it('API 응답으로 받은 검색 결과를 렌더링한다', async () => {
  render(<AnimeSearchPage />);

  expect(await screen.findByText('Naruto')).toBeInTheDocument();
});

MSW를 사용하면 성공 응답뿐 아니라 실패 응답도 테스트할 수 있습니다.

http.get('/api/anime/search', () => {
  return HttpResponse.json(
    { message: '검색 결과를 불러오지 못했습니다.' },
    { status: 500 }
  );
});

이런 식으로 에러 응답을 만들고, 화면에 에러 메시지가 제대로 표시되는지 확인할 수 있습니다.

expect(
  await screen.findByText('검색 결과를 불러오지 못했습니다.')
).toBeInTheDocument();

로딩, 에러, 빈 상태도 테스트해야 한다

프론트엔드 테스트에서 자주 놓치는 부분이 있습니다. 바로 로딩 상태, 에러 상태, 빈 데이터 상태입니다.

실제 서비스에서는 항상 성공 응답만 오지 않습니다. 데이터가 늦게 올 수도 있고, 실패할 수도 있고, 결과가 없을 수도 있습니다.

그래서 다음과 같은 상태를 테스트하는 것이 좋습니다.

데이터를 불러오는 동안 로딩 UI가 보이는가?
API 요청이 실패했을 때 에러 메시지가 보이는가?
검색 결과가 없을 때 빈 상태 UI가 보이는가?
데이터가 정상적으로 도착하면 리스트가 보이는가?

예를 들어 검색 결과가 없을 때는 다음과 같은 UI가 나올 수 있습니다.

expect(await screen.findByText('검색 결과가 없습니다.')).toBeInTheDocument();

이런 테스트는 서비스의 안정성을 높여줍니다. 사용자는 성공 케이스만 경험하지 않기 때문에, 예외 상황까지 테스트하는 것이 중요합니다.

테스트 커버리지는 어떻게 봐야 할까?

테스트 커버리지는 코드 중 어느 정도가 테스트에 의해 실행되었는지를 나타내는 지표입니다.

예를 들어 커버리지가 80%라면 전체 코드 중 80%가 테스트 실행 과정에서 지나갔다는 의미입니다.

하지만 커버리지 숫자가 높다고 해서 좋은 테스트라고 단정할 수는 없습니다.

중요한 것은 핵심 기능이 테스트되고 있는가입니다.

예를 들어 단순히 텍스트만 보여주는 컴포넌트를 많이 테스트해서 커버리지를 높이는 것보다, 로그인, 검색, 작성, 삭제, 권한 분기, API 에러 처리 같은 중요한 기능을 테스트하는 것이 더 가치 있습니다.

프로젝트에서는 보통 다음과 같은 우선순위로 테스트를 작성하는 것이 좋습니다.

우선순위 테스트 대상

높음	로그인, 회원가입, 검색, 작성, 삭제 등 핵심 사용자 흐름
높음	API 성공, 실패, 빈 데이터 상태
높음	폼 유효성 검사
높음	권한에 따른 화면 분기
중간	공통 컴포넌트
중간	유틸 함수
낮음	단순 정적 UI

커버리지는 목표가 아니라 참고 지표로 보는 것이 좋습니다. 테스트의 목적은 숫자를 채우는 것이 아니라, 기능이 깨졌을 때 빠르게 알아차리는 것입니다.

프론트엔드 테스트 도구 조합

React 프로젝트에서는 보통 다음 조합을 많이 사용합니다.

Vitest: 테스트 실행 도구
React Testing Library: React 컴포넌트 테스트 도구
user-event: 사용자 입력과 클릭 시뮬레이션
MSW: API Mocking
Playwright 또는 Cypress: E2E 테스트

Vite 기반 프로젝트라면 Vitest가 잘 어울립니다. 설정이 간단하고 실행 속도가 빠르기 때문입니다.

React Testing Library는 컴포넌트를 실제 사용자 관점에서 테스트하는 데 적합합니다.

MSW는 API 응답을 안정적으로 제어할 수 있게 해주기 때문에, API 연동이 포함된 테스트에서 유용합니다.

Playwright나 Cypress는 실제 브라우저를 띄워서 로그인부터 페이지 이동까지 전체 흐름을 검증할 때 사용합니다.

테스트는 어디까지 작성해야 할까?

모든 코드를 테스트하려고 하면 오히려 부담이 커집니다. 처음부터 완벽한 테스트 환경을 만들기보다는, 깨지면 치명적인 기능부터 테스트하는 것이 좋습니다.

예를 들어 “인생 애니메이션 9선 선택 서비스”라면 다음 기능부터 테스트할 수 있습니다.

애니메이션을 검색할 수 있는가?
검색 결과가 화면에 표시되는가?
작품을 선택할 수 있는가?
최대 9개까지만 선택되는가?
선택한 작품을 삭제할 수 있는가?
선택한 작품의 순서를 변경할 수 있는가?
결과 페이지에 9개 작품이 정상적으로 표시되는가?
API 요청 실패 시 에러 메시지가 표시되는가?

이런 테스트는 서비스의 핵심 흐름을 직접 보호합니다.

반면 단순히 제목만 출력하는 섹션이나 스타일만 담당하는 컴포넌트는 우선순위를 낮게 잡아도 됩니다.

정리

프론트엔드 테스트는 사용자가 실제로 서비스를 이용하는 흐름을 코드로 검증하는 과정입니다.

단위 테스트는 유틸 함수나 작은 로직을 검증하고, 컴포넌트 테스트는 개별 UI가 올바르게 렌더링되는지 확인합니다. 통합 테스트는 여러 컴포넌트와 API 요청이 연결된 사용자 흐름을 검증합니다. 그리고 E2E 테스트는 실제 브라우저 환경에서 서비스 전체 흐름을 확인합니다.

프론트엔드 테스트에서 중요한 것은 내부 구현을 검증하는 것이 아니라, 사용자가 보는 화면과 행동 결과를 검증하는 것입니다.

따라서 좋은 프론트엔드 테스트는 다음 질문에 답할 수 있어야 합니다.

사용자가 이 기능을 정상적으로 사용할 수 있는가?
데이터가 없거나 실패했을 때도 화면이 안정적으로 동작하는가?
리팩토링 이후에도 핵심 기능이 깨지지 않았는가?

결국 테스트는 코드를 더 복잡하게 만드는 작업이 아니라, 프로젝트를 더 안전하게 변경하기 위한 장치입니다. 특히 React 프로젝트처럼 컴포넌트와 상태가 많아지는 구조에서는 테스트가 있을수록 리팩토링과 기능 추가를 더 자신 있게 진행할 수 있습니다.

Next.js 스타일링 전략: Tailwind CSS, shadcn/ui, 그리고 CSS-in-JS

수달군 — Sun, 17 May 2026 23:41:18 +0900

Next.js 스타일링 전략: Tailwind CSS, shadcn/ui, 그리고 CSS-in-JS 이슈 직접 실험해보기

Next.js App Router 환경에서는 스타일링 도구를 선택할 때 단순히 “디자인을 어떻게 입힐 것인가”만 보면 부족합니다. Server Components, Client Components, SSR, Streaming, 하이드레이션, 번들 크기, 스타일 삽입 시점까지 함께 고려해야 합니다. 특히 App Router에서는 기본적으로 Server Components를 적극적으로 활용할 수 있기 때문에, 스타일링 방식이 서버 렌더링 흐름과 잘 맞는지 확인하는 것이 중요합니다.

이번 글에서는 Tailwind CSS와 shadcn/ui를 활용해 UI 컴포넌트를 구현해보고, Styled-Components를 사용했을 때 SSR 환경에서 어떤 추가 설정이 필요한지 직접 실험해보겠습니다. 마지막으로 이 내용을 바탕으로 Next.js 프로젝트에서 어떤 스타일링 전략을 선택하면 좋을지 정리하겠습니다.

Next.js에서 Tailwind CSS가 자주 선택되는 이유

Tailwind CSS는 유틸리티 클래스를 조합해서 UI를 만드는 방식의 CSS 프레임워크입니다. 예를 들어 flex, px-4, text-sm, rounded-xl, bg-white 같은 클래스를 JSX의 className에 직접 작성해서 스타일을 적용합니다. 이 방식은 처음에는 HTML 안에 클래스가 많아 보여 어색할 수 있지만, 컴포넌트 단위로 UI를 작성하는 React와는 꽤 잘 맞는 편입니다.

Next.js App Router에서는 컴포넌트가 기본적으로 Server Component로 동작합니다. Tailwind CSS는 런타임에 JavaScript로 스타일을 생성해서 주입하는 방식이 아니라, 빌드 과정에서 CSS를 생성하고 HTML에는 클래스 이름을 붙이는 방식에 가깝습니다. 그래서 Server Component에서도 특별한 클라이언트 런타임 없이 사용할 수 있습니다.

예를 들어 아래와 같은 컴포넌트는 별도의 "use client" 없이도 서버 컴포넌트로 작성할 수 있습니다.

// app/page.tsx

export default function HomePage() {
  return (
    <main className="min-h-screen bg-slate-50 px-6 py-10">
      <section className="mx-auto max-w-3xl rounded-2xl bg-white p-8 shadow-sm">
        <p className="text-sm font-medium text-blue-600">Next.js Styling</p>

        <h1 className="mt-3 text-3xl font-bold tracking-tight text-slate-900">
          Tailwind CSS로 빠르게 UI를 구성하기
        </h1>

        <p className="mt-4 leading-7 text-slate-600">
          Tailwind CSS는 유틸리티 클래스를 조합해 컴포넌트 단위의 UI를
          구성하기 좋은 방식입니다. Server Component에서도 className만
          사용하면 되기 때문에 Next.js App Router와 함께 사용하기 편합니다.
        </p>

        <button className="mt-6 rounded-xl bg-slate-900 px-5 py-3 text-sm font-medium text-white hover:bg-slate-700">
          시작하기
        </button>
      </section>
    </main>
  );
}

이 코드는 서버 컴포넌트로 렌더링될 수 있습니다. 버튼에 hover 스타일이 들어가 있지만, 이것만으로는 클라이언트 상태나 이벤트 핸들러가 필요하지 않습니다. 따라서 "use client"를 붙일 이유가 없습니다. 이 점은 Next.js에서 중요한 차이를 만듭니다. 스타일링을 위해 불필요하게 Client Component로 전환하지 않아도 되기 때문입니다.

Next.js 공식 문서에서도 App Router에서 CSS-in-JS를 구성하려면 스타일 레지스트리, useServerInsertedHTML, Client Component wrapper 같은 별도 구성이 필요하다고 설명합니다. 반면 Tailwind CSS나 CSS Modules는 이러한 런타임 스타일 삽입 흐름을 직접 관리하지 않아도 되는 방식입니다.

Tailwind CSS만 사용했을 때 생기는 아쉬움

Tailwind CSS는 빠르게 UI를 만들기 좋지만, 프로젝트가 커지면 클래스 조합이 반복될 수 있습니다. 예를 들어 버튼을 여러 곳에서 사용한다고 가정해보겠습니다.

<button className="rounded-xl bg-slate-900 px-5 py-3 text-sm font-medium text-white hover:bg-slate-700">
  저장하기
</button>

<button className="rounded-xl bg-slate-900 px-5 py-3 text-sm font-medium text-white hover:bg-slate-700">
  수정하기
</button>

<button className="rounded-xl bg-slate-900 px-5 py-3 text-sm font-medium text-white hover:bg-slate-700">
  삭제하기
</button>

이렇게 같은 스타일이 반복되면 유지보수가 어려워집니다. 나중에 버튼의 radius나 색상, padding을 바꾸려면 여러 파일을 찾아 수정해야 합니다. 그래서 실제 프로젝트에서는 Tailwind CSS를 그대로 쓰기보다는 공통 컴포넌트로 추상화해서 사용하는 경우가 많습니다.

예를 들어 직접 Button 컴포넌트를 만들 수 있습니다.

// components/ui/button.tsx

import { ButtonHTMLAttributes } from "react";

type ButtonVariant = "primary" | "secondary" | "danger";

interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: ButtonVariant;
}

const variantClassName: Record<ButtonVariant, string> = {
  primary: "bg-slate-900 text-white hover:bg-slate-700",
  secondary: "bg-slate-100 text-slate-900 hover:bg-slate-200",
  danger: "bg-red-600 text-white hover:bg-red-500",
};

export function Button({
  variant = "primary",
  className = "",
  children,
  ...props
}: ButtonProps) {
  return (
    <button
      className={[
        "rounded-xl px-5 py-3 text-sm font-medium transition-colors disabled:cursor-not-allowed disabled:opacity-50",
        variantClassName[variant],
        className,
      ].join(" ")}
      {...props}
    >
      {children}
    </button>
  );
}

그리고 페이지에서는 다음처럼 사용할 수 있습니다.

// app/page.tsx

import { Button } from "@/components/ui/button";

export default function HomePage() {
  return (
    <main className="p-10">
      <div className="flex gap-3">
        <Button>저장하기</Button>
        <Button variant="secondary">취소하기</Button>
        <Button variant="danger">삭제하기</Button>
      </div>
    </main>
  );
}

이렇게 하면 Tailwind의 장점은 유지하면서도, 반복되는 클래스는 컴포넌트 내부로 숨길 수 있습니다. 다만 직접 모든 컴포넌트를 만들기 시작하면 Button, Input, Modal, Dialog, Dropdown, Select 같은 UI를 계속 구현해야 합니다. 이 지점에서 shadcn/ui가 좋은 선택지가 될 수 있습니다.

shadcn/ui는 어떤 방식인가

shadcn/ui는 일반적인 UI 라이브러리와 조금 다릅니다. MUI나 Chakra UI처럼 패키지 내부에 있는 컴포넌트를 import해서 사용하는 방식이라기보다는, 필요한 컴포넌트의 코드를 내 프로젝트 안으로 가져와서 수정하며 사용하는 방식에 가깝습니다. shadcn/ui 공식 문서도 Next.js 프로젝트에서 CLI를 통해 설정하고 컴포넌트를 추가하는 방식을 안내하고 있습니다.

이 방식의 장점은 코드 소유권이 프로젝트에 있다는 점입니다. 예를 들어 Button 컴포넌트를 추가하면 components/ui/button.tsx 같은 파일이 실제 프로젝트 안에 생성됩니다. 이후에는 이 파일을 직접 수정해서 우리 서비스의 디자인 시스템에 맞게 바꿀 수 있습니다.

shadcn/ui는 보통 Tailwind CSS와 Radix UI를 함께 사용합니다. Tailwind CSS는 스타일을 담당하고, Radix UI는 Dialog, Dropdown, Select처럼 접근성 처리가 중요한 UI primitive를 제공합니다. shadcn/ui는 이 둘을 조합한 컴포넌트 예시를 프로젝트에 복사해주는 방식으로 볼 수 있습니다.

shadcn/ui 설치 예시

Next.js 프로젝트가 이미 있다고 가정하면, 먼저 shadcn/ui 초기 설정을 진행합니다.

npx shadcn@latest init

초기 설정 후 필요한 컴포넌트를 추가합니다.

npx shadcn@latest add button card input textarea

컴포넌트가 추가되면 보통 다음과 같은 구조가 생깁니다.

components/
  ui/
    button.tsx
    card.tsx
    input.tsx
    textarea.tsx

lib/
  utils.ts

lib/utils.ts에는 보통 cn 함수가 들어갑니다. 이 함수는 조건부 클래스 조합을 정리할 때 사용됩니다.

// lib/utils.ts

import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

clsx는 조건부 className을 조합하는 도구이고, tailwind-merge는 Tailwind 클래스가 충돌할 때 뒤에 온 값을 기준으로 정리해주는 도구입니다. 예를 들어 p-2 p-4가 동시에 들어왔을 때 최종적으로 p-4가 적용되도록 병합할 수 있습니다.

Tailwind + shadcn/ui로 UI 컴포넌트 구현하기

이제 shadcn/ui의 Button, Card, Input, Textarea를 활용해서 간단한 게시글 작성 카드를 만들어보겠습니다.

// app/posts/new/page.tsx

import { Button } from "@/components/ui/button";
import {
  Card,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
} from "@/components/ui/card";
import { Input } from "@/components/ui/input";
import { Textarea } from "@/components/ui/textarea";

export default function NewPostPage() {
  return (
    <main className="min-h-screen bg-slate-50 px-6 py-10">
      <section className="mx-auto max-w-2xl">
        <Card>
          <CardHeader>
            <CardTitle>새 글 작성</CardTitle>
            <CardDescription>
              Next.js 스타일링 전략에 대한 글을 작성해보세요.
            </CardDescription>
          </CardHeader>

          <CardContent>
            <form className="space-y-5">
              <div className="space-y-2">
                <label
                  htmlFor="title"
                  className="text-sm font-medium text-slate-700"
                >
                  제목
                </label>
                <Input
                  id="title"
                  name="title"
                  placeholder="글 제목을 입력하세요"
                />
              </div>

              <div className="space-y-2">
                <label
                  htmlFor="content"
                  className="text-sm font-medium text-slate-700"
                >
                  내용
                </label>
                <Textarea
                  id="content"
                  name="content"
                  placeholder="내용을 입력하세요"
                  className="min-h-40 resize-none"
                />
              </div>

              <div className="flex justify-end gap-3">
                <Button type="button" variant="outline">
                  취소
                </Button>
                <Button type="submit">작성하기</Button>
              </div>
            </form>
          </CardContent>
        </Card>
      </section>
    </main>
  );
}

이 예제에서 중요한 점은 UI를 구성하는 대부분의 코드가 Server Component로 작성될 수 있다는 것입니다. 현재 코드에는 useState, useEffect, onClick 같은 클라이언트 전용 로직이 없습니다. 따라서 페이지 전체에 "use client"를 붙일 필요가 없습니다.

물론 입력값을 실시간으로 상태 관리하거나, 모달을 열고 닫거나, 클라이언트에서 즉시 유효성 검사를 해야 한다면 해당 부분은 Client Component로 분리할 수 있습니다. 핵심은 “상호작용이 필요한 부분만 Client Component로 분리하고, 나머지 정적 UI는 Server Component로 유지할 수 있다”는 점입니다.

variant가 많은 컴포넌트는 cva로 정리하기

shadcn/ui의 Button 컴포넌트를 보면 class-variance-authority, 줄여서 cva를 사용하는 경우가 많습니다. cva는 variant와 size에 따라 className을 체계적으로 관리할 수 있게 도와줍니다.

아래는 단순화한 Button 예시입니다.

// components/ui/custom-button.tsx

import * as React from "react";
import { cva, type VariantProps } from "class-variance-authority";

import { cn } from "@/lib/utils";

const buttonVariants = cva(
  "inline-flex items-center justify-center rounded-xl text-sm font-medium transition-colors disabled:pointer-events-none disabled:opacity-50",
  {
    variants: {
      variant: {
        default: "bg-slate-900 text-white hover:bg-slate-700",
        outline: "border border-slate-200 bg-white hover:bg-slate-100",
        ghost: "hover:bg-slate-100",
        danger: "bg-red-600 text-white hover:bg-red-500",
      },
      size: {
        sm: "h-9 px-3",
        md: "h-10 px-4",
        lg: "h-12 px-6",
      },
    },
    defaultVariants: {
      variant: "default",
      size: "md",
    },
  }
);

interface CustomButtonProps
  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
    VariantProps<typeof buttonVariants> {}

export function CustomButton({
  className,
  variant,
  size,
  ...props
}: CustomButtonProps) {
  return (
    <button
      className={cn(buttonVariants({ variant, size }), className)}
      {...props}
    />
  );
}

이렇게 하면 버튼 스타일을 문자열로 매번 직접 조합하지 않고, variant와 size라는 명확한 API로 사용할 수 있습니다.

<CustomButton>기본 버튼</CustomButton>
<CustomButton variant="outline">외곽선 버튼</CustomButton>
<CustomButton variant="danger" size="lg">
  삭제하기
</CustomButton>

이 방식은 디자인 시스템을 만들 때 특히 유용합니다. 버튼, 뱃지, 카드, 인풋처럼 반복적으로 사용되는 컴포넌트는 variant를 명확히 정의해두면 UI의 일관성을 유지하기 쉽습니다.

next/image와 next/font도 함께 고려해야 하는 이유

스타일링 전략을 이야기할 때 CSS만 보는 경우가 많지만, 실제 화면 품질에는 이미지와 폰트도 큰 영향을 줍니다. Next.js에서는 next/image와 next/font를 통해 이미지와 폰트를 최적화할 수 있습니다.

next/image의 <Image /> 컴포넌트는 HTML의 <img>를 확장한 컴포넌트이며, 디바이스에 맞는 크기의 이미지 제공, WebP 같은 최신 포맷 사용, lazy loading, layout shift 방지 등의 기능을 제공합니다.

예시는 다음과 같습니다.

// app/profile/page.tsx

import Image from "next/image";

export default function ProfilePage() {
  return (
    <main className="mx-auto max-w-3xl px-6 py-10">
      <section className="flex items-center gap-5 rounded-2xl border bg-white p-6">
        <Image
          src="/images/profile.png"
          alt="프로필 이미지"
          width={96}
          height={96}
          className="rounded-full object-cover"
        />

        <div>
          <h1 className="text-2xl font-bold text-slate-900">김진성</h1>
          <p className="mt-2 text-slate-600">
            Next.js와 React 기반의 프론트엔드 개발을 학습하고 있습니다.
          </p>
        </div>
      </section>
    </main>
  );
}

폰트는 next/font를 사용할 수 있습니다. Next.js 공식 문서에 따르면 next/font는 폰트를 자동으로 최적화하고 외부 네트워크 요청을 제거하며, 자체 호스팅을 통해 layout shift 없이 웹 폰트를 로드할 수 있도록 돕습니다.

// app/layout.tsx

import type { Metadata } from "next";
import { Noto_Sans_KR } from "next/font/google";
import "./globals.css";

const notoSansKr = Noto_Sans_KR({
  subsets: ["latin"],
  weight: ["400", "500", "700"],
  variable: "--font-noto-sans-kr",
});

export const metadata: Metadata = {
  title: "Next.js Styling Strategy",
  description: "Next.js 스타일링 전략 정리",
};

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="ko" className={notoSansKr.variable}>
      <body className="font-sans">{children}</body>
    </html>
  );
}

Tailwind 설정에서 CSS 변수를 font family로 연결하면 프로젝트 전체에서 사용할 수 있습니다.

/* app/globals.css */

@import "tailwindcss";

@theme {
  --font-sans: var(--font-noto-sans-kr), sans-serif;
}

이렇게 하면 UI 컴포넌트 스타일링뿐 아니라 이미지, 폰트까지 Next.js 방식에 맞게 정리할 수 있습니다.

CSS-in-JS가 왜 문제가 될 수 있는지 직접 실험해보기

CSS-in-JS는 JavaScript 코드 안에서 CSS를 작성하는 방식입니다. 대표적으로 Styled-Components와 Emotion이 있습니다. 이 방식은 컴포넌트의 props에 따라 스타일을 바꾸기 쉽고, 스타일을 컴포넌트와 함께 관리할 수 있다는 장점이 있습니다.

예를 들어 Styled-Components를 사용하면 다음처럼 작성할 수 있습니다.

"use client";

import styled from "styled-components";

const Button = styled.button<{ $variant?: "primary" | "danger" }>`
  border: none;
  border-radius: 12px;
  padding: 12px 20px;
  font-size: 14px;
  font-weight: 600;
  color: white;
  background-color: ${({ $variant }) =>
    $variant === "danger" ? "#dc2626" : "#0f172a"};

  &:hover {
    background-color: ${({ $variant }) =>
      $variant === "danger" ? "#ef4444" : "#334155"};
  }
`;

export function StyledButton() {
  return <Button $variant="primary">Styled Button</Button>;
}

코드만 보면 깔끔합니다. props에 따라 스타일을 분기하기도 쉽습니다. 하지만 Next.js App Router 환경에서는 이 방식이 Tailwind CSS나 CSS Modules보다 고려할 점이 많습니다.

가장 먼저 Styled-Components를 사용하는 컴포넌트는 보통 Client Component로 작성해야 합니다. 위 코드에서도 "use client"가 필요합니다. 스타일 생성과 삽입이 클라이언트 환경과 관련되기 때문입니다. 이 자체가 문제는 아니지만, 단순한 UI 컴포넌트까지 클라이언트 컴포넌트가 되면 클라이언트 번들에 포함되는 코드가 늘어날 수 있습니다.

또한 SSR 환경에서 서버가 렌더링한 HTML에 스타일이 적절한 순서로 포함되지 않으면, 화면이 처음 나타나는 순간 스타일이 적용되지 않은 상태로 보이거나 하이드레이션 이후 스타일이 적용되는 현상이 생길 수 있습니다. 이를 흔히 FOUC, 즉 Flash of Unstyled Content라고 부릅니다.

Next.js 공식 문서에서는 App Router에서 CSS-in-JS를 사용하려면 렌더링 중 CSS 규칙을 수집하는 style registry, useServerInsertedHTML을 통한 스타일 삽입, 앱을 감싸는 Client Component 구성이 필요하다고 설명합니다.

실험 준비: Styled-Components 설치하기

먼저 Next.js 프로젝트에 Styled-Components를 설치합니다.

npm install styled-components
npm install -D @types/styled-components

그리고 next.config.ts 또는 next.config.js에 Styled-Components compiler 옵션을 추가합니다.

// next.config.ts

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  compiler: {
    styledComponents: true,
  },
};

export default nextConfig;

이 설정은 Styled-Components를 Next.js compiler가 처리할 수 있도록 도와줍니다. 하지만 App Router에서 SSR 스타일 삽입까지 제대로 처리하려면 이것만으로 충분하지 않을 수 있습니다. 그래서 style registry 설정이 필요합니다.

실험 1: Registry 없이 Styled-Components 사용하기

먼저 일부러 registry 설정 없이 Styled-Components를 사용해보겠습니다.

// components/styled/hero-card.tsx

"use client";

import styled from "styled-components";

const Card = styled.section`
  max-width: 720px;
  margin: 80px auto;
  padding: 40px;
  border-radius: 24px;
  background: #0f172a;
  color: white;
  box-shadow: 0 20px 50px rgba(15, 23, 42, 0.25);
`;

const Label = styled.p`
  margin: 0 0 12px;
  font-size: 14px;
  font-weight: 700;
  color: #93c5fd;
`;

const Title = styled.h1`
  margin: 0;
  font-size: 40px;
  line-height: 1.2;
`;

const Description = styled.p`
  margin: 20px 0 0;
  color: #cbd5e1;
  line-height: 1.8;
`;

export function HeroCard() {
  return (
    <Card>
      <Label>CSS-in-JS Experiment</Label>
      <Title>Styled-Components SSR 이슈 재현하기</Title>
      <Description>
        이 컴포넌트는 Styled-Components로 작성되었습니다. App Router에서
        SSR 스타일 삽입 설정이 없을 때 초기 스타일 적용 시점을 확인할 수
        있습니다.
      </Description>
    </Card>
  );
}

이제 페이지에서 사용합니다.

// app/styled-test/page.tsx

import { HeroCard } from "@/components/styled/hero-card";

export default function StyledTestPage() {
  return (
    <main>
      <HeroCard />
    </main>
  );
}

이 상태에서 개발 서버를 실행합니다.

npm run dev

그다음 브라우저에서 /styled-test 페이지를 확인합니다.

<http://localhost:3000/styled-test>

개발 환경에서는 문제가 잘 보이지 않을 수 있습니다. 개발 서버는 HMR, 빠른 재컴파일, 개발용 런타임이 섞여 있기 때문입니다. SSR 스타일 문제는 프로덕션 빌드에서 더 확인하기 쉽습니다.

npm run build
npm run start

이후 브라우저에서 페이지를 새로고침하면서 다음 항목을 확인합니다.

확인할 항목

- 페이지 첫 로딩 순간 스타일이 바로 적용되는가?
- 아주 짧은 순간 기본 HTML 스타일이 보였다가 styled-components 스타일이 적용되는가?
- 개발 환경과 프로덕션 환경의 차이가 있는가?
- View Source에서 styled-components 스타일 태그가 초기 HTML에 포함되어 있는가?

이 실험에서 무조건 FOUC가 눈에 띄게 발생한다고 단정하기는 어렵습니다. 환경, Next.js 버전, Styled-Components 버전, 브라우저 상태, 네트워크 속도에 따라 다르게 보일 수 있습니다. 중요한 것은 Styled-Components를 App Router에서 안정적으로 사용하려면 서버 렌더링 중 생성된 스타일을 적절한 시점에 HTML에 삽입하는 구성이 필요하다는 점입니다.

실험 2: Styled-Components Registry 추가하기

이번에는 Next.js 공식 문서에서 안내하는 흐름에 맞춰 Styled-Components registry를 구성해보겠습니다. App Router에서 CSS-in-JS를 사용하려면 서버 렌더링 중 생성된 스타일을 수집하고, useServerInsertedHTML을 사용해 HTML에 삽입하는 과정이 필요합니다.

먼저 registry 파일을 만듭니다.

// lib/styled-components-registry.tsx

"use client";

import React, { useState } from "react";
import { useServerInsertedHTML } from "next/navigation";
import {
  ServerStyleSheet,
  StyleSheetManager,
} from "styled-components";

export function StyledComponentsRegistry({
  children,
}: {
  children: React.ReactNode;
}) {
  const [styledComponentsStyleSheet] = useState(() => new ServerStyleSheet());

  useServerInsertedHTML(() => {
    const styles = styledComponentsStyleSheet.getStyleElement();

    styledComponentsStyleSheet.instance.clearTag();

    return <>{styles}</>;
  });

  if (typeof window !== "undefined") {
    return <>{children}</>;
  }

  return (
    <StyleSheetManager sheet={styledComponentsStyleSheet.instance}>
      {children}
    </StyleSheetManager>
  );
}

그리고 app/layout.tsx에서 전체 앱을 감쌉니다.

// app/layout.tsx

import type { Metadata } from "next";
import { StyledComponentsRegistry } from "@/lib/styled-components-registry";
import "./globals.css";

export const metadata: Metadata = {
  title: "Styled Components SSR Test",
  description: "Next.js App Router Styled-Components SSR 실험",
};

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="ko">
      <body>
        <StyledComponentsRegistry>
          {children}
        </StyledComponentsRegistry>
      </body>
    </html>
  );
}

이제 다시 프로덕션 빌드를 실행합니다.

npm run build
npm run start

그리고 /styled-test 페이지를 다시 확인합니다.

확인할 항목

- 초기 HTML에 styled-components 스타일이 포함되는가?
- 새로고침 시 스타일이 더 안정적으로 적용되는가?
- 스타일이 늦게 적용되는 현상이 줄어드는가?

이 실험을 통해 알 수 있는 점은 CSS-in-JS 자체가 항상 문제가 된다는 것이 아닙니다. 다만 Next.js App Router와 SSR 환경에서 사용하려면 Tailwind CSS나 CSS Modules보다 설정해야 할 부분이 많고, 스타일 삽입 시점을 신경 써야 한다는 점입니다.

실험 3: 같은 UI를 Tailwind CSS로 작성해보기

이번에는 같은 Hero UI를 Tailwind CSS로 작성해보겠습니다.

// app/tailwind-test/page.tsx

export default function TailwindTestPage() {
  return (
    <main className="min-h-screen bg-white px-6">
      <section className="mx-auto mt-20 max-w-3xl rounded-3xl bg-slate-900 p-10 text-white shadow-2xl shadow-slate-300">
        <p className="mb-3 text-sm font-bold text-blue-300">
          Tailwind CSS Experiment
        </p>

        <h1 className="text-4xl font-bold leading-tight">
          Tailwind CSS로 같은 UI 구현하기
        </h1>

        <p className="mt-5 leading-8 text-slate-300">
          이 컴포넌트는 Tailwind CSS로 작성되었습니다. className 기반으로
          스타일을 적용하기 때문에 별도의 Client Component 전환이나
          CSS-in-JS registry 설정이 필요하지 않습니다.
        </p>
      </section>
    </main>
  );
}

이 페이지는 기본적으로 Server Component입니다. "use client"도 없고, 스타일을 수집하기 위한 registry도 없습니다. HTML에는 className이 들어가고, CSS는 빌드된 스타일시트에서 처리됩니다.

즉, 같은 UI를 만들 수 있다면 Tailwind CSS 방식이 Next.js App Router의 서버 중심 구조와 더 단순하게 맞아떨어지는 경우가 많습니다.

실험 결과 정리

Styled-Components 방식은 컴포넌트 안에서 스타일을 함께 관리할 수 있고, props 기반 동적 스타일링이 자연스럽습니다. 하지만 Next.js App Router에서 SSR까지 고려하면 style registry, useServerInsertedHTML, Client Component wrapper 설정이 필요합니다. 또한 Styled-Components를 사용하는 컴포넌트는 클라이언트 컴포넌트가 되는 경우가 많기 때문에, 단순한 스타일링을 위해 클라이언트 번들 범위가 넓어지지 않는지 확인해야 합니다.

Tailwind CSS 방식은 클래스가 길어질 수 있다는 단점이 있지만, Server Component에서 바로 사용할 수 있고 별도의 런타임 스타일 삽입 설정이 필요하지 않습니다. 또한 shadcn/ui와 함께 사용하면 Button, Card, Dialog, Input 같은 UI 컴포넌트를 빠르게 구성하면서도 코드를 직접 수정할 수 있습니다.

CSS Modules는 Tailwind CSS와 CSS-in-JS 사이에 있는 안정적인 선택지로 볼 수 있습니다. CSS 파일을 따로 작성하면서도 클래스 이름 충돌을 막을 수 있고, Server Component와 함께 사용하기도 무난합니다. 다만 variant가 많은 디자인 시스템을 구성할 때는 Tailwind + cva 방식보다 반복이 늘어날 수 있습니다.

CSS-in-JS가 무조건 나쁜 선택은 아니다

여기서 중요한 점은 CSS-in-JS를 “사용하면 안 되는 기술”로 보면 안 된다는 것입니다. Styled-Components와 Emotion은 여전히 장점이 있습니다. 컴포넌트와 스타일을 한 파일에서 관리하기 좋고, props 기반 스타일 분기가 편하며, 기존 프로젝트에서 이미 디자인 시스템이 CSS-in-JS 기반으로 잘 구축되어 있다면 그대로 유지하는 편이 더 합리적일 수 있습니다.

다만 Next.js App Router로 새 프로젝트를 시작한다면 상황이 조금 다릅니다. 서버 컴포넌트를 적극적으로 활용하고, 초기 렌더링 성능과 번들 크기를 관리하고 싶다면 Tailwind CSS, CSS Modules, shadcn/ui 같은 선택지가 더 단순한 구조를 제공할 수 있습니다.

즉, CSS-in-JS의 문제는 “스타일을 JS로 작성한다”는 사실 하나에만 있는 것이 아닙니다. 실제로는 SSR 스타일 추출, 하이드레이션 타이밍, Client Component 경계, 런타임 비용, 설정 복잡성이 함께 얽혀 있습니다. 이 지점을 이해하고 선택하는 것이 중요합니다.

블로그 예제 프로젝트 구조

이 글에서 다룬 실험을 하나의 프로젝트 안에서 구성하면 다음과 같은 구조가 됩니다.

app/
  layout.tsx
  globals.css

  page.tsx

  posts/
    new/
      page.tsx

  styled-test/
    page.tsx

  tailwind-test/
    page.tsx

components/
  styled/
    hero-card.tsx

  ui/
    button.tsx
    card.tsx
    input.tsx
    textarea.tsx
    custom-button.tsx

lib/
  styled-components-registry.tsx
  utils.ts

next.config.ts

posts/new/page.tsx에서는 Tailwind + shadcn/ui 기반 컴포넌트를 확인하고, styled-test/page.tsx에서는 Styled-Components SSR 설정 여부에 따른 차이를 확인합니다. tailwind-test/page.tsx에서는 같은 UI를 Tailwind CSS만으로 구성해 비교할 수 있습니다.

마치며

Next.js에서 스타일링 전략을 선택할 때는 단순히 문법 취향만 기준으로 삼기보다는, App Router의 렌더링 구조와 함께 생각해야 합니다. Tailwind CSS는 className 기반으로 동작하기 때문에 Server Components와 함께 사용하기 편하고, 런타임 스타일 삽입 설정이 필요하지 않습니다. shadcn/ui는 Tailwind 기반 컴포넌트를 프로젝트 안으로 가져와 직접 수정하는 방식이라, 빠르게 UI를 만들면서도 코드 제어권을 유지할 수 있습니다.

반면 Styled-Components나 Emotion 같은 CSS-in-JS는 동적 스타일링에는 장점이 있지만, Next.js App Router에서는 SSR 스타일 삽입과 Client Component 경계를 고려해야 합니다. 특히 Styled-Components를 사용할 때는 compiler.styledComponents 설정뿐 아니라, style registry와 useServerInsertedHTML을 활용한 구성이 필요할 수 있습니다.

따라서 새 Next.js 프로젝트를 시작한다면 기본 스타일링은 Tailwind CSS 또는 CSS Modules로 가져가고, UI 컴포넌트는 shadcn/ui를 활용하는 방식이 관리하기 쉽습니다. CSS-in-JS는 기존 코드베이스, 강한 동적 스타일 요구사항, 이미 구축된 디자인 시스템이 있을 때 선택할 수 있지만, SSR과 App Router 환경에서 필요한 설정을 함께 이해하고 도입하는 것이 좋습니다.

읽어주셔서 감사합니다!

폴더 구조와 아키텍처에 대해서 알아보자!

수달군 — Sun, 17 May 2026 11:09:50 +0900

폴더 구조 & 아키텍처

프론트엔드 프로젝트가 작을 때는 보통 components, hooks, utils, api, pages 정도로 폴더를 나눠도 큰 문제가 없습니다. 하지만 기능이 많아지고, 로그인, 게시글, 댓글, 마이페이지, 관리자 기능, 실시간 알림, 검색, 필터링 같은 도메인이 늘어나면 문제가 생기기 시작합니다.

예를 들어 components 폴더 안에 UserCard, PostCard, CommentItem, AdminTable, LoginForm, ProfileEditModal 같은 파일이 계속 쌓이면, 이 컴포넌트가 어느 기능에 속하는지 알기 어려워집니다. hooks 폴더도 마찬가지입니다. useUser, usePost, useAuth, useModal, useDebounce, useInfiniteScroll 같은 훅이 한 곳에 모이면, 어떤 훅이 특정 기능 전용이고 어떤 훅이 공통 유틸인지 구분하기 어려워집니다.

그래서 규모가 있는 프론트엔드 프로젝트에서는 단순히 기술 종류별로 나누는 방식보다, 기능과 도메인을 기준으로 코드를 나누는 구조가 필요합니다. 이때 자주 사용되는 방식이 FSD, Feature-Sliced Design입니다.

FSD는 프론트엔드 애플리케이션을 layers, slices, segments라는 기준으로 나누는 구조입니다. 공식 문서에서도 FSD의 핵심 구조를 레이어, 슬라이스, 세그먼트로 설명하며, 레이어는 책임과 의존성의 크기에 따라 코드를 나누는 기준이고, 슬라이스는 비즈니스 의미 단위로 코드를 묶는 기준이며, 세그먼트는 기술적 역할에 따라 내부 코드를 나누는 기준입니다.

FSD 아키텍처란?

FSD는 Feature-Sliced Design의 약자로, 프론트엔드 코드를 기능 단위로 분리하기 위한 아키텍처 방법론입니다. 이름 그대로 애플리케이션을 기능 단위로 잘라서 관리하는 방식입니다.

기존 구조에서는 보통 다음과 같이 폴더를 나눕니다.

src/
├── components/
├── hooks/
├── pages/
├── api/
├── utils/
├── stores/
└── types/

이 구조는 초반에는 단순해서 좋습니다. 하지만 프로젝트가 커질수록 components 폴더가 너무 커지고, 특정 기능에서만 쓰이는 코드와 전역에서 재사용되는 코드가 섞이는 문제가 생깁니다.

반면 FSD는 코드를 다음과 같이 나눕니다.

src/
├── app/
├── pages/
├── widgets/
├── features/
├── entities/
└── shared/

각 폴더는 단순한 분류명이 아니라, 역할과 의존성 방향을 가진 계층입니다.

- app은 앱 전체 설정을 담당합니다. 라우터, 전역 Provider, 전역 스타일, QueryClient 설정, Zustand Provider, Theme 설정 등이 들어갑니다.

- pages는 실제 라우트 단위의 페이지를 담당합니다. Next.js App Router를 사용한다면 app/ 라우팅 폴더와 FSD의 pages 레이어를 어떻게 조합할지 팀 규칙을 정해야 합니다. 일반적으로 Next.js의 app 라우트 파일은 최대한 얇게 유지하고, 실제 페이지 UI는 FSD의 pages 또는 views 성격의 모듈로 분리하는 방식이 많이 사용됩니다.

- widgets는 여러 기능과 엔티티를 조합해서 만든 큰 UI 블록입니다. 예를 들어 Header, Sidebar, PostList, UserProfileSection, CommentSection 같은 단위가 여기에 들어갈 수 있습니다.

- features는 사용자의 행동 단위 기능입니다. 예를 들어 login, logout, create-post, edit-profile, add-comment, like-post, search-anime 같은 기능이 들어갑니다.

- entities는 비즈니스 도메인의 핵심 개체입니다. 예를 들어 user, post, comment, anime, review, favorite 같은 것들이 엔티티가 됩니다.

- shared는 특정 비즈니스 도메인에 속하지 않는 공통 코드입니다. 예를 들어 공통 Button, Modal, Input, API 클라이언트, 날짜 포맷 함수, 공통 타입, 공통 상수 등이 들어갑니다.

Layered Architecture 적용

FSD는 기본적으로 Layered Architecture, 즉 계층형 아키텍처의 성격을 가집니다. 계층형 아키텍처의 핵심은 각 계층이 자신의 역할을 명확히 가지고, 의존성 방향을 제한하는 것입니다.

프론트엔드에서 계층형 구조를 적용하지 않으면 이런 문제가 생깁니다.

// 안 좋은 예시
import {LoginForm }from'@/components/LoginForm';
import {useUserStore }from'@/stores/userStore';
import {fetchUser }from'@/api/user';
import {formatDate }from'@/utils/date';

위 코드 자체가 무조건 나쁜 것은 아닙니다. 하지만 프로젝트 전체가 이런 식으로 구성되면 어느 코드가 어느 기능에 속하는지 알기 어렵습니다. 로그인 기능에서만 쓰는 폼이 components에 있고, 유저 API는 api에 있고, 상태는 stores에 있고, 타입은 types에 흩어지게 됩니다. 결국 하나의 기능을 수정하려면 여러 폴더를 왔다 갔다 해야 합니다.

FSD에서는 같은 기능에 관련된 코드를 가까이 둡니다.

src/
├── features/
│   └── login/
│       ├── ui/
│       │   └── LoginForm.tsx
│       ├── model/
│       │   └── useLoginForm.ts
│       ├── api/
│       │   └── loginApi.ts
│       └── index.ts

이렇게 하면 로그인 기능을 수정할 때 features/login 폴더만 보면 됩니다. UI, 상태 로직, API 요청, 외부로 공개할 모듈이 한 기능 안에 모여 있기 때문에 응집도가 높아집니다.

계층형 구조에서 중요한 것은 의존성 방향입니다. 일반적으로 FSD에서는 상위 계층이 하위 계층을 가져다 쓸 수 있지만, 하위 계층이 상위 계층을 가져다 쓰면 안 됩니다.

app
 ↓
pages
 ↓
widgets
 ↓
features
 ↓
entities
 ↓
shared

예를 들어 pages는 widgets, features, entities, shared를 사용할 수 있습니다. 하지만 shared가 features를 import하면 안 됩니다. shared는 가장 낮은 계층이기 때문에 어떤 비즈니스 기능에도 의존하지 않아야 합니다.

모듈 간 의존성 관리

FSD에서 가장 중요한 부분은 모듈 간 의존성 관리입니다. 폴더를 아무리 잘 나눠도 import 규칙이 무너지면 구조는 금방 망가집니다.

예를 들어 다음과 같은 코드는 문제가 될 수 있습니다.

// 좋지 않은 예시
import {UserAvatar }from'@/entities/user/ui/UserAvatar';
import {userApi }from'@/entities/user/api/userApi';

이 코드는 entities/user 내부 구조를 외부에서 직접 알고 접근하고 있습니다. 처음에는 괜찮아 보이지만, 나중에 UserAvatar의 위치를 바꾸거나 userApi를 리팩토링하면 이 파일을 import한 모든 곳이 영향을 받습니다.

FSD에서는 이를 막기 위해 Public API 개념을 사용합니다. Public API는 특정 슬라이스가 외부에 공개할 코드만 index.ts에서 export하는 방식입니다. 공식 문서에서도 Public API를 모듈 간 계약으로 설명하며, 외부 코드는 내부 파일 구조가 아니라 Public API를 통해서만 접근하는 것이 권장됩니다.

예를 들어 entities/user가 있다면 다음처럼 구성할 수 있습니다.

src/
└── entities/
    └── user/
        ├── ui/
        │   └── UserAvatar.tsx
        ├── model/
        │   └── types.ts
        ├── api/
        │   └── userApi.ts
        └── index.ts

// entities/user/index.ts
export {UserAvatar }from'./ui/UserAvatar';
exporttype {User }from'./model/types';

외부에서는 다음처럼 import합니다.

// 좋은 예시
import {UserAvatar,typeUser }from'@/entities/user';

이렇게 하면 entities/user 내부 구조가 바뀌어도 외부 코드는 영향을 덜 받습니다. 예를 들어 UserAvatar.tsx를 ui/avatar/UserAvatar.tsx로 옮기더라도 index.ts만 수정하면 됩니다.

반대로 다음과 같은 import는 피하는 것이 좋습니다.

// 피해야 하는 예시
import {UserAvatar }from'@/entities/user/ui/UserAvatar';

이 방식은 내부 파일 경로에 직접 의존하기 때문에 리팩토링에 약합니다.

FSD의 Layers, Slices, Segments

FSD는 크게 세 가지 기준으로 코드를 나눕니다.

첫 번째는 Layer입니다. Layer는 코드의 책임 범위를 기준으로 나누는 최상위 계층입니다. 예를 들어 app, pages, widgets, features, entities, shared가 여기에 해당합니다.

두 번째는 Slice입니다. Slice는 비즈니스 도메인이나 기능 의미를 기준으로 나누는 단위입니다. 공식 문서에서도 slice는 제품, 비즈니스, 애플리케이션의 의미에 따라 코드를 그룹화하는 단위라고 설명합니다. 예를 들어 user, post, comment, anime, favorite, search 같은 이름이 slice가 될 수 있습니다.

세 번째는 Segment입니다. Segment는 slice 내부에서 기술적 목적에 따라 코드를 나누는 단위입니다. 일반적으로 ui, model, api, lib, config 같은 이름을 사용합니다.

예를 들어 애니메이션 선택 서비스를 만든다고 하면 다음처럼 구성할 수 있습니다.

src/
├── app/
│   ├── providers/
│   ├── styles/
│   └── router/
│
├── pages/
│   ├── home/
│   ├── anime-select/
│   └── result/
│
├── widgets/
│   ├── anime-search-panel/
│   ├── selected-anime-grid/
│   └── result-share-card/
│
├── features/
│   ├── search-anime/
│   ├── select-anime/
│   ├── remove-selected-anime/
│   ├── reorder-anime/
│   └── share-result/
│
├── entities/
│   ├── anime/
│   ├── user/
│   └── result/
│
└── shared/
    ├── ui/
    ├── api/
    ├── lib/
    ├── constants/
    └── types/

이 구조를 보면 각 기능의 위치를 예측하기 쉬워집니다.

애니메이션 검색 API는 features/search-anime/api 또는 검색 결과가 애니메이션 도메인에 강하게 속한다면 entities/anime/api에 둘 수 있습니다.

애니메이션 카드 UI는 entities/anime/ui/AnimeCard.tsx에 둘 수 있습니다.

선택된 애니메이션 9개를 보여주는 큰 영역은 여러 개의 AnimeCard와 선택/삭제 기능을 조합하므로 widgets/selected-anime-grid에 둘 수 있습니다.

선택 버튼을 누르는 기능은 사용자 액션이므로 features/select-anime에 둘 수 있습니다.

최종 결과 페이지는 여러 위젯과 기능을 조합하므로 pages/result에 둘 수 있습니다.

실제 예시: 애니메이션 9선 선택 서비스

예를 들어 사용자가 애니메이션을 검색하고, 9개를 선택하고, 순서를 바꾼 뒤, 결과 이미지를 공유하는 서비스를 만든다고 가정해보겠습니다.

처음에는 다음처럼 단순하게 만들 수 있습니다.

src/
├── components/
│   ├── AnimeCard.tsx
│   ├── SearchInput.tsx
│   ├── SelectedGrid.tsx
│   └── ShareButton.tsx
├── hooks/
│   ├── useAnimeSearch.ts
│   └── useSelectedAnime.ts
├── api/
│   └── animeApi.ts
├── pages/
│   ├── HomePage.tsx
│   └── ResultPage.tsx
└── stores/
    └── animeStore.ts

작은 프로젝트라면 이 구조도 충분합니다. 하지만 검색 필터, 정렬, 로그인, 결과 저장, 공유 이미지 생성, 댓글, 좋아요, 마이페이지까지 추가되면 components, hooks, stores가 금방 복잡해집니다.

FSD 방식으로 리팩토링하면 다음처럼 나눌 수 있습니다.

src/
├── app/
│   ├── providers/
│   │   ├── QueryProvider.tsx
│   │   └── ThemeProvider.tsx
│   └── styles/
│       └── globals.css
│
├── pages/
│   ├── home/
│   │   ├── ui/
│   │   │   └── HomePage.tsx
│   │   └── index.ts
│   ├── anime-select/
│   │   ├── ui/
│   │   │   └── AnimeSelectPage.tsx
│   │   └── index.ts
│   └── result/
│       ├── ui/
│       │   └── ResultPage.tsx
│       └── index.ts
│
├── widgets/
│   ├── anime-search-panel/
│   │   ├── ui/
│   │   │   └── AnimeSearchPanel.tsx
│   │   └── index.ts
│   ├── selected-anime-grid/
│   │   ├── ui/
│   │   │   └── SelectedAnimeGrid.tsx
│   │   └── index.ts
│   └── result-card/
│       ├── ui/
│       │   └── ResultCard.tsx
│       └── index.ts
│
├── features/
│   ├── search-anime/
│   │   ├── api/
│   │   │   └── searchAnime.ts
│   │   ├── model/
│   │   │   └── useAnimeSearch.ts
│   │   ├── ui/
│   │   │   └── SearchAnimeInput.tsx
│   │   └── index.ts
│   ├── select-anime/
│   │   ├── model/
│   │   │   └── selectedAnimeStore.ts
│   │   ├── ui/
│   │   │   └── SelectAnimeButton.tsx
│   │   └── index.ts
│   ├── reorder-anime/
│   │   ├── model/
│   │   │   └── useReorderAnime.ts
│   │   └── index.ts
│   └── share-result/
│       ├── lib/
│       │   └── createShareImage.ts
│       ├── ui/
│       │   └── ShareResultButton.tsx
│       └── index.ts
│
├── entities/
│   └── anime/
│       ├── api/
│       │   └── animeApi.ts
│       ├── model/
│       │   └── types.ts
│       ├── ui/
│       │   └── AnimeCard.tsx
│       └── index.ts
│
└── shared/
    ├── ui/
    │   ├── Button/
    │   ├── Input/
    │   └── Modal/
    ├── api/
    │   └── httpClient.ts
    ├── lib/
    │   ├── cn.ts
    │   └── formatDate.ts
    ├── constants/
    │   └── routes.ts
    └── types/
        └── api.ts

이 구조에서는 각 코드의 위치가 더 명확해집니다.

AnimeCard는 애니메이션이라는 도메인 자체를 표현하는 UI이므로 entities/anime/ui에 둡니다.

SearchAnimeInput은 사용자가 애니메이션을 검색하는 액션과 연결되므로 features/search-anime/ui에 둡니다.

SelectedAnimeGrid는 선택된 애니메이션 목록, 삭제 버튼, 순서 변경 기능 등을 조합하는 큰 UI 블록이므로 widgets/selected-anime-grid에 둡니다.

AnimeSelectPage는 검색 패널과 선택 그리드를 조합하는 페이지 단위이므로 pages/anime-select에 둡니다.

예시 코드

예를 들어 entities/anime는 애니메이션이라는 도메인 자체를 표현합니다.

// entities/anime/model/types.ts
exportinterfaceAnime {
  id:number;
  title:string;
  posterUrl:string;
  releaseYear?:number;
}

// entities/anime/ui/AnimeCard.tsx
importtype {Anime }from'../model/types';

interfaceAnimeCardProps {
  anime:Anime;
  rightSlot?:React.ReactNode;
}

exportfunctionAnimeCard({ anime, rightSlot }:AnimeCardProps) {
return (
<articleclassName="rounded-xl border p-3">
<img
src={anime.posterUrl}
alt={anime.title}
className="aspect-[3/4] w-full rounded-lg object-cover"
/>

<divclassName="mt-3 flex items-center justify-between gap-2">
<div>
<h3className="font-semibold">{anime.title}</h3>
          {anime.releaseYear&& (
<pclassName="text-sm text-gray-500">{anime.releaseYear}</p>
          )}
</div>

        {rightSlot}
</div>
</article>
  );
}

// entities/anime/index.ts
export {AnimeCard }from'./ui/AnimeCard';
exporttype {Anime }from'./model/types';

이제 외부에서는 내부 경로가 아니라 Public API를 통해 가져옵니다.

import {AnimeCard,typeAnime }from'@/entities/anime';

다음은 애니메이션 선택 기능입니다.

// features/select-anime/model/selectedAnimeStore.ts
import {create }from'zustand';
importtype {Anime }from'@/entities/anime';

interfaceSelectedAnimeState {
  selectedAnimeList:Anime[];
  selectAnime: (anime:Anime) =>void;
  removeAnime: (animeId:number) =>void;
}

exportconstuseSelectedAnimeStore=create<SelectedAnimeState>((set) => ({
  selectedAnimeList: [],

  selectAnime: (anime) =>
set((state) => {
constalreadySelected=state.selectedAnimeList.some(
        (item) =>item.id===anime.id,
      );

if (alreadySelected||state.selectedAnimeList.length>=9) {
returnstate;
      }

return {
        selectedAnimeList: [...state.selectedAnimeList,anime],
      };
    }),

  removeAnime: (animeId) =>
set((state) => ({
      selectedAnimeList:state.selectedAnimeList.filter(
        (anime) =>anime.id!==animeId,
      ),
    })),
}));

// features/select-anime/ui/SelectAnimeButton.tsx
importtype {Anime }from'@/entities/anime';
import {useSelectedAnimeStore }from'../model/selectedAnimeStore';

interfaceSelectAnimeButtonProps {
  anime:Anime;
}

exportfunctionSelectAnimeButton({ anime }:SelectAnimeButtonProps) {
constselectAnime=useSelectedAnimeStore((state) =>state.selectAnime);

return (
<button
type="button"
onClick={() =>selectAnime(anime)}
className="rounded-md bg-black px-3 py-2 text-sm text-white"
>
      선택
</button>
  );
}

// features/select-anime/index.ts
export {SelectAnimeButton }from'./ui/SelectAnimeButton';
export {useSelectedAnimeStore }from'./model/selectedAnimeStore';

그리고 위젯에서는 엔티티와 기능을 조합합니다.

// widgets/anime-search-panel/ui/AnimeSearchPanel.tsx
import {AnimeCard }from'@/entities/anime';
import {SelectAnimeButton }from'@/features/select-anime';
import {useAnimeSearch }from'@/features/search-anime';

exportfunctionAnimeSearchPanel() {
const { keyword, setKeyword, animeList, isLoading }=useAnimeSearch();

return (
<section>
<input
value={keyword}
onChange={(event) =>setKeyword(event.target.value)}
placeholder="애니메이션 검색"
className="w-full rounded-lg border px-4 py-3"
/>

      {isLoading&&<p>검색 중입니다.</p>}

<divclassName="mt-4 grid grid-cols-2 gap-4 md:grid-cols-4">
        {animeList.map((anime) => (
<AnimeCard
key={anime.id}
anime={anime}
rightSlot={<SelectAnimeButtonanime={anime}/>}
/>
        ))}
</div>
</section>
  );
}

이 구조에서 AnimeSearchPanel은 entities/anime의 AnimeCard와 features/select-anime의 SelectAnimeButton을 조합합니다. 즉, 위젯은 여러 하위 계층을 조합하는 역할을 합니다.

실제 프로젝트 폴더 구조 리팩토링 방식

기존 프로젝트를 FSD로 리팩토링할 때는 한 번에 모든 폴더를 갈아엎으려고 하면 오히려 위험합니다. 가장 좋은 방식은 기능 하나씩 이동하는 것입니다.

예를 들어 기존 구조가 다음과 같다고 가정해보겠습니다.

src/
├── components/
│   ├── AnimeCard.tsx
│   ├── SearchInput.tsx
│   ├── SelectedGrid.tsx
│   └── ShareButton.tsx
├── hooks/
│   ├── useAnimeSearch.ts
│   └── useSelectedAnime.ts
├── api/
│   └── animeApi.ts
├── stores/
│   └── selectedAnimeStore.ts
└── pages/
    ├── HomePage.tsx
    └── ResultPage.tsx

이때 먼저 도메인 중심으로 코드를 분류합니다.

AnimeCard, animeApi, Anime 타입은 애니메이션 도메인에 해당하므로 entities/anime로 이동합니다.

selectedAnimeStore, SelectButton, useSelectedAnime는 사용자가 애니메이션을 선택하는 기능이므로 features/select-anime로 이동합니다.

SearchInput, useAnimeSearch는 검색 기능이므로 features/search-anime로 이동합니다.

SelectedGrid는 여러 선택된 애니메이션을 보여주는 UI 블록이므로 widgets/selected-anime-grid로 이동합니다.

ShareButton과 공유 이미지 생성 로직은 결과 공유 기능이므로 features/share-result로 이동합니다.

리팩토링 후에는 다음처럼 정리됩니다.

src/
├── features/
│   ├── search-anime/
│   ├── select-anime/
│   └── share-result/
├── entities/
│   └── anime/
├── widgets/
│   └── selected-anime-grid/
├── pages/
│   ├── home/
│   └── result/
└── shared/

중요한 것은 파일 이동 후 import 경로를 정리하는 것입니다. 특히 외부에서 내부 파일을 직접 import하지 않도록 index.ts를 만들어 Public API를 구성해야 합니다.

// features/search-anime/index.ts
export {SearchAnimeInput }from'./ui/SearchAnimeInput';
export {useAnimeSearch }from'./model/useAnimeSearch';

// widgets/selected-anime-grid/index.ts
export {SelectedAnimeGrid }from'./ui/SelectedAnimeGrid';

// pages/anime-select/ui/AnimeSelectPage.tsx
import {AnimeSearchPanel }from'@/widgets/anime-search-panel';
import {SelectedAnimeGrid }from'@/widgets/selected-anime-grid';

exportfunctionAnimeSelectPage() {
return (
<main>
<AnimeSearchPanel/>
<SelectedAnimeGrid/>
</main>
  );
}

Next.js App Router와 함께 사용할 때

Next.js App Router를 사용하면 이미 src/app 폴더가 라우팅 역할을 합니다. 이때 FSD의 app 레이어와 Next.js의 app 라우터가 이름이 겹칠 수 있습니다.

이 경우 보통 두 가지 방식 중 하나를 선택합니다.

첫 번째 방식은 Next.js의 app 폴더를 라우팅 전용으로 두고, 실제 화면 구현은 FSD 구조 안으로 분리하는 방식입니다.

src/
├── app/
│   ├── page.tsx
│   ├── result/
│   │   └── page.tsx
│   └── layout.tsx
├── pages/
│   ├── home/
│   └── result/
├── widgets/
├── features/
├── entities/
└── shared/

// src/app/page.tsx
import {HomePage }from'@/pages/home';

exportdefaultfunctionPage() {
return<HomePage/>;
}

// src/app/result/page.tsx
import {ResultPage }from'@/pages/result';

exportdefaultfunctionPage() {
return<ResultPage/>;
}

이 방식의 장점은 Next.js 라우팅 규칙과 FSD 화면 구조를 분리할 수 있다는 점입니다. src/app은 라우팅 진입점으로만 사용하고,

실제 UI와 비즈니스 로직은 pages, widgets, features, entities로 분리합니다.

두 번째 방식은 FSD의 pages 레이어를 사용하지 않고, Next.js의 app 폴더 안에서 페이지를 관리하는 방식입니다.

src/
├── app/
│   ├── page.tsx
│   ├── result/
│   │   └── page.tsx
│   └── layout.tsx
├── widgets/
├── features/
├── entities/
└── shared/

이 방식은 구조가 더 단순합니다. 다만 페이지 단위 UI가 커질 경우 app 폴더가 복잡해질 수 있으므로, app/page.tsx는 얇게 유지하는 것이 좋습니다.

개인 프로젝트나 중간 규모 프로젝트에서는 첫 번째 방식이 더 관리하기 쉽습니다. 특히 포트폴리오나 팀 프로젝트에서는 app 라우팅 파일이 얇고, 실제 구현이 FSD 구조에 들어가 있으면 아키텍처 설명도 훨씬 명확해집니다.

Shared 폴더를 조심해서 사용해야 하는 이유

FSD를 적용할 때 가장 흔한 실수는 shared를 새로운 utils, components 쓰레기통처럼 사용하는 것입니다.

예를 들어 다음처럼 모든 것을 shared에 넣으면 FSD를 적용한 의미가 줄어듭니다.

shared/
├── components/
│   ├── AnimeCard.tsx
│   ├── UserProfile.tsx
│   ├── CommentItem.tsx
│   └── PostList.tsx
├── hooks/
├── api/
└── utils/

shared에는 정말로 도메인과 무관한 코드만 들어가야 합니다.

예를 들어 Button, Input, Modal, Dropdown, cn, formatDate, httpClient는 shared에 둘 수 있습니다.

하지만 AnimeCard, UserProfile, PostList, CommentItem은 도메인 의미가 있으므로 shared에 두기보다는 각각 entities/anime, entities/user, entities/post, entities/comment로 보내는 것이 좋습니다.

shared/ui/Button
shared/ui/Input
shared/lib/cn
shared/lib/formatDate
shared/api/httpClient

entities/anime/ui/AnimeCard
entities/user/ui/UserProfile
entities/comment/ui/CommentItem

이 기준을 지키면 공통 코드와 도메인 코드가 섞이지 않습니다.

FSD를 적용할 때의 판단 기준

컴포넌트를 어디에 둬야 할지 헷갈릴 때는 다음 기준으로 판단하면 됩니다.

특정 도메인 자체를 표현한다면 entities에 둡니다. 예를 들어 UserAvatar, AnimeCard, PostItem, CommentItem은 엔티티에 가깝습니다.

사용자의 행동을 처리한다면 features에 둡니다. 예를 들어 LoginForm, LikeButton, FollowButton, SearchAnimeInput, ShareResultButton은 기능에 가깝습니다.

여러 엔티티와 기능을 조합한 큰 UI 블록이라면 widgets에 둡니다. 예를 들어 Header, Sidebar, AnimeSearchPanel, SelectedAnimeGrid, CommentSection은 위젯에 가깝습니다.

라우트 단위 화면이라면 pages에 둡니다. 예를 들어 HomePage, AnimeSelectPage, ResultPage, MyPage는 페이지에 가깝습니다.

비즈니스와 무관하게 어디서든 재사용된다면 shared에 둡니다. 예를 들어 Button, Input, Modal, useDebounce, cn, formatDate, httpClient는 shared에 둘 수 있습니다.

FSD의 장점

FSD의 가장 큰 장점은 코드 위치를 예측하기 쉬워진다는 점입니다. 기능이 많아져도 “검색 기능은 features/search-anime에 있겠구나”, “애니메이션 타입과 카드는 entities/anime에 있겠구나”, “선택된 애니메이션 목록 UI는 widgets/selected-anime-grid에 있겠구나”라고 예상할 수 있습니다.

두 번째 장점은 기능 단위 리팩토링이 쉬워진다는 점입니다. 예를 들어 검색 기능을 React Query 기반에서 Server Action 기반으로 바꾸고 싶다면 features/search-anime 중심으로 수정하면 됩니다.

세 번째 장점은 의존성 방향이 명확해진다는 점입니다. features가 widgets를 가져다 쓰거나, entities가 features를 가져다 쓰는 식의 역방향 의존성을 막으면 순환 참조와 스파게티 구조를 줄일 수 있습니다.

네 번째 장점은 팀원 간 작업 충돌이 줄어든다는 점입니다. 기능별로 폴더가 분리되어 있으므로 검색 기능을 담당하는 사람, 결과 공유 기능을 담당하는 사람, 마이페이지를 담당하는 사람이 서로 다른 영역에서 작업할 수 있습니다.

다섯 번째 장점은 포트폴리오에서 아키텍처 설명이 쉬워진다는 점입니다. 단순히 “폴더를 나눴다”가 아니라, “FSD 기반으로 레이어를 분리하고, Public API를 통해 모듈 간 의존성을 제한했으며, 도메인 단위로 응집도를 높였다”고 설명할 수 있습니다.

FSD의 단점과 주의할 점

FSD는 무조건 좋은 구조는 아닙니다. 작은 프로젝트에서 처음부터 너무 엄격하게 적용하면 오히려 개발 속도가 느려질 수 있습니다.

예를 들어 페이지가 2~3개뿐이고 기능도 단순한 프로젝트에서 features, entities, widgets, shared를 모두 세세하게 나누면 파일을 만들 때마다 고민이 많아집니다. 이 경우에는 처음에는 단순한 구조로 시작하고, 기능이 복잡해지는 시점에 FSD로 점진적으로 옮기는 것이 좋습니다.

또한 FSD를 적용할 때 모든 컴포넌트를 억지로 features나 entities에 넣으려고 하면 안 됩니다. 중요한 것은 폴더 이름이 아니라 책임 분리입니다. 같은 기능을 수정할 때 관련 코드가 가까이 있고, 외부에서는 정해진 API를 통해서만 접근할 수 있으며, 의존성 방향이 깨지지 않는 것이 핵심입니다.

정리

FSD와 Layered Architecture는 프론트엔드 프로젝트가 커질수록 코드가 뒤엉키는 문제를 해결하기 위한 구조입니다. 핵심은 components, hooks, api처럼 기술 종류별로만 나누는 것이 아니라, user, anime, search, select, share처럼 도메인과 기능 중심으로 코드를 배치하는 것입니다.

실제 프로젝트에서는 app, pages, widgets, features, entities, shared 계층을 두고, 상위 계층이 하위 계층을 조합하는 방식으로 설계하는 것이 좋습니다. 또한 각 slice는 index.ts를 통해 Public API를 제공하고, 외부에서는 내부 파일 구조에 직접 접근하지 않도록 관리해야 합니다.

Next.js에서의 인증 전략과 쿠키 vs 토큰

수달군 — Sun, 10 May 2026 14:51:55 +0900

Next.js에서 인증이 중요한 이유

Next.js에서 인증이 조금 까다롭게 느껴지는 이유는 단순히 “로그인 여부를 확인하는 코드”만 작성하면 끝나는 구조가 아니기 때문입니다.

Next.js는 Server Components, Client Components, Route Handlers, Server Actions, Proxy 등 여러 실행 지점을 가지고 있고, 각각의 코드가 실행되는 위치가 다릅니다. 어떤 코드는 서버에서만 실행되고, 어떤 코드는 브라우저에서 실행되며, 어떤 코드는 사용자의 요청이 페이지에 도달하기 전에 먼저 실행됩니다.

그래서 Next.js에서 인증을 설계할 때는 “로그인 상태를 어디에 저장할 것인가”, “서버 컴포넌트에서 세션을 어떻게 읽을 것인가”, “클라이언트 컴포넌트에서는 사용자 정보를 어떻게 사용할 것인가”, “보호된 페이지 접근은 어디서 막을 것인가”를 함께 고민해야 합니다. Next.js 공식 문서에서도 인증을 단순 로그인 구현이 아니라 인증, 세션 관리, 인가라는 흐름으로 나누어 설명합니다.

일반적인 React SPA에서는 로그인 후 accessToken을 localStorage나 메모리에 저장하고, API 요청 시 Authorization 헤더에 붙이는 방식이 자주 사용됩니다.

하지만 Next.js에서는 서버에서 먼저 렌더링되는 영역이 많기 때문에 브라우저 저장소에만 의존하면 서버 컴포넌트에서 인증 정보를 바로 알기 어렵습니다. 예를 들어 localStorage는 브라우저에서만 접근할 수 있으므로 Server Component, Route Handler, Server Action에서는 직접 사용할 수 없습니다.

이 때문에 Next.js에서는 쿠키 기반 세션 관리가 자주 사용됩니다. 쿠키는 브라우저가 요청을 보낼 때 자동으로 함께 전송되기 때문에 서버에서도 인증 상태를 확인하기 쉽습니다. 특히 httpOnly 쿠키를 사용하면 클라이언트 JavaScript에서 쿠키 값을 직접 읽을 수 없어서 XSS 공격으로 토큰이 탈취될 가능성을 줄일 수 있습니다.

쿠키 기반 인증과 JWT 토큰 기반 인증

쿠키 기반 인증은 사용자의 인증 상태를 쿠키에 저장하고, 이후 요청마다 브라우저가 쿠키를 자동으로 서버에 전달하는 방식입니다. 보통 서버는 쿠키에 담긴 세션 ID나 세션 토큰을 확인한 뒤, 해당 사용자가 로그인한 사용자인지 판단합니다. 이때 쿠키에 httpOnly, Secure, SameSite 같은 옵션을 설정하는 것이 중요합니다.

httpOnly는 브라우저의 JavaScript에서 쿠키에 접근하지 못하게 하는 옵션입니다. 이 옵션을 사용하면 document.cookie로 쿠키 값을 읽을 수 없기 때문에, XSS 취약점이 발생하더라도 토큰 자체가 직접 탈취될 가능성을 낮출 수 있습니다. Secure는 HTTPS 환경에서만 쿠키가 전송되도록 제한하는 옵션이고, SameSite는 다른 사이트에서 발생한 요청에 쿠키를 함께 보낼지 제어하는 옵션입니다. SameSite=Lax 또는 Strict를 사용하면 CSRF 공격 가능성을 줄이는 데 도움이 됩니다.

JWT 기반 인증은 로그인 성공 시 서버가 JWT를 발급하고, 클라이언트가 이 토큰을 보관한 뒤 API 요청마다 Authorization 헤더에 넣어 보내는 방식입니다. JWT는 자체적으로 사용자 식별 정보와 만료 시간 등을 포함할 수 있기 때문에 서버가 매 요청마다 세션 저장소를 조회하지 않아도 되는 장점이 있습니다. 다만 JWT를 어디에 저장하느냐가 중요합니다.

JWT를 localStorage에 저장하면 구현은 간단하지만 XSS에 취약해질 수 있습니다. 공격자가 클라이언트 JavaScript 실행 권한을 얻으면 localStorage에 저장된 토큰을 읽어갈 수 있기 때문입니다. 반대로 JWT를 httpOnly 쿠키에 저장하면 JavaScript에서 직접 읽을 수 없기 때문에 XSS로 인한 토큰 탈취 위험은 줄어듭니다. 다만 쿠키는 요청에 자동 포함되기 때문에 CSRF 방어를 함께 고려해야 합니다.

즉, JWT 자체가 위험하다기보다는 JWT를 저장하고 전송하는 방식에 따라 보안 특성이 달라집니다. localStorage 기반 JWT는 클라이언트 중심 SPA에서 구현하기 쉽지만 XSS에 더 민감하고, httpOnly 쿠키 기반 JWT 또는 세션 토큰 방식은 서버 중심 렌더링과 잘 맞지만 CSRF 방어와 쿠키 설정을 신경 써야 합니다.

Next.js에서 쿠키 기반 인증이 자주 권장되는 이유

Next.js에서는 서버에서 인증 정보를 읽어야 하는 상황이 많습니다. Server Component에서 사용자 정보를 기반으로 다른 UI를 보여줘야 할 수 있고, Server Action에서 사용자의 권한을 확인해야 할 수도 있으며, Route Handler에서 요청을 처리하기 전에 세션을 검증해야 할 수도 있습니다.

이때 쿠키 기반 인증은 Next.js의 구조와 잘 맞습니다. 브라우저가 요청을 보낼 때 쿠키를 자동으로 포함하므로 서버는 요청 객체에서 쿠키를 읽어 현재 사용자를 확인할 수 있습니다. 반면 localStorage에 저장된 토큰은 서버에서 직접 읽을 수 없기 때문에, 서버 렌더링 단계에서는 인증 상태를 알기 어렵습니다.

또한 Next.js App Router에서는 서버 컴포넌트를 통해 데이터 페칭과 렌더링을 서버에서 처리하는 경우가 많습니다. 이 구조에서는 인증 정보도 서버에서 안전하게 확인하는 편이 자연스럽습니다. 예를 들어 /dashboard 페이지에 접근했을 때 서버에서 세션을 확인하고, 로그인하지 않은 사용자는 로그인 페이지로 리다이렉트하는 흐름을 만들 수 있습니다.

다만 쿠키 기반 인증이 항상 정답이라는 의미는 아닙니다. 서비스 구조, 백엔드 API 구조, 모바일 앱 연동 여부, 서브도메인 구성, 외부 API 호출 방식에 따라 JWT 헤더 기반 인증이 더 편한 경우도 있습니다. 중요한 것은 Next.js에서는 서버와 클라이언트가 함께 동작하므로, 클라이언트 저장소에만 인증 상태를 두는 방식은 제한이 있다는 점입니다.

구분 쿠키 기반 인증 JWT 토큰 기반 인증

저장 위치	주로 httpOnly 쿠키	localStorage, sessionStorage, memory, cookie 등
서버 컴포넌트 접근	요청 쿠키를 통해 접근하기 쉬움	localStorage 저장 시 서버에서 직접 접근 어려움
XSS 대응	httpOnly 설정 시 토큰 직접 탈취 위험 감소	localStorage 저장 시 XSS에 취약
CSRF 대응	쿠키 자동 전송 때문에 SameSite, CSRF 토큰 고려 필요	Authorization 헤더 방식이면 CSRF 위험이 상대적으로 낮음
구현 난이도	쿠키 옵션과 서버 세션 처리 필요	API 요청 헤더 처리 중심으로 구현 가능
Next.js와의 궁합	Server Component, Route Handler, Server Action과 잘 맞음	클라이언트 중심 구조에서는 편하지만 서버 렌더링과 연결 시 추가 설계 필요
적합한 경우	SSR, 서버 중심 인증, 보안 중심 웹 서비스	SPA, 외부 API 연동, 모바일 앱과 토큰 공유가 필요한 경우

Better Auth와 Auth.js v5

Better Auth와 Auth.js는 둘 다 웹 서비스에서 로그인, 회원가입, 세션 관리, 소셜 로그인, 권한 처리 등을 쉽게 구현하기 위한 인증 라이브러리입니다. 다만 지향점과 사용감이 조금 다릅니다.

Better Auth

Better Auth는 TypeScript 기반의 인증·인가 프레임워크입니다. 공식 문서에서는 특정 프레임워크에 묶이지 않는 “framework-agnostic” 인증 프레임워크라고 설명합니다. Next.js뿐 아니라 여러 JavaScript/TypeScript 환경에서 사용할 수 있고, 이메일/비밀번호 로그인, 세션 관리, 2FA, 패스키, 멀티 세션, 멀티 테넌시 같은 기능을 플러그인 중심으로 확장할 수 있습니다.

쉽게 말하면 Better Auth는 “인증 기능을 내 애플리케이션 안에 직접 구성하는 도구”에 가깝습니다. Clerk, Auth0처럼 외부 인증 서비스를 붙이는 느낌보다는, 내 프로젝트 안에서 인증 서버 로직과 클라이언트 사용 방식을 함께 구성하는 방식입니다.

Better Auth의 강점은 기능 확장성입니다. 예를 들어 일반 로그인만 필요한 서비스라면 이메일/비밀번호 로그인과 세션 관리만 사용할 수 있고, 보안 요구사항이 커지면 2FA, 패스키, 조직 관리 같은 기능을 플러그인으로 추가할 수 있습니다. Better Auth의 2FA 플러그인은 OTP, TOTP, 백업 코드, 신뢰할 수 있는 기기 관리 등을 지원하고, 패스키 플러그인은 WebAuthn/FIDO2 기반의 비밀번호 없는 로그인을 지원합니다.

또 하나의 특징은 타입 안정성입니다. TypeScript 프로젝트에서 인증 관련 API, 세션, 사용자 정보 등을 타입 기반으로 다룰 수 있도록 설계되어 있습니다. 그래서 인증 로직이 복잡해질수록 “어떤 데이터가 오고 가는지”를 코드 레벨에서 확인하기 좋습니다.

Next.js 프로젝트에서는 Better Auth를 사용해 서버 쪽 인증 설정을 만들고, 클라이언트에서는 로그인, 로그아웃, 세션 조회 같은 기능을 호출하는 구조로 사용할 수 있습니다. 인증 정보를 쿠키 기반 세션으로 관리하면 Server Component, Route Handler, Server Action에서도 현재 로그인 사용자를 확인하기 좋습니다.

Auth.js

Auth.js는 예전 이름으로 NextAuth.js라고 많이 알려진 인증 라이브러리입니다. Next.js에서 소셜 로그인이나 세션 관리를 구현할 때 오래 사용되어 온 선택지입니다. 현재 Auth.js 문서에서는 표준 Web API 기반의 런타임 독립 인증 라이브러리이며, Next.js, SvelteKit, Express, Qwik 등 여러 프레임워크와 통합할 수 있다고 설명합니다.

Next.js에서 사용할 때는 여전히 next-auth 패키지를 사용하며, v5부터는 auth.ts를 중심으로 설정하는 구조가 많이 사용됩니다. auth() 함수를 통해 Server Component, Route Handler, Proxy/Middleware 등에서 세션을 확인할 수 있습니다. Auth.js의 Next.js 문서에서는 Route Handler를 통해 OAuth, Email Provider, /api/auth/session 같은 인증 엔드포인트를 노출하는 구조를 설명합니다.

Auth.js의 가장 큰 장점은 소셜 로그인 Provider 생태계입니다. Google, GitHub, Discord, Apple 같은 OAuth Provider를 비교적 쉽게 붙일 수 있습니다. “빠르게 소셜 로그인을 붙이고, 세션을 관리하고, 보호된 페이지를 만들고 싶다”는 목적이라면 Auth.js가 여전히 좋은 선택지입니다.

또한 레퍼런스가 많습니다. NextAuth.js라는 이름으로 오랫동안 사용되어 왔기 때문에 블로그 글, 예제 코드, 오류 해결 사례가 많이 쌓여 있습니다. 팀원이 NextAuth 경험이 있다면 도입 장벽도 낮은 편입니다.

다만 Auth.js v5는 기존 NextAuth v4와 구조가 일부 달라졌습니다. 공식 마이그레이션 문서에서도 v5를 next-auth 패키지의 주요 재작성 버전으로 설명합니다. 따라서 기존 v4 자료를 그대로 따라 하면 맞지 않는 부분이 있을 수 있습니다.

둘의 차이를 간단히 보자면

구분	Better Auth	Auth.js
성격	TypeScript 중심 인증·인가 프레임워크	NextAuth 계열 인증 라이브러리
강점	타입 안정성, 플러그인 확장, 2FA/패스키/조직 기능	소셜 로그인 Provider, Next.js 레퍼런스, 익숙한 생태계
사용감	인증 시스템을 직접 구성하는 느낌	OAuth 로그인과 세션 관리를 빠르게 붙이는 느낌
적합한 경우	인증 요구사항이 복잡하거나 확장 가능성이 큰 서비스	소셜 로그인 중심의 일반적인 Next.js 서비스
주의점	상대적으로 학습할 개념이 있음	v4/v5 차이를 확인해야 함

정리하면, Auth.js는 Next.js에서 검증된 소셜 로그인/세션 관리 도구에 가깝고, Better Auth는 타입 안정성과 플러그인 확장성을 중심으로 인증 기능을 더 세밀하게 구성하는 도구에 가깝습니다.

개인 프로젝트나 블로그, 일반적인 서비스에서 Google/GitHub 로그인 정도가 필요하다면 Auth.js가 접근하기 쉽습니다. 반대로 회원가입, 이메일 인증, 2FA, 패스키, 조직/권한 관리처럼 인증 요구사항이 점점 커질 가능성이 있다면 Better Auth를 검토해볼 만합니다.

proxy.ts에서 인증 기반 접근 제어 구현

Next.js 16부터는 기존 middleware.ts라는 이름이 proxy.ts로 변경되었습니다. 기능 자체는 요청이 완료되기 전에 서버에서 코드를 실행하고, 요청을 리다이렉트하거나 rewrite하거나 헤더를 수정할 수 있다는 점에서 기존 Middleware와 같은 역할을 합니다.

공식 문서에서도 Next.js 16부터 Middleware가 Proxy로 이름이 변경되었고, 기능은 동일하다고 설명합니다.

proxy.ts는 인증 기반 접근 제어를 구현할 때 유용합니다. 예를 들어 로그인하지 않은 사용자가 /dashboard, /mypage, /admin 같은 보호된 경로에 접근하면 로그인 페이지로 이동시키고, 이미 로그인한 사용자가 /login에 접근하면 메인 페이지로 이동시키는 흐름을 만들 수 있습니다.

예시는 다음과 같습니다.

// src/proxy.ts
import {NextRequest,NextResponse }from'next/server';

constprotectedRoutes= ['/dashboard','/mypage','/admin'];
constauthRoutes= ['/login','/signup'];

exportfunctionproxy(request:NextRequest) {
const { pathname }=request.nextUrl;

constsessionToken=request.cookies.get('session')?.value;

constisLoggedIn=Boolean(sessionToken);
constisProtectedRoute=protectedRoutes.some((route) =>
pathname.startsWith(route)
  );
constisAuthRoute=authRoutes.some((route) =>
pathname.startsWith(route)
  );

if (!isLoggedIn&&isProtectedRoute) {
constloginUrl=newURL('/login',request.url);
loginUrl.searchParams.set('redirect',pathname);

returnNextResponse.redirect(loginUrl);
  }

if (isLoggedIn&&isAuthRoute) {
returnNextResponse.redirect(newURL('/',request.url));
  }

returnNextResponse.next();
}

exportconstconfig= {
  matcher: [
'/dashboard/:path*',
'/mypage/:path*',
'/admin/:path*',
'/login',
'/signup',
  ],
};

이 코드는 요청이 실제 페이지에 도달하기 전에 쿠키에 세션이 있는지 확인합니다. 세션이 없는데 보호된 페이지에 접근하려고 하면 /login으로 보냅니다. 반대로 이미 로그인한 사용자가 로그인 페이지에 접근하면 홈으로 이동시킵니다.

다만 proxy.ts만으로 모든 보안 처리가 끝난다고 보면 안 됩니다. Proxy는 페이지 접근을 빠르게 제어하는 데 유용하지만, 실제 데이터 접근 권한은 Server Component, Route Handler, Server Action, 백엔드 API에서도 다시 확인해야 합니다. 사용자가 UI 경로 접근을 막았다고 해서 서버 액션이나 API 요청까지 자동으로 보호되는 것은 아니기 때문입니다.

따라서 실무에서는 보통 다음과 같이 나누어 처리합니다. proxy.ts에서는 페이지 접근을 1차로 제어하고, Server Component에서는 현재 사용자 정보를 읽어 화면을 분기하며, Route Handler나 Server Action에서는 실제 데이터 변경 전에 세션과 권한을 다시 검증합니다. 관리자 페이지라면 단순히 로그인 여부만 보는 것이 아니라 사용자의 role까지 확인해야 합니다.

예를 들어 관리자 페이지는 다음처럼 role 기반으로 한 번 더 막을 수 있습니다.

// 개념 예시
if (pathname.startsWith('/admin')) {
constrole=request.cookies.get('role')?.value;

if (role!=='admin') {
returnNextResponse.redirect(newURL('/forbidden',request.url));
  }
}

다만 실제 서비스에서는 role 값을 그대로 클라이언트가 조작 가능한 쿠키에 저장하는 방식은 피하는 것이 좋습니다.

role은 세션 토큰을 통해 서버에서 검증하거나, 서명된 토큰 또는 세션 저장소를 통해 확인하는 방식이 더 안전합니다.

정리

Next.js에서 인증은 서버와 클라이언트 경계를 함께 고려해야 하기 때문에 일반적인 React SPA보다 설계할 요소가 많습니다.

특히 Server Components, Route Handlers, Server Actions, Proxy처럼 서버에서 실행되는 지점이 많기 때문에, 인증 정보를 브라우저 저장소에만 두는 방식은 한계가 있습니다.

쿠키 기반 인증은 요청과 함께 서버로 자연스럽게 전달되기 때문에 Next.js 구조와 잘 맞습니다. httpOnly, Secure, SameSite 설정을 적절히 사용하면 XSS와 CSRF 위험을 줄이는 데 도움이 됩니다. 반면 JWT 기반 인증은 API 중심 구조나 모바일 앱 연동에서는 편리할 수 있지만, 토큰 저장 위치에 따라 보안 특성이 크게 달라집니다.

라이브러리 선택에서는 Better Auth와 Auth.js v5를 함께 비교해볼 수 있습니다. Better Auth는 타입 세이프한 구조와 플러그인 기반 확장성이 강점이고, Auth.js v5는 Next.js 생태계에서 이어져 온 Provider 중심 인증 경험과 레퍼런스가 강점입니다.

마지막으로 proxy.ts는 인증 기반 접근 제어의 첫 관문으로 사용할 수 있습니다. 하지만 실제 보안은 Proxy 하나에만 맡기지 않고, 서버 컴포넌트, 서버 액션, API 계층에서도 세션과 권한을 반복적으로 확인하는 구조로 설계하는 것이 안정적입니다.

에러 핸들링 & 안정성 - 프론트엔드 에러 처리

수달군 — Mon, 4 May 2026 11:16:12 +0900

프론트엔드에서도 에러처리가 필요하다

서비스를 운영하기 위해 백엔드의 지원은 필수적이지만, 만일 백엔드 서버가 아프거나, 네트워크 상황이 좋지 않아 제대로 통신이 이루어지지 않았을 때, 에러처리가 필요하다.

만일 단순한 API를 요청이 실패하여 에러가 발생했을 경우, 그 에러로 인해 서비스 전체가 죽어버린다면 큰 손실이 발생할 것이다.

이러한 일이 발생하지 않도록 에러 핸들링과 안정성을 관리하는 방법을 알아보자.

발생할 수 있는 에러 상황에는 어떤 것이 있을까?

에러처리를 하기에 앞서 어떤 상황에서 에러가 발생하는지에 대해서 먼저 알아보고 싶었다.

다양한 에러 상황 요약 :

- 데이터에서 시작되는 에러
- 네트워크와 API에서 발생하는 에러
- 사용자 행동에서 발생하는 에러
- 비동기 처리에서 발생하는 에러
- 렌더링 과정에서 발생하는 에러
- 전역 상태와 환경에서 발생하는 에러
- 외부 라이브러리에서 발생하는 에러
- 브라우저와 환경 차이에서 발생하는 에러
- 성능 문제에서 시작되는 에러

데이터가 아직 없을 때 발생하는 에

프론트엔드에서 가장 흔한 에러는 데이터와 관련되어 있다.

특히 API 기반으로 동작하는 서비스에서는 데이터가 항상 “정상적일 것”이라는 가정 자체가 위험하다.

예를 들어 다음과 같은 코드는 매우 흔하다.

function UserProfile({ user }) {
  return <div>{user.name}</div>;
}

하지만 초기 렌더링 시점에 user가 아직 존재하지 않는다면, 이 코드는 즉시 에러를 발생시킨다.
또한 API 응답 구조가 예상과 다르게 변경되는 경우에도 문제가 발생한다.

data.items.map(...)

이때 실제 응답이 { products: [] }라면, items가 존재하지 않아 런타임 에러가 발생한다.

이러한 문제는 단순한 실수가 아니라, 프론트엔드가 “비동기 데이터” 위에서 동작한다는 특성에서 비롯된다.

따라서 데이터 접근은 항상 방어적으로 작성해야 한다.

안전한 코드

function UserProfile({ user }) {
  if (!user) return <p>로딩 중...</p>;
  return <div>{user.name}</div>;
}

또는

<div>{user?.name ?? '이름 없음'}</div>

네트워크와 API에서 발생하는 에러

프론트엔드는 항상 네트워크 위에서 동작한다.

즉, API 요청은 실패할 수 있는 것이 기본 전제다.

요청 자체가 실패하는 경우도 있고, 서버가 정상적으로 응답하지 못하는 경우도 있다.

예를 들어 단순한 API 호출 코드가 있다고 가정해보자.

const fetchUser = async () => {
  const res = await fetch('/api/user');
  return res.json();
};

이 코드는 겉보기에는 문제가 없어 보이지만, 실제로는 다음과 같은 상황에서 실패할 수 있다.

서버가 500 에러를 반환하는 경우
네트워크가 끊긴 경우
응답이 JSON이 아닌 경우

이때 아무런 처리를 하지 않으면 에러는 그대로 UI까지 전파된다.

useEffect(() => {
  fetchUser(); // 실패해도 아무 처리 없음
}, []);

안전하게 처리하려면 반드시 실패를 고려해야 한다.

useEffect(() => {
  const load = async () => {
    try {
      const data = await fetchUser();
      setUser(data);
    } catch {
      setError(true);
    }
  };

  load();
}, []);

또 하나 중요한 문제는 요청이 겹치는 상황이다.

useEffect(() => {
  fetch(`/api/user/${id}`).then(res => res.json()).then(setUser);
}, [id]);

사용자가 빠르게 id를 변경하면 이전 요청이 늦게 도착하여 최신 데이터를 덮어쓰는 문제가 발생할 수 있다.

이를 방지하려면 요청 취소나 최신 요청만 반영하는 처리가 필요하다.

사용자 행동에서 발생하는 에러

사용자는 항상 개발자가 예상한 방식으로만 행동하지 않는다. 오히려 예상 밖의 행동이 훨씬 더 많이 발생한다.

예를 들어 버튼을 여러 번 클릭하는 상황을 보자.

function OrderButton() {
  const handleOrder = async () => {
    await api.post('/order');
  };

  return <button onClick={handleOrder}>주문하기</button>;
}

이 경우 사용자가 버튼을 여러 번 누르면 요청이 중복으로 발생한다.

서버에 동일 데이터 여러 번 생성
상태 꼬임
결제 중복 같은 심각한 문제 발생 가능

이를 방지하려면 로딩 상태로 제어해야 한다.

function OrderButton() {
  const [loading, setLoading] = useState(false);

  const handleOrder = async () => {
    if (loading) return;

    setLoading(true);
    try {
      await api.post('/order');
    } finally {
      setLoading(false);
    }
  };

  return (
    <button onClick={handleOrder} disabled={loading}>
      {loading ? '처리 중...' : '주문하기'}
    </button>
  );
}

이처럼 사용자 에러는 단순 코드 문제가 아니라 UX 설계 문제에서 발생하는 경우가 많다.

이 경우 서버 데이터가 중복 생성되거나 상태가 꼬일 수 있다.

비동기 처리에서 발생하는 에러

JavaScript의 비동기 특성 역시 많은 문제를 만든다.

특히 Promise를 제대로 처리하지 않거나, 에러를 catch하지 않는 경우 문제가 발생한다.

useEffect(() => {
  fetchData(); // 에러 처리 없음
}, []);

이 경우 내부에서 에러가 발생해도 UI는 아무 반응이 없고, 콘솔에만 에러가 찍힌다.

또한 컴포넌트가 unmount된 이후 상태를 업데이트하는 문제도 자주 발생한다.

useEffect(() => {
  fetchData().then(data => setState(data));
}, []);

사용자가 페이지를 빠르게 이동하면 다음과 같은 상황이 발생한다.

컴포넌트는 이미 사라짐
하지만 비동기 요청은 완료됨
setState 실행 → 경고 발생

이를 방지하려면 마운트 상태를 체크해야 한다.

useEffect(() => {
  let isMounted = true;

  fetchData().then(data => {
    if (isMounted) {
      setState(data);
    }
  });

  return () => {
    isMounted = false;
  };
}, []);

이러한 문제는 특정 타이밍에서만 발생하기 때문에 “숨은 에러”가 되기 쉽다.

렌더링 과정에서 발생하는 에러

가장 치명적인 에러는 렌더링 중 발생하는 에러다.

이 경우 React는 해당 컴포넌트 트리를 더 이상 렌더링하지 못하고, 전체 UI가 깨질 수 있다.

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

{data.map(item => (
  <div key={item.id}>{item.name}</div>
))}

여기서 data가 undefined라면 즉시 에러가 발생한다.

또는 더 위험한 경우도 있다.

function Profile({ user }) {
  return <div>{user.name.toUpperCase()}</div>;
}

user = null
user.name = undefined

렌더링 중 즉시 crash가 발생한다.

이를 방지하려면 반드시 방어적으로 작성해야 한다.

function Profile({ user }) {
  if (!user?.name) return <p>데이터 없음</p>;

  return <div>{user.name.toUpperCase()}</div>;
}

렌더링 에러는 Error Boundary가 없다면 전체 앱을 무너뜨릴 수 있기 때문에 가장 주의해야 한다.

전역 상태와 환경에서 발생하는 에러

앱 전체를 감싸는 전역 영역에서 발생하는 에러는 특히 위험하다.

대표적인 예시는 localStorage 파싱이다.

const user = JSON.parse(localStorage.getItem('user'));

이 값이 깨진 JSON이라면 앱이 시작하자마자 에러가 발생한다.

이를 방지하려면 try-catch가 필요하다.

function getUser() {
  try {
    const value = localStorage.getItem('user');
    return value ? JSON.parse(value) : null;
  } catch {
    return null;
  }
}

또한 Next.js에서는 hydration mismatch 문제도 자주 발생한다.

// 서버
<p>{new Date().toLocaleTimeString()}</p>

// 클라이언트
<p>다른 시간</p>

서버와 클라이언트 결과 불일치 → 경고 및 UI 문제 발생

이러한 에러는 특정 기능이 아니라 서비스 전체에 영향을 준다.

외부 라이브러리에서 발생하는 에러

차트, 지도, 에디터 같은 외부 라이브러리는 내부 동작을 알기 어렵기 때문에 더 위험하다.

<Chart data={data} />

data 형식이 조금만 달라도 내부에서 에러가 발생할 수 있고, 이 에러는 렌더링 단계에서 발생하기 때문에 전체 UI에 영향을 준다.

이를 방지하려면 반드시 Error Boundary로 감싸야 한다.

<ErrorBoundary fallback={<p>차트를 불러올 수 없습니다.</p>}>
  <Chart data={data} />
</ErrorBoundary>

브라우저와 환경 차이에서 발생하는 에러

프론트엔드는 다양한 환경에서 실행되기 때문에 동일한 코드라도 다른 결과가 나올 수 있다.

window.localStorage

이 코드는 브라우저에서는 정상 동작하지만, 서버 환경에서는 에러가 발생한다.

if (typeof window !== 'undefined') {
  localStorage.getItem('user');
}

또한 특정 API는 일부 브라우저에서 지원되지 않는다.

navigator.clipboard.writeText('text');

→ 일부 환경에서는 undefined

이러한 문제는 개발 환경에서는 잘 드러나지 않기 때문에 더 위험하다.

성능 문제에서 시작되는 에러

에러는 반드시 Exception 형태로만 나타나지 않는다. 성능 문제 역시 사용자 입장에서는 “서비스가 고장난 것처럼” 보인다.

예를 들어 대량 데이터를 한 번에 렌더링하는 경우다.

{
  items.map(item => <Item key={item.id} {...item} />);
}

items가 1000개라면 화면이 멈출 수 있다.

또한 메모리 누수도 문제를 만든다.

useEffect(() => {
  const id = setInterval(() => {
    console.log('running');
  }, 1000);

  // cleanup 없음
}, []);

→ 컴포넌트가 사라져도 계속 실행

이를 해결하려면 cleanup이 필요하다.

useEffect(() => {
  const id = setInterval(() => {
    console.log('running');
  }, 1000);

  return () => clearInterval(id);
}, []);

이러한 문제는 코드가 틀리지 않았더라도 충분히 “에러 상황”으로 이어진다.

생각보다 많은 에러 상황이 존재한다.

Error Boundary - 에러를 막는 것이 아니라 ‘격리’하는 것

단순한 코드 한 줄에서 에러가 발생했을 뿐인데, 화면 전체가 하얗게 변하면서 아무것도 보이지 않는 상황이다.

React에서는 렌더링 중 에러가 발생하면 해당 컴포넌트 트리를 더 이상 렌더링할 수 없기 때문에, 별도의 처리를 하지 않으면 앱 전체가 무너질 수 있다.

이 문제를 해결하기 위해 등장한 개념이 바로 Error Boundary다.

Error Boundary란 무엇인가

Error Boundary는 하위 컴포넌트에서 발생한 렌더링 에러를 잡아서, 대체 UI(fallback UI)를 보여주는 컴포넌트다.

쉽게 말하면, 에러가 발생했을 때 앱이 죽지 않도록 “보호막” 역할을 한다.

예를 들어 아래와 같은 코드가 있다고 가정해보자.

function Profile({ user }) {
  return <div>{user.name.toUpperCase()}</div>;
}

만약 user가 null이라면 user.name에서 에러가 발생한다.
이때 Error Boundary가 없다면, 이 에러는 상위로 전파되면서 화면 전체가 깨질 수 있다.

Error Boundary가 해결하는 문제

Error Boundary의 핵심 역할은 하나다.

“에러를 막는 것이 아니라, 에러의 영향을 제한하는 것”

즉, 문제가 발생한 컴포넌트만 격리하고 나머지 UI는 정상적으로 유지한다.

예를 들어 대시보드 화면이 있다고 해보자.

<Dashboard>
  <Chart />
  <UserInfo />
  <Notifications />
</Dashboard>

여기서 Chart에서 에러가 발생했다고 해서 전체 페이지가 사라지는 것은 좋은 UX가 아니다.
Error Boundary를 사용하면 다음과 같이 개선할 수 있다.

<Dashboard>
  <ErrorBoundary fallback={<p>차트를 불러올 수 없습니다.</p>}>
    <Chart />
  </ErrorBoundary>

  <UserInfo />
  <Notifications />
</Dashboard>

이제 Chart가 깨지더라도 나머지 UI는 그대로 유지된다.

Error Boundary는 언제 동작하는가

Error Boundary는 모든 에러를 잡아주는 것이 아니다.
동작하는 범위를 정확히 이해하는 것이 중요하다.

잡을 수 있는 에러

렌더링 과정에서 발생한 에러
라이프사이클 메서드 내부 에러
하위 컴포넌트에서 발생한 에러

라이프사이클이란 무엇인가

React에서 라이프사이클(Lifecycle)은 컴포넌트가 생성되고, 업데이트되고, 사라질 때까지의 전체 과정을 의미한다.

하나의 컴포넌트는 다음 흐름을 가진다.

생성(Mount) → 업데이트(Update) → 제거(Unmount)

이 과정 중 특정 시점마다 실행되는 함수들이 있는데, 이것을 라이프사이클 메서드라고 한다.

라이프사이클 흐름을 코드로 이해하기

1. Mount (처음 화면에 등장할 때)

useEffect(() => {
  console.log('컴포넌트가 처음 렌더링됨');
}, []);

→ 컴포넌트가 처음 생성될 때 실행

2. Update (값이 바뀔 때)

useEffect(() => {
  console.log('count가 변경됨');
}, [count]);

→ state나 props가 변경될 때 실행

3. Unmount (컴포넌트가 사라질 때)

useEffect(() => {
  return () => {
    console.log('컴포넌트가 제거됨');
  };
}, []);

→ 화면에서 사라질 때 실행

라이프사이클 “메서드”라는 표현은 왜 나올까?

이건 React의 클래스 컴포넌트 시절 용어다.

class MyComponent extends React.Component {
  componentDidMount() {
    console.log('마운트');
  }

  componentDidUpdate() {
    console.log('업데이트');
  }

  componentWillUnmount() {
    console.log('언마운트');
  }

  render() {
    return <div>Hello</div>;
  }
}

이 함수들이 바로 라이프사이클 메서드다.

지금은 함수형 컴포넌트 + useEffect로 대체되었지만, 개념은 동일하다.

그럼 “라이프사이클 메서드 내부 에러”는 무슨 뜻인가

말 그대로 이 lifecycle 흐름 중에 실행되는 코드에서 에러가 발생하는 경우를 의미한다.

예시로 보면 이해가 쉽다.

예시 1: mount 시점 에러

useEffect(() => {
  const data = JSON.parse(localStorage.getItem('user')); // 여기서 에러 가능
}, []);

→ 저장된 값이 깨져 있으면 JSON.parse에서 에러 발생

예시 2: update 시점 에러

useEffect(() => {
  console.log(user.name.toUpperCase());
}, [user]);

→ user가 null이면 에러 발생

예시 3: 클래스 컴포넌트 기준

class Test extends React.Component {
  componentDidMount() {
    throw new Error('에러 발생');
  }

  render() {
    return <div>Hello</div>;
  }
}

→ 이 경우 Error Boundary가 잡을 수 있음

왜 Error Boundary랑 연결되는가

Error Boundary는 다음 에러를 잡는다.

render 중 에러
lifecycle 내부 에러

즉 이런 경우는 잡힌다.

useEffect(() => {
  throw new Error('에러');
}, []);

하지만 이런 건 못 잡는다.

const handleClick = () => {
  throw new Error('에러');
};

→ 이벤트 핸들러는 lifecycle이 아니라 “사용자 액션”이기 때문

잡지 못하는 에러

이벤트 핸들러 에러 (onClick 등)
비동기 코드 (setTimeout, Promise)
서버 사이드 렌더링 에러

예를 들어 다음 코드는 Error Boundary가 잡지 못한다.

const handleClick = () => {
  throw new Error('에러 발생');
};

이 경우에는 try-catch 또는 별도의 에러 처리 로직이 필요하다.

Error Boundary 직접 구현하기

Error Boundary는 클래스 컴포넌트로만 구현할 수 있다.

import { Component, ReactNode } from 'react';

interface Props {
  children: ReactNode;
  fallback: ReactNode;
}

interface State {
  hasError: boolean;
}

export class ErrorBoundary extends Component<Props, State> {
  state: State = {
    hasError: false,
  };

  static getDerivedStateFromError() {
    return { hasError: true };
  }

  componentDidCatch(error: Error) {
    console.error('ErrorBoundary caught:', error);
  }

  render() {
    if (this.state.hasError) {
      return this.props.fallback;
    }

    return this.props.children;
  }
}

이 컴포넌트는 하위에서 에러가 발생하면 fallback UI를 렌더링한다.

실제 사용 예시

function App() {
  return (
    <div>
      <h1>대시보드</h1>

      <ErrorBoundary fallback={<p>차트를 불러올 수 없습니다.</p>}>
        <Chart />
      </ErrorBoundary>

      <ErrorBoundary fallback={<p>유저 정보를 불러올 수 없습니다.</p>}>
        <UserInfo />
      </ErrorBoundary>
    </div>
  );
}

이렇게 기능 단위로 Error Boundary를 나누면, 특정 기능이 깨져도 전체 앱은 안정적으로 유지된다.

Error Boundary 설계 전략

Error Boundary는 “어디에 두느냐”가 중요하다.

너무 크게 감싸는 경우

<ErrorBoundary>
  <App />
</ErrorBoundary>

→ 하나의 에러로 전체 앱이 fallback으로 대체됨

너무 작게 감싸는 경우

→ 관리 포인트 증가, 코드 복잡도 증가

선언적 에러 처리 vs 명령적 에러 처리

선언적 에러 처리 (Declarative)

선언적 에러 처리는 상태 기반으로 UI를 분기하는 방식이다.
즉, “지금 상태가 어떤가”에 따라 보여줄 UI를 결정한다.

예를 들어 React Query를 사용한 코드다.

function UserProfile() {
  const { data, isLoading, isError, error, refetch } = useQuery({
    queryKey: ['user'],
    queryFn: fetchUser,
  });

  if (isLoading) {
    return <p>로딩 중...</p>;
  }

  if (isError) {
    return (
      <div>
        <p>{error.message}</p>
        <button onClick={refetch}>다시 시도</button>
      </div>
    );
  }

  return <div>{data.name}</div>;
}

이 코드의 특징은

상태(isLoading, isError)에 따라 UI가 자동으로 결정된다
흐름이 눈에 보인다
유지보수가 쉽다

이 방식은 특히 데이터 조회 UI에서 강력하다.

명령적 에러 처리 (Imperative)

명령적 에러 처리는 흐름을 직접 제어하면서 에러를 처리하는 방식이다.

대표적으로 try-catch가 있다.

function LoginButton() {
  const handleLogin = async () => {
    try {
      await api.post('/login', {
        email: 'test@test.com',
        password: '1234',
      });

      alert('로그인 성공');
    } catch (e) {
      alert('로그인 실패');
    }
  };

  return <button onClick={handleLogin}>로그인</button>;
}

이 방식은 다음과 같은 특징이 있다.

사용자의 행동에 즉각 반응
흐름 제어가 명확
사이드 이펙트 처리에 유리

즉, 버튼 클릭, 폼 제출 같은 사용자 액션에 적합하다.

선언적 vs 명령적 - 같이 써야 한다

실제 서비스에서는 둘 중 하나만 쓰지 않는다.

function Page() {
  const { data, isError } = useQuery(...);

  // 선언적 처리
  if (isError) return <ErrorUI />;

  // 명령적 처리
  const handleSubmit = async () => {
    try {
      await api.post('/submit');
    } catch {
      alert('실패');
    }
  };

  return <button onClick={handleSubmit}>제출</button>;
}

정리하면 다음과 같다.

렌더링 → 선언적 처리
사용자 액션 → 명령적 처리

API 에러는 ‘분류’부터 시작해야 한다

에러 처리가 어려운 이유는 대부분 “모든 에러를 동일하게 처리하려 하기 때문”이다.

안정적인 설계를 위해서는 먼저 에러를 예측 가능한 에러와 예측 불가능한 에러로 나누어야 한다.

예측 가능한 에러는 사용자 입력이나 권한 문제 등 비즈니스 로직에서 발생하는 에러다.

예를 들어 인증 실패나 잘못된 요청은 사용자에게 안내 메시지를 보여주고, 필요한 행동을 유도해야 한다.

예시 코드:

const login = async () => {
  try {
    await api.post('/login');
  } catch (error) {
    if (error.status === 401) {
      alert('로그인이 필요합니다.');
    }
  }
};

→ 사용자에게 안내해야 하는 에러

반대로 예측 불가능한 에러는 서버 장애나 네트워크 문제처럼 시스템 레벨에서 발생한다.

이런 경우에는 Error Boundary를 통해 UI를 격리하고, fallback UI를 보여주는 것이 핵심이다.

이렇게 에러를 분리하면 “어떤 에러는 사용자에게 안내하고, 어떤 에러는 시스템적으로 보호한다”는 명확한 전략을 세울 수 있다.

Fallback UI - 단순한 에러 화면이 아니라 UX 전략

Fallback UI는 에러 상황에서 사용자에게 무엇을 보여줄지를 결정하는 요소다.

단순히 “에러가 발생했습니다”라는 메시지를 보여주는 것만으로는 충분하지 않다.

좋은 Fallback UI는 현재 상황을 이해할 수 있게 하고, 다음 행동을 유도해야 한다.

전체 페이지에서 문제가 발생한 경우에는 새로고침이나 홈으로 이동하는 선택지를 제공하는 것이 좋다.

반면 특정 기능에서만 문제가 발생했다면 해당 영역만 대체 UI로 바꾸고 나머지는 그대로 유지해야 한다.

또한 데이터가 없는 상태는 에러가 아니라 정상 상태이기 때문에, “데이터 없음”에 대한 별도의 UI를 설계해야 한다.

여기에 재시도 버튼이나 자동 재요청 전략을 함께 고려하면 사용자 경험이 크게 개선된다.

결국 Fallback UI는 단순한 예외 처리가 아니라, 서비스의 완성도를 결정짓는 중요한 UX 요소다.

1. 전체 페이지 에러

function GlobalError() {
  return (
    <div>
      <h2>문제가 발생했습니다</h2>
      <button onClick={() => window.location.reload()}>
        다시 시도
      </button>
    </div>
  );
}

2. 부분 UI 에러

if (isError) {
  return (
    <div>
      <p>차트를 불러올 수 없습니다.</p>
      <button onClick={refetch}>다시 시도</button>
    </div>
  );
}

→ 특정 기능만 교체

3. Empty State (에러 아님)

if (data.length === 0) {
  return (
    <div>
      <p>데이터가 없습니다</p>
      <button>추가하기</button>
    </div>
  );
}

→ 정상 상태

4. 재시도 전략

<button onClick={refetch}>다시 시도</button>

또는 React Query

useQuery({
  queryKey: ['data'],
  queryFn: fetchData,
  retry: 2,
});

안정적인 에러 처리 구조는 어떻게 만들어지는가

프론트엔드에서 안정적인 에러 처리 구조는 한 가지 기술로 해결되지 않는다. 여러 레이어가 함께 작동해야 한다.

API 레벨에서는 에러를 구조화하고, 예측 가능한지 여부를 구분해야 한다.

로직 레벨에서는 try-catch를 통해 사용자 액션에 대한 피드백을 처리한다.

UI 레벨에서는 상태 기반으로 화면을 분기하고, 마지막으로 Error Boundary를 통해 전체 앱이 깨지는 것을 방지한다.

이 모든 구조 위에서 Fallback UI가 사용자 경험을 책임진다.

1. API 레벨

api.interceptors.response.use(
  res => res,
  error => {
    return Promise.reject({
      type: error.response?.status < 500 ? 'EXPECTED' : 'UNEXPECTED',
      message: error.message,
    });
  }
);

2. 로직 레벨

try {
  await api.post('/submit');
} catch {
  alert('실패');
}

3. UI 레벨

if (isError) return <ErrorUI />;

4. 렌더링 보호

<ErrorBoundary fallback={<ErrorPage />}>
  <App />
</ErrorBoundary>

마무리

에러 핸들링은 단순히 “에러를 처리하는 코드”가 아니라, 서비스의 안정성과 사용자 경험을 동시에 설계하는 영역이다.

Error Boundary를 통해 시스템을 보호하고, 선언적·명령적 처리를 상황에 맞게 사용하며, API 에러를 명확하게 분류하고, Fallback UI를 전략적으로 설계하는 것. 이 네 가지가 결합될 때 비로소 “깨지지 않는 프론트엔드”가 만들어진다.

감사합니다!

Profiler부터 memo까지 제대로 사용해보자!

수달군 — Mon, 27 Apr 2026 06:23:16 +0900

React 렌더링 최적화 실전 - Profiler부터 memo까지 제대로 사용해보자!

React에서 성능 최적화를 이야기할 때 가장 많이 나오는 키워드는 useMemo, useCallback, React.memo입니다.

하지만 이들을 어떻게 올바르게 적용할 수 있을까요?

중요한 것은 어디가 느린지 먼저 확인하고, 그 원인을 분석한 뒤 필요한 부분에만 최적화를 적용하는 것입니다.

이 글에서는 React DevTools Profiler와 memo를 사용하여 불필요한 렌더링을 찾아 최적화하는 방법에 대해서 알아보겠습니다!

React에서의 렌더링의 조건

React useState 완전 이해하기에서 state에 관련된 렌더링 조건에 대해서만 다뤘습니다.

React 컴포넌트는 다음 네 가지 상황에서 렌더링됩니다.

state가 변경될 때
props가 변경될 때
부모 컴포넌트가 렌더링될 때
context 값이 변경될 때

또한 중요한 점은, 렌더링은 단순히 함수가 다시 실행되는 것이지 곧바로 DOM이 변경되는 것은 아니라는 점입니다.

React는 이전 결과와 비교하여 실제 변경이 필요한 부분만 DOM에 반영합니다.

렌더링이 문제되는 순간

모든 렌더링이 문제되는 것은 아닙니다. 다음과 같은 경우에만 성능 문제가 발생합니다.

렌더링 비용이 큰 컴포넌트가 포함된 경우
리스트, 차트, 복잡한 UI가 함께 렌더링되는 경우
불필요하게 넓은 범위의 state가 존재하는 경우

예를 들어, 입력창 하나 때문에 페이지 전체가 다시 렌더링되면서 차트나 대형 리스트까지 같이 렌더링된다면 이는 비효율적인 구조가 됩니다.

React DevTools Profiler 활용법

React DevTools의 Profiler는 렌더링 성능을 분석하기 위한 도구입니다.

어떤 컴포넌트가 렌더링되었는지, 그리고 그 렌더링에 얼마나 시간이 걸렸는지를 확인할 수 있습니다.

기본적인 사용 방법은 다음과 같습니다.

먼저 설치를 진행합니다. 설치링크

Profiler 탭에서 Record 버튼을 누릅니다.

사용자가 실제로 수행하는 인터랙션을 재현합니다.

Record를 중지하고 결과를 확인합니다.

Profiler에서는 다음 정보를 확인할 수 있습니다.

어떤 컴포넌트가 렌더링되었는지
각 컴포넌트의 렌더링 시간
렌더링이 발생한 원인

Profiler에서 가장 중요하게 봐야 할 부분은 두 가지입니다.

첫째는 어떤 컴포넌트가 렌더링되었는지입니다.
둘째는 그 렌더링이 얼마나 비용이 큰지입니다.

Flamegraph에서는 컴포넌트의 렌더링 시간을 시각적으로 확인할 수 있으며, 넓고 진한 블록일수록 비용이 큰 컴포넌트입니다.

Ranked 탭에서는 렌더링 시간이 긴 컴포넌트를 순위로 확인할 수 있어 병목을 빠르게 찾는 데 유용합니다.

또한 특정 컴포넌트를 클릭하면 해당 컴포넌트가 왜 렌더링되었는지도 확인할 수 있습니다.
props 변경인지, state 변경인지, 부모 렌더링 때문인지 파악하는 것이 핵심입니다.

실제로 Profiler를 사용해보자!

제가 진행했던 '마음모음' 프로젝트의 2차 인증 비밀번호 입력화면입니다.

다음은 PIN.tsx 페이지의 코드 일부이며, 컴포넌트 상단에서 입력한 비밀번호에 대한 state를 관리하기 때문에,

비밀번호가 입력되면 페이지 전체가 재렌더링 되는 상태였습니다.

const [password, setPassword] = useState(['', '', '', '']);

export default function PIN() {
  const [password, setPassword] = useState(['', '', '', '']);
  const [errorMessage, setErrorMessage] = useState<string | null>(null);
  
  ...

  const handleSubmit = () => {
    verifyPassword({
      data: { secondaryPassword: password.join('') },
    });
  };

  return (
    <SubPageLayout title="2차 비밀번호 입력하기" backTo={ROUTE.LOGIN}>
      <div className="flex w-full flex-col items-center">
        <div className="mt-6 flex h-auto flex-col items-center gap-4 px-6">
          <div className="h-51">
            <img src={lockGif} alt="" className="h-auto w-51 object-cover" />
          </div>
        </div>
        <h1 className="text-title-2-semibold mt-5 text-center whitespace-pre-line text-gray-800">
          소중한 마음 기록을{'\n'}보호하고 있어요
        </h1>
        <h1 className="text-body-3-regular mt-1 mb-6 text-gray-400">현재 비밀번호를 입력해주세요</h1>
        <InputOTP
          value={password}
          onChange={setPassword}
          isError={!!errorMessage}
          onErrorReset={() => setErrorMessage(null)}
        />
        {errorMessage && <h1 className="text-caption-1-regular mt-3 text-red-500">{errorMessage}</h1>}
      </div>

      <Button
        className="fixed right-0 bottom-0 left-0 mx-6 mb-6 flex justify-center gap-3"
        variant="primary"
        appearance="filled"
        size="lg"
        onClick={handleSubmit}
        disabled={!password.every((v) => v) || isPending}
        data-submit-btn
      >
        <p className="text-body-2-semibold">다음</p>
      </Button>
    </SubPageLayout>
  );
}

실제로 PIN 내부에 있는 Input에 값을 입력할경우 페이지 전체가 리렌더링 되는 모습을 볼 수 있습니다.
SubPageLayout 내부의 모든 컴포넌트가 렌더링 되는 모습입니다.

export default function PIN() {
  
  ...

  const [formErrorMessage, setFormErrorMessage] = useState<string | null>(null);

  const handleSubmit = useCallback(
    (password: string[]) => {
      verifyPassword({
        data: { secondaryPassword: password.join('') },
      });
    },
    [verifyPassword]
  );

  return (
    <SubPageLayout title="2차 비밀번호 입력하기" backTo={ROUTE.LOGIN}>
      <div className="flex w-full flex-col items-center">
        <div className="mt-6 flex h-auto flex-col items-center gap-4 px-6">
          <div className="h-51">
            <img src={lockGif} alt="" className="h-auto w-51 object-cover" />
          </div>
        </div>
        <h1 className="text-title-2-semibold mt-5 text-center whitespace-pre-line text-gray-800">
          소중한 마음 기록을{'\n'}보호하고 있어요
        </h1>
        <h1 className="text-body-3-regular mt-1 mb-6 text-gray-400">현재 비밀번호를 입력해주세요</h1>
        <PinForm
          onSubmit={handleSubmit}
          errorMessage={formErrorMessage}
          onErrorReset={() => setFormErrorMessage(null)}
          isPending={isPending}
        />
      </div>
    </SubPageLayout>
  );
}

type PinFormProps = {
  onSubmit: (password: string[]) => void;
  errorMessage: string | null;
  onErrorReset: () => void;
  isPending: boolean;
};

function PinForm({ onSubmit, errorMessage, onErrorReset, isPending }: PinFormProps) {
  const [password, setPassword] = useState(['', '', '', '']);
  const isPasswordComplete = password.every(Boolean);

  return (
    <>
      <InputOTP value={password} onChange={setPassword} isError={!!errorMessage} onErrorReset={onErrorReset} />

      {errorMessage && <h1 className="text-caption-1-regular mt-3 text-red-500">{errorMessage}</h1>}

      <Button
        className="fixed right-0 bottom-0 left-0 mx-6 mb-6 flex justify-center gap-3"
        variant="primary"
        appearance="filled"
        size="lg"
        onClick={() => onSubmit(password)}
        disabled={!isPasswordComplete || isPending}
        data-submit-btn
      >
        <p className="text-body-2-semibold">다음</p>
      </Button>
    </>
  );
}

따라서 PinForm 컴포넌트를 새로 만들고, 그 안에서 state를 관리하기로 하였다.

이제 PIN을 입력하더라도 PinForm 내부만 다시 재렌더링이 발생하는 모습을 볼 수 있습니다.

물론 기존 구조에서, 이미지나 텍스트도 함께 렌더링되지만 실제 비용은 거의 발생하지 않는다는 것( 4ms )입니다.

React는 동일한 JSX 결과에 대해서는 DOM을 다시 생성하지 않으며, 이미지 역시 동일한 src를 유지하는 경우 재요청이 발생하지 않습니다.

따라서 극적인 최적화가 이뤄지지는 않을 것이며, 반드시 필요한 최적화라고도 말할 순 없습니다.

하지만 지금은 단순한 이미지와 텍스트지만, 여기에 다음과 같은 요소가 추가된다면 상황이 달라집니다.

대형 리스트
차트
애니메이션
복잡한 계산 로직

이 경우 입력값 하나 때문에 모든 요소가 다시 렌더링되는 구조는 비효율적이 됩니다.

무거운 계산이 필요한 컴포넌트가 함께 있을 경우 이러한 최적화는 필요할 것입니다.

Profiler를 어떻게 사용하는지 실제 코드에 적용하여 실습해볼 수 있었습니다.

이미지와 렌더링

렌더링 최적화를 고민할 때 자주 나오는 질문 중 하나는 이미지나 GIF가 다시 렌더링되면 비용이 큰 것이 아닌가 하는 점입니다.

React에서 렌더링은 함수 실행을 의미하며, 동일한 JSX 결과가 생성되면 실제 DOM은 변경되지 않습니다.
또한 이미지의 src가 동일하다면 브라우저 캐시를 활용하기 때문에 네트워크 요청이 다시 발생하지 않습니다.

따라서 단순한 이미지나 텍스트는 렌더링 비용 측면에서 큰 문제가 되지 않는 경우가 많습니다.
진짜로 신경 써야 할 대상은 리스트, 차트, 복잡한 계산과 같은 무거운 컴포넌트입니다.

useMemo, useCallback, React.memo - 언제 쓰고, 왜 써야 하는가

React에서 성능 최적화를 고민하다 보면 useMemo, useCallback, React.memo라는 세 가지 도구를 자주 접하게 됩니다. 하지만 이들을 단순히 “렌더링을 줄이는 기술”로 이해하고 사용하는 경우가 많습니다.

실제로는 각각의 역할이 명확하게 다르며,

잘못 사용하면 오히려 코드 복잡도만 증가하고 성능 개선 효과는 거의 없는 경우도 많습니다.

밑에서는 세 가지 도구가 각각 무엇을 하는지, 그리고 어떤 상황에서 사용하는 것이 적절한지를 실제 예시와 함께 설명합니다.

useMemo - 값을 기억하는 Hook

useMemo는 특정 계산 결과를 기억하고, 의존성이 변경되지 않는 한 이전 값을 재사용하는 Hook입니다.

즉, 동일한 계산을 반복하지 않도록 만들어주는 역할을 합니다.

React는 컴포넌트가 렌더링될 때마다 함수 내부 코드가 다시 실행됩니다.

이때 데이터 가공이나 필터링과 같은 연산이 포함되어 있다면, 렌더링이 반복될수록 불필요한 계산이 계속 발생하게 됩니다.

useMemo는 이러한 문제를 해결하기 위해 존재합니다.

예를 들어 리스트를 필터링하는 코드가 있다고 가정해보겠습니다.

const filteredList = items.filter(item => item.name.includes(keyword));

이 코드는 렌더링이 발생할 때마다 실행됩니다. 만약 items의 크기가 크다면 이 연산은 성능에 영향을 줄 수 있습니다. 이를 useMemo로 감싸면 다음과 같이 개선할 수 있습니다.

const filteredList = useMemo(() => {
  return items.filter(item => item.name.includes(keyword));
}, [items, keyword]);

이제 items나 keyword가 변경될 때만 필터링이 다시 실행되며, 그렇지 않은 경우에는 이전 결과를 그대로 사용합니다.

또한 useMemo는 단순히 계산 최적화뿐만 아니라 객체나 배열의 참조를 유지하는 용도로도 활용됩니다.

React에서는 객체와 배열이 매번 새로 생성되면 값이 같더라도 다른 것으로 판단되기 때문에, 이를 방지하기 위해 useMemo를 사용할 수 있습니다.

useCallback - 함수를 기억하는 Hook

useCallback은 함수 자체를 기억하는 Hook입니다. React에서는 컴포넌트가 렌더링될 때마다 함수도 함께 새로 생성됩니다.

대부분의 경우 이는 문제가 되지 않지만, 해당 함수가 자식 컴포넌트로 전달되는 경우에는 상황이 달라집니다.

예를 들어 다음과 같은 코드가 있다고 가정해보겠습니다.

<Child onClick={() => doSomething()} />

이 경우 렌더링이 발생할 때마다 새로운 함수가 생성되며, 자식 컴포넌트 입장에서는 props가 변경된 것으로 판단할 수 있습니다. 특히 자식 컴포넌트가 React.memo로 최적화되어 있다면, 이로 인해 불필요한 렌더링이 발생할 수 있습니다.

이를 해결하기 위해 useCallback을 사용할 수 있습니다.

const handleClick = useCallback(() => {
  doSomething();
}, []);

<Child onClick={handleClick} />

이제 handleClick 함수는 동일한 참조를 유지하게 되며, 자식 컴포넌트의 불필요한 렌더링을 방지할 수 있습니다.

다만 중요한 점은, useCallback은 모든 함수에 적용해야 하는 것이 아니라 props로 전달되는 함수이며, 해당 컴포넌트가 memoization되어 있는 경우에만 의미가 있다는 점입니다.

React.memo - 컴포넌트를 기억하는 기능

React.memo는 컴포넌트를 감싸서, props가 변경되지 않은 경우 렌더링을 건너뛰도록 하는 기능입니다. 이는 함수형 컴포넌트에서 사용할 수 있는 최적화 방법입니다.

const Child = memo(function Child({ value }) {
  return <div>{value}</div>;
});

이렇게 작성하면 value가 변경되지 않는 한 Child 컴포넌트는 다시 렌더링되지 않습니다.

React.memo는 특히 리스트 아이템처럼 동일한 구조의 컴포넌트가 반복되는 경우나, 렌더링 비용이 큰 컴포넌트에 적용할 때 효과적입니다.

예를 들어 리스트가 다음과 같이 구성되어 있다고 가정해보겠습니다.

const ListItem = memo(({ item }) => {
  return <li>{item.name}</li>;
});

이 경우 부모 컴포넌트가 렌더링되더라도 item이 변경되지 않는 한 각 ListItem은 다시 렌더링되지 않습니다.

언제 사용해야 하는가

세 가지 도구를 사용할 때 가장 중요한 기준은 “필요할 때만 사용한다”는 것입니다.

useMemo는 계산 결과를 캐싱하기 위한 Hook입니다.

filter, sort, map과 같이 비용이 큰 연산이 반복될 때 사용합니다.

또한 객체나 배열을 props로 전달할 때 참조를 안정화하기 위해 사용할 수 있습니다.

useCallback은 함수 참조를 유지하기 위한 Hook입니다.

함수를 props로 전달할 때, 특히 React.memo와 함께 사용할 때 의미가 있습니다.
불필요하게 함수가 새로 생성되는 것을 방지하여 자식 컴포넌트의 리렌더링을 줄입니다.

React.memo는 props가 변경되지 않았을 경우 렌더링을 건너뛰는 기능입니다.
렌더링 비용이 큰 컴포넌트나, 리스트 아이템처럼 반복적으로 렌더링되는 컴포넌트에 적용하는 것이 효과적입니다.

중요한 점은, 이 세 가지 도구는 모두 “렌더링을 줄이기 위한 수단”이 아니라 이미 확인된 병목을 해결하기 위한 도구라는 것입니다.

마무리

React 렌더링 최적화의 핵심은 단순히 렌더링을 줄이는 것이 아니라, 렌더링의 범위와 비용을 통제하는 것입니다.

모든 컴포넌트에 memo를 적용하는 것이 아니라, Profiler를 통해 병목을 찾고 그 부분만 정확하게 최적화하는 것이 중요합니다.

결국 좋은 최적화는 다음과 같이 정리할 수 있습니다.

렌더링을 막는 것이 아니라, 불필요한 렌더링과 비용이 큰 렌더링을 구분하고 제어하는 것이 중요합니다.

오늘도 읽어주셔서 감사합니다!

Next.js 데이터 페칭과 Server Actions

수달군 — Thu, 9 Apr 2026 11:45:58 +0900

Next.js 데이터 페칭과 Server Actions

이 글에서는 Next.js에서 제공하는 데이터 페칭 방식과 Server Actions를 중심으로,
실무에서 어떻게 활용해야 하는지까지 함께 정리해보겠습니다.

React 개발을 처음 시작했을 때, 대부분의 데이터 페칭은 이런 형태였습니다.

useEffect(() => {
  fetch('/api/posts')
    .then(res => res.json())
    .then(data => setPosts(data));
}, []);

컴포넌트가 마운트된 뒤에야 요청을 보내고, 로딩 상태를 따로 관리하고, 에러 처리도 별도로 해야 했습니다.

이 패턴 자체가 나쁜 것은 아니지만, 한 가지 근본적인 한계가 있었습니다.

바로 데이터 페칭이 클라이언트에 종속되어 있다는 점입니다.

Next.js App Router와 React Server Components는 이 전제를 바꿨습니다.

데이터를 "클라이언트가 받아서 가져오는" 것이 아니라, "서버가 그려서 전달하는" 방식으로 전환한 것입니다.

이 글에서는 그 변화의 핵심인 데이터 페칭 전략을 처음부터 차근히 살펴봅니다.

React Server Components - 서버에서 바로 그린다

위에서 말씀드렸듯이, 기존 React에서는 데이터를 가져오기 위해 useEffect를 사용했습니다.

컴포넌트가 먼저 렌더링되고, 브라우저에서 마운트된 이후에야 데이터 요청이 시작되는 구조입니다.

사용자는 잠깐이라도 빈 화면이나 스켈레톤을 보게 되고, 클라이언트-서버 간 요청 왕복(round trip)이 발생합니다.

Server Components에서는 이 방식이 필요하지 않습니다.

컴포넌트 자체를 async로 선언하고, 서버에서 직접 데이터를 가져올 수 있습니다.

// app/posts/page.tsx
export default async function Page() {
  const res = await fetch('https://api.example.com/posts');
  const posts = await res.json();

  return (
    <ul>
      {posts.map(post => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  );
}

이 방식의 흐름은 다음과 같습니다.

서버에서 데이터 fetch → HTML 생성 → 클라이언트 전달

클라이언트는 이미 완성된 UI를 받기 때문에 초기 렌더링 속도가 크게 개선됩니다.

또한 Server Components는 브라우저에 자바스크립트 번들로 전송되지 않습니다.

데이터베이스 접근 코드나 API 키 같은 민감한 로직을 클라이언트에 노출하지 않아도 된다는 점도 중요한 장점입니다.

fetch란 무엇인가 - Web API에서 Next.js 내장 기능으로

기본 개념

fetch는 원래 브라우저가 제공하는 Web API입니다.

HTTP 요청을 보내고 응답을 받는 표준 인터페이스로, XMLHttpRequest를 대체하기 위해 등장했습니다.

Promise 기반으로 설계되어 async/await와 자연스럽게 연동됩니다.

const res = await fetch('https://api.example.com/posts');

if (!res.ok) {
  throw new Error(`HTTP error: ${res.status}`);
}

const data = await res.json();

fetch는 Response 객체를 반환합니다. 응답 본문을 읽으려면 .json(), .text(), .blob() 등의 메서드를 명시적으로 호출해야 합니다.

한 가지 중요한 점은, fetch는 네트워크 오류가 아닌 이상 HTTP 에러(4xx, 5xx)에서도 Promise를 reject하지 않는다는 것입니다.

따라서 res.ok 또는 res.status를 직접 확인해 에러를 처리하는 습관이 필요합니다.

Next.js의 fetch - 캐싱 시스템과 함께 동작한다

Next.js는 기존 fetch Web API를 그대로 사용하되, 서버 환경에서 동작할 수 있도록 확장했습니다.

Node.js 18 이전에는 서버 환경에서 fetch가 기본 제공되지 않아 node-fetch나 axios 같은 별도 라이브러리가 필요했지만, 이제는 클라이언트와 서버 모두에서 동일한 fetch API를 사용할 수 있습니다.

더 중요한 차이는 Next.js의 fetch가 내장 캐싱 시스템과 연결되어 있다는 점입니다. 단순히 데이터를 가져오는 것을 넘어, 그 데이터를 언제까지 보관하고 언제 다시 가져올지를 선언적으로 제어할 수 있습니다.

// 캐시 전략을 명시적으로 지정
const res = await fetch('https://api.example.com/posts', {
  cache: 'no-store',        // 항상 최신 데이터
  // cache: 'force-cache',  // 캐시 최대 활용
  // next: { revalidate: 60 } // 60초마다 갱신
});

요청 중복 제거 (Deduplication)

Server Components에서 여러 컴포넌트가 동일한 URL로 fetch를 호출하더라도, Next.js는 동일한 요청 주기 내에서 이를 자동으로 중복 제거합니다.

같은 렌더링 트리 안에서 같은 URL을 여러 번 호출해도 실제 네트워크 요청은 한 번만 발생한다는 의미입니다.

덕분에 각 컴포넌트가 필요한 데이터를 독립적으로 요청하도록 설계해도 불필요한 성능 낭비 없이 구조를 깔끔하게 유지할 수 있습니다.

fetch API 캐싱 전략 - 데이터는 언제 새로 가져와야 하는가

Next.js의 fetch에서 가장 중요한 개념 중 하나는 캐싱 전략입니다.

같은 URL이라도 어떤 옵션을 지정하느냐에 따라 전혀 다른 동작을 합니다.

no-store - 항상 최신 데이터

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

매 요청마다 서버에서 새 데이터를 가져옵니다.

캐시를 전혀 사용하지 않기 때문에 항상 최신 상태를 보장하지만, 그만큼 서버 부하와 응답 시간이 늘어납니다.

실시간 대시보드, 주식 시세, 채팅 메시지처럼 데이터 변경이 잦은 상황에 적합합니다.

Next.js 15부터는 이 옵션이 fetch의 기본값으로 변경되었습니다.

force-cache - 최대한 캐시 사용

fetch(url, { cache: 'force-cache' })

한 번 가져온 데이터를 계속 재사용합니다.

블로그 글, 정적 문서처럼 데이터 변경이 드문 콘텐츠에 적합합니다.

데이터를 매번 새로 요청하지 않기 때문에 서버 부하를 줄이고 응답 속도를 높일 수 있지만,

데이터가 바뀌어도 캐시가 갱신되기 전까지는 오래된 내용이 표시될 수 있다는 점을 감안해야 합니다.

revalidate - ISR 기반 갱신

fetch(url, { next: { revalidate: 60 } })

60초마다 데이터를 재검증합니다.

캐시를 활용하면서도 주기적으로 최신 데이터를 반영할 수 있어, 성능과 최신성 사이의 균형을 맞추는 전략입니다.

상품 목록, 뉴스 피드처럼 실시간성이 완벽하게 필요하진 않지만 어느 정도 최신 상태를 유지해야 하는 데이터에 잘 맞습니다.

이 방식은 Next.js의 ISR(Incremental Static Regeneration)을 fetch 단위로 적용하는 것과 동일합니다.

태그 기반 캐싱

fetch(url, { next: { tags: ['posts'] } })

특정 태그를 붙여두면, 나중에 그 태그를 기준으로 캐시를 무효화할 수 있습니다.

시간 기반 갱신이 아니라 특정 이벤트(글 작성, 수정 등)가 발생했을 때 정확히 해당 데이터만 다시 불러오고 싶을 때 유용합니다.

뒤에서 설명할 revalidateTag와 함께 사용하면 데이터 단위의 정밀한 캐시 제어가 가능합니다.

Server Actions - 서버에서 직접 처리하는 로직

Server Actions는 클라이언트에서 서버 함수를 직접 호출할 수 있는 기능입니다.

파일 상단 또는 함수 내부에 'use server' 지시어를 선언하는 것만으로 해당 함수는 서버에서만 실행되며,

클라이언트에서는 마치 일반 함수를 호출하듯 사용할 수 있습니다.

1. Next.js 내부에서 DB를 직접 사용하는 경우

서버에서 직접 DB에 접근하는 구조입니다.

게시물 작성 예시

// app/actions.ts
'use server';

import db from '@/lib/db';
import { revalidatePath } from 'next/cache';

export async function createPost(formData: FormData) {
  const title = formData.get('title') as string;

  await db.post.create({
    data: { title },
  });

  // 데이터 변경 후 화면 갱신
  revalidatePath('/posts');
}

동작 흐름

사용자가 폼 제출
Next.js가 자동으로 서버 요청 생성
서버에서 createPost 실행
DB에 데이터 저장
revalidatePath로 캐시 무효화
페이지가 최신 데이터로 다시 렌더링

2. 외부 백엔드 API를 사용하는 경우

Server Actions는 DB뿐만 아니라 외부 API를 감싸는 서버 레이어(BFF, BackEnd-For-FrontEnd) 로도 사용할 수 있습니다.

댓글 작성 예시

// app/actions.ts
'use server';

import { revalidatePath } from 'next/cache';

export async function createComment(formData: FormData) {
  const postId = formData.get('postId');
  const content = formData.get('content');

  await fetch(`${process.env.API_URL}/comments`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      postId,
      content,
    }),
  });

  // 댓글 작성 후 해당 게시글 페이지 갱신
  revalidatePath(`/posts/${postId}`);
}

클라이언트에서는 공통적으로 다음과 같이 사용할 수 있습니다.

<form action={createPost}>
  <input name="title" />
  <button type="submit">등록</button>
</form>

useActionState - 폼 상태 관리

React 19에서는 useActionState를 통해 Server Action의 상태를 직접 관리할 수 있습니다. 기존에는 폼 제출 결과를 처리하기 위해 별도의 useState와 try/catch 로직을 작성해야 했지만, 이 훅을 사용하면 서버 응답 상태를 선언적으로 다룰 수 있습니다.

'use client';

import { useActionState } from 'react';
import { createPost } from './actions';

const initialState = { message: '', success: false };

export function PostForm() {
  const [state, formAction, isPending] = useActionState(createPost, initialState);

  return (
    <form action={formAction}>
      <input name="title" />
      {state.message && (
        <p className={state.success ? 'text-green-600' : 'text-red-600'}>
          {state.message}
        </p>
      )}
      <button disabled={isPending}>
        {isPending ? '등록 중...' : '등록'}
      </button>
    </form>
  );
}

첫 번째 반환값 state는 Server Action이 반환한 최신 상태이고, 두 번째 formAction은 폼에 연결할 액션 함수입니다. 세 번째 isPending은 액션이 진행 중인지를 나타내며, 이를 통해 제출 버튼 비활성화나 로딩 UI를 별도의 상태 없이 간단히 구현할 수 있습니다.

useFormStatus - 로딩 상태 제어

useFormStatus는 가장 가까운 상위 <form>의 제출 상태를 읽어오는 훅입니다. useActionState의 isPending과 역할이 비슷해 보이지만, 용도가 다릅니다.

useFormStatus는 폼과 분리된 자식 컴포넌트에서 제출 상태를 읽어야 할 때 유용합니다.

버튼 컴포넌트를 별도로 분리하거나, 폼 내부의 여러 요소가 제출 상태에 반응해야 하는 상황에서 특히 깔끔한 해법이 됩니다.

'use client';

import { useFormStatus } from 'react-dom';

function SubmitButton() {
  const { pending } = useFormStatus();

  return (
    <button disabled={pending}>
      {pending ? '등록 중...' : '등록'}
    </button>
  );
}

SubmitButton은 폼의 내부 구조를 전혀 알 필요가 없습니다. 상위에 <form>이 있다면 그 폼의 제출 상태를 자동으로 구독하기 때문에, 폼 로직과 버튼 UI를 완전히 분리하면서도 중복 제출 방지와 사용자 피드백을 자연스럽게 처리할 수 있습니다.

캐시 무효화 - 데이터를 언제 다시 그릴 것인가

Server Actions로 데이터를 변경한 뒤에는 화면을 최신 상태로 갱신해야 합니다.

Next.js는 이를 위한 캐시 무효화 API를 제공합니다.

revalidatePath

import { revalidatePath } from 'next/cache';

revalidatePath('/posts');

특정 경로에 해당하는 페이지 캐시를 무효화합니다.

다음 요청 시 서버에서 해당 페이지를 다시 렌더링합니다.

글을 새로 작성한 뒤 목록 페이지를 갱신하거나, 설정을 변경한 뒤 해당 페이지를 최신 상태로 보여줘야 할 때 사용합니다.

revalidateTag

import { revalidateTag } from 'next/cache';

revalidateTag('posts');

fetch 옵션에서 tags로 지정한 태그를 기준으로 캐시를 무효화합니다. 페이지 단위가 아니라 데이터 단위로 캐시를 제어할 수 있어, 여러 페이지에서 동일한 데이터를 공유하는 구조에서 특히 효과적입니다.

예를 들어 글 목록과 글 상세 페이지가 모두 'posts' 태그를 사용하고 있다면, revalidateTag('posts') 한 번으로 두 페이지의 캐시를 동시에 무효화할 수 있습니다.

revalidatePath는 특정 URL 경로를 알고 있을 때, revalidateTag는 여러 경로에 걸쳐 있는 데이터를 한 번에 무효화하고 싶을 때 각각 사용하면 됩니다.

두 API를 조합하면 데이터 단위와 페이지 단위 모두에서 정밀하게 캐시를 제어할 수 있습니다.

Route Handlers vs Server Actions - 무엇을 선택해야 할까

두 가지 방식은 역할이 다릅니다. 선택 기준은 "누가 이 로직을 호출하는가"로 단순하게 정리할 수 있습니다.

Route Handlers는 app/api 디렉토리 아래에 위치하며, HTTP 엔드포인트를 만드는 방식입니다. 외부 시스템이나 서드파티 서비스가 호출해야 하는 API, REST 또는 GraphQL 구조가 필요한 경우, 웹훅 수신, 복잡한 인증 미들웨어 처리 등이 해당됩니다. 외부에 공개되는 인터페이스가 필요할 때 선택합니다.

Server Actions는 앱 내부의 UI와 강하게 결합된 로직에 적합합니다. 폼 제출, 간단한 데이터 생성·수정·삭제, 같은 앱 안에서만 사용하는 비즈니스 로직이 이에 해당합니다. API 엔드포인트 없이 서버 함수를 직접 호출하기 때문에 코드가 간결해지고, 타입 안정성도 자연스럽게 유지됩니다.

정리하면, 외부에 공개하는 API라면 Route Handler를, 내부 UI 로직이라면 Server Actions를 선택하는 것이 명확한 기준입니다.

Streaming & Suspense - 느린 데이터도 빠르게 보여주기

데이터 페칭에서 가장 흔한 UX 문제는 "느린 데이터 때문에 전체 페이지가 지연되는 것"입니다.

댓글 목록처럼 무거운 데이터가 로딩될 때까지 페이지 전체가 블로킹되면,
빠르게 렌더링될 수 있는 본문 영역까지 함께 지연됩니다.

Next.js는 Streaming을 통해 이 문제를 해결합니다.

React의 Suspense와 결합하면, 느린 데이터를 기다리는 동안 빠른 부분은 즉시 렌더링하고,

느린 부분은 나중에 스트리밍으로 채워 넣을 수 있습니다.

Streaming이란?

Streaming은 페이지를 한 번에 완성해서 보내는 것이 아니라, 준비된 부분부터 먼저 클라이언트에 전달하는 방식입니다.
이를 통해 서버는 빠르게 준비된 UI부터 먼저 전송하고, 느리게 도착하는 데이터는 나중에 이어서 전달할 수 있습니다.

결과적으로 사용자는 페이지의 일부를 이미 확인할 수 있는 상태에서 나머지 콘텐츠가 점진적으로 채워지는 경험을 하게 됩니다.

Suspense란?

Suspense는 React에서 아직 준비되지 않은 컴포넌트를 기다리는 동안 fallback UI를 보여주는 기능입니다.

다음과 같이 사용할 수 있습니다.

import { Suspense } from 'react';

<Suspense fallback={<Loading />}>
  <Component />
</Suspense>

Suspense로 감싸진 컴포넌트가 데이터를 아직 가져오지 못한 상태라면,

React는 해당 컴포넌트의 렌더링을 잠시 멈추고 fallback UI를 대신 보여줍니다.

그리고 데이터가 준비되는 순간, 해당 부분만 다시 렌더링하여 화면을 교체합니다.

Suspense와 Streaming을 함께 활용하기

이제 Streaming과 Suspense를 함께 사용하는 예시를 살펴보겠습니다.

async function Comments() {
  const res = await fetch("https://api.example.com/comments");
  const comments = await res.json();

  return (
    <ul>
      {comments.map((c) => (
        <li key={c.id}>{c.content}</li>
      ))}
    </ul>
  );
}

import { Suspense } from 'react';
import Comments from './Comments';

export default function PostPage() {
  return (
    <article>
      <h1>게시글 제목</h1>
      <p>본문 내용...</p>

      {/* 댓글은 느리게 로딩될 수 있으므로 Suspense로 감싼다 */}
      <Suspense fallback={<div>댓글을 불러오는 중...</div>}>
        <Comments />
      </Suspense>
    </article>
  );
}

먼저 게시글 제목과 본문은 즉시 렌더링되어 사용자에게 전달됩니다.
이와 동시에 Comments 컴포넌트는 데이터를 요청하게 되지만, 아직 응답이 도착하지 않았기 때문에
Suspense가 이를 감지하고 fallback UI를 대신 렌더링합니다.

이 상태에서 사용자는 이미 본문을 읽고 있는 상황이 되고,
댓글 영역에는 “댓글을 불러오는 중...”이라는 메시지가 표시됩니다.

이후 댓글 데이터가 도착하면, 해당 부분만 다시 렌더링되어
fallback UI가 실제 댓글 목록으로 자연스럽게 교체됩니다.

이 모든 과정은 페이지 전체를 다시 그리는 것이 아니라
필요한 부분만 업데이트되며, 그 사이의 데이터 전달은 Streaming을 통해 이루어집니다.

이 구조의 핵심은 “전체를 기다리지 않는다”는 점입니다.

기존 방식에서는 모든 데이터가 준비될 때까지 화면이 지연되었지만,

Streaming과 Suspense를 사용하면 준비된 UI부터 먼저 사용자에게 보여줄 수 있습니다.

그 결과 초기 렌더링 속도와 사용자 체감 속도가 동시에 개선됩니다.

또한 이 구조는 Server Actions와도 자연스럽게 연결됩니다.

예를 들어 댓글을 작성한 뒤 revalidatePath를 통해 페이지 캐시를 무효화하면,

페이지는 다시 렌더링되면서 댓글 영역은 다시 Suspense 상태로 들어가게 됩니다.

이때 fallback UI가 잠시 표시되고, 이후 최신 댓글 데이터가 Streaming을 통해 채워지게 됩니다.

데이터 변경 -> 캐시 무효화 -> 부분 렌더링 -> Streaming 업데이트

라는 흐름을 구현할 수 있게 됩니다.

마무리

fetch를 어떤 옵션으로 사용하느냐에 따라 페이지가 정적이 될 수도, 동적이 될 수도, 주기적으로 갱신될 수도 있습니다.

이 글에서 다룬 개념들을 바탕으로, 실제 프로젝트에서 "어디서 데이터를 가져오고, 어디서 처리하고, 언제 갱신할지"를 직접 고민해보시면 그 차이를 바로 체감하실 수 있을 것입니다.

읽어주셔서 감사합니다!

TanStack Query 에 대해서 알아보기!

수달군 — Sat, 4 Apr 2026 04:45:31 +0900

왜 TanStack Query를 사용해야 할까요?

TanStack Query는 React 애플리케이션에서 서버 상태(Server State) 를 효율적으로 다루기 위한 라이브러리입니다.
예전에는 React Query라는 이름으로 많이 알려져 있었고, v4부터 TanStack Query로 이름이 바뀌었습니다.

React에서 상태는 크게 두 가지로 나눌 수 있습니다.

하나는 사용자 입력, 모달 열림 여부, 탭 상태처럼 프론트엔드 내부에서 직접 관리하는 클라이언트 상태이고,
다른 하나는 서버에서 받아오고, 다시 동기화해야 하며, 시간이 지나면 낡을 수 있는 서버 상태입니다.

서버 상태는 다음과 같은 특징을 가집니다 :

비동기다 (요청 → 응답 기다림)
실패할 수 있다
여러 컴포넌트에서 공유된다
시간이 지나면 낡는다 (stale)
다시 가져올 타이밍을 결정해야 한다

이러한 요소들을 useState나 useEffect로 다루기엔 로직이 계속 반복되고 점점 복잡해질 수 있습니다.

Tanstack Query (구 React Query)는 이러한 복잡한 문제를 손쉽게 다루기 위해 나온 라이브러리입니다.

TanStack Query 없이 데이터를 가져오면 보통 이렇게 작성합니다.

const [data, setData] = useState(null);
const [isLoading, setIsLoading] = useState(false);
const [error, setError] = useState(null);

useEffect(() => {
  setIsLoading(true);
  fetch("/api/posts")
    .then((res) => res.json())
    .then((data) => {
      setData(data);
      setIsLoading(false);
    })
    .catch((err) => {
      setError(err);
      setIsLoading(false);
    });
}, []);

이 코드를 모든 API 호출마다 반복해야 합니다.

그러나 TanStack Query를 쓰면 같은 작업이 이렇게 줄어듭니다.

const { data, isLoading, error } = useQuery({
  queryKey: ["posts"],
  queryFn: () => fetch("/api/posts").then((res) => res.json()),
});

코드가 줄어드는 것 이상으로, 캐싱 / 재요청 / 에러 처리 / 로딩 상태 관리까지 자동으로 챙겨줍니다.

이렇게 편리한 기능을 사용할 수 있는 TanStack Query에 대해서 본격적으로 알아봅시다!

설치와 기본 세팅

설치

npm install @tanstack/react-query

개발 중 쿼리 상태를 눈으로 확인하고 싶다면 DevTools도 함께 설치하는 것을 추천합니다.

npm install @tanstack/react-query-devtools

QueryClient와 QueryClientProvider 설정

앱의 최상단에서 QueryClient를 생성하고 QueryClientProvider로 감싸야 합니다.

이 설정이 있어야 앱 어디서든 TanStack Query 훅을 사용할 수 있습니다.

// main.tsx 또는 App.tsx
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { ReactQueryDevtools } from "@tanstack/react-query-devtools";

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 1000 * 60,  // 기본 staleTime: 1분
      retry: 1,              // 실패 시 1회 재시도
    },
  },
});

export default function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <MyApp />
      {/* 개발 환경에서만 Devtools 표시 */}
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  );
}

QueryClient는 앱 전체에서 공유하는 캐시 저장소입니다.
defaultOptions로 모든 쿼리에 공통 설정을 적용할 수 있어, 각 훅마다 같은 옵션을 반복할 필요가 없습니다.

useQuery - 데이터 읽기

서버에서 데이터를 가져올 때 사용하는 기본 훅입니다. 반드시 queryKey와 queryFn 두 가지를 전달해야 합니다.

import { useQuery } from "@tanstack/react-query";

async function fetchPosts() {
  const res = await fetch("/api/posts");
  if (!res.ok) throw new Error("데이터를 불러오지 못했습니다.");
  return res.json();
}

function PostList() {
  const { data, isLoading, isError, error } = useQuery({
    queryKey: ["posts"],   // 이 데이터를 구분하는 고유 키
    queryFn: fetchPosts,   // 실제 데이터를 가져오는 함수
  });

  if (isLoading) return <div>로딩 중...</div>;
  if (isError) return <div>에러: {error.message}</div>;

  return (
    <ul>
      {data.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  );
}

동적 데이터 - queryKey에 변수 넣기

특정 ID에 해당하는 데이터를 가져올 때는 queryKey에 해당 변수를 함께 넣어야 합니다.

키가 바뀌면 자동으로 새 요청을 보냅니다.

function PostDetail({ postId }: { postId: number }) {
  const { data, isLoading } = useQuery({
    queryKey: ["posts", "detail", postId],  // postId가 바뀌면 자동으로 재요청
    queryFn: () =>
      fetch(`/api/posts/${postId}`).then((r) => r.json()),
  });

  if (isLoading) return <div>로딩 중...</div>;
  return <h1>{data.title}</h1>;
}

queryFn에서 에러가 발생하려면 반드시 throw를 해야 합니다.
fetch는 404, 500 응답도 성공으로 처리하므로, res.ok를 체크하고 직접 throw하는 습관이 중요합니다.

자주 쓰는 옵션

enabled	false이면 쿼리를 실행하지 않습니다. 특정 조건이 충족됐을 때만 요청할 때 씁니다.
staleTime	데이터를 신선하게 볼 시간(ms). 이 시간 안에는 재요청하지 않습니다.
refetchOnWindowFocus	탭을 다시 활성화했을 때 자동으로 재요청할지 여부. 기본값은 true입니다.
retry	실패 시 재시도 횟수. 기본값은 3입니다.
select	응답 데이터를 가공해서 반환합니다. 원본 캐시는 그대로 유지됩니다.
placeholderData	데이터가 없을 때 보여줄 임시 데이터입니다. 스켈레톤 대신 쓸 수 있습니다.

// enabled 예시 — userId가 있을 때만 요청
const { data } = useQuery({
  queryKey: ["user", userId],
  queryFn: () => fetchUser(userId),
  enabled: !!userId,
});

// select 예시 — 제목만 추출해서 반환
const { data: titles } = useQuery({
  queryKey: ["posts"],
  queryFn: fetchPosts,
  select: (data) => data.map((post) => post.title),
});

useMutation - 데이터 쓰기

데이터를 생성/수정/삭제할 때 사용하는 훅입니다.
useQuery와 달리 자동으로 실행되지 않고, mutate()를 직접 호출해야 실행됩니다.

import { useMutation, useQueryClient } from "@tanstack/react-query";

async function createPost(newPost: { title: string; body: string }) {
  const res = await fetch("/api/posts", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(newPost),
  });
  if (!res.ok) throw new Error("게시글 생성 실패");
  return res.json();
}

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

  const mutation = useMutation({
    mutationFn: createPost,
    onSuccess: () => {
      // 성공하면 게시글 목록 캐시를 무효화 → 다음 접근 시 재요청 발생
      queryClient.invalidateQueries({ queryKey: ["posts"] });
    },
    onError: (error) => {
      alert(`에러: ${error.message}`);
    },
  });

  const handleSubmit = () => {
    mutation.mutate({ title: "새 게시글", body: "내용입니다." });
  };

  return (
    <button onClick={handleSubmit} disabled={mutation.isPending}>
      {mutation.isPending ? "저장 중..." : "게시글 작성"}
    </button>
  );
}

useMutation의 콜백 함수들

onSuccess	요청이 성공했을 때 실행됩니다. 캐시 무효화나 리다이렉트 처리를 주로 합니다.
onError	요청이 실패했을 때 실행됩니다. 에러 메시지 표시나 롤백 처리를 합니다.
onSettled	성공/실패 관계없이 항상 실행됩니다. 최종 동기화나 로딩 해제에 씁니다.
onMutate	요청 직전에 실행됩니다. Optimistic Update의 시작점입니다.

useQueryClient - 캐시 직접 다루기

useQueryClient는 캐시에 직접 접근할 수 있는 훅입니다.

주로 mutation 이후 캐시를 갱신하거나, 특정 쿼리를 강제로 다시 가져올 때 씁니다.

const queryClient = useQueryClient();

// 특정 쿼리 캐시를 무효화 → 다음 접근 시 재요청 발생
queryClient.invalidateQueries({ queryKey: ["posts"] });

// 캐시에 직접 데이터 쓰기 → 재요청 없이 즉시 반영
queryClient.setQueryData(["posts", "detail", 1], updatedPost);

// 캐시에서 데이터 읽기
const cachedPost = queryClient.getQueryData(["posts", "detail", 1]);

// 미리 데이터 가져오기 (Prefetch)
await queryClient.prefetchQuery({
  queryKey: ["posts", "detail", 2],
  queryFn: () => fetchPostDetail(2),
});

invalidateQueries는 캐시를 "낡았다"고 표시해 다음 접근 시 재요청을 유도합니다.
setQueryData는 재요청 없이 캐시를 직접 덮어씁니다. 이 둘의 차이를 이해하면 mutation 후처리가 훨씬 명확해집니다.

주요 상태값 한눈에 보기

useQuery와 useMutation이 반환하는 상태값은 처음엔 헷갈릴 수 있습니다. 자주 쓰는 것들만 정리했습니다.

useQuery 상태

isLoading	캐시가 없고 처음으로 데이터를 가져오는 중
isFetching	백그라운드 포함, 요청이 진행 중인 모든 상태
isSuccess	데이터를 성공적으로 가져온 상태
isError	요청이 실패한 상태
isStale	staleTime이 지나 데이터가 낡은 상태
isPending	데이터가 아직 없는 상태 (v5 이상)

isLoading은 캐시가 없어 처음 로딩 중일 때만 true입니다. isFetching은 백그라운드에서 갱신 중일 때도 true입니다. 스켈레톤 UI에는 isLoading을, 상단 로딩 바에는 isFetching을 쓰는 것이 일반적입니다.

useMutation 상태

isPending	요청이 진행 중인 상태
isSuccess	요청이 성공한 상태
isError	요청이 실패한 상태
isIdle	아직 실행되지 않은 초기 상태

실전 예제 -게시글 CRUD

지금까지 배운 것들을 하나로 묶어봅니다. 게시글 목록 조회, 상세 조회, 생성, 삭제를 모두 담은 예제입니다.

// api.ts — API 함수 정의
export const api = {
  getPosts: () =>
    fetch("/api/posts").then((r) => r.json()),

  getPost: (id: number) =>
    fetch(`/api/posts/${id}`).then((r) => r.json()),

  createPost: (data: { title: string; body: string }) =>
    fetch("/api/posts", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(data),
    }).then((r) => r.json()),

  deletePost: (id: number) =>
    fetch(`/api/posts/${id}`, { method: "DELETE" }),
};

// postKeys.ts — Query Key 팩토리
export const postKeys = {
  all: ["posts"] as const,
  lists: () => [...postKeys.all, "list"] as const,
  detail: (id: number) => [...postKeys.all, "detail", id] as const,
};

// PostList.tsx — 목록 조회 + 삭제
function PostList() {
  const queryClient = useQueryClient();

  const { data: posts, isLoading } = useQuery({
    queryKey: postKeys.lists(),
    queryFn: api.getPosts,
  });

  const deleteMutation = useMutation({
    mutationFn: api.deletePost,
    onSuccess: () => {
      // 삭제 성공 시 목록 캐시 무효화
      queryClient.invalidateQueries({ queryKey: postKeys.lists() });
    },
  });

  if (isLoading) return <div>로딩 중...</div>;

  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>
          {post.title}
          <button
            onClick={() => deleteMutation.mutate(post.id)}
            disabled={deleteMutation.isPending}
          >
            삭제
          </button>
        </li>
      ))}
    </ul>
  );
}

// CreatePost.tsx — 게시글 생성
function CreatePost() {
  const queryClient = useQueryClient();
  const [title, setTitle] = useState("");

  const createMutation = useMutation({
    mutationFn: api.createPost,
    onSuccess: (newPost) => {
      // 목록 캐시 무효화 → 새 글이 포함된 목록을 다시 가져옴
      queryClient.invalidateQueries({ queryKey: postKeys.lists() });

      // 생성된 글을 상세 캐시에 바로 저장 → 상세 진입 시 재요청 없이 즉시 표시
      queryClient.setQueryData(postKeys.detail(newPost.id), newPost);
    },
  });

  return (
    <div>
      <input
        value={title}
        onChange={(e) => setTitle(e.target.value)}
        placeholder="게시글 제목"
      />
      <button
        onClick={() => createMutation.mutate({ title, body: "" })}
        disabled={createMutation.isPending || !title}
      >
        {createMutation.isPending ? "저장 중..." : "작성"}
      </button>
      {createMutation.isError && (
        <p style={{ color: "red" }}>저장에 실패했습니다.</p>
      )}
    </div>
  );
}

생성 후 invalidateQueries와 setQueryData를 함께 쓰는 패턴은 실무에서 흔합니다. 목록은 서버에서 다시 받아오고, 상세는 응답 데이터를 바로 캐시에 넣어 다음 진입 시 즉시 보여줄 수 있습니다.

기초 정리 체크리스트

QueryClientProvider로 앱 최상단을 감싼다
데이터 읽기는 useQuery, 데이터 쓰기는 useMutation
queryKey는 리소스 종류와 조회 조건을 모두 포함한다
queryFn에서 에러가 나면 반드시 throw를 한다
mutation 성공 후에는 관련 캐시를 invalidateQueries로 무효화한다
isLoading과 isFetching의 차이를 구분해서 UI에 적용한다
개발 중에는 Devtools로 캐시 상태를 항상 확인한다

Query Key 설계 전략과 캐시 관리

TanStack Query에서 Query Key는 캐시를 식별하는 기준입니다.

필터·정렬·페이지네이션이 붙기 시작하면 단순한 이름표로 다루기 어려워집니다. 조건이 다른 요청이 같은 캐시를 공유하거나, 의도치 않게 캐시가 재사용되는 문제가 생깁니다.

좋은 Query Key의 조건

리소스 종류가 드러나야 합니다. 게시글 목록인지, 상세인지, 댓글인지 — 키만 봐도 구분이 가야 합니다.

조회 조건이 키에 포함되어야 합니다. 페이지 번호, 정렬 기준, 검색어가 빠지면 서로 다른 조건의 요청이 같은 캐시를 바라보게 됩니다.

일관된 계층 구조를 가져야 합니다.

["posts"]
["posts", "list", { page, sort, category }]
["posts", "detail", postId]
["posts", "comments", postId]

이 구조를 유지하면 ["posts"]를 invalidate하는 것만으로 하위 캐시 전체를 무효화할 수 있습니다.

Query Key Factory 패턴

프로젝트가 커질수록 Query Key를 하드코딩하는 방식은 유지보수가 어려워집니다. 이럴 때 쓰는 것이 Query Key Factory 패턴입니다.

export const postKeys = {
  all: ["posts"] as const,
  lists: () => [...postKeys.all, "list"] as const,
  list: (params: { page: number; sort: string; category?: string }) =>
    [...postKeys.lists(), params] as const,
  details: () => [...postKeys.all, "detail"] as const,
  detail: (id: number) => [...postKeys.details(), id] as const,
};

useQuery({
  queryKey: postKeys.list({ page: 1, sort: "latest", category: "react" }),
  queryFn: () => fetchPosts({ page: 1, sort: "latest", category: "react" }),
});

오타를 줄이고, invalidateQueries나 setQueryData를 쓸 때 실수를 방지해 줍니다.
부수적으로 캐시 구조를 코드로 문서화하는 역할도 합니다.

staleTime, gcTime

Query Key 설계만큼 캐시 정책도 같이 잡아야 합니다.

staleTime 은 데이터를 신선하다고 볼 시간입니다.

useQuery({
  queryKey: postKeys.detail(1),
  queryFn: () => fetchPostDetail(1),
  staleTime: 1000 * 60,
});

1분으로 설정하면 1분 안에 같은 쿼리가 다시 마운트되어도 재요청하지 않습니다.
값이 너무 짧으면 요청이 과도해지고, 너무 길면 낡은 데이터를 오래 보여주게 됩니다.

자주 바뀌지 않는 데이터는 길게, 실시간성이 중요한 데이터는 짧게 가져가는 것이 일반적입니다.

gcTime 은 사용하지 않는 캐시를 메모리에 얼마나 유지할지 결정합니다.

staleTime이 신선도의 문제라면, gcTime은 보관 기간의 문제입니다. 둘을 혼동하지 않는 것이 중요합니다.

invalidateQueries vs setQueryData

mutation 이후에 무조건 invalidateQueries만 쓰는 경우가 많은데, 상황에 따라 setQueryData가 더 적합할 때가 있습니다.

// 데이터를 다시 가져와야 할 때
queryClient.invalidateQueries({ queryKey: postKeys.lists() });

// 서버 응답을 이미 갖고 있을 때
queryClient.setQueryData(postKeys.detail(post.id), post);

서버 응답으로 확정된 데이터를 캐시에 바로 반영할 수 있다면 setQueryData가 효율적입니다. 영향 범위가 넓거나 최신 상태를 반드시 서버에서 받아와야 한다면 invalidateQueries가 안전합니다.

Optimistic Update 패턴 심화

개념

서버 응답을 기다리지 않고 UI를 먼저 바꾸는 방식입니다. 좋아요 수를 누르는 즉시 올려 보여주고, 실패하면 되돌리는 식입니다. UX를 크게 개선할 수 있지만, 잘못 쓰면 데이터 불일치나 롤백 복잡도가 높아집니다.

기본 흐름

const mutation = useMutation({
  mutationFn: toggleLike,
  onMutate: async (postId: number) => {
    // 진행 중인 쿼리 취소 — 덮어쓰기 충돌 방지
    await queryClient.cancelQueries({ queryKey: postKeys.detail(postId) });

    // 롤백을 위해 이전 데이터 저장
    const previousPost = queryClient.getQueryData(postKeys.detail(postId));

    // 캐시를 먼저 수정
    queryClient.setQueryData(postKeys.detail(postId), (old: any) => {
      if (!old) return old;
      return {
        ...old,
        liked: !old.liked,
        likeCount: old.liked ? old.likeCount - 1 : old.likeCount + 1,
      };
    });

    return { previousPost };
  },
  onError: (error, postId, context) => {
    // 실패 시 원래 상태로 복원
    if (context?.previousPost) {
      queryClient.setQueryData(postKeys.detail(postId), context.previousPost);
    }
  },
  onSettled: (_, __, postId) => {
    // 성공·실패 무관하게 서버 기준으로 재동기화
    queryClient.invalidateQueries({ queryKey: postKeys.detail(postId) });
  },
});

흐름은 단순합니다. 미리 반영하고, 실패하면 되돌리고, 끝나면 서버와 맞춥니다.

쓰면 안 되는 경우

좋아요, 북마크, 체크박스처럼 결과가 단순하고 예측 가능한 경우에 잘 맞습니다. 반면 아래 상황에서는 피하는 것이 낫습니다.

서버 검증이 복잡한 경우
실패 가능성이 높은 경우
응답이 서버 계산 결과에 크게 의존하는 경우 (slug 생성, 작성자 정보 가공 등)

이런 경우에는 로딩 상태를 보여주고 성공 후 invalidate하는 것이 더 안정적입니다.

목록과 상세 캐시를 함께 다뤄야 하는 문제

게시글 하나가 목록 캐시와 상세 캐시 양쪽에 존재하는 경우가 많습니다. 상세만 수정하고 목록을 그대로 두면 UI가 어긋납니다.

queryClient.setQueriesData(
  { queryKey: postKeys.lists() },
  (oldData: any) => {
    if (!oldData) return oldData;
    return {
      ...oldData,
      pages: oldData.pages?.map((page: any) => ({
        ...page,
        items: page.items.map((post: any) =>
          post.id === postId
            ? {
                ...post,
                liked: !post.liked,
                likeCount: post.liked ? post.likeCount - 1 : post.likeCount + 1,
              }
            : post
        ),
      })),
    };
  }
);

Optimistic Update를 설계할 때는 해당 데이터가 어느 캐시에 중복으로 존재하는지를 반드시 함께 고려해야 합니다.

Prefetching 전략과 성능 최적화

사용자가 진입하기 전에 데이터를 미리 가져와 화면 전환 시 로딩을 줄이는 전략입니다.

const handlePrefetch = (postId: number) => {
  queryClient.prefetchQuery({
    queryKey: postKeys.detail(postId),
    queryFn: () => fetchPostDetail(postId),
    staleTime: 1000 * 60,
  });
};

상세 페이지 진입 시 캐시가 이미 존재하면 로딩 없이 바로 표시되거나, 대기 시간이 크게 줄어듭니다.

효과적인 경우

모든 페이지에 붙이는 것이 아니라, 사용자의 다음 행동이 예측 가능한 지점에 한해 적용해야 합니다.

목록 → 상세 이동이 잦은 구조
탭 전환이 빈번한 구조
hover, focus, viewport 진입 시점을 활용할 수 있는 경우

예측 없이 모든 페이지를 prefetch하면 네트워크 낭비와 캐시 오염으로 이어집니다.

Infinite Query 최적화

const {
  data,
  fetchNextPage,
  hasNextPage,
  isFetchingNextPage,
} = useInfiniteQuery({
  queryKey: ["feed"],
  queryFn: ({ pageParam = 1 }) => fetchFeed(pageParam),
  initialPageParam: 1,
  getNextPageParam: (lastPage) => lastPage.nextCursor ?? undefined,
});

cursor 기반 페이지네이션

페이지 번호 방식은 중간에 데이터가 추가·삭제될 때 항목이 밀려 중복이나 누락이 발생할 수 있습니다.

cursor 기반은 "마지막으로 본 항목의 다음부터"가 기준이므로 목록이 변해도 안정적입니다.

백엔드 API 설계 단계부터 cursor 방식을 고려하는 것이 좋습니다.

성능 문제

const allPosts = data?.pages.flatMap((page) => page.items) ?? [];

흔하게 쓰는 패턴이지만 페이지가 많이 쌓이면 렌더링 비용이 올라갑니다. 이 시점부터는 리스트 가상화, memoization, item key 안정성까지 같이 고려해야 합니다.

중복 호출 방지

useEffect(() => {
  if (inView && hasNextPage && !isFetchingNextPage) {
    fetchNextPage();
  }
}, [inView, hasNextPage, isFetchingNextPage, fetchNextPage]);

hasNextPage와 isFetchingNextPage 조건이 없으면 sentinel이 보이는 동안 요청이 연속으로 나갑니다.

Error / Loading 바운더리 패턴

컴포넌트마다 처리할 때의 문제

const { data, isLoading, isError, error } = useQuery(...);

if (isLoading) return <Loading />;
if (isError) return <ErrorMessage error={error} />;
return <Content data={data} />;

페이지가 적을 때는 괜찮습니다. 화면이 늘어나면 이 분기문이 모든 컴포넌트에 반복되고, 로딩 UI와 에러 처리 기준이 제각각이 됩니다.

Suspense 기반 로딩 처리

useSuspenseQuery({
  queryKey: postKeys.detail(postId),
  queryFn: () => fetchPostDetail(postId),
});

<Suspense fallback={<PostDetailSkeleton />}>
  <PostDetail />
</Suspense>

컴포넌트 내부에서 isLoading 분기를 작성할 필요 없이, 상위에서 fallback을 통일해 관리할 수 있습니다.

QueryErrorResetBoundary

<QueryErrorResetBoundary>
  {({ reset }) => (
    <ErrorBoundary
      onReset={reset}
      fallbackRender={({ resetErrorBoundary }) => (
        <div>
          데이터를 불러오지 못했습니다.
          <button onClick={resetErrorBoundary}>다시 시도</button>
        </div>
      )}
    >
      <Suspense fallback={<div>로딩 중...</div>}>
        <PostDetail />
      </Suspense>
    </ErrorBoundary>
  )}
</QueryErrorResetBoundary>

쿼리 실패 시 Error Boundary가 에러를 잡고, "다시 시도"를 누르면 reset을 통해 쿼리가 재실행됩니다.

에러 처리 계층 나누기

모든 에러를 Boundary로 올릴 필요는 없습니다.

Boundary: 페이지 진입에 필수적인 데이터 조회 실패
로컬 메시지·토스트: 댓글 등록, 좋아요처럼 페이지 자체는 유지되어야 하는 경우
섹션 수준 fallback: 특정 영역만 실패한 경우

계층을 나눠두면 에러 처리 코드도 정리되고 UX도 자연스러워집니다.

마무리

오늘은 서버 상태 관리의 필수적이라고 봐도 무방한 TanStack Query 에 대해서 알아봤습니다.

저도 처음에 Tanstack Query를 사용했을때는 단순히 data, isFetching과 error등의 서버 상태 관리 훅만 사용하였었는데,

깊이 공부하면 할 수록 신경써야할 부분이 많다는 것을 깨달았습니다.

TanStack Query를 깊이 이해한다는 건 결국 서버 상태를 어떤 정책으로 운영할지 설계할 수 있다는 뜻입니다.

작은 프로젝트에서는 편리함이 먼저 보이지만, 규모가 커지면 설계력이 바로 드러나는 도구입니다.

여러분들도 TanStack Query를 정복하셔서 효과적인 서버 상태 관리를 이루어내셨으면 좋겠습니다!

읽어주셔서 감사합니다!