Configuration Migration

Learn how to migrate your Nuxt 2 configuration to Nuxt 3’s new configuration system.

The starting point for your Nuxt app remains your nuxt.config file.

Nuxt configuration will be loaded using unjs/jiti and unjs/c12.

Migrate to defineNuxtConfig

You should migrate to the new defineNuxtConfig function that provides a typed configuration schema.

Nuxt 2

export default {
  // ...
}

Router Configuration

Extending Routes

If you were using router.extendRoutes, migrate to the new pages:extend hook:

Nuxt 2

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

Route Name Splitter

If you were using router.routeNameSplitter, you can achieve the same result by updating route name generation logic in the new pages:extend hook:

Nuxt 2

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

ESM Syntax

Nuxt 3 is an ESM native framework. Although unjs/jiti provides semi compatibility when loading nuxt.config file, avoid any usage of require and module.exports in this file.

1. Change module.exports to export default
2. Change const lib = require('lib') to import lib from 'lib'

Async Configuration

In order to make Nuxt loading behavior more predictable, async config syntax is deprecated. Consider using Nuxt hooks for async operations.

Environment Variables

Nuxt has built-in support for loading .env files. Avoid directly importing it from nuxt.config.

Modules

Nuxt and Nuxt modules are now build-time-only.

Migration Steps

1. Move all your buildModules into modules - There is no longer a distinction between build and runtime modules.
2. Check for Nuxt 3 compatibility of modules - Some modules may need updates.
3. Update local module paths - If you have any local modules pointing to a directory, update this to point to the entry file:

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

If you are a module author, you can check out more information about module compatibility and our module author guide.

Directory Changes

The static/ directory (for storing static assets) has been renamed to public/. You can either rename your static directory to public, or keep the name by setting dir.public in your nuxt.config.

TypeScript

It will be much easier to migrate your application if you use Nuxt’s TypeScript integration. This does not mean you need to write your application in TypeScript, just that Nuxt will provide automatic type hints for your editor.

Nuxt can type-check your app using vue-tsc with nuxt typecheck command.

Setup TypeScript

1. Create a tsconfig.json with the following content:

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

2. Run npx nuxt prepare to generate the tsconfig files.
3. Install Volar following the instructions in the docs.

Vue Changes

There are a number of changes to what is recommended Vue best practice, as well as a number of breaking changes between Vue 2 and 3.

It is recommended to read the Vue 3 migration guide and in particular the breaking changes list.

It is not currently possible to use the Vue 3 migration build with Nuxt 3.

Vuex

Nuxt no longer provides a Vuex integration. Instead, the official Vue recommendation is to use pinia, which has built-in Nuxt support via a Nuxt module.

Migrate to Pinia

A simple way to provide global state management with pinia:

1. Install the @pinia/nuxt module:

yarn add pinia @pinia/nuxt

2. Enable the module in your nuxt configuration:

import { defineNuxtConfig } from 'nuxt/config'

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

3. Create a store folder at the root of your application:

store/index.ts

import { defineStore } from 'pinia'

export const useMainStore = defineStore('main', {
  state: () => ({
    counter: 0,
  }),
  actions: {
    increment () {
      // `this` is the store instance
      this.counter++
    },
  },
})

4. Create a plugin file to globalize your store:

app/plugins/pinia.ts

import { useMainStore } from '~/store'

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

Keep Using Vuex

If you want to keep using Vuex, you can manually migrate to Vuex 4 following these steps.

Once it’s done, you will need to add the following plugin to your Nuxt app:

app/plugins/vuex.ts

import store from '~/store'

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

For larger apps, this migration can entail a lot of work. If updating Vuex still creates roadblocks, you may want to use the community module: nuxt3-vuex-module, which should work out of the box.