mirror of
https://github.com/nuxt/nuxt.git
synced 2024-11-14 10:04:05 +00:00
18cf0ba865
Co-authored-by: Sylvain Marroufin <marroufin.sylvain@gmail.com> Co-authored-by: Pooya Parsa <pyapar@gmail.com>
107 lines
4.8 KiB
Markdown
107 lines
4.8 KiB
Markdown
# Migration
|
|
|
|
Nuxt 3 migration guide (Work in progress)
|
|
|
|
## ⬆️ Nuxt 2 to Nuxt 3
|
|
|
|
At the moment, there is no Nuxt 2 to Nuxt 3 migration guide nor is recommanded to do it due to potentially more changes coming.
|
|
We are working to provide a stable migration guide and tooling to make it as smooth as possible. Please check [Bridge](/getting-started/bridge) for the alternative.
|
|
|
|
Some features have been dropped from Nuxt 2, some yet need to be implemented for Nuxt 3 and some are new in Nuxt 3 (and Bridge).
|
|
|
|
Noticable and/or Breaking changes with Nuxt 3 other than the requirements of bridge are:
|
|
|
|
- Vue app templates are rewritten
|
|
- Vue upgraded to `3.x`
|
|
- Using suspense for async data fetching
|
|
- Webpack `5.x` (if not using `vite`)
|
|
- Components discovery is rewritten
|
|
- Introduced new `App.vue`
|
|
- Introduced new `layouts`
|
|
- `pages/` directory conventions changed
|
|
|
|
In table below there is an overall feature comparation table:
|
|
|
|
Feature / Version | Nuxt 2 | Nuxt 3 | Changes required
|
|
--------------------------|---------|----------|------------------
|
|
Vue Version | 2 | 3 | Yes
|
|
`app.vue` | ❌ | ✅ | -
|
|
Assets | ✅ | ✅ | No
|
|
Components | ✅ | ✅ | No
|
|
Layouts | ✅ | ✅ | Yes
|
|
Error Pages | ✅ | 🚧 | Yes
|
|
Pages | ✅ | ✅ | Yes
|
|
Pages: Dynamic Params | ✅ | ✅ | Yes
|
|
Pages: _.vue | ✅ | ✅ | No
|
|
Plugins | ✅ | ✅ | Yes (compatible by default)
|
|
Store | ✅ | 🚧 | Yes
|
|
Transitions | ✅ | 🚧 | ?
|
|
Suspense | ❌ | ✅ | -
|
|
Options API: `asyncData` | ✅ | 🚧 | ?
|
|
Options API: `fetch` | ✅ | 🚧 | ?
|
|
|
|
|
|
### Nuxt Module Compatibility
|
|
|
|
- All Nuxt 2 modules should be forward compatible with Nuxt 3 as long as they migrate to bridge or if they are already following guidelines
|
|
- All (upcoming) modules made with `@nuxt/kit` should be backward compatible with Nuxt 2 projects (even without bridge) as long as they are not depending on a nuxt3/bridge-only feature
|
|
|
|
### Nuxt Plugin Compatibility
|
|
|
|
- Most Nuxt 2 plugins should be forward compatible with nuxt3 with a magical compat layer we inject
|
|
- Nuxt3 plugins are **not** backward compatible with Nuxt 2
|
|
|
|
### Vue Compatibility
|
|
|
|
For plugins and composition API and components, it needs exclusive vue2 or vue3 support from plugins.
|
|
By using [vue-demi](https://github.com/vueuse/vue-demi) they should be compatible with both nuxt2 and nuxt3.
|
|
|
|
## 📦 Module Migration Guide
|
|
|
|
When users of nuxt3 use your module, a compatible module container layer from `@nuxt/kit` is automatically injected
|
|
so as long as your code is following below guidelines, it should continue working as is.
|
|
|
|
### Test it with `@nuxt/bridge`:
|
|
|
|
Migrating to `@nuxt/bridge` is the first and most important step for supporting nuxt3.
|
|
|
|
If you have a fixture in your module, add `@nuxt/bridge` package to its config (same steps as previous section for nuxt2 projects)
|
|
|
|
### Avoid CommonJS syntax:
|
|
|
|
Nuxt natively supports TypeScript and ECMAScript Modules. In every file make sure to:
|
|
|
|
- Change `require('lib')` to `import lib from 'lib'` or `await import('lib').then(e => e.default || e)`
|
|
- Change `module.exports` to `export default` or `export const`
|
|
- Avoid usage of `__dirname` and `__filename` as much as possible
|
|
|
|
### Ensure plugins have default export
|
|
|
|
If you inject a nuxt plugin that does not have `export default` (such as global Vue plugins), ensure you add `export default {}` to the end of it
|
|
|
|
### Avoid runtime modules
|
|
|
|
With nuxt3 and nitro project, we started to rethink how the nuxt build process should work and modules hooking into the Nuxt runtime is now considered an anti-pattern and will not work with nuxt3.
|
|
|
|
Your module should work fine by adding only to `buildModules[]` (instead of `modules[]`):
|
|
|
|
- Avoid updating `process.env` within nuxt module and reading by a nuxt plugin. Use `runtimeConfig` instead
|
|
- (*) Avoid depending on runtime hooks like `vue-renderer:*` for production
|
|
- (*) Avoid adding `serverMiddleware` by importing them inside module. Add them by referencing to file path so that they are independent of module context
|
|
|
|
(*) Unless it is for `nuxt dev` purpose only and guarded with `if (nuxt.options.dev) { }`.
|
|
|
|
### Add module meta
|
|
|
|
Ensure your module is exporting meta object.
|
|
|
|
[TODO]
|
|
|
|
### Migrate to TypeScript (optional)
|
|
|
|
While it is not essential, most of nuxt ecosystem is shifting to use TypeScript, it is highly recommended to consider migration.
|
|
|
|
**Tip:** You can start migration by simply renaming `.js` files, to `.ts`. TypeScript is designed to be progressive!
|
|
|
|
**Tip:** You can use TypeScript syntax for nuxt 2/3 modules and plugins without any extra dependencies.
|