[Nuxt] definePageMeta로 layout 지정 시 린트에러와 layout이 정상적으로 설정되지 않는 현상

문제 상황

Nuxt 공식문서에 따르면 definePageMeta를 이용해 페이지에 특정 레이아웃을 사용할 수 있다.

에러페이지에서 error 레이아웃을 사용하기 위해 아래와 같은 코드를 작성했다.

<script setup lang="ts">
definePageMeta({
  layout: 'error',
});
</script>
<template>
  <PageError/>
</template>

 

에러페이지에서는 error 레이아웃을 보여줘야하지만, App.vue에서 사용되고 있는 'default' 레이아웃이 표시되고 있었다. 

 

그리고 definePageMeta에는 "'definePageMeta' is not defined." 라는 린트 에러가 발생했다. 

 

원인 파악

현재 nuxt v3.12.x 버전을 사용중인데, 해당 버전에서 nuxt 깃허브 issue에서 동일한 현상으로 제보된 이슈를 발견했다..!

In nuxt@3.12.0 the definePageMeta function is broken · Issue #28591 · nuxt/nuxt

 

definePageMeta doesn't work/ gets ignored · Issue #27943 · nuxt/nuxt

 

대강 요약하자면, v3.13.0에서 이슈 해결되었다는 뜻

 

"'definePageMeta' is not defined."는 definePageMeta 관련 타입이 제대로 잡히지 않아서 발생하는 린트 에러였다.

해결 방법

definePageMeta가 제대로 동작하지 않는 이슈는 nuxt v.3.13.0 이상으로 설치하니 해소가 되었고, 린트 에러의 경우는 아래와 같이 ts를 적용하지 않고 no-undef 관련 린트룰을 제외하면 간단하게 해소가 가능했다.

<!-- <script setup lang="ts"> 사용 시 버그 발생 -->
<script setup>
// eslint-disable-next-line no-undef
definePageMeta({
  layout: 'error',
});
</script>

하지만, 이 경우 ts를 적용하지 못하기 때문에 완전한 해결방법이 아니다.

관련해서 살펴보던중 또 다시 nuxt 깃헙 issue에서 동일한 현상을 발견했는데...

Add documentation about import for definePageMeta · Issue #21306 · nuxt/nuxt

Nuxt는 프로젝트에서 사용 중인 확인된 별칭과 기타 합리적인 기본값을 사용하여 .nuxt/tsconfig.json 파일을 자동으로 생성한다. tsconfig.json에서 아래와 같이 extends를 설정하면, 별다른 설정없이 nuxt에 정의된 type을 가져올 수 있다.

현재 프로젝트에서는 alias(ex. '@/components', '~/pages')의 타입 적용을 위해 tsconfig.json 하위 path 설정을 커스텀해서 사용하고 있는데, 해당 설정을 추가하면 ./.nuxt/tsconfig.json이 무시되는 현상이 발생했다.

 

tsconfig.json의 incould에 ".nuxt/**/*.d.ts"를 추가하면, 아래와 같이 타입은 잘 잡히게된다. 

 

eslintrc.cjs 파일에 아래와 같은 코드를 추가하면, 린트 에러도 사라지게 된다.

 globals: {
    definePageMeta: 'readonly',
  },

 

아직 해결하지 못한 문제

"'xxx' is not defined." 라는 린트 에러가 발생하는 경우 eslintrc.cjs 파일에 하나씩 정의해주는 방법 말고 tsconfing.js의 types에 ".nuxt/**/*.d.ts"를 넣는 것 처럼 린트의 globals도 한 번에 등록 가능한 방법이 있는지.. 하나하나 등록하는 건 너무 귀찮고 번거롭다 ㅠ.ㅠ