Configuration

nuxt.config

Nuxt 앱의 시작점은 여전히 nuxt.config 파일입니다.

Migration

1. 타입이 지정된 설정 스키마를 제공하는 새로운 defineNuxtConfig 함수로 마이그레이션해야 합니다.

export default {
  // ...
}

export default defineNuxtConfig({
  // ...
})

1. router.extendRoutes를 사용하고 있었다면 새로운 pages:extend 훅으로 마이그레이션할 수 있습니다:

export default {
  router: {
    extendRoutes (routes) {
      //
    },
  },
}

export default defineNuxtConfig({
  hooks: {
    'pages:extend' (routes) {
      //
    },
  },
})

1. router.routeNameSplitter를 사용하고 있었다면, 새로운 pages:extend 훅에서 라우트 이름 생성 로직을 업데이트하여 동일한 결과를 얻을 수 있습니다:

export default {
  router: {
    routeNameSplitter: '/',
  },
}

import { createResolver } from '@nuxt/kit'

export default defineNuxtConfig({
  hooks: {
    'pages:extend' (routes) {
      const routeNameSplitter = '/'
      const root = createResolver(import.meta.url).resolve('./pages')

      function updateName (routes) {
        if (!routes) {
          return
        }

        for (const route of routes) {
          const relativePath = route.file.substring(root.length + 1)
          route.name = relativePath.slice(0, -4).replace(/\/index$/, '').replace(/\//g, routeNameSplitter)

          updateName(route.children)
        }
      }
      updateName(routes)
    },
  },
})

ESM Syntax

Nuxt 3는 ESM 네이티브 프레임워크입니다. unjs/jiti가 nuxt.config 파일을 로드할 때 어느 정도의 호환성을 제공하긴 하지만, 이 파일 안에서는 require와 module.exports 사용을 피해야 합니다.

1. module.exports를 export default로 변경하세요.
2. const lib = require('lib')를 import lib from 'lib'으로 변경하세요.

Async Configuration

Nuxt의 로딩 동작을 더 예측 가능하게 만들기 위해, 비동기 설정 문법은 더 이상 사용되지 않습니다. 비동기 작업에는 Nuxt 훅을 사용하는 것을 고려하세요.

Dotenv

Nuxt는 .env 파일 로딩을 기본적으로 지원합니다. nuxt.config에서 직접 임포트하는 것은 피하세요.

Modules

Nuxt와 Nuxt 모듈은 이제 빌드 타임 전용입니다.

Migration

1. 모든 buildModules를 modules로 옮기세요.
2. 모듈의 Nuxt 3 호환성을 확인하세요.
3. 디렉터리를 가리키는 로컬 모듈이 있다면, 엔트리 파일을 가리키도록 업데이트해야 합니다:

  export default defineNuxtConfig({
    modules: [
-     '~/modules/my-module'
+     '~/modules/my-module/index'
    ]
  })

Directory Changes

정적 에셋을 저장하던 static/ 디렉터리는 public/으로 이름이 변경되었습니다. static 디렉터리 이름을 public으로 바꾸거나, nuxt.config에서 dir.public을 설정해 기존 이름을 유지할 수 있습니다.

TypeScript

Nuxt의 TypeScript 통합을 사용하면 애플리케이션을 마이그레이션하는 것이 훨씬 쉬워집니다. 이는 애플리케이션을 TypeScript로 작성해야 한다는 의미는 아니며, Nuxt가 에디터를 위한 자동 타입 힌트를 제공한다는 뜻입니다.

Nuxt의 TypeScript 지원에 대해 더 알고 싶다면 문서를 참고하세요.

Migration

1. 다음 내용을 가진 tsconfig.json을 생성하세요:

{
  "files": [],
  "references": [
    {
      "path": "./.nuxt/tsconfig.app.json"
    },
    {
      "path": "./.nuxt/tsconfig.server.json"
    },
    {
      "path": "./.nuxt/tsconfig.shared.json"
    },
    {
      "path": "./.nuxt/tsconfig.node.json"
    }
  ]
}

1. npx nuxt prepare를 실행해 tsconfig 파일들을 생성하세요.
2. 문서의 안내에 따라 Volar를 설치하세요.

Vue Changes

권장되는 Vue 모범 사례에 여러 변경 사항이 있으며, Vue 2와 3 사이에는 여러 가지 브레이킹 체인지가 있습니다.

Vue 3 마이그레이션 가이드, 특히 브레이킹 체인지 목록을 읽는 것이 좋습니다.

현재 Nuxt 3에서는 Vue 3 마이그레이션 빌드를 사용할 수 없습니다.

Vuex

Nuxt는 더 이상 Vuex 통합을 제공하지 않습니다. 대신 공식 Vue 권장 사항은 pinia를 사용하는 것이며, Nuxt 모듈을 통해 Nuxt 지원이 내장되어 있습니다. pinia에 대해 더 알아보세요.

pinia로 전역 상태 관리를 제공하는 간단한 방법은 다음과 같습니다:

@pinia/nuxt 모듈을 설치하세요:

yarn add pinia @pinia/nuxt

Nuxt 설정에서 모듈을 활성화하세요:

import { defineNuxtConfig } from 'nuxt/config'

export default defineNuxtConfig({
  modules: ['@pinia/nuxt'],
})

애플리케이션 루트에 store 폴더를 생성하세요:

import { defineStore } from 'pinia'

export const useMainStore = defineStore('main', {
  state: () => ({
    counter: 0,
  }),
  actions: {
    increment () {
      // `this`는 스토어 인스턴스입니다
      this.counter++
    },
  },
})

스토어를 전역화하기 위해 플러그인 파일을 생성하세요:

import { useMainStore } from '~/store'

export default defineNuxtPlugin(({ $pinia }) => {
  return {
    provide: {
      store: useMainStore($pinia),
    },
  }
})

Vuex를 계속 사용하고 싶다면, 이 단계들을 따라 수동으로 Vuex 4로 마이그레이션할 수 있습니다.

마이그레이션이 완료되면 Nuxt 앱에 다음 플러그인을 추가해야 합니다:

import store from '~/store'

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.use(store)
})

대형 앱의 경우 이 마이그레이션에는 많은 작업이 필요할 수 있습니다. Vuex 업데이트가 여전히 장애물이 된다면, 커뮤니티 모듈인 nuxt3-vuex-module을 사용하는 것을 고려해 볼 수 있으며, 이는 별다른 설정 없이 바로 동작해야 합니다.