mirror of
https://github.com/nuxt/nuxt.git
synced 2025-01-31 15:50:32 +00:00
79 lines
2.9 KiB
Markdown
79 lines
2.9 KiB
Markdown
|
# Bridge
|
||
|
|
|
||
|
|
Experience Nuxt 3 on existing Nuxt 2 projects
|
||
|
|
|
||
|
|
> Please skip this section if starting a new Nuxt 3 project and go to [Installation](/getting-started/installation) instead.
|
||
|
|
> Learn more in the [Intorduction](/getting-started/introduction).
|
||
|
|
|
||
|
|
Bridge, is a forward-compatibility layer as a module that allows you to opt-in and experience many of new Nuxt 3 features.
|
||
|
|
Using bridge, you can make sure your project is almost ready for Nuxt 3 and have the latest DX experience without major rewrites and risk of breaking changes by adding a simple module.
|
||
|
|
|
||
|
|
|
||
|
|
### **Step 1:** Upgrade to the latest version of Nuxt 2
|
||
|
|
|
||
|
|
Remove package lock-file (`package-lock.json` and `yarn.lock`) and use latest `nuxt-edge`:
|
||
|
|
|
||
|
|
**package.json**
|
||
|
|
|
||
|
|
```diff
|
||
|
|
- "nuxt": "^2.15.0"
|
||
|
|
+ "nuxt-edge": "latest"
|
||
|
|
```
|
||
|
|
|
||
|
|
✔️ After upgrade, please make sure both development and production builds are working fine before proceed to the module installation.
|
||
|
|
|
||
|
|
### **Step 2:** Install bridge module
|
||
|
|
|
||
|
|
Install `@nuxt/bridge-edge` 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
|
||
|
|
```
|
||
|
|
|
||
|
|
### **Step 3:** Update `nuxt.config`
|
||
|
|
|
||
|
|
Please make sure to avoid any CommonJS syntax such as `module.exports`, `require` or `require.resolve` in config file. It will be soon deprecated and unsupported. You can use static `import`, dynamic `import()` and `export default` instead. Using typescript by renaming to `nuxt.config.ts` is also possible and recommended.
|
||
|
|
|
||
|
|
```ts [nuxt.config.js]
|
||
|
|
import { defineNuxtConfig } from '@nuxt/bridge'
|
||
|
|
|
||
|
|
export default defineNuxtConfig({
|
||
|
|
// Your existing configuration
|
||
|
|
})
|
||
|
|
```
|
||
|
|
|
||
|
|
### **Step 4:** 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 5:** Remove incompatible and obsolete modules
|
||
|
|
|
||
|
|
- Remove `@nuxt/content` (1.x) a v2 rewrite for nuxt 3 support is planned, or you may also use docus
|
||
|
|
- Remove `nuxt-vite`: Bridge enables same functionality
|
||
|
|
- Remove `@nuxtjs/typescript-build`: Bridge enables same functionality
|
||
|
|
- Remove `@nuxtjs/typescript-runtime` and `nuxt-ts`: Nuxt 2 has built-in runtime support
|
||
|
|
- Remove `@nuxt/nitro`: Bridge injects same functionality
|
||
|
|
- Remove `@nuxtjs/composition-api`: Bridge provides a Nuxt 3 compatible composition-api layer and help to remove dependency
|
||
|
|
|
||
|
|
### **Step 6:** Ensure everything goes well
|
||
|
|
|
||
|
|
✔️ Try with `nuxt dev` and `nuxt build` (or `nuxt generate`) to see if everything goes well.
|
||
|
|
|
||
|
|
🐛 Something is wrong? Please report us by creating an issue. Also, you can easily disable bridge in the meantime:
|
||
|
|
|
||
|
|
```ts [nuxt.config.js]
|
||
|
|
import { defineNuxtConfig } from '@nuxt/bridge'
|
||
|
|
|
||
|
|
export default defineNuxtConfig({
|
||
|
|
bridge: false // Temporary disable bridge integration
|
||
|
|
})
|
||
|
|
```
|