[Nuxt3] definePageMeta

정리

definePageMeta()는 pages/ 디렉토리에 있는 페이지 컴포넌트에 대한 메타데이터를 설정하는 데 사용할 수 있는 컴파일러 매크로 함수입니다. 이것은 컴포넌트 내에서 참조할 수 없도록 컴파일됩니다. 대신 전달된 메타데이터가 컴포넌트 밖으로 끌어올려집니다. 따라서 페이지 메타 객체는 컴포넌트(또는 컴포넌트에 정의된 값)를 참조할 수 없습니다. 그러나 가져온 바인딩을 참조할 수 있습니다.

속성	설명	사용 예제
alias	하나의 페이지를 여러 개의 URL로 접근 가능하게 함	alias: ["/home", "/start"]
keepalive	페이지 상태를 캐싱하여 다시 방문했을 때 유지	keepalive: true
keepalive.max	캐싱할 페이지 개수를 제한	keepalive: { max: 5 }
key	특정 페이지를 강제로 새로 렌더링	key: (route) => route.fullPath
redirect	특정 조건에서 자동 리디렉션	redirect: "/dashboard"
scrollToTop	페이지 이동 시 스크롤 최상단으로 이동	scrollToTop: true

 

alias 속성

하나의 페이지를 여러 개의 URL로 접근할 수 있도록 설정하는 기능입니다. 즉, 동일한 페이지를 여러 개의 다른 URL로 매핑할 수 있습니다.

<script setup>
definePageMeta({
  alias: ["/home", "/main", "/start"]
});
</script>

• 위 코드를 적용하면 /, /home, /main, /start 모든 경로에서 같은 페이지가 렌더링됩니다.
• 기존 URL 구조를 변경할 때 기존 URL을 유지하면서 새로운 URL을 도입할 때 유용합니다.

keepalive속성

페이지를 캐싱하여 다시 방문했을 때 상태를 유지할 수 있도록 도와줍니다. SPA(Single Page Application)에서 성능을 최적화하는 데 매우 유용합니다.

<script setup>
definePageMeta({
  keepalive: true
});
</script>

• 위 설정을 적용하면 사용자가 입력한 폼 데이터, 스크롤 위치, 컴포넌트 상태 등이 유지됩니다.

<script setup>
definePageMeta({
  keepalive: { max: 5 }
});
</script>

• { max: 5 } 설정을 추가하면 최근 방문한 최대 5개의 페이지를 캐싱하여 성능을 최적화합니다.
• 너무 많은 페이지를 캐싱하면 메모리 사용량이 증가할 수 있으므로 주의해야 합니다.

key 속성

페이지의 고유한 식별자를 설정하는 역할을 합니다. 특정 페이지를 강제로 다시 렌더링해야 할 때 유용합니다.

<script setup>
definePageMeta({
  key: "dashboard-page"
});
</script>

• URL이 변경될 때마다 새로 마운트하도록 하려면 route.fullPath를 활용할 수 있습니다.

<script setup>
const route = useRoute();

definePageMeta({
  key: (route) => route.fullPath // URL 변경 시 새로운 인스턴스 생성
});
</script>

redirect 속성

특정 경로에서 자동으로 다른 경로로 이동하도록 설정할 수 있습니다.

<script setup>
definePageMeta({
  redirect: "/dashboard" //자동으로 /dashboard로 이동합니다.
});
</script>

• 함수를 이용하여 동적으로 설정할 수 있습니다.

<script setup>
definePageMeta({
  redirect: (to) => to.query.redirect || "/home"
});
</script>

 

scrollToTop 속성

이 옵션을 사용하면 새로운 페이지로 이동할 때 스크롤이 자동으로 최상단으로 이동합니다. scrollToTop을 사용하면 유저가 스크롤을 내린 상태에서 페이지를 변경할 때 부자연스러운 경험을 방지할 수 있습니다.

<script setup>
definePageMeta({
  scrollToTop: true
});
</script>

middleware 속성

페이지를 로드하기 전에 적용할 미들웨어를 정의할 수 있습니다. 일치하는 상위/하위(parent/child) 경로에 사용되는 다른 모든 미들웨어와 병합됩니다. 문자열, 함수 또는 문자열/함수의 배열일 수 있습니다.

<script setup>
definePageMeta({
  middleware: ['auth']
});
</script>