mirror of
https://github.com/nuxt/nuxt.git
synced 2024-11-16 19:04:48 +00:00
140 lines
3.8 KiB
Markdown
140 lines
3.8 KiB
Markdown
# Bridge
|
||
|
||
Experience Nuxt 3 features on existing Nuxt 2 projects.
|
||
|
||
::alert
|
||
If you're starting a fresh Nuxt 3 project, please skip this section and go to [Nuxt 3 Installation](/getting-started/installation).<br>
|
||
Learn more in [Introduction](/getting-started/introduction).
|
||
::
|
||
|
||
Bridge is a forward-compatibility layer that allows you to experience many of new Nuxt 3 features by simply installing and enabling a Nuxt module.
|
||
|
||
Using Nuxt Bridge, you can make sure your project is (almost) ready for Nuxt 3 and have the best developer experience without needing a major rewrite or risk breaking changes.
|
||
|
||
|
||
### Upgrade Nuxt 2
|
||
|
||
Remove any package lockfiles (`package-lock.json` and `yarn.lock`) and use the latest `nuxt-edge`:
|
||
|
||
**package.json**
|
||
|
||
```diff
|
||
- "nuxt": "^2.15.0"
|
||
+ "nuxt-edge": "latest"
|
||
```
|
||
|
||
Then, reinstall your dependencies:
|
||
|
||
::code-group
|
||
```bash [Yarn]
|
||
yarn install
|
||
```
|
||
```bash [NPM]
|
||
npm install
|
||
```
|
||
::
|
||
|
||
::alert
|
||
Once the installation is complete, make sure both development and production builds are working as expected before proceeding.
|
||
::
|
||
|
||
### Install Nuxt Bridge
|
||
|
||
Install `@nuxt/bridge-edge` as a development dependency:
|
||
|
||
::code-group
|
||
```bash [Yarn]
|
||
yarn add --dev @nuxt/bridge@npm:@nuxt/bridge-edge
|
||
```
|
||
```bash [NPM]
|
||
npm install -D @nuxt/bridge@npm:@nuxt/bridge-edge
|
||
```
|
||
::
|
||
|
||
### Update `nuxt.config`
|
||
|
||
Please make sure to avoid any CommonJS syntax such as `module.exports`, `require` or `require.resolve` in your config file. It will soon be 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|ts]
|
||
import { defineNuxtConfig } from '@nuxt/bridge'
|
||
|
||
export default defineNuxtConfig({
|
||
// Your existing configuration
|
||
})
|
||
```
|
||
|
||
### Update `tsconfig.json`
|
||
|
||
If you are using TypeScript, you can edit your `tsconfig.json` to benefit from autogenerated Nuxt types:
|
||
|
||
**tsconfig.json**
|
||
|
||
```diff
|
||
{
|
||
+ "extends": "./.nuxt/tsconfig.json",
|
||
"compilerOptions": {
|
||
```
|
||
|
||
### Avoid CommonJS syntax
|
||
|
||
Nuxt 3 natively supports TypeScript and ECMAScript Modules.
|
||
|
||
#### Update the imports
|
||
|
||
::code-group
|
||
```js [Before]
|
||
const lib = require('lib')
|
||
```
|
||
```js [After]
|
||
import lib from 'lib'
|
||
// or using code-splitting
|
||
const lib = await import('lib').then(e => e.default || e)
|
||
```
|
||
::
|
||
|
||
#### Update the exports
|
||
|
||
::code-group
|
||
```js [Before]
|
||
module.exports = ...
|
||
```
|
||
```js [After]
|
||
export default ...
|
||
// or using named export
|
||
export const hello = ...
|
||
```
|
||
::
|
||
|
||
#### Avoid using specific CJS syntax
|
||
|
||
Avoid the usage of `__dirname` and `__filename` as much as possible.
|
||
|
||
### Remove incompatible and obsolete modules
|
||
|
||
- Remove `@nuxt/content` (1.x). A rewrite for nuxt 3 is planned (2.x)
|
||
- Remove `nuxt-vite`: Bridge enables same functionality
|
||
- Remove `@nuxt/typescript-build`: Bridge enables same functionality
|
||
- Remove `@nuxt/typescript-runtime` and `nuxt-ts`: Nuxt 2 has built-in runtime support
|
||
- Remove `@nuxt/nitro`: Bridge injects same functionality
|
||
- Remove `@nuxtjs/composition-api` from your dependencies (and from your modules in `nuxt.config`). Bridge provides a legacy composition API layer that handles imports within your files from `@nuxtjs/composition-api` until you've fully finished migrating to native Bridge/Nuxt 3 composables (which you will import from by `#app`, or via auto-imports).
|
||
|
||
### Exclude Nuxt build folder from git
|
||
|
||
Add the folder `.output` to the `.gitignore` file.
|
||
|
||
### Ensure everything goes well
|
||
|
||
✔️ Try with `nuxt dev` and `nuxt build` (or `nuxt generate`) to see if everything goes well.
|
||
|
||
🐛 Is something wrong? Please let us know by creating an issue. Also, you can easily disable bridge in the meantime:
|
||
|
||
```ts [nuxt.config.js|ts]
|
||
import { defineNuxtConfig } from '@nuxt/bridge'
|
||
|
||
export default defineNuxtConfig({
|
||
bridge: false // Temporarily disable bridge integration
|
||
})
|
||
```
|