Nuxt/docs/content/1.getting-started/4.bridge.md

284 lines
8.4 KiB
Markdown
Raw Normal View History

# Migrating to Bridge
Experience Nuxt 3 features on existing Nuxt 2 projects.
::alert
2021-10-11 21:49:54 +00:00
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.
::
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.
2021-10-11 21:49:54 +00:00
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"
```
2021-10-11 21:49:54 +00:00
Then, reinstall your dependencies:
::code-group
```bash [Yarn]
yarn install
```
```bash [NPM]
npm install
```
::
::alert
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 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
2021-10-29 10:38:22 +00:00
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"
2021-10-29 10:38:22 +00:00
}
}
```
### Static target
2021-10-29 10:38:22 +00:00
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": {
2021-10-29 10:38:22 +00:00
"build": "nuxi generate"
}
}
```
### Server target
2021-10-29 10:38:22 +00:00
For all other situations, you can use the `nuxi build` command.
```json [package.json]
{
"scripts": {
2021-10-29 10:38:22 +00:00
"build": "nuxi build",
"start": "nuxi preview"
}
}
```
## 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.
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({
2021-10-11 21:49:54 +00:00
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
}
})
```