fe-agent-new/skills/nuxt-page-layout/SKILL.md

name, description

name	description
nuxt-page-layout	Nuxt 3 페이지, 레이아웃, 미들웨어를 생성할 때 사용합니다. "페이지 만들어줘", "레이아웃 추가", "미들웨어 작성", "라우트 추가", "새 페이지", "page", "layout", "middleware" 등을 요청하면 트리거됩니다.

Nuxt 페이지·레이아웃·미들웨어 생성

이 skill은 Nuxt 3의 파일 기반 라우팅 체계에 맞춰 페이지, 레이아웃, 미들웨어를 생성합니다. 프로젝트 컨벤션(.claude/project/conventions.md)이 있으면 해당 규칙을 우선합니다.

작업 순서

1. 기존 구조 탐색

   • pages/ 디렉토리 트리를 확인하여 라우팅 구조 파악
   • layouts/ 에서 기존 레이아웃 확인
   • middleware/ 에서 기존 미들웨어 확인

2. 라우트 구조 결정

   • 사용자와 파일 기반 라우팅 경로를 확인
   • 동적 파라미터: [id].vue, catch-all: [...slug].vue, 중첩 라우트 처리
   • 수동 라우트 정의는 특수한 경우에만 허용 (rules/framework-rules.md 참조)

3. 레이아웃 선택 또는 생성

   • 기존 레이아웃이 적합하면 재사용
   • 새 레이아웃이 필요한 경우에만 생성
   • definePageMeta({ layout: 'xxx' }) 로 페이지에 연결

4. 페이지 파일 생성

   • <script setup lang="ts"> 템플릿 사용
   • definePageMeta 로 layout, middleware, title 설정
   • useSeoMeta 로 SEO 메타태그 설정

5. 미들웨어 추가 (필요 시)

   • named middleware: middleware/auth.ts → definePageMeta({ middleware: ['auth'] })
   • inline middleware: 페이지 내 definePageMeta({ middleware: [...] })

6. 검증

   • TypeScript 오류 없는지 확인
   • nuxt dev 에서 라우트가 정상 인식되는지 안내

페이지 템플릿

<script setup lang="ts">
definePageMeta({
  layout: 'default',
  middleware: ['auth'],
});

useSeoMeta({
  title: '페이지 제목',
  ogTitle: '페이지 제목',
  description: '페이지 설명',
});
</script>

<template>
  <div>
    <!-- content -->
  </div>
</template>

레이아웃 템플릿

<script setup lang="ts">
</script>

<template>
  <div class="min-h-screen">
    <AppHeader />
    <main>
      <slot />
    </main>
    <AppFooter />
  </div>
</template>

Named 미들웨어 템플릿

// middleware/auth.ts
export default defineNuxtRouteMiddleware((to, from) => {
  const { isLoggedIn } = useAuth();

  if (!isLoggedIn.value) {
    return navigateTo('/login');
  }
});

동적 라우트 패턴

파일명	라우트	예시 URL
pages/users/[id].vue	/users/:id	/users/123
pages/posts/[...slug].vue	/posts/:slug(.*)	/posts/2026/04/hello
pages/[[optional]].vue	/:optional?	/ 또는 /about

주의사항

• definePageMeta 에는 정적/직렬화 가능한 값만 허용. 런타임 표현식 사용 불가
• 동적 라우트 파라미터는 [param].vue 형식 사용 (_param.vue 는 Nuxt 2 문법)
• pages/ 외부에 페이지 파일을 생성하지 않음
• 한국어 SEO: useSeoMeta 에 lang="ko" 관련 설정 고려
• 컴포넌트 네이밍은 PascalCase (rules/coding-conventions.md 참조)
• 사용자가 명시적으로 요청하지 않는 한 기존 파일을 수정하지 않음