돌멩이,

Nextjs-Error UI (error.tsx)

서비스의 ‘최후 방어선’을 구축할 차례예요로딩 상태까지 잘 처리했다면, 이제는 서비스 운영 중 반드시 마주하게 되는 에러 상황을 다뤄야 해요.외부 API 장애, DB 연결 문제, 예상치 못한 런타임 에러는 언제든 발생할 수 있어요. 이때 사용자가 보게 되는 화면이 하얀 화면이나 에러 코드라면 신뢰는 바로 무너져요.그래서 중요한 건 에러를 숨기는 게 아니라, 우아하게 처리하는 것이에요.1. 에러는 관리하는 대상이에요서비스가 깨지는 순간에도 UX는 유지되어야 해요.“서비스가 완전히 고장 났네” “일시적인 문제인가 보네, 다시 해봐야지” ✅이 차이를 만드는 게 바로 error.tsx예요.2. 의도적으로 에러 상황 만들어보기먼저 에러가 어떻게 터지는지 확인해볼게요.export default async function ProductsPage() { await new Promise((resolve) => setTimeout(resolve, 3000)); if (Math.random() < 0.5) { throw new Error('데이터를 불러오지 못했습니다.'); } return <div>상품 리스트</div>; }문제 상황50% 확률로 화면이 깨져요하얀 화면 또는 에러 오버레이가 보여요사용자 입장에서는 그냥 “망가진 서비스”예요3. error.tsx의 핵심 규칙반드시 지켜야 할 2가지파일명은 error.tsx (소문자)반드시 'use client' 선언버튼 클릭 같은 인터랙션이 필요하기 때문이에요

2026. 04. 07

Nextjs-Loading UI (loading.tsx) 기다림조차 디자인하는 스트리밍(Streaming) SSR

이번에는 Next.js 15의 Streaming SSR과 loading.tsx를 활용해서 이 기다림을 자연스럽고 세련된 UX로 바꾸는 방법을 정리해볼게요.상품 데이터가 많아서 로딩에 3초가 걸릴 때, 아무 화면도 없이 하얀 화면만 보여준다면 사용자 입장에서는 서비스가 멈췄다고 느끼게 돼요. 이 경험은 이탈로 바로 이어질 가능성이 높아요.1. 하얀 화면은 서비스 중단처럼 느껴져요사용자가 페이지를 이동했는데 아무 변화 없이 멈춰 있는 화면만 보이면, 대부분 다음처럼 생각해요.인터넷이 끊겼나?앱이 고장 났나?그냥 나가야겠다그래서 중요한 건 “지금 뭔가 진행 중이다”라는 신호를 명확하게 주는 거예요.2. 인위적인 지연으로 문제 상황 만들기먼저 실제로 느린 상황을 만들어서 문제를 확인해볼게요.// src/app/products/page.tsx export default async function ProductsPage() { await new Promise((resolve) => setTimeout(resolve, 3000)); const products = [ { id: 1, name: 'Premium Wireless Headphone', price: '$299' }, { id: 2, name: 'Ergonomic Office Chair', price: '$150' }, ]; return ( <div> <h1>Best Sellers</h1> </div> ); }현재 문제클릭해도 바로 화면이 바뀌지 않아요3초 동안 아무것도 안 보이다가 갑자기 렌더링돼요사용자 입장에서는 “멈췄다”라고 느껴요 3. loading.tsx로 로딩 UI 만들기이 문제는 loading.tsx 하나로 해결할 수 있어요.// src/app/loading.tsx export default function Loading() { return ( <div className="fixed inset-0 flex items-center justify-center bg-white/80 backdrop-blur-sm"> <div className="flex flex-col items-center gap-4"> <div className="w-16 h-16 border-4 border-indigo-600 border-t-transparent rounded-full animate-spin"></div> <p className="text-indigo-600 font-semibold"> Loading... </p> </div> </div> ); }핵심 포인트loading.tsx는 Next.js에서 예약된 파일이에요데이터가 로딩되는 동안 자동으로 이 컴포넌트를 보여줘요별도의 코드 연결 없이도 동작해요

2026. 04. 07

Nextjs-404페이지 notFound() 관리하기

이번에는 길을 잃은 사용자를 위한 안내 페이지, not-found.tsx 파일과 notFound() 함수를 2026년 Next.js 15+ 표준 방식에 맞게 정리해볼게요.1. 404 페이지도 하나의 브랜드 경험이에요웹 서비스에서 404 에러(Page Not Found)는 피할 수 없는 상황이에요. 하지만 Next.js App Router에서는 not-found.tsx라는 약속된 파일을 사용해서 이 상황을 훨씬 자연스럽고 친절하게 처리할 수 있어요.파일 배치 규칙: 글로벌 vs 로컬Next.js는 에러가 발생했을 때 현재 위치에서 가장 가까운 not-found.tsx를 찾아서 렌더링해요.src/app/not-found.tsx → 전체 서비스에서 사용하는 글로벌 404 페이지예요.src/app/blog/not-found.tsx → /blog 경로에서만 동작하는 로컬 404 페이지예요. 특정 도메인에 맞는 메시지를 보여주고 싶을 때 유용해요.2. 글로벌 404 페이지 UI 구성프로젝트 최상단에 src/app/not-found.tsx 파일을 만들고, 사용자가 자연스럽게 홈으로 돌아갈 수 있도록 UI를 구성해보세요.import Link from 'next/link'; export default function NotFound() { return ( <div className="min-h-screen flex flex-col items-center justify-center bg-gray-50 text-gray-800"> <div className="relative"> <h1 className="text-9xl font-extrabold text-indigo-200 tracking-widest"> 404 </h1> <div className="bg-[#FF6A3D] px-2 text-sm rounded rotate-12 absolute top-0 left-0 right-0 bottom-0 m-auto h-8 w-max flex items-center justify-center text-white font-bold shadow-lg"> Page Not Found </div> </div> <div className="mt-8 text-center"> <h3 className="text-2xl md:text-3xl font-bold mb-2"> 죄송합니다. 길을 잃으셨나요? </h3> <p className="text-gray-500 mb-8 max-w-md mx-auto"> 요청하신 페이지가 삭제되었거나, 이름이 변경되었거나, 일시적으로 사용할 수 없어요. </p> <Link href="/" className="group relative inline-block text-sm font-medium text-[#FF6A3D] focus:outline-none"> <span className="absolute inset-0 translate-x-0.5 translate-y-0.5 bg-[#FF6A3D] transition-transform group-hover:translate-y-0 group-hover:translate-x-0"></span> <span className="relative block border border-current bg-[#1A2238] px-8 py-3 text-white transition-colors group-hover:bg-gray-800"> 홈으로 돌아가기 </span> </Link> </div> </div> ); }핵심 포인트큰 404 숫자를 연한 색으로 배치해서 시각적인 안정감을 줘요.가운데 배지를 살짝 기울여서 의도된 디자인이라는 느낌을 줘요.버튼은 CSS만으로 입체적인 클릭 효과를 만들어서 사용자 행동을 유도해요.3. 데이터가 없을 때 404 강제 처리 (notFound)URL은 정상인데 실제 데이터가 없는 경우도 있어요. 예를 들어 /products/999 같은 요청인데 해당 상품이 이미 삭제된 상황이에요.이럴 때는 notFound() 함수를 사용해서 서버에서 직접 404를 발생시킬 수 있어요.import { notFound } from 'next/navigation'; interface Product { id: number; name: string; price: string; category: string; } export default function ProductsPage() { const products: Product[] = []; if (products.length === 0) { notFound(); } return ( <div className="min-h-screen bg-gray-50 py-12 px-8 text-black"> {/* 정상 렌더링 */} </div> ); }동작 방식notFound()가 실행되면 해당 컴포넌트 렌더링이 즉시 중단돼요.이후 가장 가까운 not-found.tsx를 찾아서 화면을 대체해요.동시에 HTTP 상태 코드도 404로 정확하게 반환돼요.4. 테스트 방법존재하지 않는 URL 입력 → 글로벌 404 페이지 확인데이터 없는 상태에서 페이지 접근 → notFound() 동작 확인

하네스코딩(Harness Coding)과 하네스 엔지니어링(Harness Engineering)

요즘 개발 생산성을 극대화하기 위해 다양한 자동화 도구와 워크플로우가 등장하고 있는데요, 그중에서도 “하네스코딩”과 “하네스 엔지니어링”은 특히 AI 기반 개발 환경에서 점점 중요해지고 있어요. 단순히 코드를 작성하는 것을 넘어서, 개발 흐름 자체를 설계하고 자동화하는 개념이라고 이해하면 좋아요.목차하네스코딩이란?하네스 엔지니어링의 개념프론트엔드 개발자를 위한 claude.md 세팅 방법실무에서의 활용 전략과 효율 극대화 방법마무리하네스코딩이란?하네스코딩은 쉽게 말하면 AI나 자동화 시스템이 잘 동작하도록 ‘환경’을 코드로 설계하는 방식이에요. 기존에는 사람이 직접 로직을 짰다면, 이제는 AI가 코드를 잘 생성하도록 가이드(프롬프트, 규칙, 컨텍스트)를 설계하는 것이 핵심이에요.예를 들면:“이 프로젝트는 Vue2 + Vite 기반이다”“컴포넌트는 atomic 디자인 구조를 따른다”“API 호출은 TanStack Query를 사용한다”이런 맥락을 미리 정의해두면 AI가 훨씬 정확한 코드를 만들어줘요. 즉, 코드를 짜기 전에 ‘코드가 생성될 환경’을 설계하는 것이 하네스코딩이에요.하네스 엔지니어링의 개념하네스 엔지니어링은 한 단계 더 확장된 개념이에요. 단순히 프롬프트를 잘 쓰는 것을 넘어서, 개발 파이프라인 전체를 자동화하고 최적화하는 것을 의미해요.구성 요소를 보면:AI 프롬프트 설계코드 생성 규칙 정의테스트 자동화CI/CD 연동코드 스타일 및 아키텍처 강제즉, 개발자의 의도를 시스템으로 강제하는 구조를 만드는 것이 핵심이에요.

2026. 04. 07

Toss 결제 단말기 개발_part.1

토스플레이스 카드결제 단말기 연동 회고. 추가 예정

2026. 01. 21

Next.js(App Router) 렌더링 방식을 알고 설계하는 것, 우선 페이지 작업부터 시작하는 것!

Next.js 공식 문서를 읽다 보면 데이터 렌더링 방식이 크게 세 가지가 있다는 것을 알 수 있다.신규 프로젝트를 시작하기 전에는 다양한 디자인 패턴을 고려하게 되는데, 프로젝트의 성격에 맞는 패턴을 선택하고 전체적인 아키텍처부터 설계해야 한다. 예를 들어, A라는 페이지는 실시간 데이터가 중요하므로 SSR 방식으로 구현하고, 메인 페이지는 초기 렌더링 속도가 중요하지만 자주 변경되지 않는 데이터이기 때문에 SSG 방식으로, 또 다른 페이지는 ISR 방식으로 설계하는 식이다. 이렇게 렌더링 방식을 미리 고민하며 개발할 때도 있지만, 때로는 명확한 기준 없이 개발을 시작했다가 중간에 렌더링 방식을 변경하는 경험을 하기도 한다. 레이어 설계 단계에서부터 컴포넌트를 세분화해 “이 컴포넌트는 SSG, 오른쪽 컴포넌트는 ISR”처럼 나누다 보면, 과연 내가 Next.js 프레임워크의 렌더링 생태계를 제대로 이해하고 활용하고 있는지 스스로에게 질문을 던지게 된다. 그래서 오늘은 Next.js에서 가장 중요한 개념 중 하나인 렌더링 방식에 대해 정리해보려고 한다. 사실 누군가에게는 크게 중요하지 않은 주제일 수도 있다. 결국 화면에 보이는 결과는 같으니까 말이다.App Router의 핵심은 페이지 레벨이 아닌 데이터 페칭(fetch) 수준에서 렌더링 방식을 결정한다.SSR, SSG, ISR의 차이와 구현 방법을 확인해보자. fetch는 force-cache이므로 SSG로 동작한다. (수정)1. SSR: Dynamic Rendering (요청 시 렌더링)App Router에서 SSR은 특정 경로가 Dynamic API(쿠키, 헤더, searchParams 등)를 사용하거나, 데이터 페칭 시 캐시를 사용하지 않도록 설정할 때 사용한다. 실시간 가격, 실시간 주식 등 초단위 최신성 필요 시SEO가 중요하면서 데이터가 매번 바뀌어야 할 때사용자별 개인화된 데이터(로그인 정보) /* * ...app/products/page.tsx **/ async function getProducts() { // cache: 'no-store' 설정을 통해 SSR처럼 동작하게 만든다. const res = await fetch('https://api.example.com/products', { cache: 'no-store' // 캐시를 무효화한다. 기본옵션은 force-cache이다 }); return res.json(); } export default async function Page() { const products = await getProducts(); return ( <div> <h1>최신 상품 목록 (SSR)</h1> {/* 데이터 렌더링 */} </div> ); }SSG: Static Rendering (빌드 시 렌더링)빌드 타임에 데이터가 포함된 HTML을 미리 생성하여 저장한다. CDN에 캐싱될 수 있어 가장 빠른 사용자 경험을 제공한다블로그 포스트, 문서 가이드마케팅 페이지, 회사 소개 페이지변경 빈도가 낮고 모든 사용자에게 동일한 정보 /* * ...app/posts/[id]/page.tsx **/ // 빌드 시 미리 생성할 경로 목록을 정의 export async function generateStaticParams() { const posts = await fetch('https://api.example.com/posts').then(res => res.json()); return posts.map((post: any) => ({ id: post.id.toString(), })); } export default async function PostPage({ params }: { params: { id: string } }) { const { id } = params; // 기본 fetch는 force-cache이므로 SSG로 동작한다. const res = await fetch(`https://api.example.com/posts/${id}`); const post = await res.json(); return <article>{post.title}</article>; }근데 여기서 함정은, 블로그 게시글을 수정했다고 가정하고, 수정한 글이 반영이 되나??? 안된다................ 다음 편에서 알아보기!!

2026. 01. 18

자바스크립트의 비동기 동작원리... 내가 이해한 콜스택과 태스크 큐

이 글을 "왜" 쓰는가?프론트 개발에서 화면에 보여지는 data는 백엔드와 통신을 통해 데이타를 주고 받아 화면에 알 맞는 데이타를 보여주는 역할을 한다.특히 백엔드와 통신하며 데이터를 주고받을 때, 호출 타이밍이 꼬여서 내가 의도한 순서가 아닌 다른 함수가 먼저 실행되는 상황을 빈번하게 겪곤 한다.분명 머릿속으로는 흐름을 그리고 있는데, 왜 실제 실행 결과는 다를까? 싱글 스레드인 자바스크립트가 어떻게 이런 '동시성'을 가질 수 있는지, 그리고 내가 생각하는 호출 순서가 맞는지 확인하기 위해 잊고 있었던 머릿속 지식을 다시 한번 깊게 정리하고 복습해 보려 한다.1. 콜스택 (Call Stack): 모든 실행의 시작점콜스택은 자바스크립트 엔진이 함수 호출을 관리하는 핵심 장치다. 말 그대로 '스택(Stack)' 구조라 LIFO(Last In, First Out) 방식으로 작동한다. 현재 어떤 함수가 실행 중인지, 그 함수가 끝나면 어디로 돌아가야 하는지를 기록한다.항상 염두에 두어야 할 점은 자바스크립트 엔진의 콜스택은 하나뿐이라는 것이다. 한 번에 하나의 함수만 실행할 수 있다는 뜻이다. function first() { second(); console.log('첫 번째'); } function second() { console.log('두 번째'); } first(); // 실행 흐름: first() 함수 호출 -> second() 함수 호출 -> second() 함수에 로그 출력 -> first 함수에 로그 출력 // '두번째' -> '첫 번째'2. Web APIs자바스크립트 엔진 자체는 비동기 처리를 하지 못한다. 대신 브라우저(또는 Node.js) 런타임 환경이 제공하는 Web APIs가 이 역할을 대신해 준다.setTimeout, fetch, DOM Events 같은 비동기 함수들은 호출되는 즉시 콜스택에서 빠져나와 Web API 세션으로 넘겨진다. 덕분에 메인 스레드는 멈추지 않고 다음 코드를 바로 실행할 수 있는 것이다.3. 이벤트 루프와 대기실 (Queue)비동기 처리가 끝난 콜백 함수들은 곧장 실행되지 않고 큐(Queue)라는 대기실에서 대기한다. 여기서 이벤트 루프(Event Loop)가 등장한다.이벤트 루프는 콜스택이 비어 있는지 끊임없이 확인한다. 만약 콜스택이 텅 비어 있다면, 대기 중인 콜백을 순서대로 콜스택으로 옮겨준다. 이것이 자바스크립트가 비동기를 처리하는 근본적인 메커니즘이다.4. 마이크로태스크 vs 매크로태스크 (가장 헷갈렸던 부분)가장 흥미로웠던 점은 큐가 하나가 아니라는 사실이다. 비동기 콜백에도 엄격한 우선순위가 존재한다.1) Microtask Queue (마이크로태스크 큐)

2026. 01. 12

SSR(Server Side Rendering)이란?

SSR(Server Side Rendering)이란?SSR(Server Side Rendering) 방식은 서버에서 완성된 정적 HTML을 클라이언트에 내려주는 방식이다. 클라이언트 측에서는 해당 HTML을 파싱만 하여 화면을 그리게 된다.반면, CSR(Client Side Rendering) 방식은 브라우저가 서버로부터 비어있는 뼈대 HTML을 받아온 후, 필요한 자바스크립트 번들을 다운로드하고 번들을 실행하여 동적으로 컨텐츠를 채우는 방식이다.Next.js에서는, SSR 방식으로 정적인 HTML을 내려주어 초기 화면을 빠르게 렌더한 이후, hydration을 통해 이벤트 리스너 부착 등의 자바스크립트 작업을 수행하여 정적인 화면을 동적으로 전환하는 작업을 수행하기도 한다.SSR의 장점은 무엇인가?SEO(검색 엔진 최적화) 측면에서 유리하다. 화면이 동적으로 그려지는 CSR에 비해 크롤러가 컨텐츠를 쉽게 인식하며, 초기 로드가 상대적으로 빨라 우선순위가 부여되어 상위에 노출될 가능성이 높아지기 때문이다. 이런 점에서 SSR은 블로그나 커머스 등 SEO가 중요한 웹 애플리케이션에 특히 적합하다.또한, SSR 방식에서는 사용자가 빠른 초기 로딩 속도를 경험할 수 있다. CSR과 달리 SSR에서는 번들을 다운로드 받거나 번들을 실행하여 동적으로 화면을 그려야 할 필요가 없기 때문이다.SSR의 단점은 없는가?전통적인 SSR 방식에서는 클라이언트 사이드 라우팅이 불가능하기 때문에 빠르고 매끄러운 페이지 전환 경험을 제공하기 어렵다. 또한, 단순히 정적인 리소스를 내려주는 것이 아니라, 요청 시마다 페이지를 동적으로 구성해서 내려주어야 하는 경우에는 WAS 서버 구동으로 인해 서버 비용이 증가할 수 있다는 단점이 있다.Next.js를 통한 최신의 방식으로 SSR을 구현할 경우에는 다음과 같은 단점이 있다.첫째, hydration을 통해 동적인 화면으로 전환할 경우 상호작용 초기화가 비교적 느리다. 이는 페이지가 표시되기까지 걸리는 시간(TTV)과 상호작용까지 걸리는 시간(TTI) 사이에 격차가 발생한다는 의미이다. 그 사이에 사용자가 버튼을 클릭해도 동작하지 않는 등의 답답한 상황을 겪을 수 있다.둘째, 상대적으로 구현 복잡도가 높다. 현대의 웹앱은 SSR과 CSR을 동시에 사용하는 경우가 많다. 이때 클라이언트 사이드 로직과 서버 사이드의 로직을 구분해가면서 구현해야 하기 때문에 상대적으로 구현 복잡도가 높다.

2026. 01. 03

Next.js와 React Query로 SSR 사용하기

2025. 12. 14

[Refactoring] 결제 모듈 의존성 제거기: 단일 구조에서 멀티 VAN 아키텍처로 (feat. Adapter Pattern)

2025. 11. 02

Tanstack Query - useMutation!!!

오늘은 내가 직접 삽질하며 깨달은 useQuery와 useMutation 그리고 왜 이게 선택이 아닌 필수인지 아주 상세하게 정리해본다.useMutation 반환 메소드 요약TanStack Query(React Query)의 useMutation이 반환하는 객체에는 실제 동작을 트리거하거나 제어하는 3가지 핵심 메소드가 포함되어있다.1. mutate가장 기본적으로 사용되는 실행 함수특징: 호출 후 아무것도 반환하지 않음 (void).에러 처리: 내부적으로 에러를 잡아두기 때문에 호출부에서 try...catch를 사용할 필요 없음 대신 onError 콜백을 통해 에러 처리용도: 일반적인 UI 이벤트(버튼 클릭 등)에서 가볍게 요청을 보낼 때 사용2. mutateAsyncPromise를 반환하는 비동기 실행 함수특징: 성공 시 데이터, 실패 시 에러를 담은 Promise를 반환에러 처리: 호출부에서 직접 async/await와 try...catch를 사용하여 비동기 흐름을 제어할 수 있음용도: 뮤테이션 실행 후 연쇄적인 비동기 작업이 필요하거나, 여러 개의 뮤테이션을 순차적으로 실행해야 할 때 사용3. reset뮤테이션의 모든 상태를 초기화하는 함수특징: data, error, isPending, isSuccess 등 해당 뮤테이션이 가졌던 상태를 모두 'idle' 상태로 되돌린다용도:4. 라이프사이클 콜백뮤테이션의 각 단계에 개입해서 특정 로직을 실행할 수 있음.onMutate: 뮤테이션이 시작되기 직전에 실행돼. (예: 낙관적 업데이트-Optimistic Update 할 때 미리 UI를 바꿔두는 용도)onSuccess: 성공했을 때 실행. (예: 쿼리 무효화-Invalidation를 통해 목록 새로고침)onError: 실패했을 때 실행. (예: 에러 알림 띄우기)onSettled: 성공하든 실패하든 상관없이 마지막에 무조건 실행. (예: 로딩 상태 해제)5. 코드예시

2025. 10. 01

[Next.js] 프론트엔드 배포 독립! i18n 자동화 파이프라인 구축기 (feat. Google Sheets, S3)

2025. 09. 19

좋은 코드를 작성하기 위한 기준은 무엇일까??

2025. 09. 10

골프장 예약 시스템 리뉴얼: 단순한 디자인 변경이 아닌 사용자 경험의 재설계

1. 프로젝트 배경 이번 프로젝트는 기존 서비스를 새로운 프론트엔드 환경으로 리뉴얼하는 과정에서 회원가입 및 로그인 보안 체계를 강화하기 위해 NICE 본인인증 기능을 도입했다. 왜 본인인증이 필요했을까? 골프장 예약 시스템의 가장 큰 문제는 '노쇼(No-show)'였다. 누구나 손쉽게 회원가입을 한 뒤 예약을 걸어두고 나타나지 않는 경우가 빈번했고, 이는 실제 이용 고객의 기회를 제한하고 운영 효율성을 떨어뜨리는 주요 원인이었다. 단순히 이메일이나 전화번호만으로 회원가입을 허용할 경우, 동일인이 여러 계정을 생성하거나 허위 정보로 가입하는 것을 막을 방법이 없었다. 이를 해결하기 위해 본인 명의 인증 절차를 필수 단계로 추가하여, 실제 사용자만 예약을 진행할 수 있도록 구조를 개편했다.

2025. 08. 29

ERP 내장등록 화면 개편기: Tanstack Query로 비동기 통신 구조 개선하기

2025. 07. 26

Next.js 폴더 구조 파악하기

Next.js 폴더 구조, '정답'은 없었다. 내가 놓치고 있던 5가지 핵심 원칙Next.js로 프로젝트 처음 시작할 때, 다들 비슷한 고민 한 번쯤은 해봤을 거다. "컴포넌트는 어디다 둬야 하지? lib 폴더는 app 안에 넣나, 밖에 빼나? 대체 어떻게 정리해야 나중에 고생 안 할까?"나도 깔끔하고 확장성 있는 구조를 만들고 싶어서 정답을 찾아 헤맸는데, 생각보다 그 길은 잘 안 보이지 않았다. 그런데 공부하다 보니 문득 이런 생각이 들었다. 만약 Next.js가 의도적으로 '정답'을 정해두지 않은 거라면?사실 Next.js는 특정 구조를 강요하기보다 개발자한테 엄청난 유연성을 주는 프레임워크다. 공식 문서 곳곳에 숨겨져 있지만 의외로 많은 사람들이 놓치는, 강력하고도 반직관적인 5가지 핵심 원칙을 정리해 봤다. 이 글을 다 읽고 나면 폴더 구조에 대한 막막함이 "이렇게 짜면 되겠구나"라는 자신감으로 바뀔 거라고 예상한다.1. Next.js는 원래 '독선적이지 않다' Next.js 폴더 구조를 이해하려면 이 녀석의 근본 철학부터 알아야 하는데 Next.js는 프로젝트 파일을 어떻게 구성하든 크게 간섭하지 않는 '독선적이지 않은' 입장을 취해. 공식 문서에도 작성되어있다.Next.js is unopinionated about how you organize and colocate your project files.이건 그냥 방치하는 게 아니라, 프로젝트가 작은 프로토타입에서 거대한 엔터프라이즈 앱으로 성장할 때 개발자가 상황에 맞춰 최적의 전략을 선택할 수 있게 자율성을 존중해 주는 거야. 이 철학만 이해해도 구조 짜는 게 훨씬 자유로워진다. 내가 생각한 폴더 구조가 맞다고 할 수 있고 사수나 동료가 생각한 폴더구조가 맞을 수 있다는 것이다. 상황에 맞게(자유롭게) 구조를 잡으면 된다 이 말이다.2. 폴더가 곧 라우트는 아니다.예전의 파일 기반 라우팅 시스템은 '폴더 = URL 경로'라는 공식이 강했지. 하지만 Next.js App Router에서는 이 고정관념을 깨야 한다 app 디렉토리 안에 폴더를 만든다고 무조건 URL이 생기는 게 아니란 말이다.라우트는 오직 해당 폴더 안에 page.js나 route.js가 있을 때만 활성화가 된다.이 단순한 규칙 덕분에 '코로케이션(Colocation)'이라는 강력한 패턴이 가능해져. 예전엔 컴포넌트 하나 수정하려면 components 폴더랑 pages 폴더를 왔다 갔다 하느라 정신없었는데 이제는 특정 페이지에서만 쓰는 UI 컴포넌트, 커스텀 훅, 스타일, 테스트 파일을 그냥 그 페이지 폴더 안에 같이 둬도 된다는 말! 관련 코드들이 한곳에 모여 있으니까 응집도도 높아지고 유지보수도 훨씬 편해지는 장점이 생긴거다. 이제 부터 app 라우터 기준 폴더가 주는 의미를 알아보자3. 괄호 ()로 URL 영향 없이 그룹화하기 (Route Groups)프로젝트가 커지면 라우트들을 논리적으로 묶고 싶어질 때가 있다. 예를 들어 마케팅 페이지, 쇼핑몰 페이지, 관리자 페이지를 구분하고 싶을 때 말이야. 이때 ()괄호형태 폴더명이 필요하다.폴더 이름을 (marketing) 처럼 괄호로 감싸면, 이 폴더는 URL 경로에는 전혀 영향을 주지 않으면서 관련된 라우트들을 정리하는 논리적인 그룹 역할만 한다 말 그대로 그룹핑!! 피그마 처럼 그룹으로 감싼다는 의미로 생각하면 이해가 편하다.섹션별 정리: (marketing), (shop), (admin)으로 나눠서 구조를 한눈에 파악.특정 그룹만 레이아웃 적용: (shop) 폴더 안에 layout.js를 두면 장바구니나 결제 페이지 같은 쇼핑몰 관련 페이지들만 특정 레이아웃을 공유하게 할 수 있다.특정 페이지에만 로딩 UI: 예를 들어 app/dashboard/(overview)/ 처럼 만들고 그 안에 loading.js를 넣으면, URL은 /dashboard/overview로 깔끔하게 유지되면서 로딩 스켈레톤은 딱 그 페이지에만 적용할 수 있다.4. 밑줄 _로 라우팅에서 완전히 제외하기 (Private Folders)라우팅이랑 상관없는 파일들을 완벽하게 분리하고 싶다면 '프라이빗 폴더(Private Folders)'를 쓰면 된다. 폴더 이름 앞에 밑줄을 붙여서 _folderName으로 만들면 Next.js 라우팅 시스템이 이 폴더를 아예 무시해버려.역할 분담: 라우팅과 상관없는 공용 컴포넌트나 라이브러리를 _components, _lib에 담아서 역할과 책임을 명확히 분리할 수 있다.충돌 방지: 나중에 Next.js에 새로운 파일 규칙(예: analytics.js)이 생기더라도 _로 시작하는 폴더 안에 있으면 이름이 겹칠 걱정이 없다.여기서 핵심! 코로케이션은 특정 페이지 전용 파일을 위한 거고, 프라이빗 폴더는 여러 라우트에서 공유하지만 특정 라우트 세그먼트는 아닌 공통 자산을 위한 거다.

2025. 06. 28

App Router: 서버 컴포넌트, 제약사항과 주의점

개발을 하다 보면 웬만한 건 다 안다고 생각할 때가 있는데, 기술은 정말 끝이 없다. 최근 Next.js의 App Router로 마이그레이션을 진행하면서 수많은 "빨간 줄(에러)"과 싸웠다.단순히 "서버에서 렌더링 된다"를 넘어서, 도대체 뭘 쓸 수 있고 뭘 쓸 수 없는지, 그리고 "실수하기 딱 좋은 함정"들이 무엇인지, 내가 겪은 시행착오를 바탕으로 상세하게 정리해 본다.1. 서버 컴포넌트(RSC), 다시 보자기본 개념은 간단하다. "서버에서 돌고, 결과물(HTML/JSON)만 브라우저로 보낸다." 하지만 이게 가져오는 파급력은 생각보다 크다. 왜 굳이 이걸 쓸까? (장점 심화)Zero Bundle Size: 서버 컴포넌트 내부에서만 쓰이는 라이브러리(예: 마크다운 파서, 날짜 변환기 등)는 브라우저 번들에 포함되지 않는다.보안: API Key나 민감한 토큰이 브라우저로 노출될 일이 없다. 서버에서 다 처리하니까.2. 절대 쓰면 안 되는 것들 (제약 사항)서버 컴포넌트는 리액트 컴포넌트지만, "리액트 훅(Hook)"을 쓸 수 없다. 이 부분이 가장 헷갈렸다. 2-1. State와 Lifecycle 관련 Hooks 사용 불가 서버는 요청을 받으면 컴포넌트를 한 번 딱 실행해서 결과를 보내고 끝이다. "상태(State)"를 유지하거나, "마운트 된 후(Effect)"라는 개념 자체가 없다.useState, useReducer (X)useEffect, useLayoutEffect (X)useRef (X) - 렌더링 결과물에 영향 없는 변수는 쓸 수 있지만, DOM 접근용으론 불가. 2-2. 브라우저 전용 API 사용 불가 서버(Node.js 환경)에서 돌기 때문에 브라우저 객체는 당연히 없다.window, document, navigator (X)localStorage, sessionStorage (X)onClick, onChange 같은 이벤트 핸들러 (X)3. 실수하기 딱 좋은 포인트 (주의점 & 패턴)이론은 알겠는데 막상 코드를 짜다 보면 마주치는 에러들이다.주의점 1: Props 직렬화(Serialization) 문제 서버 컴포넌트에서 클라이언트 컴포넌트로 데이터를(props) 넘길 때, 그 데이터는 반드시 네트워크를 탈 수 있는 형태(직렬화 가능)여야 한다.가능: string, number, array, object (JSON 가능한 것들)

2025. 06. 26

골프장 예약 시스템에 NICE 본인인증 도입하기

2025. 04. 09

Google Sheets + Next.js i18n 자동화 구축기 (google-spreadsheet v5) 버전 업

2025. 03. 18

기술 블로그를 React에서 Next.js로 마이그레이션한 이유와 과정

2025. 03. 06

Suspense?_? 잘 알고 잘 사용하자!!

2025. 02. 23

SSR: SEO의 최적화 + 시맨틱태그 중요성

2025. 02. 17

SSR(Next.js) AWS EC2 배포 (수동)_01

2025. 02. 14