pages 디렉토리

pages 디렉토리

Nuxt는 파일 기반 라우팅을 제공해서 웹 애플리케이션 안의 라우트를 만들어요. app/pages/ 디렉토리의 모든 페이지에 대해 Nuxt가 자동으로 라우트를 생성해요. 예를 들어 app/pages/index.vue는 앱의 / 라우트에 매핑돼요. 동적 라우트, 캐치올 라우트, 중첩 라우트, 페이지 메타데이터까지 정리할게요.

출처: https://nuxt.com/docs/4.x/directory-structure/app/pages

app.vue를 쓰고 있다면 <NuxtPage/> 컴포넌트로 현재 페이지를 표시해야 해요. 앱 크기를 줄이기 위해 이 디렉토리는 선택 사항이라는 점도 알아두세요. app.vue만 쓰면 vue-router가 포함되지 않아요.

동적 라우트

파일 이름에서 대괄호 안에 넣은 부분은 동적 라우트 파라미터가 돼요. 파라미터를 선택적으로 만들려면 이중 대괄호로 감싸면 돼요. 예를 들어 ~/pages/[[slug]].vue는 /와 /test 둘 다 매치해요.

-| pages/
---| index.vue
---| users-[group]/
-----| [id].vue

이 구조에서 $route 객체로 group/id에 접근할 수 있어요. /users-admins/123으로 이동하면 admins - 123이 렌더링돼요. Composition API에서는 useRoute() 함수로 라우트에 접근해요.

캐치올 라우트

[...slug].vue 같은 파일로 캐치올 라우트를 만들 수 있어요. 이건 해당 경로 아래의 모든 라우트에 매치돼요. /hello/world로 이동하면 ["hello", "world"]가 렌더링돼요.

중첩 라우트

<NuxtPage>로 중첩 라우트(nested routes)를 표시할 수 있어요. 자식 라우트 컴포넌트를 표시하려면 부모 페이지 안에 <NuxtPage>를 삽입해야 해요.

<template>
  <div>
    <h1>I am the parent view</h1>
    <NuxtPage :foobar="123" />
  </div>
</template>

자식 라우트 키

<NuxtPage>가 언제 다시 렌더링될지 제어하려면 pageKey prop으로 문자열이나 함수를 전달하거나, definePageMeta로 key 값을 정의할 수 있어요.

definePageMeta({
  key: route => route.fullPath,
})

라우트 그룹(Route Groups)

라우트를 묶되 URL 구조에는 영향을 주지 않으려면 파일을 (와 )로 감싼 폴더에 넣으면 돼요. 예를 들어 (marketing)/about.vue는 앱에서 /about 페이지로 나타나고, marketing 그룹은 URL 구조에서 무시돼요.

라우트 그룹은 라우트 메타데이터에서 route.meta.groups로 자동 접근할 수 있어요. 조건부 로직·스타일링·기타 목적에 활용할 수 있어요.

페이지 메타데이터

각 라우트에 메타데이터를 정의하려면 definePageMeta 매크로를 사용해요. 이 데이터는 앱 전체에서 route.meta 객체로 접근할 수 있어요. 중첩 라우트를 쓰면 모든 라우트의 페이지 메타데이터가 하나의 객체로 병합돼요.

특정 목적을 가진 메타데이터도 있어요.

  • alias — 같은 페이지를 다른 경로에서 접근할 수 있게 하는 별칭 정의
  • keepalive — keepalive: true로 설정하면 페이지를 Vue <KeepAlive> 컴포넌트로 감쌈
  • layout — 라우트 렌더링에 쓸 레이아웃 정의(false, 문자열, 또는 ref/computed)
  • layoutTransition, pageTransition — 페이지·레이아웃을 감싸는 <transition> 컴포넌트의 전환 속성 정의
  • middleware — 라우트별 미들웨어
  • name — 페이지 라우트 이름 정의
  • path — 파일 이름으로 표현하기 어려운 복잡한 패턴의 경로 매처 정의
  • props — 라우트 params를 페이지 컴포넌트에 props로 접근하게 함

definePageMeta는 컴파일러 매크로예요. 컴파일될 때 사라지므로 컴포넌트 안에서 참조할 수 없어요. 대신 메타데이터는 컴포넌트 밖으로 호이스트(hoist)되므로 반응형 데이터나 부작용을 일으키는 함수를 참조하면 안 돼요.

커스텀 메타데이터 타입

index.d.ts에서 #app 모듈의 PageMeta 인터페이스를 확장해 definePageMeta가 받는 객체의 타입을 안전하게 만들 수 있어요.

페이지 사이 내비게이션

페이지 사이를 이동하려면 <NuxtLink> 컴포넌트를 써요. 이 컴포넌트는 Nuxt에 포함되어 있어서 다른 컴포넌트처럼 import할 필요가 없어요.

<template>
  <NuxtLink to="/">Home page</NuxtLink>
</template>

프로그래밍 방식 내비게이션은 navigateTo() 유틸리티 메서드로 할 수 있어요. 이때 항상 navigateTo를 await하거나 그 결과를 return으로 연결해야 해요.

클라이언트 전용 / 서버 전용 페이지

.client.vue 접미사를 주면 페이지를 클라이언트 전용으로 정의할 수 있어요. 서버에서 이 페이지의 콘텐츠는 렌더링되지 않아요. .server.vue 접미사는 서버 전용 페이지로, 클라이언트 사이드 번들에 페이지 렌더링 코드가 포함되지 않아요.

더 알아보기