mirror of https://github.com/nuxt/nuxt.git
284 lines
8.4 KiB
Markdown
284 lines
8.4 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).
|
||
::
|
||
|
||
::alert{type=warning}
|
||
Nuxt Bridge provides identical features to Nuxt 3 ([docs](/docs/usage)) but there are some limitations, notably that `useAsyncData` and `useFetch` composables are not available. Please read the rest of this page for details.
|
||
::
|
||
|
||
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 have the best developer experience without needing a major rewrite or risk breaking changes.
|
||
|
||
## 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-edge`:
|
||
|
||
```diff [package.json]
|
||
- "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 your scripts
|
||
|
||
You will also need to update your scripts within your `package.json` to reflect the fact that Nuxt will now produce a Nitro server as build output.
|
||
|
||
### Nuxi
|
||
|
||
Nuxt 3 introduced the new Nuxt CLI command [`nuxi`](/getting-started/commands/). Update your scripts as follows to leverage the better support from Nuxt Bridge:
|
||
|
||
```diff
|
||
{
|
||
"scripts": {
|
||
- "dev": "nuxt",
|
||
+ "dev": "nuxi dev",
|
||
- "build": "nuxt build",
|
||
+ "build": "nuxi build",
|
||
- "start": "nuxt start",
|
||
+ "start": "nuxi preview"
|
||
}
|
||
}
|
||
```
|
||
|
||
### Static target
|
||
|
||
If you have set `target: 'static'` in your `nuxt.config` then you need to ensure that you update your build script to be `nuxi generate`.
|
||
|
||
```json [package.json]
|
||
{
|
||
"scripts": {
|
||
"build": "nuxi generate"
|
||
}
|
||
}
|
||
```
|
||
|
||
### Server target
|
||
|
||
For all other situations, you can use the `nuxi build` command.
|
||
|
||
```json [package.json]
|
||
{
|
||
"scripts": {
|
||
"build": "nuxi build",
|
||
"start": "nuxi preview"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 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 auto-generated Nuxt types:
|
||
|
||
```diff [tsconfig.json]
|
||
{
|
||
+ "extends": "./.nuxt/tsconfig.json",
|
||
"compilerOptions": {
|
||
...
|
||
}
|
||
}
|
||
```
|
||
|
||
::alert
|
||
You may also need to add `@vue/runtime-dom` as a devDependency if you are struggling to get template type inference working with [Volar](https://marketplace.visualstudio.com/items?itemName=johnsoncodehk.volar).
|
||
::
|
||
::alert
|
||
Keep in mind that all options extended from `./.nuxt/tsconfig.json` will be overwritten by the options defined in your `tsconfig.json`.
|
||
Overwriting options such as `"compilerOptions.paths"` with your own configuration will lead Typescript to not factor in the module resolutions from `./.nuxt/tsconfig.json`. This can lead to module resolutions such as `#imports` not being recognized.
|
||
|
||
In case you need to extend options provided by `./.nuxt/tsconfig.json` further, you can use the `alias` property withing your `nuxt.config`. `nuxi` will pick them up and extend `./.nuxt/tsconfig.json` accordingly.
|
||
::
|
||
|
||
## Migrate Composition API
|
||
|
||
If you were using `@vue/composition-api` or `@nuxtjs/composition-api`, please read the [composition api migration guide](/getting-started/bridge-composition-api).
|
||
|
||
### Migrate from CommonJS to ESM
|
||
|
||
Nuxt 3 natively supports TypeScript and ECMAScript Modules. Please check [Native ES Modules](/concepts/esm) for more info and upgrading.
|
||
|
||
## 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 `@vue/composition-api` from your dependencies ([migration guide](/getting-started/bridge-composition-api)).
|
||
- Remove `@nuxtjs/composition-api` from your dependencies (and from your modules in `nuxt.config`) ([migration guide](/getting-started/bridge-composition-api)).
|
||
|
||
## Exclude built Nitro folder from git
|
||
|
||
Add the folder `.output` to the `.gitignore` file.
|
||
|
||
## Ensure everything goes well
|
||
|
||
✔️ Try with `nuxi dev` and `nuxi build` (or `nuxi generate`) to see if everything goes well.
|
||
|
||
🐛 Is something wrong? Please let us know by creating an issue. Also, you can easily disable the bridge in the meantime:
|
||
|
||
```ts [nuxt.config.js|ts]
|
||
import { defineNuxtConfig } from '@nuxt/bridge'
|
||
|
||
export default defineNuxtConfig({
|
||
bridge: false // Temporarily disable bridge integration
|
||
})
|
||
```
|
||
|
||
## New plugins format (optional)
|
||
|
||
You can now migrate to the Nuxt 3 plugins API, which is slightly different in format from Nuxt 2.
|
||
|
||
Plugins now take only one argument (`nuxtApp`). You can find out more in [the docs](/docs/directory-structure/plugins).
|
||
|
||
```js
|
||
export default defineNuxtPlugin(nuxtApp => {
|
||
nuxtApp.provide('injected', () => 'my injected function')
|
||
// now available on `nuxtApp.$injected`
|
||
})
|
||
```
|
||
|
||
::alert
|
||
If you want to use the new Nuxt composables (such as `useNuxtApp` or `useRuntimeConfig`) within your plugins, you will need to use the `defineNuxtPlugin` helper for those plugins.
|
||
::
|
||
|
||
::alert{type=warning}
|
||
Although a compatibility interface is provided via `nuxtApp.vueApp` you should avoid registering plugins, directives, mixins or components this way without adding your own logic to ensure they are not installed more than once, or this may cause a memory leak.
|
||
::
|
||
|
||
## New `useMeta` (optional)
|
||
|
||
Nuxt Bridge provides a new Nuxt 3 meta API that can be accessed with a new `useMeta` composable.
|
||
|
||
```vue
|
||
<script setup>
|
||
useMeta({
|
||
title: 'My Nuxt App',
|
||
})
|
||
</script>
|
||
```
|
||
|
||
You will also need to enable this feature explicitly in your `nuxt.config`:
|
||
|
||
```js
|
||
import { defineNuxtConfig } from '@nuxt/bridge'
|
||
|
||
export default defineNuxtConfig({
|
||
bridge: {
|
||
meta: true
|
||
}
|
||
})
|
||
```
|
||
|
||
This `useMeta` composable uses `@vueuse/head` under the hood (rather than `vue-meta`) to manipulate your `<head>`.
|
||
Accordingly, we recommend not to use both the native Nuxt 2 `head()` properties as well as `useMeta`, as they may conflict.
|
||
|
||
For more information on how to use this composable, see [the docs](/docs/usage/meta-tags#usemeta-composable).
|
||
|
||
## Feature Flags
|
||
|
||
You can optionally disable some features from bridge or opt-in to less stable ones. In normal circumstances, it is always best to stick with defaults!
|
||
|
||
You can check [bridge/src/module.ts](https://github.com/nuxt/framework/blob/main/packages/bridge/src/module.ts) for latest defaults.
|
||
|
||
```ts [nuxt.config.js|ts]
|
||
import { defineNuxtConfig } from '@nuxt/bridge'
|
||
|
||
export default defineNuxtConfig({
|
||
bridge: {
|
||
|
||
// -- Opt-in features --
|
||
|
||
// Use Vite as the bundler instead of Webpack 4
|
||
// vite: true,
|
||
|
||
// Enable Nuxt 3 compatible useMeta
|
||
// meta: true,
|
||
|
||
// -- Default features --
|
||
|
||
// Use legacy server instead of Nitro
|
||
// nitro: false,
|
||
|
||
// Disable nuxt 3 compatible `nuxtApp` interface
|
||
// app: false,
|
||
|
||
// Disable composition API support
|
||
// capi: false,
|
||
|
||
// ... or just disable legacy composition API support
|
||
// capi: {
|
||
// legacy: false
|
||
// },
|
||
|
||
// Do not transpile modules
|
||
// transpile: false,
|
||
|
||
// Disable <script setup> support
|
||
// scriptSetup: false,
|
||
|
||
// Disable composables auto importing
|
||
// autoImports: false,
|
||
|
||
// Do not warn about module incompatibilities
|
||
// constraints: false
|
||
},
|
||
|
||
vite: {
|
||
// Config for Vite
|
||
}
|
||
})
|
||
```
|