diff --git a/docs/6.bridge/1.overview.md b/docs/6.bridge/1.overview.md
index 704fe3717b..0871c4d9a0 100644
--- a/docs/6.bridge/1.overview.md
+++ b/docs/6.bridge/1.overview.md
@@ -1,6 +1,6 @@
# Overview
-Experience Nuxt 3 features on existing Nuxt 2 projects.
+Reduce the differences with Nuxt 3 and reduce the burden of migration to Nuxt 3.
::alert
If you're starting a fresh Nuxt 3 project, please skip this section and go to [Nuxt 3 Installation](/docs/getting-started/introduction).
@@ -12,9 +12,11 @@ Nuxt Bridge provides identical features to Nuxt 3 ([docs](/docs/guide/concepts/a
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.
+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.
-## Upgrade Nuxt 2
+## 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:
@@ -41,7 +43,7 @@ npm install
Once the installation is complete, make sure both development and production builds are working as expected before proceeding.
::
-## Install Nuxt Bridge
+### Install Nuxt Bridge
Install `@nuxt/bridge-edge` as a development dependency:
@@ -57,57 +59,7 @@ 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`](/docs/api/commands/add). 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"
- }
-}
-```
-
-::alert
-If `nitro: false`, use the `nuxt` command.
-::
-
-### 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`
+### 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.
@@ -117,227 +69,35 @@ You can use static `import`, dynamic `import()` and `export default` instead. Us
import { defineNuxtConfig } from '@nuxt/bridge'
export default defineNuxtConfig({
- // Your existing configuration
+ bridge: false
})
```
-## Update `tsconfig.json`
+Try running `nuxt dev` once here. You will see that the application works as before.
-If you are using TypeScript, you can edit your `tsconfig.json` to benefit from auto-generated Nuxt types:
+(If 'bridge' is set to false, your application will operate without any changes as before.)
-```diff [tsconfig.json]
-{
-+ "extends": "./.nuxt/tsconfig.json",
- "compilerOptions": {
- ...
- }
-}
-```
+## Upgrade Steps
-::alert
-As `.nuxt/tsconfig.json` is generated and not checked into version control, you'll need to generate that file before running your tests. Add `nuxi prepare` as a step before your tests, otherwise you'll see `TS5083: Cannot read file '~/.nuxt/tsconfig.json'`
-::
-::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=Vue.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.
+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.
-In case you need to extend options provided by `./.nuxt/tsconfig.json` further, you can use the `alias` property within your `nuxt.config`. `nuxi` will pick them up and extend `./.nuxt/tsconfig.json` accordingly.
-::
+- [TypeScript](/docs/bridge/typescript)
-## Update Runtime Config
+- [Migrate Legacy Composition API](/docs/bridge/bridge-composition-api)
-Nuxt 3 approaches runtime config differently than Nuxt 2, using a new combined `runtimeConfig` option.
+- [Plugins and Middleware](/docs/bridge/plugins-and-middleware)
-First, you'll need to combine your `publicRuntimeConfig` and `privateRuntimeConfig` properties into a new one called `runtimeConfig`, with the public config within a key called `public`.
+- [Migrate New Composition API](/docs/bridge/nuxt3-compatible-api)
-```diff
-// nuxt.config.js
-- privateRuntimeConfig: {
-- apiKey: process.env.NUXT_API_KEY || 'super-secret-key'
-- },
-- publicRuntimeConfig: {
-- websiteURL: 'https://public-data.com'
-- }
-+ runtimeConfig: {
-+ apiKey: process.env.NUXT_API_KEY || 'super-secret-key',
-+ public: {
-+ websiteURL: 'https://public-data.com'
-+ }
-+ }
-```
+- [Meta Tags](/docs/bridge/meta)
-This also means that when you need to access public runtime config, it's behind a property called `public`. If you use public runtime config, you'll need to update your code.
+- [Runtime Config](/docs/bridge/runtime-config)
-```diff
-// MyWidget.vue
-- Website: {{ $config.websiteURL }}
-+ Website: {{ $config.public.websiteURL }}
-```
+- [Nitro](/docs/bridge/nitro)
-## Migrate Composition API
+- [Vite](/docs/bridge/vite)
-If you were using `@vue/composition-api` or `@nuxtjs/composition-api`, please read the [composition api migration guide](/docs/bridge/bridge-composition-api).
-
-### Migrate from CommonJS to ESM
+## 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.
-
-## Remove Incompatible and Obsolete Modules
-
-- Remove `@nuxt/content` (1.x). A rewrite for Nuxt 3 [is available](https://content.nuxtjs.org/) (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](/docs/bridge/bridge-composition-api)).
-- Remove `@nuxtjs/composition-api` from your dependencies (and from your modules in `nuxt.config`) ([migration guide](/docs/bridge/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/guide/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`](/docs/api/composables/use-nuxt-app) 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 Middleware Format (Optional)
-
-You can now migrate to the Nuxt 3 middleware API, which is slightly different in format from Nuxt 2.
-
-Middleware now take only two argument (`to`, `from`). You can find out more in [the docs](/docs/guide/directory-structure/middleware).
-
-```js
-export default defineNuxtRouteMiddleware((to) => {
- if (to.path !== '/') {
- return navigateTo('/')
- }
-})
-```
-
-::alert{type=warning}
-Use of `defineNuxtRouteMiddleware` is not supported outside of the middleware directory.
-::
-
-::alert{type=warning}
-Nuxt Bridge does not support `definePageMeta`.
-::
-
-## New `useHead` (Optional)
-
-Nuxt Bridge provides a new Nuxt 3 meta API that can be accessed with a new [`useHead`](/docs/api/composables/use-head) composable.
-
-```vue
-
-```
-
-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
- }
-})
-```
-
-::alert
-This [`useHead`](/docs/api/composables/use-head) composable uses `@vueuse/head` under the hood (rather than `vue-meta`) to manipulate your ``. You need to add `@vueuse/head` to your package.json file for it to work properly.
-::
-
-::alert{type=warning}
-We recommend not using the native Nuxt 2 `head()` properties in addition to [`useHead`](/docs/api/composables/use-head) , as they may conflict.
-::
-
-For more information on how to use this composable, see [the docs](/docs/getting-started/seo-meta).
-
-## 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/bridge/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 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
+```
+
+### Disabling Auto-imports
+
+If you want to disable auto-importing composables and utilities, you can set `imports.autoImport` to `false` in the `nuxt.config` file.
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+ imports: {
+ autoImport: false
+ }
+})
+```
+
+This will disable auto-imports completely but it's still possible to use [explicit imports](#explicit-imports) from `#imports`.
diff --git a/docs/6.bridge/6.meta.md b/docs/6.bridge/6.meta.md
new file mode 100644
index 0000000000..346dd45145
--- /dev/null
+++ b/docs/6.bridge/6.meta.md
@@ -0,0 +1,109 @@
+# Meta Tags
+
+If you need to access the component state with `head`, you should migrate to using [`useHead`](/docs/api/composables/use-head) .
+
+If you need to use the Options API, there is a `head()` method you can use when you use `defineNuxtComponent`.
+
+## Migration
+
+### Set `bridge.meta`
+
+```js
+import { defineNuxtConfig } from '@nuxt/bridge'
+export default defineNuxtConfig({
+ bridge: {
+ meta: true
+ }
+})
+```
+
+### Update head properties
+
+In your `nuxt.config`, rename `head` to `meta`. (Note that objects no longer have a `hid` key for deduplication.)
+
+::code-group
+
+```ts [Nuxt 2]
+export default {
+ head: {
+ titleTemplate: '%s - Nuxt',
+ meta: [
+ { charset: 'utf-8' },
+ { name: 'viewport', content: 'width=device-width, initial-scale=1' },
+ { hid: 'description', name: 'description', content: 'Meta description' }
+ ]
+ }
+}
+```
+
+```ts [Nuxt 3]
+export default defineNuxtConfig({
+ app: {
+ head: {
+ titleTemplate: '%s - Nuxt',
+ meta: [
+ { charset: 'utf-8' },
+ { name: 'viewport', content: 'width=device-width, initial-scale=1' },
+ { name: 'description', content: 'Meta description' }
+ ]
+ }
+ }
+})
+```
+
+::
+
+## `useHead` Composables
+
+Nuxt Bridge provides a new Nuxt 3 meta API that can be accessed with a new [`useHead`](/docs/api/composables/use-head) composable.
+
+```vue
+
+```
+
+::alert
+This [`useHead`](/docs/api/composables/use-head) composable uses `@unhead/vue` under the hood (rather than `vue-meta`) to manipulate your ``.
+::
+
+::alert{type=warning}
+We recommend not using the native Nuxt 2 `head()` properties in addition to [`useHead`](/docs/api/composables/use-head) , as they may conflict.
+::
+
+For more information on how to use this composable, see [the docs](/docs/getting-started/seo-meta).
+
+## Options API
+
+```vue
+
+```
+
+## Title Template
+
+If you want to use a function (for full control), then this cannot be set in your nuxt.config, and it is recommended instead to set it within your `/layouts` directory.
+
+```vue [layouts/default.vue]
+
+```
diff --git a/docs/6.bridge/7.runtime-config.md b/docs/6.bridge/7.runtime-config.md
new file mode 100644
index 0000000000..73e8e7d703
--- /dev/null
+++ b/docs/6.bridge/7.runtime-config.md
@@ -0,0 +1,31 @@
+# Runtime Config
+
+## Update Runtime Config
+
+Nuxt 3 approaches runtime config differently than Nuxt 2, using a new combined `runtimeConfig` option.
+
+First, you'll need to combine your `publicRuntimeConfig` and `privateRuntimeConfig` properties into a new one called `runtimeConfig`, with the public config within a key called `public`.
+
+```diff
+// nuxt.config.js
+- privateRuntimeConfig: {
+- apiKey: process.env.NUXT_API_KEY || 'super-secret-key'
+- },
+- publicRuntimeConfig: {
+- websiteURL: 'https://public-data.com'
+- }
++ runtimeConfig: {
++ apiKey: process.env.NUXT_API_KEY || 'super-secret-key',
++ public: {
++ websiteURL: 'https://public-data.com'
++ }
++ }
+```
+
+This also means that when you need to access public runtime config, it's behind a property called `public`. If you use public runtime config, you'll need to update your code.
+
+```diff
+// MyWidget.vue
+- Website: {{ $config.websiteURL }}
++ Website: {{ $config.public.websiteURL }}
+```
diff --git a/docs/6.bridge/8.nitro.md b/docs/6.bridge/8.nitro.md
new file mode 100644
index 0000000000..e5cb531579
--- /dev/null
+++ b/docs/6.bridge/8.nitro.md
@@ -0,0 +1,75 @@
+# Nitro
+
+## Remove Modules
+
+- Remove `@nuxt/nitro`: Bridge injects same functionality
+
+## Update Config
+
+```ts [nuxt.config.js|ts]
+import { defineNuxtConfig } from '@nuxt/bridge'
+
+export default defineNuxtConfig({
+ bridge: {
+ nitro: true
+ }
+})
+```
+
+## 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`](/docs/api/commands/add). 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"
+ }
+}
+```
+
+::alert
+If `nitro: false`, use the `nuxt` command.
+::
+
+### 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"
+ }
+}
+```
+
+## 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.
diff --git a/docs/6.bridge/9.vite.md b/docs/6.bridge/9.vite.md
new file mode 100644
index 0000000000..4bf7d289aa
--- /dev/null
+++ b/docs/6.bridge/9.vite.md
@@ -0,0 +1,34 @@
+# Vite
+
+::alert{type=warning}
+When using `vite`, [nitro](/docs/bridge/nitro) must have been configured.
+::
+
+## Remove Modules
+
+- Remove `nuxt-vite`: Bridge enables same functionality
+
+## Update Config
+
+```ts [nuxt.config.js|ts]
+import { defineNuxtConfig } from '@nuxt/bridge'
+
+export default defineNuxtConfig({
+ bridge: {
+ vite: true,
+ nitro: true
+ }
+})
+```
+
+## Configuration
+
+```ts [nuxt.config.js|ts]
+import { defineNuxtConfig } from '@nuxt/bridge'
+
+export default defineNuxtConfig({
+ vite: {
+ // Config for Vite
+ }
+})
+```