Nuxt/docs/6.bridge/1.overview.md

122 lines
3.3 KiB
Markdown
Raw Normal View History

---
title: Overview
description: Reduce the differences with Nuxt 3 and reduce the burden of migration to Nuxt 3.
---
::callout
If you're starting a fresh Nuxt 3 project, please skip this section and go to [Nuxt 3 Installation](/docs/getting-started/introduction).
::
::callout{color="amber" icon="i-ph-warning-duotone"}
2023-07-07 16:24:09 +00:00
Nuxt Bridge provides identical features to Nuxt 3 ([docs](/docs/guide/concepts/auto-imports)) but there are some limitations, notably that [`useAsyncData`](/docs/api/composables/use-async-data) and [`useFetch`](/docs/api/composables/use-fetch) composables are not available. Please read the rest of this page for details.
::
2021-11-21 12:31:44 +00:00
Bridge is a forward-compatibility layer that allows you to experience many of the 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 you can gradually proceed with the transition to Nuxt 3.
## First Step
### Upgrade Nuxt 2
Make sure your dev server (`nuxt dev`) isn't running, remove any package lock files (`package-lock.json` and `yarn.lock`), and install the latest Nuxt 2 version:
```diff [package.json]
- "nuxt": "^2.16.3"
+ "nuxt": "^2.17.0"
```
2021-10-11 21:49:54 +00:00
Then, reinstall your dependencies:
::code-group
```bash [yarn]
yarn install
```
```bash [npm]
npm install
```
::
::callout
2021-10-11 21:49:54 +00:00
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`
2021-10-11 21:49:54 +00:00
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.
2023-07-07 16:24:09 +00:00
You can use static `import`, dynamic `import()` and `export default` instead. Using TypeScript by renaming to [`nuxt.config.ts`](/docs/guide/directory-structure/nuxt.config) is also possible and recommended.
```ts [nuxt.config.ts]
import { defineNuxtConfig } from '@nuxt/bridge'
export default defineNuxtConfig({
bridge: false
})
```
### Update Commands
The `nuxt` command should now be changed to the `nuxt2` command.
```diff
{
"scripts": {
- "dev": "nuxt",
+ "dev": "nuxt2",
- "build": "nuxt build",
+ "build": "nuxt2 build",
- "start": "nuxt start",
+ "start": "nuxt2 start"
}
}
```
Try running `nuxt2` once here. You will see that the application works as before.
(If 'bridge' is set to false, your application will operate without any changes as before.)
## Upgrade Steps
With Nuxt Bridge, the migration to Nuxt 3 can proceed in steps.
The below `Upgrade Steps` does not need to be done all at once.
- [TypeScript](/docs/bridge/typescript)
- [Migrate Legacy Composition API](/docs/bridge/bridge-composition-api)
- [Plugins and Middleware](/docs/bridge/plugins-and-middleware)
- [Migrate New Composition API](/docs/bridge/nuxt3-compatible-api)
- [Meta Tags](/docs/bridge/meta)
- [Runtime Config](/docs/bridge/runtime-config)
- [Nitro](/docs/bridge/nitro)
- [Vite](/docs/bridge/vite)
## Migrate from CommonJS to ESM
Nuxt 3 natively supports TypeScript and ECMAScript Modules. Please check [Native ES Modules](/docs/guide/concepts/esm) for more info and upgrading.