Nuxt 4 패치 변경점 살펴보기

Vue 3 가 패치됬을 당시에도 Nuxt 2 -> 3에서 많은 변화가 있었는데, 꽤 길지 않은 주기로 Nuxt 4가 출시된 느낌이다. 이번 패치에서는 저번 패치(Nuxt 2 -> 3)보다는 Breaking Changes가 적게 느껴졌고, 언급했듯 패치 주기가 그렇게 길지 않았기 때문에 혼란을 최소화하도록 하는 노력이 돋보였다.

이 글은 Nuxt 4에서 변경된 주요 내용들을 살펴보고, 학습한 내용을 정리한다.

주요 변경 내용

공식 블로그에 따르면, 큰 꼭지로 나눌 수 있는 변경점이라고 하면 아래와 같이 정리할 수 있다.

프로젝트 디렉터리 구조
데이터 페칭에 대한 내용
개선된 타입스크립트 지원
더 빠른 개발 환경과 CLI 도구

각 항목별로 어떻게 변경되었는지 상세하게 살펴보자.

프로젝트 디렉터리 구조

Nuxt 3에서는 srcDir을 따로 지정하지 않는 한, 루트 디렉터리에 모든 디렉터리가 포함되어 있는 구조였다. Nuxt 4에서는 어플리케이션에 필요한 파일들을 모아 app 디렉터리에 보관하도록 명시한다.

어플리케이션에 필요한 파일들을 모은 디렉터리들의 대표 예시가 components, layouts, middleware, pages, plugins 등이 있다.

예를 들면 Nuxt 4에서는 아래와 같은 구조를 가진다.

nuxt-app/
├─ app/
│  ├─ assets/
│  ├─ components/
│  ├─ composables/
│  ├─ layouts/
│  ├─ middleware/
│  ├─ pages/
│  ├─ plugins/
│  ├─ utils/
│  ├─ app.vue
│  ├─ app.config.ts
│  └─ error.vue
├─ content/
├─ public/
├─ shared/
├─ server/
└─ nuxt.config.ts

공식 블로그의 내용에 따르면, 이렇게 하는 이유는 사용자 코드가 포함된 디렉터리를 watching 하는 부분과, 루트 디렉터리의 node_modules, .git 같은 디렉터리들의 watching 을 분리할 수 있다고 설명한다. 즉, 일부 OS에서 watching 기능이 더 빨라질 수 있다고 설명한다.

단, app 디렉터리에 코드를 포함시키지 않고, 기존 버전의 기조를 따라가면 Nuxt가 알아서 기존 구조를 감지하여 이전 버전의 기능과 동일하게 작동한다고 한다.

데이터 페칭

Nuxt에서 데이터를 가져올 때 사용하는 컴포저블 중 가장 대표적인 두 컴포저블 useAsyncData, useFetch에 대한 개선 내용이 있다.

제일 큰 변경 사항은 동일한 키를 가진 호출의 리턴 값을 공유한다는 점이다.

const { data: users1 } = useAsyncData('users', () => $fetch('/api/users'), {
  deep: false
})
const { data: users2 } = useAsyncData('users', () => $fetch('/api/users'), {
  deep: true
})

위 두 코드의 users1, users2는 동일한 참조를 가진다. - 이건 데이터 페칭 레이어가 싱글톤으로 재구성됬기 때문이다. 따라서 동일한 키를 가지면 동일한 참조를 가리키게 되는데, 위 예제의 경우 옵션이 서로 다르므로 warning이 발생한다. 명시적으로 키가 지정되어 있으면 옵션이 일관되어야 한다고 설명한다. 그리고 키 입력 부에 이제 반응형 상태를 집어 넣을 수 있다.

const userId = ref(1)
const { data: user } = useAsyncData(
  computed(() => `user-${userId.value}`),
  () => $fetch(`/api/users/${userId.value}`)
)

위와 같이 사용할 수 있고, userId 상태가 변경되면 데이터를 다시 가져온다.

이렇게보면 TanStack의 그것과 비슷하게 보일 수 있지만... 데이터의 유효 기간 보존 등 특정 상황에서 쿼리 재실행 등의 세부적인 기능은 없으므로 TanStack 의 그것을 대체하기에는 무리가 있어 보인다. 추가적으로, 특정 키를 사용한 useAsyncData 호출이 더이상 존재하지 않을 때, 컴포넌트가 언마운트되면 자동으로 메모리에서 해제되므로 메모리 누수 측면에서도 안정적이라고 볼 수 있다.

개선된 타입스크립트 지원

웃기게도 모든 타입스크립트 프로젝트들의 큰 패치에는 항상 껴있는 항목있는 것 같다. 그만큼 타입스크립트 지원에 대한 내용은 항상 개선 가능한 점이 많고, 개선해야될 점이 꾸준히 나오기도 하고, 사용자들의 체감도 큰 부분인 것 같다. Nuxt 4에서 진행된 타입스크립트 패치를 살펴보자.

먼저, 여러 섹션을 나누어 타입스크립트 프로젝트를 생성한다.

.nuxt/tsconfig.app.json Vue 컴포넌트, 컴포저블 등등
.nuxt/tsconfig.server.json 서버 사이드 코드
.nuxt/tsconfig.node.json 빌드시 필요한 코드 (모듈, nuxt.config.ts)
.nuxt/tsconfig.shared.json shared 디렉터리 내 코드에 대한 것, 클라이언트 사이드와 서버 사이드 양측 모두에서 사용되는 코드
.nuxt/tsconfig.json 이전 버전 호환성 (레거시)

잠깐, 이렇게 여러 프로젝트를 나누어 생성한 이유는 무엇일까? 정확하게는, 각 프로젝트별 적절한 유형 검사를 제공하기 위함과 IDE 경험, 성능, 더 나은 Intellisense 제공 등이 있겠다.

클라이언트 사이드에서 코드를 작성하고 있을 때, 서버 사이드에서만 사용되는 코드가 제안되거나, 자동 완성되면 안돼는 것처럼 상황마다 적절한 행위가 필요한데, 이렇게 여러 프로젝트로 나눔으로써 해결할 수 있는 부분이기도 하다. 성능 측면에서도 각 섹션별 유형 검사 방식이 다를 것이므로 성능 향상에 도움이 될 수 있는 부분이 있을 것이라 생각한다.

더 빠른 개발 환경과 CLI 도구

개발 서버 시작이 눈에 띄게 빨라졌다고 하는데, 아직까지는 마이그레이션이 완벽하게 완료되지 않아 기존 프로젝트와 시작 비교는 하지 못하였다. 근데 그런 표현을 많이 쓰는 사람들이라 그런지.... 아무튼 상세한 내용이 없어 CHANGELOG 도 살펴보고 했으나 어떤 내용으로 개발 속도 시작이 눈에띄게 향상시켰는지는 정확히 파악하지 못하였다. 아마도 이 커밋이 아닐까 생각이 든다.

그 외

스타터 템플릿의 접근성 개선, 에러 페이지 등의 UI 템플릿 개선, 제목 수정 등의 업데이트 (<NuxtWelcome /> 컴포넌트에 대한 내용 같다.)

이외에도 이 글에서 정리하지 못한 새로운 기능들이 매우 많다. 혹은 아직 개발 중인 것으로 보이는 기능인 SSR 스트리밍, 패칭 캐시 전략, 다중 앱 지원 등등등이 있다.