Communitygithub.com

ASoudy/AGS

Next.js App Router 원칙: 서버 컴포넌트, 데이터 페칭, 라우팅 패턴

AGS란 무엇인가요?

이 스킬은 Next.js App Router 개발을 위한 모범 사례들을 체계적으로 정리한 것입니다. 서버 컴포넌트와 클라이언트 컴포넌트의 올바른 선택 기준, 데이터 페칭 전략(정적, ISR, 동적), 파일 기반 라우팅 규칙, API 라우트 핸들러, 이미지 및 번들 최적화 방법, 메타데이터 설정, 캐싱 전략, 서버 액션 사용법, 그리고 자주 발생하는 안티 패턴과 프로젝트 구조 예시를 포함합니다. 주로 Next.js 13+ App Router 환경에서 개발하는 AI 에이전트(예: Claude Code, Cursor)가 workflows나 코딩 작업을 수행할 때 활용됩니다. 개발자는 이 스킬을 통해 서버 우선 접근법을 따르고, 불필요한 클라이언트 컴포넌트 사용을 피하며, 효율적인 데이터 흐름과 성능 최적화를 구현할 수 있습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ASoudy/AGS/tree/HEAD/AGAS/plugins/antigravity-awesome-skills-claude/skills/nextjs-best-practices

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

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

문서

Next.js 모범 사례

Next.js App Router 개발을 위한 원칙


1. 서버 vs 클라이언트 컴포넌트

결정 트리

다음이 필요한가요...?
│
├── useState, useEffect, 이벤트 핸들러
│   └── 클라이언트 컴포넌트 ('use client')
│
├── 직접 데이터 페칭, 상호작용 없음
│   └── 서버 컴포넌트 (기본값)
│
└── 둘 다?
    └── 분할: 서버 부모 + 클라이언트 자식

기본 설정

유형사용처
서버데이터 페칭, 레이아웃, 정적 콘텐츠
클라이언트폼, 버튼, 인터랙티브 UI

2. 데이터 페칭 패턴

페치 전략

패턴사용처
기본정적 (빌드 시 캐시)
재검증ISR (시간 기반 갱신)
no-store동적 (매 요청마다)

데이터 흐름

소스패턴
데이터베이스서버 컴포넌트 fetch
API캐싱이 포함된 fetch
사용자 입력클라이언트 상태 + 서버 액션

3. 라우팅 원칙

파일 규칙

파일목적
page.tsx라우트 UI
layout.tsx공유 레이아웃
loading.tsx로딩 상태
error.tsx에러 경계
not-found.tsx404 페이지

라우트 구성

패턴사용처
라우트 그룹 (name)URL 없이 구성
병렬 라우트 @slot동일 레벨의 여러 페이지
가로채기 (.)모달 오버레이

4. API 라우트

라우트 핸들러

메서드사용처
GET데이터 읽기
POST데이터 생성
PUT/PATCH데이터 업데이트
DELETE데이터 제거

모범 사례

  • Zod로 입력 검증
  • 적절한 상태 코드 반환
  • 오류를 우아하게 처리
  • 가능한 경우 Edge 런타임 사용

5. 성능 원칙

이미지 최적화

  • next/image 컴포넌트 사용
  • 접힌 부분 위 우선순위 설정
  • 블러 플레이스홀더 제공
  • 반응형 크기 사용

번들 최적화

  • 무거운 컴포넌트는 동적 임포트
  • 라우트 기반 코드 분할 (자동)
  • 번들 분석기로 분석

6. 메타데이터

정적 vs 동적

유형사용처
정적 내보내기고정 메타데이터
generateMetadata라우트별 동적 메타데이터

필수 태그

  • title (50-60자)
  • description (150-160자)
  • Open Graph 이미지
  • 표준 URL

7. 캐싱 전략

캐시 계층

계층제어 방식
요청fetch 옵션
데이터revalidate/tags
전체 라우트라우트 설정

재검증

방법사용처
시간 기반revalidate: 60
요청 시revalidatePath/Tag
캐시 없음no-store

8. 서버 액션

사용 사례

  • 폼 제출
  • 데이터 변경
  • 재검증 트리거

모범 사례

  • 'use server'로 표시
  • 모든 입력 검증
  • 타입이 지정된 응답 반환
  • 오류 처리

9. 안티 패턴

❌ 하지 말 것✅ 할 것
모든 곳에 'use client'기본적으로 서버
클라이언트 컴포넌트에서 fetch서버에서 fetch
로딩 상태 생략loading.tsx 사용
에러 경계 무시error.tsx 사용
큰 클라이언트 번들동적 임포트

10. 프로젝트 구조

app/
├── (marketing)/     # 라우트 그룹
│   └── page.tsx
├── (dashboard)/
│   ├── layout.tsx   # 대시보드 레이아웃
│   └── page.tsx
├── api/
│   └── [resource]/
│       └── route.ts
└── components/
    └── ui/

기억하세요: 서버 컴포넌트가 기본인 데는 이유가 있습니다. 서버에서 시작하고, 필요할 때만 클라이언트를 추가하세요.

사용 시기

이 스킬은 개요에 설명된 워크플로나 작업을 실행할 때 적용 가능합니다.

제한 사항

  • 이 스킬은 작업이 위에 설명된 범위와 명확히 일치할 때만 사용하십시오.
  • 출력물을 환경별 검증, 테스트 또는 전문가 검토의 대체물로 취급하지 마십시오.
  • 필수 입력, 권한, 안전 경계 또는 성공 기준이 누락된 경우 멈추고 명확히 요청하십시오.

Individual skills in this repo

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

ASoudy/AGS

Advanced JavaScript animation library skill for creating complex, high-performance web animations.

ASoudy/AGS

Astropy is the core Python package for astronomy, providing essential functionality for astronomical research and data analysis.

ASoudy/AGS

Build content-focused websites with Astro — zero JS by default, islands architecture, multi-framework components, and Markdown/MDX support.

ASoudy/AGS

One sentence - what this skill does and when to invoke it

ASoudy/AGS

Audit and fix animation performance issues including layout thrashing, compositor properties, scroll-linked motion, and blur effects. Use when animations stutter, transitions jank, or reviewing CSS/JS animation performance.

ASoudy/AGS

Internationalization and localization patterns. Detecting hardcoded strings, managing translations, locale files, RTL support.

ASoudy/AGS

Pull a YouTube video transcript into a queryable markdown vault with yt-dlp subtitle discovery, VTT cleanup, metadata frontmatter, and capture-seed stubs.

ASoudy/AGS

Expert in building portfolios that actually land jobs and clients - not just showing work, but creating memorable experiences. Covers developer portfolios, designer portfolios, creative portfolios, and portfolios that convert visitors into opportunities.

ASoudy/AGS

Generates high-converting Next.js/React landing pages with Tailwind CSS. Uses PAS, AIDA, and BAB frameworks for optimized copy/components (Heroes, Features, Pricing). Focuses on Core Web Vitals/SEO.

ASoudy/AGS

AI-powered animation tool for creating motion in logos, UI, icons, and social media assets.

ASoudy/AGS

CRITICAL: Use for Makepad animation system. Triggers on: makepad animation, makepad animator, makepad hover, makepad state, makepad transition, "from: { all: Forward", makepad pressed, makepad 动画, makepad 状态, makepad 过渡, makepad 悬停效果

ASoudy/AGS

Comprehensive patterns for Next.js 14+ App Router architecture, Server Components, and modern full-stack React development.

ASoudy/AGS

Expert integration of Supabase Auth with Next.js App Router

ASoudy/AGS

React and Next.js 14+ application development with App Router, Server Components, TypeScript, Tailwind CSS, and modern frontend patterns.

ASoudy/AGS

Best practices for Remotion - Video creation in React

ASoudy/AGS

Generate walkthrough videos from Stitch projects using Remotion with smooth transitions, zooming, and text overlays

ASoudy/AGS

Seek and analyze video content using Memories.ai Large Visual Memory Model for persistent video intelligence

ASoudy/AGS

Writes complete, structured landing pages optimized for SEO ranking, AEO citation, and visitor conversion. Activate when the user wants to write or generate a landing page for a product, service, or offer.

ASoudy/AGS

Three.js animation - keyframe animation, skeletal animation, morph targets, animation mixing. Use when animating objects, playing GLTF animations, creating procedural motion, or blending animations.

ASoudy/AGS

Skill for discovering and researching autonomous AI agents, tools, and ecosystems using the AgentFolio directory.

관련 스킬