Experience Nuxt 3 features on existing Nuxt 2 projects.
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.
useAsyncData
and useFetch
composables are not available. Please read the rest of this page for details.
π± Note: If you're starting a fresh Nuxt project, please skip this module and directly go to the Nuxt 3 Installation.
- Clone repository
- Ensure you have the latest LTS version of Node.js installed
- Install dependencies with
npx yarn install
- Run
npx yarn dev:prepare
to activate passive development - Open playground with
npx yarn dev
Learn more about in our documentation on how to contribute to Nuxt.
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
:
- "nuxt": "^2.15.0"
+ "nuxt-edge": "latest"
Then, reinstall your dependencies:
# Using yarn
yarn install
# Using npm
npm install
Once the installation is complete, make sure both development and production builds are working as expected before proceeding.
Install @nuxt/bridge-edge
as a development dependency:
# Using yarn
yarn add --dev @nuxt/bridge@npm:@nuxt/bridge-edge
# Using npm
npm install -D @nuxt/bridge@npm:@nuxt/bridge-edge
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.
Nuxt 3 introduced the new Nuxt CLI command nuxi
. Update your scripts as follows to leverage the better support from Nuxt Bridge:
{
"scripts": {
- "dev": "nuxt",
+ "dev": "nuxi dev",
- "build": "nuxt build",
+ "build": "nuxi build",
- "start": "nuxt start",
+ "start": "nuxi preview"
}
}
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
.
{
"scripts": {
"build": "nuxi generate"
}
}
For all other situations, you can use the nuxi build
command.
{
"scripts": {
"build": "nuxi build",
"start": "nuxi preview"
}
}
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.
import { defineNuxtConfig } from '@nuxt/bridge'
export default defineNuxtConfig({
// Your existing configuration
})
If you are using TypeScript, you can edit your tsconfig.json
to benefit from auto-generated Nuxt types:
{
+ "extends": "./.nuxt/tsconfig.json",
"compilerOptions": {
...
}
}
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.
If you were using @vue/composition-api
or @nuxtjs/composition-api
, please read the composition api migration guide.
Nuxt 3 natively supports TypeScript and ECMAScript Modules. Please check Native ES Modules for more info and upgrading.
- 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
andnuxt-ts
: Nuxt 2 has built-in runtime support - Remove
@nuxt/nitro
: Bridge injects same functionality - Remove
@vue/composition-api
from your dependencies (migration guide). - Remove
@nuxtjs/composition-api
from your dependencies (and from your modules innuxt.config
) (migration guide).
Add the folder .output
to the .gitignore
file.
βοΈ 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:
import { defineNuxtConfig } from '@nuxt/bridge'
export default defineNuxtConfig({
bridge: false // Temporarily disable bridge integration
})
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.
export default defineNuxtPlugin(nuxtApp => {
nuxtApp.provide('injected', () => 'my injected function')
// now available on `nuxtApp.$injected`
})
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.
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.
Nuxt Bridge provides a new Nuxt 3 meta API that can be accessed with a new useHead
composable.
<script setup>
useHead({
title: 'My Nuxt App',
})
</script>
You will also need to enable this feature explicitly in your nuxt.config
:
import { defineNuxtConfig } from '@nuxt/bridge'
export default defineNuxtConfig({
bridge: {
meta: true
}
})
This useHead
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 useHead
, as they may conflict.
For more information on how to use this composable, see the docs.
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 for latest defaults.
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 useHead
// 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 composables auto importing
// autoImports: false,
// Do not warn about module incompatibilities
// constraints: false
},
vite: {
// Config for Vite
}
})