Nuxt를 최신 릴리스로 업그레이드하려면 nuxt upgrade 명령을 사용하세요.
npx nuxt upgrade
yarn nuxt upgrade
pnpm nuxt upgrade
bun x nuxt upgrade
최신 Nuxt 빌드를 사용하고 정식 릴리스 전에 기능을 테스트하려면, nightly 릴리스 채널 가이드를 읽어보세요.
Nuxt 5는 현재 개발 중입니다. 정식 릴리스 전까지는 Nuxt 4.2+ 버전에서 Nuxt 5의 많은 파괴적 변경 사항을 테스트할 수 있습니다.
먼저 Nuxt를 최신 릴리스로 업그레이드하세요.
그런 다음 future.compatibilityVersion을 설정하여 Nuxt 5 동작과 일치시킬 수 있습니다:
export default defineNuxtConfig({
future: {
compatibilityVersion: 5,
},
})
future.compatibilityVersion을 5로 설정하면, Nuxt 설정 전반의 기본값이 Nuxt v5 동작에 옵트인하도록 변경됩니다. 여기에는 다음이 포함됩니다:
future.compatibilityVersion: 5를 사용해 Nuxt 5를 테스트 중이라면 정기적으로 이곳을 다시 확인해 주세요.하위/상위 호환성을 위한 마이그레이션 단계와 함께 파괴적이거나 중요한 변경 사항은 아래에 표시됩니다.
🚦 영향 수준: 중간
Nuxt 5는 Vite 6의 새로운 Environment API로 마이그레이션합니다. 이 API는 환경의 개념을 공식화하고 환경별 구성에 대한 더 나은 제어를 제공합니다.
이전에는 Nuxt가 클라이언트와 서버에 대해 별도의 Vite 구성을 사용했습니다. 이제 Nuxt는 공유 Vite 구성을 사용하며, 특정 환경을 대상으로 하기 위해 applyToEnvironment() 메서드를 사용하는 환경별 플러그인을 사용합니다.
future.compatibilityVersion: 5를 설정하여 이 기능을 미리 테스트할 수 있습니다. ( Nuxt 5 테스트 참고) 또는 experimental.viteEnvironmentApi: true를 명시적으로 활성화해도 됩니다.주요 변경 사항:
extendViteConfig() 사용 중단: extendViteConfig()의 server 및 client 옵션은 사용 중단되었으며 사용 시 경고가 표시됩니다.addVitePlugin()으로 등록되고 하나의 환경만을 대상으로 하는 Vite 플러그인(server: false 또는 client: false 전달)은 더 이상 config 또는 configResolved 훅이 호출되지 않습니다.vite:extendConfig 및 vite:configResolved 훅은 이제 클라이언트/서버 별도 구성 대신 공유 구성을 사용합니다.Vite Environment API는 다음을 제공합니다:
extendViteConfig, vite:configResolved, vite:extendConfig 대신 Vite 플러그인을 사용하는 것을 권장합니다.
// Before
extendViteConfig((config) => {
config.optimizeDeps.include.push('my-package')
}, { server: false })
nuxt.hook('vite:extendConfig' /* or vite:configResolved */, (config, { isClient }) => {
if (isClient) {
config.optimizeDeps.include.push('my-package')
}
})
// After
addVitePlugin(() => ({
name: 'my-plugin',
config (config) {
// 여기에서 전역 vite 구성을 설정할 수 있습니다
},
configResolved (config) {
// 여기에서 완전히 해석된 vite 구성을 액세스할 수 있습니다
},
configEnvironment (name, config) {
// 여기에서 환경별 vite 구성을 설정할 수 있습니다
if (name === 'client') {
config.optimizeDeps ||= {}
config.optimizeDeps.include ||= []
config.optimizeDeps.include.push('my-package')
}
},
applyToEnvironment (environment) {
return environment.name === 'client'
},
}))
server: false 또는 client: false와 함께 addVitePlugin을 사용하는 대신, 플러그인 내에서 새로운 applyToEnvironment 훅을 사용할 수 있습니다.
// Before
addVitePlugin(() => ({
name: 'my-plugin',
config (config) {
config.optimizeDeps.include.push('my-package')
},
}), { client: false })
// After
addVitePlugin(() => ({
name: 'my-plugin',
config (config) {
// 여기에서 전역 vite 구성을 설정할 수 있습니다
},
configResolved (config) {
// 여기에서 완전히 해석된 vite 구성을 액세스할 수 있습니다
},
configEnvironment (name, config) {
// 여기에서 환경별 vite 구성을 설정할 수 있습니다
if (name === 'client') {
config.optimizeDeps ||= {}
config.optimizeDeps.include ||= []
config.optimizeDeps.include.push('my-package')
}
},
applyToEnvironment (environment) {
return environment.name === 'client'
},
}))
Nuxt 4에는 상당한 개선 사항과 변경 사항이 포함되어 있습니다. 이 가이드는 기존 Nuxt 3 애플리케이션을 Nuxt 4로 마이그레이션하는 데 도움을 줍니다.
먼저 Nuxt 4로 업그레이드하세요:
npm install nuxt@^4.0.0
yarn add nuxt@^4.0.0
pnpm add nuxt@^4.0.0
bun add nuxt@^4.0.0
업그레이드 후 대부분의 Nuxt 4 동작은 이제 기본값입니다. 그러나 마이그레이션 중에 하위 호환성을 유지해야 하는 경우 일부 기능은 여전히 구성할 수 있습니다.
다음 섹션에서는 Nuxt 4로 업그레이드할 때 필요한 주요 변경 사항과 마이그레이션을 자세히 설명합니다.
파괴적이거나 중요한 변경 사항은 아래에 마이그레이션 단계 및 사용 가능한 구성 옵션과 함께 문서화되어 있습니다.
업그레이드 프로세스를 용이하게 하기 위해, 우리는 Codemod 팀과 협력하여 여러 오픈 소스 codemod로 많은 마이그레이션 단계를 자동화했습니다.
npx codemod feedback으로 Codemod 팀에 보고해 주세요 🙏Nuxt 4 codemod의 전체 목록, 각 codemod에 대한 자세한 정보, 소스 및 다양한 실행 방법은 Codemod Registry를 방문하세요.
이 가이드에서 언급된 모든 codemod는 다음 codemod 레시피를 사용하여 실행할 수 있습니다:
# https://github.com/codemod/codemod/issues/1710 때문에 고정 버전 사용
npx codemod@0.18.7 nuxt/4/migration-recipe
# https://github.com/codemod/codemod/issues/1710 때문에 고정 버전 사용
yarn dlx codemod@0.18.7 nuxt/4/migration-recipe
# https://github.com/codemod/codemod/issues/1710 때문에 고정 버전 사용
pnpm dlx codemod@0.18.7 nuxt/4/migration-recipe
# https://github.com/codemod/codemod/issues/1710 때문에 고정 버전 사용
bun x codemod@0.18.7 nuxt/4/migration-recipe
이 명령은 실행을 원하지 않는 codemod를 선택 해제할 수 있는 옵션과 함께 모든 codemod를 순차적으로 실행합니다. 각 codemod는 아래에 해당 변경 사항과 함께 나열되어 있으며, 독립적으로 실행할 수도 있습니다.
🚦 영향 수준: 상당함
Nuxt는 이제 새로운 디렉터리 구조를 기본값으로 사용하며, 하위 호환성을 제공합니다. (예: 최상위에 app/pages/ 디렉터리가 있는 기존 구조를 Nuxt가 감지하면 이 새로운 구조는 적용되지 않습니다.)
srcDir는 기본적으로 app/이며, 대부분의 항목은 이곳에서 해석됩니다.serverDir는 이제 <srcDir>/server 대신 <rootDir>/server를 기본값으로 사용합니다.layers/, modules/, public/은 기본적으로 <rootDir> 기준으로 해석됩니다.content/는 <rootDir> 기준으로 해석됩니다.dir.app이 추가되었으며, 이 디렉터리는 router.options.ts와 spa-loading-template.html을 찾는 위치입니다. 기본값은 <srcDir>/입니다..output/
.nuxt/
app/
assets/
components/
composables/
layouts/
middleware/
pages/
plugins/
utils/
app.config.ts
app.vue
router.options.ts
content/
layers/
modules/
node_modules/
public/
shared/
server/
api/
middleware/
plugins/
routes/
utils/
nuxt.config.ts
~ 별칭은 기본적으로 app/ 디렉터리(즉, srcDir)를 가리킵니다. 즉, ~/components는 app/components/, ~/pages는 app/pages/로 해석됩니다.👉 자세한 내용은 이 변경을 구현한 PR을 참조하세요.
.git/ 및 node_modules/ 폴더가 FS 워처에 의해 스캔/포함되어, 특히 Mac이 아닌 OS에서 시작 시간이 크게 지연될 수 있습니다.server/와 앱의 나머지 부분은 서로 완전히 다른 컨텍스트에서 실행되며, 사용 가능한 전역 import도 다릅니다. server/가 앱의 나머지 부분과 같은 폴더 _내부_에 있지 않도록 하는 것은 IDE에서 좋은 자동 완성을 보장하기 위한 중요한 첫 단계입니다.app/이라는 새 디렉터리를 생성합니다.assets/, components/, composables/, app/layouts/, app/middleware/, app/pages/, app/plugins/, utils/ 폴더와 app.vue, error.vue, app.config.ts를 이 디렉터리 아래로 이동합니다. app/router-options.ts 또는 app/spa-loading-template.html이 있는 경우, 이 경로는 그대로 유지됩니다.nuxt.config.ts, content/, layers/, modules/, public/, server/ 폴더는 app/ 폴더 밖, 프로젝트 루트에 그대로 두세요.tailwindcss나 eslint 설정과 같은 서드파티 설정 파일이 새로운 디렉터리 구조에서 올바르게 동작하는지 확인하세요. (필요한 경우에만 - @nuxtjs/tailwindcss는 tailwindcss를 자동으로 올바르게 구성해야 합니다.)npx codemod@latest nuxt/4/file-structure를 실행하여 이 마이그레이션을 자동화할 수 있습니다.그러나 마이그레이션은 필수는 아닙니다. 현재 폴더 구조를 유지하려면 Nuxt가 이를 자동으로 감지해야 합니다. (그렇지 않다면 이슈를 등록해 주세요.) 한 가지 예외는 이미 사용자 정의 srcDir를 사용 중인 경우입니다. 이 경우 modules/, public/, server/ 폴더는 사용자 정의 srcDir가 아니라 rootDir 기준으로 해석된다는 점을 알아야 합니다. 필요하다면 dir.modules, dir.public, serverDir를 구성하여 이를 재정의할 수 있습니다.
다음 설정을 사용하여 v3 폴더 구조를 강제로 사용할 수도 있습니다:
export default defineNuxtConfig({
// 새로운 srcDir 기본값 `app`을 루트 디렉터리로 되돌립니다
srcDir: '.',
// `router.options.ts`와 `spa-loading-template.html`의 디렉터리 접두사를 지정합니다
dir: {
app: 'app',
},
})
🚦 영향 수준: 중간
Nuxt의 데이터 페칭 시스템(useAsyncData 및 useFetch)이 성능과 일관성을 위해 크게 재구성되었습니다:
useAsyncData 또는 useFetch를 호출하면 이제 동일한 data, error, status ref를 공유합니다. 즉, 명시적 키를 사용하는 모든 호출은 deep, transform, pick, getCachedData, default 옵션이 서로 충돌하지 않아야 합니다.getCachedData에 대한 더 많은 제어: getCachedData 함수는 이제 데이터가 페칭될 때마다 호출됩니다. 이는 워처에 의해 또는 refreshNuxtData 호출로 인해 발생하는 경우도 포함됩니다. (이전에는 이러한 경우 항상 새 데이터를 페칭했으며 이 함수는 호출되지 않았습니다.) 캐시 데이터를 언제 사용할지, 언제 다시 페칭할지에 대한 더 많은 제어를 위해, 이 함수는 요청의 원인을 포함하는 컨텍스트 객체를 받습니다.useAsyncData로 페칭된 데이터를 사용하는 마지막 컴포넌트가 언마운트되면, Nuxt는 메모리 사용량이 계속 증가하는 것을 방지하기 위해 해당 데이터를 제거합니다.이러한 변경은 메모리 사용량을 개선하고 useAsyncData 호출 간의 로딩 상태 일관성을 높이기 위해 이루어졌습니다.
// 이제 경고가 발생합니다
const { data: users1 } = useAsyncData('users', () => $fetch('/api/users'), { deep: false })
const { data: users2 } = useAsyncData('users', () => $fetch('/api/users'), { deep: true })
명시적 키를 공유하고(그리고 사용자 정의 옵션을 가진) useAsyncData 호출은 별도의 composable로 추출하는 것이 좋을 수 있습니다:
export function useUserData (userId: string) {
return useAsyncData(
`user-${userId}`,
() => fetchUser(userId),
{
deep: true,
transform: user => ({ ...user, lastAccessed: new Date() }),
},
)
}
getCachedData 구현 업데이트:useAsyncData('key', fetchFunction, {
- getCachedData: (key, nuxtApp) => {
- return cachedData[key]
- }
+ getCachedData: (key, nuxtApp, ctx) => {
+ // ctx.cause - 'initial' | 'refresh:hook' | 'refresh:manual' | 'watch' 중 하나입니다
+
+ // 예: 수동 새로고침 시 캐시를 사용하지 않기
+ if (ctx.cause === 'refresh:manual') return undefined
+
+ return cachedData[key]
+ }
})
또는, 당분간 다음 설정으로 이 동작을 비활성화할 수 있습니다:
export default defineNuxtConfig({
experimental: {
granularCachedData: false,
purgeCachedData: false,
},
})
🚦 영향 수준: 최소
Nuxt 레이어를 사용할 때 모듈이 로드되는 순서가 수정되었습니다. 이전에는 프로젝트 루트의 모듈이 확장 레이어의 모듈보다 먼저 로드되었는데, 이는 기대되는 동작과 반대였습니다.
이제 모듈은 올바른 순서로 로드됩니다:
이는 다음 모두에 영향을 미칩니다:
nuxt.config.ts의 modules 배열에 정의된 모듈modules/ 디렉터리에서 자동으로 발견된 모듈이 변경은 다음을 보장합니다:
대부분의 프로젝트는 변경이 필요하지 않습니다. 이 변경은 로딩 순서를 기대되는 동작과 일치하도록 수정합니다.
그러나 이전의 잘못된 순서에 의존하던 프로젝트라면 다음이 필요할 수 있습니다:
새로운 올바른 순서의 예:
// 레이어: my-layer/nuxt.config.ts
export default defineNuxtConfig({
modules: ['layer-module-1', 'layer-module-2'],
})
// 프로젝트: nuxt.config.ts
export default defineNuxtConfig({
extends: ['./my-layer'],
modules: ['project-module-1', 'project-module-2'],
})
// 로딩 순서 (수정됨):
// 1. layer-module-1
// 2. layer-module-2
// 3. project-module-1 (레이어 모듈을 오버라이드할 수 있음)
// 4. project-module-2 (레이어 모듈을 오버라이드할 수 있음)
훅을 등록해야 해서 모듈 순서 의존성에 문제가 발생한다면, 훅을 호출해야 하는 모듈에 modules:done 훅 사용을 고려하세요. 이 훅은 다른 모든 모듈이 로드된 후 실행되므로 안전하게 사용할 수 있습니다.
👉 자세한 내용은 PR #31507 및 이슈 #25719를 참조하세요.
🚦 영향 수준: 최소
definePageMeta를 사용하여 name, path 등 일부 라우트 메타데이터를 설정할 수 있습니다. 이전에는 이러한 값이 라우트와 라우트 메타데이터 모두에서 사용 가능했습니다. (예: route.name 및 route.meta.name)
이제 이 값들은 라우트 객체에서만 접근할 수 있습니다.
이는 experimental.scanPageMeta를 기본값으로 활성화한 결과이며, 성능 최적화입니다.
마이그레이션은 간단해야 합니다:
const route = useRoute()
- console.log(route.meta.name)
+ console.log(route.name)
🚦 영향 수준: 중간
이제 Vue는 컴포넌트 이름을 Nuxt의 컴포넌트 네이밍 패턴과 일치하도록 생성합니다.
기본적으로, 수동으로 설정하지 않았다면 Vue는 컴포넌트 파일 이름과 일치하는 컴포넌트 이름을 할당합니다.
├─ components/
├─── SomeFolder/
├───── MyComponent.vue
이 경우 Vue 관점에서 컴포넌트 이름은 MyComponent입니다. <KeepAlive>에서 사용하거나 Vue DevTools에서 식별하려면 이 이름을 사용해야 합니다.
하지만 자동 import를 사용하려면 SomeFolderMyComponent를 사용해야 했습니다.
이 변경으로 두 값이 일치하게 되며, Vue는 Nuxt의 컴포넌트 네이밍 패턴과 일치하는 컴포넌트 이름을 생성합니다.
@vue/test-utils의 findComponent를 사용하는 테스트와, 컴포넌트 이름에 의존하는 <KeepAlive>에서 업데이트된 이름을 사용하는지 확인하세요.
또는, 당분간 다음 설정으로 이 동작을 비활성화할 수 있습니다:
export default defineNuxtConfig({
experimental: {
normalizeComponentNames: false,
},
})
🚦 영향 수준: 최소
<head> 태그 생성을 위해 사용되는 Unhead가 버전 2로 업데이트되었습니다.
대부분 호환되지만, 저수준 API에 대해 몇 가지 파괴적 변경 사항이 포함되어 있습니다.
vmid, hid, children, body.위 변경 사항은 앱에 최소한의 영향을 미쳐야 합니다.
문제가 있다면 다음을 확인해야 합니다:
useHead({
meta: [{
name: 'description',
// meta 태그에는 vmid나 key가 필요하지 않습니다
- vmid: 'description'
- hid: 'description'
}]
})
import { AliasSortingPlugin, TemplateParamsPlugin } from '@unhead/vue/plugins'
export default defineNuxtPlugin({
setup () {
const unhead = injectHead()
unhead.use(TemplateParamsPlugin)
unhead.use(AliasSortingPlugin)
},
})
필수는 아니지만, @unhead/vue에서의 import를 #imports 또는 nuxt/app으로 업데이트하는 것이 권장됩니다.
-import { useHead } from '@unhead/vue'
+import { useHead } from '#imports'
여전히 문제가 있다면 head.legacy 설정을 활성화하여 v1 동작으로 되돌릴 수 있습니다.
export default defineNuxtConfig({
unhead: {
legacy: true,
},
})
🚦 영향 수준: 최소
클라이언트 전용 페이지(ssr: false)를 렌더링할 때, 선택적으로 Nuxt 앱 루트 내에 로딩 화면(~/app/spa-loading-template.html에서 가져옴 - Nuxt 4에서는 ~/spa-loading-template.html로 변경되었음을 참고)을 렌더링했습니다:
<div id="__nuxt">
<!-- spa loading template -->
</div>
이제 기본적으로 Nuxt 앱 루트와 나란히 템플릿을 렌더링합니다:
<div id="__nuxt"></div>
<!-- spa loading template -->
이 변경으로 Vue 앱의 suspense가 resolve될 때까지 spa 로딩 템플릿이 DOM에 남아 있어, 흰 화면이 잠깐 보이는 현상을 방지할 수 있습니다.
CSS 또는 document.queryElement로 spa 로딩 템플릿을 선택하고 있었다면, 선택자를 업데이트해야 합니다. 이를 위해 새로운 app.spaLoaderTag 및 app.spaLoaderAttrs 구성 옵션을 사용할 수 있습니다.
또는, 다음 설정으로 이전 동작으로 되돌릴 수 있습니다:
export default defineNuxtConfig({
experimental: {
spaLoadingTemplateLocation: 'within',
},
})
error.data🚦 영향 수준: 최소
data 속성이 있는 에러를 throw하는 것이 가능했지만, 이 값은 파싱되지 않았습니다. 이제 이 값이 파싱되어 error 객체에서 사용할 수 있습니다. 이는 버그 수정이지만, 이전 동작에 의존해 수동으로 파싱하고 있었다면 기술적으로는 파괴적 변경입니다.
사용자 정의 error.vue에서 error.data에 대한 추가 파싱을 제거하세요:
<script setup lang="ts">
import type { NuxtError } from '#app'
const props = defineProps({
error: Object as () => NuxtError
})
- const data = JSON.parse(error.data)
+ const data = error.data
</script>
🚦 영향 수준: 중간
Nuxt는 이제 전역 CSS가 아닌 Vue 컴포넌트에 대해서만 스타일을 인라인합니다.
이전에는 Nuxt가 전역 스타일을 포함한 모든 CSS를 인라인하고, 별도의 CSS 파일에 대한 <link> 요소를 제거했습니다. 이제 Nuxt는 Vue 컴포넌트에 대해서만(이전에는 별도의 CSS 청크를 생성하던) 이 작업을 수행합니다. 이는 초기 로드 시 페이지별 또는 컴포넌트별 개별 .css 파일에 대한 별도 요청이 없다는 점에서 네트워크 요청을 줄이는 동시에, 단일 전역 CSS 파일의 캐싱을 허용하고 초기 요청의 문서 다운로드 크기를 줄이는 더 나은 균형이라고 생각합니다.
이 기능은 완전히 구성 가능하며, 전역 CSS와 컴포넌트별 CSS 모두를 인라인하려면 inlineStyles: true를 설정하여 이전 동작으로 되돌릴 수 있습니다.
export default defineNuxtConfig({
features: {
inlineStyles: true,
},
})
🚦 영향 수준: 최소
이제 definePageMeta에 정의된 페이지 메타데이터는 pages:extend 훅을 호출한 이후에 스캔됩니다.
이는 사용자가 pages:extend에서 추가하고자 하는 페이지의 메타데이터를 스캔할 수 있도록 하기 위함입니다. 여전히 새로운 pages:resolved 훅에서 페이지 메타데이터를 변경하거나 오버라이드할 수 있는 기회를 제공합니다.
페이지 메타데이터를 오버라이드하려면 pages:extend가 아니라 pages:resolved에서 수행하세요.
export default defineNuxtConfig({
hooks: {
- 'pages:extend'(pages) {
+ 'pages:resolved'(pages) {
const myPage = pages.find(page => page.path === '/')
myPage.meta ||= {}
myPage.meta.layout = 'overridden-layout'
}
}
})
또는, 다음 설정으로 이전 동작으로 되돌릴 수 있습니다:
export default defineNuxtConfig({
experimental: {
scanPageMeta: true,
},
})
🚦 영향 수준: 중간
useAsyncData 및 useFetch 호출에서 데이터를 페이지 간에 공유하는, 이전의 실험적 기능을 활성화했습니다. 원래 PR을 참조하세요.
이 기능은 프리렌더링된 페이지 간에 payload _데이터_를 자동으로 공유합니다. 이는 useAsyncData 또는 useFetch를 사용하고 서로 다른 페이지에서 동일한 데이터를 페칭하는 사이트를 프리렌더링할 때 상당한 성능 향상을 가져올 수 있습니다.
예를 들어, 사이트의 모든 페이지에서 useFetch 호출이 필요하다면(예: 메뉴용 내비게이션 데이터 또는 CMS에서 사이트 설정을 가져오기 위해), 이 데이터는 이를 사용하는 첫 번째 페이지를 프리렌더링할 때 한 번만 페칭되고, 이후 다른 페이지를 프리렌더링할 때 캐시된 데이터가 사용됩니다.
데이터의 고유 키가 항상 동일한 데이터로 해석될 수 있도록 하세요. 예를 들어, 특정 페이지와 관련된 데이터를 페칭하기 위해 useAsyncData를 사용하는 경우, 해당 데이터를 고유하게 식별하는 키를 제공해야 합니다. (useFetch는 이를 자동으로 처리해야 합니다.)
// 이 코드는 동적 페이지(예: `[slug].vue`)에서 안전하지 않습니다.
// 라우트 slug가 페칭되는 데이터에 영향을 주지만, 키에 반영되지 않아 Nuxt가 이를 알 수 없기 때문입니다.
const route = useRoute()
const { data } = await useAsyncData(async () => {
return await $fetch(`/api/my-page/${route.params.slug}`)
})
// 대신, 페칭되는 데이터를 고유하게 식별하는 키를 사용해야 합니다.
const { data } = await useAsyncData(route.params.slug, async () => {
return await $fetch(`/api/my-page/${route.params.slug}`)
})
또는, 다음 설정으로 이 기능을 비활성화할 수 있습니다:
export default defineNuxtConfig({
experimental: {
sharedPrerenderData: false,
},
})
useAsyncData 및 useFetch의 기본 data 및 error 값🚦 영향 수준: 최소
useAsyncData에서 반환되는 data 및 error 객체는 이제 기본값이 undefined입니다.
이전에는 data가 null로 초기화되었지만, clearNuxtData에서 undefined로 재설정되었습니다. error는 null로 초기화되었습니다. 이번 변경은 더 큰 일관성을 위한 것입니다.
data.value 또는 error.value가 null인지 확인하고 있었다면, 이제 undefined를 확인하도록 업데이트할 수 있습니다.
npx codemod@latest nuxt/4/default-data-error-value를 실행하여 이 단계를 자동화할 수 있습니다.useAsyncData 및 useFetch에서 refresh 호출 시 dedupe 옵션의 boolean 값 제거🚦 영향 수준: 최소
이전에는 refresh에 dedupe: boolean을 전달할 수 있었습니다. 이 값들은 각각 cancel(true)과 defer(false)의 별칭이었습니다.
const { refresh } = await useAsyncData(() => Promise.resolve({ message: 'Hello, Nuxt!' }))
async function refreshData () {
await refresh({ dedupe: true })
}
이 별칭들은 더 명확성을 위해 제거되었습니다.
useAsyncData에 dedupe 옵션을 추가할 때 이 문제가 발생했으며, 두 값이 결국 반대 의미를 가지게 되어 boolean 값을 제거했습니다.
refresh({ dedupe: false })는 기존 요청을 이 새로운 요청을 위해 취소하지 않는다는 의미였습니다. 하지만 useAsyncData 옵션 내에서 dedupe: true를 전달하는 것은 기존에 보류 중인 요청이 있다면 새로운 요청을 만들지 않는다는 의미입니다. ( PR 참고)
마이그레이션은 간단해야 합니다:
const { refresh } = await useAsyncData(async () => ({ message: 'Hello, Nuxt 3!' }))
async function refreshData () {
- await refresh({ dedupe: true })
+ await refresh({ dedupe: 'cancel' })
- await refresh({ dedupe: false })
+ await refresh({ dedupe: 'defer' })
}
npx codemod@latest nuxt/4/deprecated-dedupe-value를 실행하여 이 단계를 자동화할 수 있습니다.useAsyncData 및 useFetch에서 data를 지울 때 기본값 존중🚦 영향 수준: 최소
useAsyncData에 사용자 정의 default 값을 제공한 경우, 이제 clear 또는 clearNuxtData를 호출할 때 이 값이 사용되며, 단순히 해제되는 대신 기본값으로 재설정됩니다.
사용자는 종종 반복 시 null/undefined를 확인할 필요가 없도록 빈 배열과 같은 적절한 비어 있는 값을 설정합니다. 데이터 재설정/삭제 시 이러한 값이 존중되어야 합니다.
useAsyncData 및 useFetch에서 pending 값 정렬🚦 영향 수준: 중간
useAsyncData, useFetch, useLazyAsyncData, useLazyFetch에서 반환되는 pending 객체는 이제 status가 pending일 때만 true가 되는 계산 속성입니다.
이제 immediate: false가 전달되면, 첫 번째 요청이 이루어질 때까지 pending은 false입니다. 이는 이전 동작(첫 번째 요청이 이루어질 때까지 pending이 항상 true였던 것)과 다릅니다.
이는 요청이 진행 중일 때 pending이 pending인 status 속성과 의미를 일치시키기 위한 것입니다.
pending 속성에 의존하고 있다면, 이제 pending이 status가 pending일 때만 true라는 새로운 동작을 고려하도록 로직을 조정해야 합니다.
<template>
- <div v-if="!pending">
+ <div v-if="status === 'success'">
<p>Data: {{ data }}</p>
</div>
<div v-else>
<p>Loading...</p>
</div>
</template>
<script setup lang="ts">
const { data, pending, execute, status } = await useAsyncData(() => fetch('/api/data'), {
immediate: false
})
onMounted(() => execute())
</script>
또는, 다음 설정으로 이전 동작으로 임시로 되돌릴 수 있습니다:
export default defineNuxtConfig({
experimental: {
pendingWhenIdle: true,
},
})
useAsyncData 및 useFetch에서 키 변경 동작🚦 영향 수준: 중간
useAsyncData 또는 useFetch에서 반응형 키를 사용할 때, 키가 변경되면 Nuxt는 자동으로 데이터를 다시 페칭합니다. immediate: false가 설정된 경우, useAsyncData는 데이터가 한 번 이상 페칭된 경우에만 키 변경 시 데이터를 페칭합니다.
이전에는 useFetch가 약간 다른 동작을 했습니다. 키가 변경될 때마다 항상 데이터를 페칭했습니다.
이제 useFetch와 useAsyncData는 일관되게 동작합니다. 즉, 데이터가 한 번 이상 페칭된 경우에만 키 변경 시 데이터를 페칭합니다.
이는 useAsyncData와 useFetch 간의 동작을 일관되게 하고, 예기치 않은 페칭을 방지하기 위함입니다. immediate: false를 설정한 경우, useFetch 또는 useAsyncData에서 데이터를 페칭하려면 refresh 또는 execute를 호출해야 합니다. 그렇지 않으면 데이터는 절대 페칭되지 않습니다.
이 변경은 일반적으로 기대되는 동작을 개선하지만, immediate가 아닌 useFetch에서 키 또는 옵션 변경만으로 첫 번째 페칭이 이루어지기를 기대했다면, 이제는 첫 번째 페칭을 수동으로 트리거해야 합니다.
const id = ref('123')
const { data, execute } = await useFetch('/api/test', {
query: { id },
immediate: false
})
+ watch(id, () => execute(), { once: true })
이 동작을 옵트아웃하려면:
// 또는 Nuxt 설정에서 전역으로
export default defineNuxtConfig({
experimental: {
alwaysRunFetchOnKeyChange: true,
},
})
useAsyncData 및 useFetch에서 얕은 데이터 반응성🚦 영향 수준: 최소
useAsyncData, useFetch, useLazyAsyncData, useLazyFetch에서 반환되는 data 객체는 이제 ref가 아닌 shallowRef입니다.
새 데이터가 페칭되면, 전체 객체가 교체되므로 data에 의존하는 모든 것은 여전히 반응형입니다. 하지만 코드에서 해당 데이터 구조 _내부_의 속성을 변경하는 경우, 이는 앱의 반응성을 트리거하지 않습니다.
이는 깊게 중첩된 객체와 배열에 대해 Vue가 모든 속성/배열의 변경을 감시할 필요가 없어지므로 상당한 성능 향상을 가져옵니다. 대부분의 경우 data는 불변이어야 하기도 합니다.
대부분의 경우 마이그레이션 단계가 필요 없지만, 데이터 객체의 반응성에 의존하는 경우 두 가지 선택지가 있습니다:
- const { data } = useFetch('/api/test')
+ const { data } = useFetch('/api/test', { deep: true })
export default defineNuxtConfig({
experimental: {
defaults: {
useAsyncData: {
deep: true,
},
},
},
})
npx codemod@latest nuxt/4/shallow-function-reactivity를 실행하여 이 단계를 자동화할 수 있습니다.builder:watch에서 절대 경로 감시🚦 영향 수준: 최소
Nuxt의 builder:watch 훅은 이제 프로젝트 srcDir 기준 상대 경로가 아닌, 절대 경로를 내보냅니다.
이를 통해 srcDir 밖의 경로 감시를 지원하고, 레이어 및 기타 더 복잡한 패턴에 대한 더 나은 지원을 제공합니다.
이 훅을 사용하는 것으로 알려진 공개 Nuxt 모듈은 이미 사전에 마이그레이션했습니다. 이슈 #25339를 참조하세요.
그러나 builder:watch 훅을 사용하는 모듈 작성자이며, Nuxt v3 및 Nuxt v4에서 하위/상위 호환성을 유지하고자 한다면, 다음 코드를 사용하여 두 버전에서 동일하게 동작하도록 할 수 있습니다:
+ import { relative, resolve } from 'node:fs'
// ...
nuxt.hook('builder:watch', async (event, path) => {
+ path = relative(nuxt.options.srcDir, resolve(nuxt.options.srcDir, path))
// ...
})
npx codemod@latest nuxt/4/absolute-watch-path를 실행하여 이 단계를 자동화할 수 있습니다.window.__NUXT__ 객체 제거앱이 hydration을 마친 후 전역 window.__NUXT__ 객체를 제거합니다.
이는 멀티 앱 패턴(#21635)을 가능하게 하고, Nuxt 앱 데이터에 접근하는 단일 방식인 useNuxtApp()에 집중할 수 있도록 합니다.
데이터는 여전히 사용 가능하지만, 이제 useNuxtApp().payload로 접근할 수 있습니다:
- console.log(window.__NUXT__)
+ console.log(useNuxtApp().payload)
🚦 영향 수준: 중간
app/middleware/ 폴더의 하위 폴더도 index 파일을 스캔하며, 이제 이 파일들도 프로젝트의 미들웨어로 등록됩니다.
Nuxt는 app/middleware/ 및 app/plugins/를 포함한 여러 폴더를 자동으로 스캔합니다.
app/plugins/ 폴더의 하위 폴더는 index 파일을 스캔하며, 우리는 스캔되는 디렉터리 간의 동작을 일관되게 만들고자 했습니다.
아마도 마이그레이션이 필요 없겠지만, 이전 동작으로 되돌리고 싶다면 다음 훅을 추가하여 이러한 미들웨어를 필터링할 수 있습니다:
export default defineNuxtConfig({
hooks: {
'app:resolve' (app) {
app.middleware = app.middleware.filter(mw => !/\/index\.[^/]+$/.test(mw.path))
},
},
})
🚦 영향 수준: 최소
이전에는 Nuxt가 .ejs 파일 형식/문법을 사용하여 파일 시스템에 있는 템플릿을 컴파일하기 위해 lodash/template를 사용했습니다.
또한, 이러한 템플릿 내에서 코드 생성을 위해 사용할 수 있는 템플릿 유틸리티(serialize, importName, importSources)를 제공했는데, 이제 제거됩니다.
Nuxt v3에서는 훨씬 더 유연하고 성능이 좋은 getContents() 함수가 있는 '가상' 문법으로 전환했습니다.
또한, lodash/template는 연속적인 보안 이슈가 있었습니다. 이는 Nuxt 프로젝트에서는 빌드 타임에 신뢰할 수 있는 코드에 의해 사용되므로 실제로는 큰 문제가 되지 않지만, 여전히 보안 감사에 나타납니다. 게다가 lodash는 대부분의 프로젝트에서 사용되지 않는 무거운 의존성입니다.
마지막으로, Nuxt 내에서 직접 코드 직렬화 함수를 제공하는 것은 이상적이지 않습니다. 대신, 우리는 unjs/knitwork와 같은 프로젝트를 유지 관리하며, 이는 프로젝트의 의존성이 될 수 있고, 보안 이슈는 Nuxt 자체를 업그레이드할 필요 없이 직접 보고/해결할 수 있습니다.
EJS 문법을 사용하는 모듈을 업데이트하기 위해 PR을 올렸지만, 직접 해야 한다면 하위/상위 호환 가능한 세 가지 대안이 있습니다:
getContents()로 옮깁니다.es-toolkit/compat(lodash template의 드롭인 대체)를 사용합니다:+ import { readFileSync } from 'node:fs'
+ import { template } from 'es-toolkit/compat'
// ...
addTemplate({
fileName: 'appinsights-vue.js'
options: { /* some options */ },
- src: resolver.resolve('./runtime/plugin.ejs'),
+ getContents({ options }) {
+ const contents = readFileSync(resolver.resolve('./runtime/plugin.ejs'), 'utf-8')
+ return template(contents)({ options })
+ },
})
마지막으로, 템플릿 유틸리티(serialize, importName, importSources)를 사용 중이라면, 이를 knitwork의 유틸리티로 다음과 같이 대체할 수 있습니다:
import { genDynamicImport, genImport, genSafeVariableName } from 'knitwork'
const serialize = (data: any) => JSON.stringify(data, null, 2).replace(/"\{(.+)\}"(?=,?$)/gm, r => JSON.parse(r).replace(/^\{(.*)\}$/, '$1'))
const importSources = (sources: string | string[], { lazy = false } = {}) => {
return toArray(sources).map((src) => {
if (lazy) {
return `const ${genSafeVariableName(src)} = ${genDynamicImport(src, { comment: `webpackChunkName: ${JSON.stringify(src)}` })}`
}
return genImport(src, genSafeVariableName(src))
}).join('\n')
}
const importName = genSafeVariableName
npx codemod@latest nuxt/4/template-compilation-changes를 실행하여 이 단계를 자동화할 수 있습니다.🚦 영향 수준: 최소
compilerOptions.noUncheckedIndexedAccess가 false에서 true로 변경되었습니다.
이 변경은 대부분 TotalTypeScript의 권장 사항을 따르며, 이전 3.12 설정 업데이트의 후속 조치입니다.
두 가지 접근 방식이 있습니다:
nuxt.config.ts에서 새로운 기본값을 재정의합니다:export default defineNuxtConfig({
typescript: {
tsConfig: {
compilerOptions: {
noUncheckedIndexedAccess: false,
},
},
},
})
🚦 영향 수준: 최소
Nuxt는 더 나은 타입 체크 경험을 제공하기 위해 서로 다른 컨텍스트에 대해 별도의 TypeScript 설정을 생성합니다:
.nuxt/tsconfig.app.json - 앱 코드용 (Vue 컴포넌트, composable 등).nuxt/tsconfig.server.json - 서버 사이드 코드용 (Nitro/server 디렉터리).nuxt/tsconfig.node.json - 빌드 타임 코드용 (모듈, nuxt.config.ts 등).nuxt/tsconfig.shared.json - 앱과 서버 컨텍스트 간에 공유되는 코드용 (타입 및 환경 비의존 유틸리티 등).nuxt/tsconfig.json - 하위 호환성을 위한 레거시 설정.nuxt/tsconfig.json을 확장하는 기존 프로젝트는 이전과 동일하게 동작합니다.typescript.nodeTsConfig 옵션: 이제 Node.js 빌드 타임 코드에 대한 TypeScript 설정을 사용자 정의할 수 있습니다.이 변경은 다음과 같은 이점을 제공합니다:
예를 들어, nuxt.config.ts에서는 auto-import가 사용 가능하지 않지만, 이전에는 TypeScript가 이를 표시하지 않았습니다. 또한 IDE는 server/ 디렉터리의 tsconfig.json으로 별도 컨텍스트를 인식했지만, 이는 타입 체크에 반영되지 않아 별도의 단계가 필요했습니다.
마이그레이션은 필요하지 않습니다. 기존 프로젝트는 이전과 동일하게 동작합니다.
그러나 향상된 타입 체크를 활용하려면, 새로운 프로젝트 참조 방식을 옵트인할 수 있습니다:
tsconfig.json을 프로젝트 참조를 사용하도록 업데이트:tsconfig.json에 "extends": "./.nuxt/tsconfig.json" 줄이 있다면, 참조를 추가하기 전에 제거하세요. 프로젝트 참조와 extends는 상호 배타적입니다.{
// 존재한다면 "extends": "./.nuxt/tsconfig.json"을 제거하세요
"files": [],
"references": [
{ "path": "./.nuxt/tsconfig.app.json" },
{ "path": "./.nuxt/tsconfig.server.json" },
{ "path": "./.nuxt/tsconfig.shared.json" },
{ "path": "./.nuxt/tsconfig.node.json" }
]
}
.nuxt/tsconfig.server.json을 확장하던 server/tsconfig.json과 같은 수동 서버 tsconfig.json 파일을 제거합니다.- "typecheck": "nuxt prepare && vue-tsc --noEmit"
+ "typecheck": "nuxt prepare && vue-tsc -b --noEmit"
app/ 디렉터리로 이동합니다.server/ 디렉터리로 이동합니다.shared/ 디렉터리로 이동합니다.app/, server/, shared/ 디렉터리 밖에서 타입을 보강하는 것은 새로운 프로젝트 참조 설정에서 동작하지 않습니다.export default defineNuxtConfig({
typescript: {
// tsconfig.app.json 사용자 정의
tsConfig: {
// ...
},
// tsconfig.shared.json 사용자 정의
sharedTsConfig: {
// ...
},
// tsconfig.node.json 사용자 정의
nodeTsConfig: {
// ...
},
},
nitro: {
typescript: {
// tsconfig.server.json 사용자 정의
tsConfig: {
// ...
},
},
},
})
새로운 설정은 옵트인하는 프로젝트에 더 나은 타입 안정성과 IntelliSense를 제공하며, 기존 설정에 대한 완전한 하위 호환성을 유지합니다.
🚦 영향 수준: 최소
Nuxt 4에서는 네 가지 실험적 기능을 더 이상 구성할 수 없습니다:
experimental.treeshakeClientOnly는 true입니다 (v3.0부터 기본값)experimental.configSchema는 true입니다 (v3.3부터 기본값)experimental.polyfillVueUseHead는 false입니다 (v3.4부터 기본값)experimental.respectNoSSRHeader는 false입니다 (v3.4부터 기본값)vite.devBundler는 더 이상 구성할 수 없으며, 기본적으로 vite-node를 사용합니다.이 옵션들은 오랫동안 현재 값으로 설정되어 있었으며, 계속 구성 가능하게 유지해야 할 이유가 없습니다.
polyfillVueUseHead는 이 플러그인을 사용해 사용자 코드에서 구현할 수 있습니다.respectNoSSRHeader는 서버 미들웨어를 사용해 사용자 코드에서 구현할 수 있습니다.generate 설정 제거🚦 영향 수준: 최소
Nuxt 4에서는 최상위 generate 설정 옵션을 더 이상 사용할 수 없습니다. 여기에는 다음 속성이 포함됩니다:
generate.exclude - 프리렌더링에서 라우트를 제외generate.routes - 프리렌더링할 라우트 지정최상위 generate 설정은 Nuxt 2에서 이어진 것입니다. 우리는 이미 한동안 nitro.prerender를 지원해 왔으며, 이는 Nuxt 3+에서 프리렌더링을 구성하는 선호되는 방법입니다.
generate 설정을 해당하는 nitro.prerender 옵션으로 교체하세요:
export default defineNuxtConfig({
- generate: {
- exclude: ['/admin', '/private'],
- routes: ['/sitemap.xml', '/robots.txt']
- }
+ nitro: {
+ prerender: {
+ ignore: ['/admin', '/private'],
+ routes: ['/sitemap.xml', '/robots.txt']
+ }
+ }
})
아래 표는 세 가지 Nuxt 버전을 간단히 비교한 것입니다:
| Feature / Version | Nuxt 2 | Nuxt Bridge | Nuxt 3+ |
|---|---|---|---|
| Vue | 2 | 2 | 3 |
| Stability | 😊 Stable | 😊 Stable | 😊 Stable |
| Performance | 🏎 Fast | ✈️ Faster | 🚀 Fastest |
| Nitro Engine | ❌ | ✅ | ✅ |
| ESM support | 🌙 Partial | 👍 Better | ✅ |
| TypeScript | ☑️ Opt-in | 🚧 Partial | ✅ |
| Composition API | ❌ | 🚧 Partial | ✅ |
| Options API | ✅ | ✅ | ✅ |
| Components Auto Import | ✅ | ✅ | ✅ |
<script setup> syntax | ❌ | 🚧 Partial | ✅ |
| Auto Imports | ❌ | ✅ | ✅ |
| webpack | 4 | 4 | 5 |
| Vite | ⚠️ Partial | 🚧 Partial | ✅ |
| Nuxt CLI | ❌ Old | ✅ nuxt | ✅ nuxt |
| Static sites | ✅ | ✅ | ✅ |
마이그레이션 가이드는 Nuxt 2 기능과 Nuxt 3+ 기능을 단계별로 비교하고, 현재 애플리케이션을 적응시키는 방법을 안내합니다.
Nuxt 2 애플리케이션을 Nuxt 3로 점진적으로 마이그레이션하고 싶다면, Nuxt Bridge를 사용할 수 있습니다. Nuxt Bridge는 Nuxt 2에서 Nuxt 3+ 기능을 옵트인 방식으로 사용할 수 있게 해주는 호환성 레이어입니다.