Communitygithub.com

Next.js 15 + App Router 스페셜리스트

Next.js 15 기능, App Router, 서버 컴포넌트, 서버 액션, 데이터 패칭 패턴 작업 시 사용합니다. 서버/클라이언트 컴포넌트의 올바른 사용과 최신 Next.js 패턴을 보장합니다.

Next.js 15 + App Router 스페셜리스트란 무엇인가요?

이 스킬은 Next.js 15 App Router를 사용하는 Quetrex 개발을 위한 포괄적인 가이드입니다. 에이전트가 최신 Next.js 패턴을 올바르게 구현하도록 돕습니다. 주요 규칙으로는 `<Image>` 컴포넌트 강제 사용, 서버 컴포넌트 기본 설정, async 클라이언트 컴포넌트 금지, 명시적 캐시 전략 지정 등이 있습니다. 또한 App Router 완전 가이드(45개 이상 예제), 데이터 패칭 완전 가이드(35개 이상 예제), 캐싱 전략 가이드(35개 이상 예제), 서버 액션 완전 가이드(31개 이상 예제), 메타데이터 API 가이드(26개 이상 예제) 등 150개 이상의 예제를 포함한 세부 문서를 제공합니다. 패턴 검증기(validate-patterns.py)를 통해 서버/클라이언트 컴포넌트 규칙, 데이터 패칭 전략, 이미지 최적화 등을 자동으로 검사할 수 있어 빌드 오류를 사전에 방지합니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ComeOnOliver/skillshub/tree/HEAD/skills/aiskillstore/marketplace/barnhardt-enterprises-inc/nextjs-15-specialist

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

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

미리보기

스킬 README에서

Next.js 15 + App Router 스페셜리스트 preview

문서

Next.js 15 + App Router 스페셜리스트은(는) 무엇을 하나요?

Quetrex 개발을 위한 완전한 Next.js 15 참고서

이 스킬은 Next.js 15 App Router의 모든 패턴에 대한 포괄적인 지침을 제공하여 에이전트가 최신 Next.js를 처음부터 올바르게 구현하도록 보장합니다.


중요 규칙 (절대 위반 금지)

다음 규칙은 절대 협상 불가입니다. 위반 시 빌드가 실패합니다.

1. 항상 next/image의 <Image> 사용 - <img> 사용 금지

// ✅ 항상 이렇게 하세요
import Image from 'next/image'

<Image src="/logo.png" alt="로고" width={200} height={100} />
<Image src={user.avatar} alt={user.name} width={40} height={40} />

// ❌ 절대 이렇게 하지 마세요 - 빌드 실패
<img src="/logo.png" alt="로고" />
<img src={user.avatar} alt={user.name} />

이유: Next.js Image 컴포넌트는 자동 최적화, 지연 로딩을 제공하고 레이아웃 시프트를 방지합니다. ESLint는 <img> 사용 시 빌드 실패하도록 구성되어 있습니다.

2. 서버 컴포넌트가 기본값 - 필요한 경우에만 'use client' 추가

3. async 클라이언트 컴포넌트는 절대 만들지 않음

4. fetch()에 항상 캐시 전략 지정


이 스킬을 사용해야 하는 경우

다음 작업 시 이 스킬을 사용하세요:

  • 새 라우트나 페이지 생성
  • 데이터 패칭 구현 (서버 컴포넌트 vs 클라이언트 컴포넌트)
  • 서버 vs 클라이언트 컴포넌트 결정
  • 서버 액션 및 폼 처리
  • 스트리밍 및 Suspense
  • 메타데이터 및 SEO
  • 라우트 핸들러 (API 라우트)
  • 캐싱 전략
  • 성능 최적화

전체 문서

이 스킬은 모든 Next.js 15 패턴을 다루는 포괄적인 가이드를 포함합니다:

📁 App Router 완전 가이드

45개 이상의 예제 포함:

  • 파일 기반 라우팅 (page.tsx, layout.tsx, route.ts)
  • 동적 라우트 ([id], [...slug], [[...slug]])
  • 라우트 그룹 ((group))
  • 비공개 폴더 (_folder)
  • 라우트 핸들러 (API 라우트)
  • 레이아웃 및 템플릿
  • 로딩 UI (loading.tsx)
  • 에러 바운더리 (error.tsx, global-error.tsx)
  • 찾을 수 없음 페이지 (not-found.tsx)
  • 병렬 라우트 (@folder)
  • 인터셉팅 라우트 ((.)folder)
  • 라우트 세그먼트 설정 (dynamic, revalidate, runtime)

🔄 데이터 패칭 완전 가이드

35개 이상의 예제 포함:

  • 서버 컴포넌트 데이터 패칭 (async/await)
  • 클라이언트 컴포넌트 데이터 패칭 (useEffect, React Query, SWR)
  • 병렬 데이터 패칭 (Promise.all)
  • 순차 데이터 패칭 (워터폴 방지)
  • 스트리밍 데이터 (Suspense 바운더리)
  • 서버 전송 이벤트 (Quetrex 음성용 SSE)
  • 데이터 변경 (서버 액션)
  • 낙관적 업데이트 (useOptimistic)
  • 폼 처리 (useFormStatus, useActionState)
  • 요청 중복 제거
  • 데이터 사전 로딩

💾 캐싱 전략 가이드

35개 이상의 예제 포함:

  • 요청 메모이제이션 (자동 중복 제거)
  • 데이터 캐시 (fetch 캐시 동작)
  • 전체 라우트 캐시 (정적 vs 동적)
  • 라우터 캐시 (클라이언트 측 캐시)
  • 캐시 설정 (force-cache, no-store, revalidate)
  • 캐시 태그 (revalidateTag, revalidatePath)
  • 온디맨드 재검증
  • 시간 기반 재검증 (ISR)
  • 캐시 디버깅 기법
  • 캐시 옵트아웃

⚡ 서버 액션 완전 가이드

31개 이상의 예제 포함:

  • 기본 서버 액션 패턴
  • 폼 액션 (점진적 향상)
  • 버튼 액션 (프로그래매틱 호출)
  • useFormStatus 훅 (로딩 상태)
  • useActionState 훅 (상태 관리)
  • useOptimistic 훅 (낙관적 UI)
  • 액션 내 에러 처리
  • Zod를 사용한 검증
  • JSON 반환 vs 리디렉트
  • 보안 (인증, CSRF)
  • 속도 제한
  • 데이터베이스 트랜잭션

🎯 메타데이터 API 가이드

26개 이상의 예제 포함:

  • 정적 메타데이터 (내보낸 객체)
  • 동적 메타데이터 (generateMetadata)
  • 파일 기반 메타데이터 (icon.png, opengraph-image.png)
  • Open Graph 메타데이터
  • Twitter 카드
  • JSON-LD 구조화된 데이터
  • Viewport 설정
  • PWA 매니페스트
  • Robots.txt
  • 사이트맵 생성

✅ 패턴 검증기

실행 가능한 Python 스크립트로 다음을 검사:

  • 서버 컴포넌트가 클라이언트 전용 API를 사용하지 않는지
  • 클라이언트 컴포넌트에 'use client' 지시문이 있는지
  • 데이터 패칭이 적절한 캐시 전략을 사용하는지
  • 서버 액션이 'use server'로 표시되었는지
  • 메타데이터 API가 올바르게 사용되었는지
  • 이미지 최적화 ( 사용, 미사용)
  • 무거운 컴포넌트에 동적 임포트 사용

실행: python validate-patterns.py /path/to/src


빠른 참조

서버 vs 클라이언트 컴포넌트 결정 트리

상호작용이 필요합니까? (onClick, onChange 등)
├─ 예 → 클라이언트 컴포넌트 ('use client')
└─ 아니오 → 서버 컴포넌트 (기본값)

React 훅이 필요합니까? (useState, useEffect)
├─ 예 → 클라이언트 컴포넌트
└─ 아니오 → 서버 컴포넌트

브라우저 API가 필요합니까? (window, localStorage)
├─ 예 → 클라이언트 컴포넌트
└─ 아니오 → 서버 컴포넌트

데이터를 패칭해야 합니까?
├─ 서버 컴포넌트 사용 (권장)
└─ 데이터가 반드시 클라이언트 측에 있어야 하는 경우에만 클라이언트 컴포넌트 사용

컴포넌트가 순수 프레젠테이션용입니까?
└─ 서버 컴포넌트 (더 나은 성능)

일반 패턴

1. 서버 컴포넌트 데이터 패칭

// app/projects/page.tsx
export default async function ProjectsPage() {
  const projects = await db.project.findMany()
  return <ProjectList projects={projects} />
}

2. 상호작용이 있는 클라이언트 컴포넌트

// components/ProjectCard.tsx
'use client'

import { useState } from 'react'

export function ProjectCard({ project }: Props) {
  const [loading, setLoading] = useState(false)

  const handleDelete = async () => {
    setLoading(true)
    await deleteProject(project.id)
    setLoading(false)
  }

  return (
    <div>
      <h2>{project.name}</h2>
      <button onClick={handleDelete} disabled={loading}>
        삭제
      </button>
    </div>
  )
}

3. 폼을 사용한 서버 액션

// app/actions.ts
'use server'

export async function createProject(formData: FormData) {
  const name = formData.get('name') as string
  const project = await db.project.create({ data: { name } })
  revalidatePath('/projects')
  return { success: true, project }
}

// app/projects/new/page.tsx
import { createProject } from '@/app/actions'

export default function NewProjectPage() {
  return (
    <form action={createProject}>
      <input name="name" required />
      <button type="submit">생성</button>
    </form>
  )
}

4. Suspense를 사용한 스트리밍

// app/dashboard/page.tsx
import { Suspense } from 'react'

export default function DashboardPage() {
  return (
    <div>
      <Suspense fallback={<ProjectsSkeleton />}>
        <ProjectsAsync />
      </Suspense>
      <Suspense fallback={<UsersSkeleton />}>
        <UsersAsync />
      </Suspense>
    </div>
  )
}

async function ProjectsAsync() {
  const projects = await fetchProjects() // 느린 쿼리
  return <ProjectList projects={projects} />
}

5. 동적 메타데이터

// app/blog/[slug]/page.tsx
import type { Metadata } from 'next'

export async function generateMetadata({
  params,
}: {
  params: Promise<{ slug: string }>
}): Promise<Metadata> {
  const { slug } = await params
  const post = await fetchPost(slug)

  return {
    title: post.title,
    description: post.excerpt,
    openGraph: {
      title: post.title,
      description: post.excerpt,
      images: [post.coverImage],
    },
  }
}

Quetrex를 위한 모범 사례

1. 서버 컴포넌트를 기본으로

// ✅ 올바름: 서버 컴포넌트 (기본값)
export default async function ProjectsPage() {
  const projects = await fetchProjects()
  return <ProjectList projects={projects} />
}

// ❌ 틀림: 필요하지 않은데 클라이언트 컴포넌트 사용
'use client'
export default function ProjectsPage() {
  const [projects, setProjects] = useState([])
  useEffect(() => {
    fetchProjects().then(setProjects)
  }, [])
  return <ProjectList projects={projects} />
}

2. 적절한 캐시 전략 사용

// 정적 콘텐츠 (영구 캐시)
const categories = await fetch('https://api.example.com/categories', {
  cache: 'force-cache',
}).then(r => r.json())

// 동적 콘텐츠 (캐시 없음)
const user = await fetch('https://api.example.com/me', {
  cache: 'no-store',
}).then(r => r.json())

// ISR (1시간마다 재검증)
const products = await fetch('https://api.example.com/products', {
  next: { revalidate: 3600 },
}).then(r => r.json())

3. 적절한 에러 바운더리 구현

// app/dashboard/error.tsx
'use client'

export default function DashboardError({
  error,
  reset,
}: {
  error: Error
  reset: () => void
}) {
  return (
    <div>
      <h2>문제가 발생했습니다!</h2>
      <button onClick={reset}>다시 시도</button>
    </div>
  )
}

4. 로딩 상태 사용

// app/dashboard/loading.tsx
export default function DashboardLoading() {
  return <DashboardSkeleton />
}

5. 이미지 최적화

// ✅ 올바름: next/image 사용
import Image from 'next/image'

export function ProjectCard({ project }) {
  return (
    <Image
      src={project.image}
      alt={project.name}
      width={400}
      height={300}
    />
  )
}

// ❌ 틀림: <img> 태그 사용
export function ProjectCard({ project }) {
  return <img src={project.image} alt={project.name} />
}

피해야 할 일반적인 실수

❌ 실수 1: async 클라이언트 컴포넌트

// ❌ 틀림: 문법 오류
'use client'

export default async function BadComponent() {
  const data = await fetch('/api/data')
  return <div>{data}</div>
}

// ✅ 올바름: 서버 컴포넌트 또는 useEffect 사용
export default async function GoodComponent() {
  const data = await fetch('/api/data')
  return <div>{data}</div>
}

❌ 실수 2: 서버 컴포넌트에서 클라이언트 API 사용

// ❌ 틀림: 서버 컴포넌트는 브라우저 API를 사용할 수 없음
export default function BadComponent() {
  const [state, setState] = useState(false) // 오류!
  return <div>{state}</div>
}

// ✅ 올바름: 'use client' 지시문 추가
'use client'

export default function GoodComponent() {
  const [state, setState] = useState(false)
  return <div>{state}</div>
}

❌ 실수 3: 캐시 전략 누락

// ❌ 틀림: 불명확한 캐싱 동작
const data = await fetch('/api/data')

// ✅ 올바름: 명시적 캐시 전략
const data = await fetch('/api/data', {
  cache: 'no-store', // 또는 'force-cache', 또는 { next: { revalidate: 60 } }
})

❌ 실수 4: <Image> 사용 안 함

// ❌ 틀림: 최적화되지 않은 이미지
<img src="/logo.png" alt="로고" />

// ✅ 올바름: Next.js Image 최적화 사용
<Image src="/logo.png" alt="로고" width={200} height={100} />

문제 해결

오류: "useState가 필요한 컴포넌트를 가져오고 있습니다..."

해결책: 컴포넌트 파일에 'use client'를 추가하세요.

오류: "async/await는 클라이언트 컴포넌트에서 유효하지 않습니다"

해결책: 'use client'를 제거하거나 async 컴포넌트 대신 useEffect를 사용하세요.

오류: "process가 정의되지 않았습니다"

해결책: 클라이언트 컴포넌트의 환경 변수는 NEXT_PUBLIC_ 접두사가 필요합니다.

오류: "Headers가 이미 전송되었습니다"

해결책: 응답을 보낸 후에는 headers()나 cookies()를 사용하지 마세요. 스트리밍 전에 호출하세요.


공식 문서


검증

패턴 검증기를 실행하여 코드를 확인하세요:

python .claude/skills/nextjs-15-specialist/validate-patterns.py src/

검증기는 다음을 확인합니다:

  • ✅ async 클라이언트 컴포넌트 (금지)
  • ✅ 서버 컴포넌트 내 클라이언트 API
  • ✅ 'use client' 지시문 배치
  • ✅ 서버 액션 비동기 함수
  • ✅ 이미지 최적화
  • ✅ 동적 라우트의 메타데이터
  • ✅ 무거운 컴포넌트에 대한 동적 임포트
  • ✅ fetch 캐시 전략
  • ✅ 라우트 세그먼트 설정

요약

이 스킬은 다음을 보장합니다:

  1. 올바른 컴포넌트 유형 선택 (서버 vs 클라이언트)
  2. 적절한 데이터 패칭 패턴 구현
  3. 적절한 캐싱 전략 사용
  4. 서버 액션 올바르게 처리
  5. 메타데이터 및 SEO 최적화
  6. 일반적인 Next.js 실수 방지
  7. Quetrex 아키텍처 가이드라인 준수

의문이 있을 때:

  • 특정 가이드 읽기 (위 링크)
  • 검증기 실행
  • 공식 Next.js 15 문서 확인
  • 서버 컴포넌트를 기본으로 사용

최종 업데이트: 2025-11-23 Next.js 버전: 15.5 총 예제 수: 150개 이상 총 라인 수: 4,000줄 이상

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

관련 스킬