diff --git a/README.md b/README.md index f26281d6..e1f00fd1 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,264 @@ # Nuxt Bridge -> Use backported Nuxt 3 features in Nuxt 2 +> Experience Nuxt 3 features on existing Nuxt 2 projects. -Learn more about this package: +If you're starting a fresh Nuxt 3 project, please skip this section and go to [Nuxt 3 Installation](/getting-started/quick-start). + +**Note:** Nuxt Bridge provides identical features to Nuxt 3 ([docs](/guide/features)) 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. + +## Preparation: 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: + +```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: + +```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`](/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" + } +} +``` + +### 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": { + ... + } +} +``` + +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](/bridge/bridge-composition-api). + +### Migrate from CommonJS to ESM + +Nuxt 3 natively supports TypeScript and ECMAScript Modules. Please check [Native ES Modules](/guide/going-further/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](/bridge/bridge-composition-api)). +- Remove `@nuxtjs/composition-api` from your dependencies (and from your modules in `nuxt.config`) ([migration guide](/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](/guide/directory-structure/plugins). + +```js +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. + +## New `useHead` (optional) + +Nuxt Bridge provides a new Nuxt 3 meta API that can be accessed with a new `useHead` 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 + } +}) +``` + +This `useHead` composable uses `@vueuse/head` under the hood (rather than `vue-meta`) to manipulate your ``. +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](/guide/features/head-management). + +## 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 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