mirror of https://github.com/nuxt/nuxt.git
137 lines
5.2 KiB
Markdown
137 lines
5.2 KiB
Markdown
# Bridge Migration
|
|
|
|
> ⚠️ This section is work-in-progress and can change. Please regularly check this page.
|
|
|
|
## ... I have a nuxt2 project
|
|
|
|
Migration to nuxt-bridge, should be almost straight forward!
|
|
|
|
**Why migrate:**
|
|
|
|
- It is risk-free! You can roll back by just commenting out one line in config
|
|
- Makes your project almost ready for nuxt3 migration
|
|
- Enjoy new DX improvements without major rewrites for vue3
|
|
- Use nitro engine for platform agnostic and optimized deployments
|
|
- Help us stabilize nuxt3 and discover flows
|
|
- Bridge is more stable than nuxt3 at the moment for migration
|
|
|
|
### **Step 1:** Ensure using latest version of nuxt
|
|
|
|
Remove package lock file (`package-lock.json` and `yarn.lock`) and update to latest version of nuxt2 ([releases](https://github.com/nuxt/nuxt.js/releases)) or use `nuxt-edge` for latest updates and fixes.
|
|
|
|
### **Step 2:** Install bridge module
|
|
|
|
Install `@nuxt/bridge` as a devDependency:
|
|
|
|
```bash
|
|
# Using npm
|
|
npm install -D @nuxt/bridge@npm:@nuxt/bridge-edge
|
|
|
|
# Using yarn
|
|
yarn add --dev @nuxt/bridge@npm:@nuxt/bridge-edge
|
|
```
|
|
|
|
Update `nuxt.config` file:
|
|
|
|
```ts [nuxt.config.js]
|
|
import { defineNuxtConfig } from '@nuxt/bridge'
|
|
|
|
export default defineNuxtConfig({
|
|
bridge: {
|
|
nitro: true,
|
|
// vite: true
|
|
}
|
|
})
|
|
```
|
|
|
|
If you have a project with `target: 'static'`, update "build" script to use `nuxt generate`
|
|
|
|
```json [package.json]
|
|
{
|
|
"scripts": {
|
|
"build": "nuxt generate"
|
|
}
|
|
}
|
|
```
|
|
|
|
### **Step 3:** Avoid CommonJS syntax
|
|
|
|
See [Migrating from CommonJS](#step-2-avoid-commonjs-syntax) from module author section.
|
|
We need same steps for `plugins`, `store`, `pages`, `serverMiddleware` and `nuxt.config.js`.
|
|
|
|
### **Step 4:** Remove incompatible modules
|
|
|
|
- Remove `@nuxt/content` (1.x): **note**: a v2 rewrite for nuxt 3 support is planned, or you may also use docus
|
|
- Remove `nuxt-vite`: Bridge injects module when enabled with `{ bridge: { vite: true } }`
|
|
- Remove `@nuxt/nitro`: Bridge injects module
|
|
- Remove `@nuxtjs/composition-api`: Bridge provides a nuxt 3 compatible composition-api layer.
|
|
|
|
### **Step 5:** Ensure everything goes well
|
|
|
|
Try with both `nuxt dev`, `nuxt build` and `nuxt start` if everything goes as expected
|
|
If there is an issue, please report it to us or to relevant module repository.
|
|
|
|
If you cannot take the risk of using experimental code, you can comment out the module and regularly check back to ensure your project stays ready for nuxt3 compatibly.
|
|
|
|
### 🥳 Enjoy new possibilities!
|
|
|
|
Everything goes well? Congratulations! You are welcome to enjoy new features from nuxt3 without full migration. See table in intro section for more.
|
|
|
|
## ... I am a module author
|
|
|
|
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.
|
|
|
|
### **Step 1:** 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)
|
|
|
|
### **Step 2:** 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
|
|
|
|
### **Step 3:** 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
|
|
|
|
### **Step 4:** 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) { }`.
|
|
|
|
### **Step 5**: Add module meta
|
|
|
|
Ensure your module is exporting meta object.
|
|
|
|
[TODO]
|
|
|
|
### **Step 6:** 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.
|
|
|
|
### 🛣️ Next Steps
|
|
|
|
While we are evolving nuxt3 and modules, you are welcome to share any ideas in Discussions section.
|
|
|
|
A brand new experience of defining nuxt modules is coming with `@nuxt/kit` project but it is still not ready so it is advised only to try it and not release to stable versions of your module.
|
|
|
|
Please regularly check this section for latest updates.
|
|
|