OpenClaw용 Next.js Expert 스킬

OpenClaw Next.js Expert 스킬 개요

Next.js Expert 스킬은 OpenClaw 에이전트에게 Next.js 프레임워크에 대한 깊은 지식을 제공합니다 — App Router, React Server Components, Server Actions, 미들웨어, 캐싱 전략, 프로덕션 배포 패턴을 포괄합니다. 문서나 Stack Overflow를 검색하는 대신 OpenClaw에 직접 질문하여 프로젝트에 맞는 정확하고 최신의 안내를 받으세요.

이 스킬은 Next.js 13+로 최신 풀스택 React 애플리케이션을 구축하는 개발자에게 적합합니다. Pages Router에서 마이그레이션하거나, 복잡한 데이터 페칭 패턴을 구현하거나, 애플리케이션의 성능을 최적화하는 경우 등 OpenClaw Next.js Expert 스킬은 현재 모범 사례에 기반한 상황 인식 답변을 제공합니다.

일반적인 워크플로:

1. OpenClaw에 Next.js 아키텍처 질문을 하거나 겪고 있는 문제를 설명합니다.
2. 에이전트가 Next.js 규칙 및 패턴에 대한 지식을 활용하여 질문을 분석합니다.
3. 코드 예시, 파일 구조 권장 사항, 관련 Next.js 문서 링크와 함께 상세한 설명을 받습니다 — 탭 전환이 필요 없습니다.

Next.js Expert 스킬 사전 요구 사항

Next.js Expert 스킬을 설치하기 전에 다음 사항을 확인하세요:

• OpenClaw이 설치되어 실행 중이어야 합니다 (v1.0+)
• **Node.js 18.17+**가 설치되어야 합니다 — Node.js 다운로드
• Next.js 프로젝트가 있어야 합니다 (App Router 기능을 위해 13+ 권장)
• 스킬 관리를 위한 clawhub CLI가 설치되어야 합니다

설정을 확인하세요:

# OpenClaw 버전 확인
openclaw --version

# Node.js 버전 확인
node --version

# Next.js 프로젝트가 있는지 확인
npx next --version

Next.js Expert 스킬 설치 방법

단일 명령으로 Next.js Expert 스킬을 설치합니다:

npx clawhub@latest install nextjs-expert

설치를 확인하려면:

clawhub list

설치된 스킬 목록에 nextjs-expert가 표시되어야 합니다. 설치 전에 clawhub inspect nextjs-expert로 스킬을 사전에 확인할 수도 있습니다.

Next.js Expert 스킬 구성

Next.js Expert 스킬은 지식 기반 스킬로 API 키나 외부 서비스 인증이 필요하지 않습니다. 설치 후 바로 사용할 수 있습니다.

선택적 프로젝트 컨텍스트

최상의 결과를 위해 OpenClaw 에이전트가 프로젝트 디렉토리에 접근할 수 있도록 하세요. 이 스킬은 기존 코드를 분석하여 더 맞춤화된 조언을 제공할 수 있습니다:

# Next.js 프로젝트 루트로 이동
cd /path/to/your-nextjs-app

# 프로젝트 디렉토리에서 OpenClaw 시작
openclaw

OpenClaw이 next.config.js, tsconfig.json, app/ 디렉토리 구조에 접근할 수 있으면 Next.js Expert 스킬은 라우팅 구조, 미들웨어 구성, 설치된 패키지 등 특정 설정에 맞는 권장 사항을 제공할 수 있습니다.

최신 상태 유지

이 스킬은 Next.js 13부터 최신 릴리스까지 다룹니다. 최신 안내를 받으려면:

# 스킬을 최신 버전으로 업데이트
npx clawhub@latest install nextjs-expert

Next.js Expert 스킬 사용 예시

1. App Router 아키텍처 결정

사용자： "대시보드 섹션에 layout을 사용해야 할까요, template을 사용해야 할까요? 사이드바는 유지되지만 메인 콘텐츠는 내비게이션할 때 다시 렌더링되어야 합니다."

에이전트는 layout.tsx(내비게이션 간에 유지되며 상태를 보존)와 template.tsx(각 내비게이션마다 다시 생성)의 차이를 설명한 다음, 사이드바에는 layout을 사용할 것을 권장하고 각 페이지가 별도의 라우트 세그먼트이므로 메인 콘텐츠 영역은 자동으로 다시 렌더링됨을 확인합니다.

2. 데이터 페칭 전략

사용자： "5분마다 업데이트되는 제품 데이터를 가져와야 합니다. App Router에서 가장 좋은 방법은 무엇인가요?"

에이전트는 Server Component에서 시간 기반 재검증과 함께 fetch를 사용할 것을 권장하고 완전한 예시를 제공합니다:

// app/products/page.tsx
async function getProducts() {
  const res = await fetch('https://api.example.com/products', {
    next: { revalidate: 300 } // 5분마다 재검증
  });
  return res.json();
}

또한 Server Actions를 통한 주문형 재검증에 revalidatePath 또는 revalidateTag를 사용해야 하는 시점도 설명합니다.

3. Server Components vs Client Components

사용자： "정적 설명과 인터랙티브한 '장바구니에 추가' 버튼이 있는 제품 페이지가 있습니다. 컴포넌트를 어떻게 분리해야 하나요?"

에이전트는 SEO와 성능을 위해 제품 페이지를 Server Component로 유지하고, AddToCartButton만 'use client'를 사용하여 Client Component로 분리할 것을 권장합니다. 이점도 설명합니다: 제품 설명 HTML은 클라이언트 측 JavaScript 없이 서버에서 렌더링되며, 인터랙티브 버튼은 독립적으로 하이드레이션됩니다.

4. 미들웨어 및 인증

사용자： "/dashboard 하위의 모든 라우트를 인증 미들웨어로 보호하려면 어떻게 해야 하나요?"

에이전트는 matcher 구성을 사용한 미들웨어 구현을 제공하고, 세션 토큰을 확인하는 방법과 리다이렉트 패턴을 설명합니다. 또한 미들웨어는 Edge에서 실행되어 fs와 같은 Node.js API를 사용할 수 없다는 점을 안내하며, 프로덕션 인증에는 NextAuth.js 또는 Clerk 통합 패턴을 권장합니다.

보안 및 모범 사례

AI 지원을 활용하여 Next.js 애플리케이션을 구축할 때 다음 지침을 따르세요:

• 생성된 코드를 신중하게 검토하세요. 코드 제안을 프로젝트에 추가하기 전에 항상 읽고 이해하세요. 이 스킬은 안내를 제공하는 것이지 프로덕션에 바로 사용할 수 있는 코드를 보장하지는 않습니다.
• Server Actions 입력을 검증하세요. 스킬이 폼 처리를 위한 Server Actions를 제안할 때 적절한 입력 검증과 권한 확인을 추가하세요 — 에이전트가 상기시켜 주겠지만 항상 직접 확인하세요.
• 민감한 데이터는 서버 측에 유지하세요. API 키, 데이터베이스 자격 증명 또는 비밀 정보를 Client Components에 노출하지 마세요. NEXT_PUBLIC_ 접두사가 붙은 환경 변수는 진정으로 공개적인 값에만 사용하세요.
• 타입 안전성을 위해 TypeScript를 사용하세요. 이 스킬은 기본적으로 TypeScript 예시를 제공합니다. 특히 복잡한 데이터 페칭 패턴에서 오류를 조기에 발견하기 위해 타입 검사를 활용하세요.
• 최소 권한 원칙을 따르세요. 스킬이 API 라우트 핸들러나 미들웨어 패턴을 제안할 때 최소한으로 필요한 데이터와 접근만 노출하도록 하세요.

일반적인 오류 해결

"You're importing a component that needs useState. It only works in a Client Component."

Server Component에서 React 훅(useState, useEffect, useContext 등)을 사용하고 있습니다. 파일 상단에 'use client' 디렉티브를 추가하거나, 인터랙티브 부분을 별도의 Client Component로 분리하세요.

// 파일 맨 위에 추가
'use client';

import { useState } from 'react';

"Error: Dynamic server usage: Route /api/... couldn't be rendered statically"

라우트가 동적 기능(쿠키, 헤더, searchParams)을 사용하고 있지만 Next.js가 이를 정적으로 생성하려고 시도하고 있습니다. 라우트에 export const dynamic = 'force-dynamic'을 추가하거나, 정적 렌더링 가능한 페이지에서 동적 API를 사용하지 않도록 구조를 변경하세요.

// 이 라우트에 동적 렌더링 강제 적용
export const dynamic = 'force-dynamic';

"Module not found: Can't resolve 'fs' in middleware"

미들웨어 또는 Edge 라우트에서 Node.js 전용 모듈을 사용하려고 하고 있습니다. 미들웨어는 fs, path 또는 기타 Node.js 내장 모듈을 지원하지 않는 Edge Runtime에서 실행됩니다. 파일 시스템 로직을 export const runtime = 'nodejs'가 설정된 API 라우트로 이동하세요.