Skip to content

Commit

Permalink
docs: remove bridge migration steps from README (#905)
Browse files Browse the repository at this point in the history
  • Loading branch information
@wattanx
wattanx authored Sep 10, 2023
1 parent 59dce34 commit 909ba5a
Showing 1 changed file with 5 additions and 270 deletions.
275 changes: 5 additions & 270 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -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
<script setup>
useHead({
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 `useHead` composable uses `@unhead/vue` 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](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)

0 comments on commit 909ba5a

Please sign in to comment.