diff --git a/README.md b/README.md index 58cc51c1..469cebb0 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,19 @@ # 🌉 Nuxt Bridge -> Experience Nuxt 3 features on existing Nuxt 2 projects. +> Reduce the differences with Nuxt 3 and reduce the burden of migration to Nuxt 3. 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. ⚠️ **Note:** Nuxt Bridge provides identical features to Nuxt 3 ([Nuxt 3 docs](https://nuxt.com/docs/getting-started/views#views)) but there are some limitations, notably that `useAsyncData` and `useFetch` composables are not available. Please read the rest of this page for details. ⚠️ **Note:** Nuxt Bridge does not support Internet Explorer. Supported browsers are listed at https://caniuse.com/es6-module-dynamic-import. 🌱 **Note:** If you're starting a fresh Nuxt project, please skip this module and directly go to the [Nuxt 3 Installation](https://nuxt.com/docs/getting-started/introduction). +## Docs + +Visit the [documentation site](https://nuxt.com/docs/bridge/overview) for migration guide. ## 💻 Development @@ -23,274 +26,6 @@ Using Nuxt Bridge, you can make sure your project is (almost) ready for Nuxt 3 a Learn more about in our documentation on [how to contribute to Nuxt](https://nuxt.com/docs/community/contribution). - -## Installation - -### Upgrade to the latest Nuxt 2 - -Make sure your dev server (`nuxt dev`) isn't running, remove any package lock files (`package-lock.json`, `yarn.lock` or `pnpm-lock.yaml`), and install the latest `nuxt` version: - -```diff [package.json] -- "nuxt": "^2.15.0" -+ "nuxt": "^2.16.0" -``` - -Then, reinstall your dependencies: - -```bash -# Using yarn -yarn install - -# Using npm -npm install - -# Using pnpm -pnpm 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-edge` as a development dependency: - -```bash - -# Using yarn -yarn add --dev @nuxt/bridge@npm:@nuxt/bridge-edge - -# Using npm -npm install -D @nuxt/bridge@npm:@nuxt/bridge-edge - -# Using pnpm -pnpm 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`](https://nuxt.com/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" - } -} -``` - -### 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](https://nuxt.com/docs/bridge/bridge-composition-api). - -### Migrate from CommonJS to ESM - -Nuxt 3 natively supports TypeScript and ECMAScript Modules. Please check [Native ES Modules](https://nuxt.com/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 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](https://nuxt.com/docs/bridge/bridge-composition-api)). -- Remove `@nuxtjs/composition-api` from your dependencies (and from your modules in `nuxt.config`) ([migration guide](https://nuxt.com/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](https://nuxt.com/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 `@unhead/vue` 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](https://nuxt.com/docs/getting-started/seo-meta#seo-and-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 [packages/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 (nuxt dev) instead of Nitro (nuxi dev) - // If opting out of Nitro server, restore the original script tasks to use nuxt, not nuxi. - // nitro: false, - - // Use legacy generator rather than new nitro prerenderer - // nitroGenerator: 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 - // It is recommended not to change `imports` but instead to set `imports.autoImport` to false (see below) - // imports: false, - - // Do not warn about module incompatibilities - // constraints: false - }, - - // Disabling auto-imports this way allows you to import nuxt composables explicitly from `#imports` - // imports: { - // autoImport: false - // }, - - vite: { - // Config for Vite - } -}) -``` - ## License [MIT](https://github.com/nuxt/nuxt.js/blob/dev/LICENSE)