Next.js Pages Router 레거시를 넘어, App Router 기반 구조 다시 설계하기

들어가며

안녕하세요, 노머스 FE 개발자 김민영입니다.

이번에 노머스에서 새로운 이커머스 서비스를 구현하게 되었습니다.

개발 기간은 약 한 달 정도였고, 요구사항 상당수가 기존 fromm store와 유사한 구조를 가지고 있었습니다.

한 달이라는 기간 안에 모든 것을 처음부터 만들기보다는, 기존 코드를 잘 활용하는 편이 효율적이었습니다. 다만 그대로 복사하면 Next.js Pages Router 기반의 레거시 구조까지 함께 유입되는 문제가 있었습니다.

그래서 팀은 다음과 같은 방향을 선택했습니다.

“기존 코드는 참조 자산으로 활용하되, App Router 구조에 맞춰 재설계하고 필요한 리팩토링까지 함께 진행한다.”

단순한 코드 복사가 아니라, 검증된 비즈니스 로직은 재활용하면서도 새로운 아키텍처와 팀 컨벤션에 맞게 다시 구현하는 전략이었습니다.

1. Pages Router vs App Router: 핵심 차이점

새 프로젝트를 시작하기 전, 팀 내에서 App Router의 핵심 변화를 먼저 정리했습니다.

라우팅 구조

# Pages Router (기존 fromm store)
pages/
├── _app.tsx
├── _document.tsx
├── index.tsx
├── goods/
│   └── [id].tsx

# App Router (새 프로젝트)
app/
├── layout.tsx
├── page.tsx
├── goods/
│   └── [id]/
│       └── page.tsx

Pages Router에서는 _app.tsx와 _document.tsx가 전역 역할을 담당했지만, App Router에서는 layout.tsx를 중심으로 계층적인 레이아웃 구성이 가능해졌습니다.

컴포넌트 패러다임 변화

구분	Pages Router	App Router
기본 컴포넌트	Client Component	Server Component
데이터 페칭	getServerSideProps, getStaticProps	Server Component 내부 async/await
메타데이터	next/head	generateMetadata

가장 큰 변화는 Server Component가 기본값이 되었다는 점입니다.

기존 Pages Router에서는 대부분의 컴포넌트가 브라우저에서 실행되는 Client Component 중심이었지만, App Router에서는 별도의 'use client' 선언이 없는 한 기본적으로 서버에서 렌더링됩니다.

Server Component는 브라우저로 전달되는 JavaScript 양을 줄일 수 있고, 서버에서 직접 데이터를 페칭할 수 있다는 장점이 있습니다. 반면 상태(useState), 이펙트(useEffect), 브라우저 API(window, document), 이벤트 핸들러(onClick 등)는 사용할 수 없습니다.

다만 이번 프로젝트에서는 Server Component에서 직접 데이터를 페칭하기보다, 대부분의 데이터 페칭을 클라이언트의 TanStack Query에 위임하는 구조를 택했습니다. Server Component는 API 헤더 초기화, 인증 가드 래핑, 메타데이터 생성 등 최소한의 서버 작업만 담당하고, 사용자 인터랙션과 데이터 처리는 Client Component에서 처리합니다.

이 변화로 인해 단순히 라우팅 방식만 달라진 것이 아니라, “어떤 컴포넌트를 서버에서 실행할 것인가”까지 함께 고려하는 구조적 설계가 중요해졌습니다.

useRouter API 변화

// Pages Router
import { useRouter } from 'next/router';
const router = useRouter();
router.pathname   // ✅
router.query      // ✅
router.push()     // ✅

// App Router
import { useRouter } from 'next/navigation';
const router = useRouter();
router.pathname   // ❌ → usePathname()
router.query      // ❌ → useSearchParams()
router.push()     // ✅

기존 Pages Router에서 익숙했던 API 일부가 제거되면서, 프로젝트 전반에 걸쳐 라우팅 관련 코드를 다시 설계할 필요가 있었습니다.

2. App Router 기반 구조 재설계

상황

새 프로젝트였지만 다음 조건들이 존재했습니다.

• 기존 fromm store와 도메인 로직이 매우 유사
• 주문, 결제, 장바구니 등 검증된 비즈니스 로직이 이미 존재
• 하지만 기존 구조를 그대로 복사하면 Pages Router 패턴까지 함께 유입됨

즉, “로직은 재사용하고 싶지만 구조는 가져오고 싶지 않은” 상황이었습니다.

접근 방식

기존 구조를 그대로 복사하지 않고, App Router 기반 아키텍처와 새로운 팀 컨벤션에 맞춰 처음부터 다시 설계하는 방향으로 진행했습니다.

특히 아래 항목들을 중점적으로 정리했습니다.

• App Router 기반 폴더 구조 정립
• Server / Client Component 역할 분리
• 공통 라우터 인터페이스 재설계
• 스타일 시스템 및 토큰 체계 개선
• 전역 레이아웃과 Provider 책임 분리

실제 워크플로우

1. 기존 서비스 구조 및 도메인 흐름 분석
2. App Router + 팀 컨벤션 기준 정의
3. 기능 단위로 새로운 구조에 맞춰 구현
4. 구현 과정에서 공통 패턴과 정책 정리

이 과정을 통해 단순 마이그레이션이 아니라, 새 프로젝트 기준에 맞는 구조와 개발 문화를 함께 정립할 수 있었습니다.

3. 구체적으로 개선한 부분들

새 프로젝트 구조를 설계하면서, 기존에 개선하고 싶었던 부분들도 함께 정리했습니다.

3.1 useRouter 호환 레이어 구성 + safeBack() 추가

기존 Pages Router의 사용 패턴은 최대한 유지하되, 새 프로젝트에서는 safeBack() 기능을 추가했습니다.

• safeBack() → SNS, 외부 브라우저 등에서 직접 유입된 사용자가 뒤로가기 시 예상치 못한 외부 페이지로 이동하지 않도록 처리

safeBack() {
    const prevPath = sessionStorage.getItem(StorageKey.prevPath);

    if (prevPath) {
        sessionStorage.removeItem(StorageKey.prevPath);
        appRouter.back();
    } else {
        appRouter.push(withLocale(Path.Home));
    }
}

일반적인 router.back()은 이전 히스토리가 없을 경우 브라우저 동작에 의존하기 때문에, 외부 유입 사용자가 서비스 바깥으로 이동하거나 빈 화면을 마주하는 UX 문제가 발생할 수 있었습니다.

그래서 내부 이동 이력이 없는 경우 메인 페이지로 안전하게 이동시키는 방식으로 보완했습니다.

또한 기존 코드의 라우터 사용 방식을 유지했기 때문에, 마이그레이션 과정에서 대규모 수정 없이 점진적으로 App Router 구조에 적응할 수 있었습니다.

3.2 Server / Client Component 경계 명확화

기존 프로젝트에서는 대부분의 컴포넌트가 클라이언트 기반이었지만, 새 프로젝트에서는 Server Component를 기본으로 사용하는 규칙을 정립했습니다.

app/[M]/order/
├── page.tsx              # Server Component
└── OrderClientPage.tsx   # Client Component

// page.tsx — Server Component ('use client' 없음)
const OrderPage = async () => {
    return (
        <SigninRequiredGuard>
            <OrderClientPage />
        </SigninRequiredGuard>
    );
};

// OrderClientPage.tsx — Client Component
'use client';

const OrderClientPage: FC = () => {
    const { data } = useGetOrderInfo();
    return (...);
};

다만 현재 구조에서는 Server Component에서 직접 데이터를 페칭하지 않기 때문에, 서버 렌더링의 핵심 이점을 충분히 활용하고 있다고 보기는 어렵습니다. 기존 fromm store의 TanStack Query 기반 클라이언트 데이터 페칭 구조를 유지하면서 App Router 위에 안정적으로 올리는 것이 이번 프로젝트의 우선 목표였기 때문입니다. 서버 사이드 데이터 페칭 활용은 이후 개선 과제로 남아 있습니다.

3.3 z-index 토큰 체계 개선

기존 프로젝트에서는 z-index를 modalZIndex라는 단일 기준값을 두고, 필요에 따라 CSS 변수에 더하거나 빼는 방식으로 관리하고 있었습니다.

// 기존 프로젝트: 단일 기준값 정의
zIndex: {
    modalZIndex: { value: 10 }
}

// 사용처에서 기준값에 더하거나 빼서 레이어 조절
zIndex: 'calc(var(--z-index-modal-z-index) + 2)'   // 드롭다운
zIndex: 'calc(var(--z-index-modal-z-index) + 10)'  // 드롭다운 목록

하나의 기준값에 의존하다 보니 +2, +10 같은 매직 넘버가 곳곳에 생겼고, 레이어 간 우선순위를 한눈에 파악하기 어려웠습니다.

해결: 역할별 토큰 분리

새 프로젝트에서는 각 레이어의 역할에 맞는 토큰을 개별 정의하는 방식으로 변경했습니다.

tokens: {
    zIndex: {
        local: { value: 1 },       // 배너 컨트롤, 캐러셀 인디케이터
        backdrop: { value: 9 },     // 헤더, 모달 백드롭
        modalZIndex: { value: 10 }, // 모달, 다이얼로그
        overlay: { value: 11 },     // 모달 위 오버레이 (검색창 등)
        loading: { value: 20 }      // 로딩 스피너
    }
}

// Before: 매직 넘버 의존
zIndex: 'calc(var(--z-index-modal-z-index) + 2)'

// After: 의미 기반 토큰
zIndex: 'overlay'

local(1) < backdrop(9) < modal(10) < overlay(11) < loading(20) 체계로 정리되면서, 숫자가 아닌 레이어 역할 기준으로 관리할 수 있게 되었고, 스타일 충돌과 우선순위 혼란이 크게 줄어들었습니다.

3.4 _app.tsx 역할 분리

기존 _app.tsx는 서버 로직과 클라이언트 로직이 혼재되어 있었습니다. 새 프로젝트에서는 이를 layout.tsx와 providers.tsx로 분리했습니다.

// layout.tsx — Server Component
const RootLayout = ({ children }: { children: ReactNode }) => {
    const locale = getLang();
    const currency = getCurrency();
    const messages = messagesMap[locale] ?? messagesMap.ko;

    setApiHeaders({ lang: locale, currency });

    return (
        <html lang={locale}>
            <body>
                <Providers locale={locale} messages={messages} currency={currency}>
                    {children}
                </Providers>
            </body>
        </html>
    );
};

// providers.tsx — Client Component
'use client';

const Providers = ({ children, locale, messages, currency }: Props) => {
    const [queryClient] = useState(() => new QueryClient({ ... }));

    return (
        <NextIntlClientProvider locale={locale} messages={messages}>
            <JotaiProvider>
                <QueryClientProvider client={queryClient}>
                    <InitHeaders locale={locale} currency={currency}>
                        <ErrorBoundary>
                            <CustomApp>
                                <AuthReadyGate>{children}</AuthReadyGate>
                            </CustomApp>
                        </ErrorBoundary>
                    </InitHeaders>
                </QueryClientProvider>
            </JotaiProvider>
        </NextIntlClientProvider>
    );
};

개선 포인트

• 서버/클라이언트 책임 명확 분리
• Provider 초기화 책임 집중
• AuthReadyGate를 통한 인증 준비 전 로딩 처리로 화면 깜빡임 감소

3.5 Panda CSS: breakpoints vs conditions 정리

프로젝트를 진행하면서 스타일 시스템에서도 혼란 요소가 발견되었습니다.

breakpoints와 conditions를 동시에 사용하고 있었다는 점입니다.

문제 상황

breakpoints: {
    tablet: '760px',
    pc: '1000px'
}

conditions: {
    tablet: '@media (min-width: 760px) and (max-width: 999px)',
    pc: '@media (min-width: 1000px)'
}

이름은 같지만 실제 의미가 달랐습니다.

구분	breakpoints	conditions
방식	모바일 퍼스트 (min-width 누적)	커스텀 범위 지정
사용 형태	{ base, tablet, pc }	{ _tablet, _pc }
tablet 의미	760px 이상 전체	760px ~ 999px 한정

같은 tablet이라는 이름이 맥락에 따라 전혀 다른 범위로 동작하고 있었습니다.

최종 방향

여러 방안을 검토한 끝에, conditions를 제거하고 breakpoints 중심으로 통일하기로 결정했습니다.

이유:

• 모바일 퍼스트 전략의 일관성 확보
• Panda CSS 기본 철학과 부합
• 팀 내 혼란 감소
• 반응형 스타일 패턴 단순화

초기에는 마이그레이션 비용이 있었지만, 장기적으로는 유지보수성과 예측 가능성이 더 중요하다고 판단했습니다.

마무리

이번 프로젝트는 단순히 Pages Router에서 App Router로 마이그레이션하는 작업이 아니었습니다. 기존 레거시를 어떻게 활용할 것인지, 그리고 새로운 구조를 어떤 기준으로 설계할 것인지에 대한 고민에 더 가까웠습니다.

프로젝트 후반에는 서버/클라이언트 역할 분리, 라우팅 규칙, 스타일 토큰 정책 등이 자리 잡으면서 이후 기능 개발에서도 일관된 방식으로 구현할 수 있는 기반이 마련되었습니다.

App Router 환경에서는 Server Component, Client Component, 라우팅, 레이아웃, 스타일 시스템이 모두 연결되어 있기 때문에, 초기 아키텍처와 컨벤션 설계가 프로젝트 전체의 생산성과 유지보수성에 큰 영향을 줍니다.

새 프로젝트를 빠르게 구축해야 하는 상황이라면, 기능 구현만 우선하기보다 프로젝트 구조와 개발 기준을 먼저 정리하는 접근도 충분히 가치 있는 선택이라고 생각합니다.

감사합니다.