Communitygithub.com

Next.js App Router 라우팅 시스템

파일 시스템 기반 라우팅, 레이아웃, 라우트 그룹. Next.js에서 App Router 라우팅, 중첩 레이아웃, 라우트 그룹을 구현할 때 사용합니다. (트리거: app/**/page.tsx, app/**/layout.tsx, app/**/loading.tsx, App Router, Layout, Route Group, parallel routes)

Next.js App Router 라우팅 시스템란 무엇인가요?

이 스킬은 Next.js App Router의 핵심 라우팅 아키텍처와 구현 가이드라인을 제공합니다. `app/` 디렉토리를 기반으로 한 파일 시스템 라우팅, `layout.tsx`를 통한 중첩 레이아웃, `loading.tsx` 및 `error.tsx`를 통한 상태 관리, Route Groups, Dynamic Routes, Parallel Routes, Intercepting Routes 등 고급 패턴을 자세히 설명합니다. 특히 Next.js 15 이상에서 `params`, `searchParams`, `cookies()`, `headers()`를 Promise로 취급하여 반드시 `await`해야 하는 점을 강조하며, 보안을 위해 `middleware.ts`를 사용한 에지-사이드 인증과 Route Handler의 권한 검사를 권장합니다. React Server Components(RSC)를 기본으로 하고 인터랙티브한 부분에만 `'use client'`를 사용하는 모범 사례와, 루트 레이아웃 외의 중첩 레이아웃에서 `<html>`/`<body>`를 사용하지 말아야 하는 안티패턴도 포함되어 있습니다. 이 스킬은 Next.js 개발자, 특히 App Router를 사용하는 프로젝트에서 일관된 라우팅 구조와 성능 최적화를 원하는 팀에게 유용합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ComeOnOliver/skillshub/tree/HEAD/skills/HoangNguyen0403/agent-skills-standard/nextjs-app-router

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

우선순위: P0 (매우 중요)

구현 가이드라인

라우팅 아키텍처

  • 구조: app/ 디렉터리를 사용하세요. **app/dashboard/layout.tsx**에서 **{children}**을 반환하여 경로를 정의합니다. 공유 UI는 자동으로 app/layout.tsx 내에 중첩됩니다. loading.tsx, error.tsx, **not-found.tsx**로 상태를 처리합니다.
  • 세그먼트: Route Groups (대괄호 (auth))를 사용하여 URL 경로에서 제외되는 방식으로 기능을 구성하세요. Dynamic Routes (대괄호 [slug])를 사용하고 **generateStaticParams**를 통해 정적 경로를 정의합니다.
  • 고급 기능: Parallel Routes (@modal)는 슬롯을 부모 레이아웃에 추가하고 default.tsx 폴백을 제공하여 사용합니다. 대시보드와 같은 고급 레이아웃에는 Intercepting Routes ((.)route)를 사용합니다.

데이터 및 함수

  • Next.js 15+ 비동기: params: Promise, searchParams, cookies() 및 **headers()**는 항상 await 해야 합니다.

  • 보안: **middleware.ts**를 사용하여 에지-사이드 인증 및 리디렉션을 처리하고, 모든 **Route Handler (route.ts)**에 적절한 인증 검사를 적용합니다.

  • RSC: 기본적으로 **React Server Components (RSC)**를 사용합니다. 인터랙티브한 부분(훅/이벤트)에서만 **'use client'**를 리프 노드에 사용합니다.

  • 에러 바운더리: **app/dashboard/loading.tsx**를 생성하여 경로를 자동으로 Suspense 경계로 감쌉니다. **error.tsx**에서는 **'use client'**를 사용하고 reset: () => void 함수를 제공합니다.

    const theme = cookieStore.get('theme');


## 파일 컨벤션

- **page.tsx**: 경로의 UI를 정의합니다.
- **layout.tsx**: 자식 요소를 감싸는 공유 UI로, 네비게이션 간에 유지됩니다.
- **loading.tsx**: 로딩 상태를 위한 Suspense 경계입니다.
- **error.tsx**: 에러 경계 (클라이언트 컴포넌트여야 함).
- **route.ts**: 서버 측 API 엔드포인트를 정의합니다.

## 구조 패턴

- **Route Groups**: 괄호 `(auth)`를 사용하여 URL 경로에 영향을 주지 않고 구조를 구성합니다.
- **Private Folders**: 밑줄 `_lib`을 사용하여 라우팅에서 제외합니다.
- **Dynamic Routes**: 대괄호 `[slug]` 또는 `[...slug]` (캐치-올)을 사용합니다.

## 모범 사례

- **RSC 경계**: 클라이언트 컴포넌트에 전달되는 props는 직렬화 가능해야 합니다. [RSC 경계 및 직렬화](../architecture/references/RSC_BOUNDARIES.md)를 참조하세요.
- **Parallel Routes (`@folder`)**: 동일한 레이아웃에서 여러 페이지를 렌더링합니다. 폴백으로 `default.tsx`를 사용합니다.
- **Intercepting Routes (`(..)folder`)**: 현재 레이아웃 컨텍스트 내에서 경로를 로드합니다.
- **Colocation**: 컴포넌트 파일, 스타일, 테스트를 경로 폴더 내에 함께 배치합니다.
- **Layouts**: 루트 레이아웃 (`app/layout.tsx`)에서 `<html>` 및 `<body>` 태그를 사용합니다.
- [**셀프-호스팅 표준**](references/SELF_HOSTING.md)

## 안티패턴

- **await하지 않은 비동기 API 금지**: `params`, `cookies()`, `headers()`는 Next.js 15+에서 Promise입니다. 항상 await하세요.
- **트리 루트에서 `'use client'` 금지**: 리프 노드에만 배치하고, 레이아웃과 페이지는 서버 컴포넌트로 유지합니다.
- **중첩 레이아웃에서 `<html>`/`<body>` 금지**: `app/layout.tsx` (루트 레이아웃)에서만 포함해야 합니다.
- **`error.tsx` 누락 금지**: 모든 경로 세그먼트에는 클라이언트 컴포넌트 에러 바운더리가 필요합니다.

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

ComeOnOliver/skillshub

Create stunning, animation-rich HTML presentations from scratch or by converting PowerPoint files. Use when the user wants to build a presentation, convert a PPT/PPTX to web, or create slides for a talk/pitch. Helps non-designers discover their aesthetic through visual exploration rather than abstract choices.

ComeOnOliver/skillshub

Next.js 16+ 和 Turbopack — 增量打包、文件系统缓存、开发速度,以及何时使用 Turbopack 与 webpack。

ComeOnOliver/skillshub

SwiftUI architecture patterns, state management with @Observable, view composition, navigation, performance optimization, and modern iOS/macOS UI best practices.

ComeOnOliver/skillshub

See, Understand, Act on video and audio. See- ingest from local files, URLs, RTSP/live feeds, or live record desktop; return realtime context and playable stream links. Understand- extract frames, build visual/semantic/temporal indexes, and search moments with timestamps and auto-clips. Act- transcode and normalize (codec, fps, resolution, aspect ratio), perform timeline edits (subtitles, text/image overlays, branding, audio overlays, dubbing, translation), generate media assets (image, audio, video), and create real time alerts for events from live streams or desktop capture.

ComeOnOliver/skillshub

AI-assisted video editing workflows for cutting, structuring, and augmenting real footage. Covers the full pipeline from raw capture through FFmpeg, Remotion, ElevenLabs, fal.ai, and final polish in Descript or CapCut. Use when the user wants to edit video, cut footage, create vlogs, or build video content.

ComeOnOliver/skillshub

Next.js 15 애플리케이션을 위한 프론트엔드 개발 가이드라인. React 19, TypeScript, Shadcn/ui, Tailwind CSS를 사용한 모던 패턴. Server Components, Client Components, App Router, 파일 구조, Shadcn/ui 컴포넌트, 성능 최적화, TypeScript 모범 사례 포함. 컴포넌트, 페이지, 기능 생성, 데이터 페칭, 스타일링, 라우팅, 프론트엔드 코드 작업 시 사용.

ComeOnOliver/skillshub

Provides Tamagui patterns for config v4, compiler optimization, styled context, and cross-platform styling. Must use when working with Tamagui projects (tamagui.config.ts, @tamagui imports).

ComeOnOliver/skillshub

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.

ComeOnOliver/skillshub

Create high-converting, visually distinctive landing pages. Use when building marketing pages, product launches, SaaS homepages, or any single-page conversion-focused website. Guides section-by-section composition with anti-AI-slop principles.

ComeOnOliver/skillshub

Auto-loaded context for Portfolio Buddy 2 development. Use for ANY task involving: React 19 development, TypeScript, portfolio analysis features, metrics calculations, trading strategy comparison, or working with the Portfolio Buddy 2 codebase. Contains tech stack, known issues, and architectural constraints.

ComeOnOliver/skillshub

Next.js development tooling via MCP. Inspect routes, components, build info, and debug Next.js apps. Use when working on Next.js applications, debugging routing, or inspecting app structure. NOT for general React or non-Next.js projects.

ComeOnOliver/skillshub

Implement UI using Shadcn MCP (atoms/theme) and 21st.dev MCP (complex sections). Use when adding buttons, layouts, or generating landing pages.

ComeOnOliver/skillshub

A conceptual skill for building an API client in Next.js that handles JWT tokens

ComeOnOliver/skillshub

Best practices and patterns for Next.js App Router, Server Actions, and Routing in this project.

ComeOnOliver/skillshub

The Design System, Theme, and UX rules for the Physical AI Hub.

ComeOnOliver/skillshub

Comprehensive frontend development skill for building modern, performant web applications using ReactJS, NextJS, TypeScript, Tailwind CSS. Includes component scaffolding, performance optimization, bundle analysis, and UI best practices. Use when developing frontend features, optimizing performance, implementing UI/UX designs, managing state, or reviewing frontend code.

ComeOnOliver/skillshub

This document captures learnings from fixing keyboard navigation issues when floating components (Select, DropdownMenu, Popover) have CSS open/close animations.

ComeOnOliver/skillshub

Build Next.js 16 applications with correct patterns and distinctive design. Use when creating pages, layouts, dynamic routes, upgrading from Next.js 15, or implementing proxy.ts. Covers breaking changes (async params/searchParams, Turbopack, cacheComponents) and frontend aesthetics. NOT when building non-React or backend-only applications.

ComeOnOliver/skillshub

Comprehensive Framer Motion animation library for React. Covers motion components, variants, gestures, page transitions, and scroll animations. Use when adding animations to React/Next.js applications.

ComeOnOliver/skillshub

Build interfaces that resonate, not just render. This skill enforces bold, intentional

관련 스킬