Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: remove bridge migration steps from README #905

Merged
merged 1 commit into from
Sep 10, 2023
Merged

docs: remove bridge migration steps from README #905

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
275 changes: 5 additions & 270 deletions README.md
View file
Open in desktop
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)
Loading