5.2 KiB

Raw Blame History

Bridge Migration

⚠️ This section is work-in-progress and can change. Please regularly check this page.

... I have a nuxt2 project

Migration to nuxt-bridge, should be almost straight forward!

Why migrate:

It is risk-free! You can roll back by just commenting out one line in config
Makes your project almost ready for nuxt3 migration
Enjoy new DX improvements without major rewrites for vue3
Use nitro engine for platform agnostic and optimized deployments
Help us stabilize nuxt3 and discover flows
Bridge is more stable than nuxt3 at the moment for migration

Step 1: Ensure using latest version of nuxt

Remove package lock file (package-lock.json and yarn.lock) and update to latest version of nuxt2 (releases) or use nuxt-edge for latest updates and fixes.

Step 2: Install bridge module

Install @nuxt/bridge as a devDependency:

# Using npm
npm install -D @nuxt/bridge@npm:@nuxt/bridge-edge

# Using yarn
yarn add --dev @nuxt/bridge@npm:@nuxt/bridge-edge

Update nuxt.config file:

import { defineNuxtConfig } from '@nuxt/bridge'

export default defineNuxtConfig({
  bridge: {
    nitro: true,
    // vite: true
  }
})

If you have a project with target: 'static', update "build" script to use nuxt generate

{
  "scripts": {
    "build": "nuxt generate"
  }
}

Step 3: Avoid CommonJS syntax

See Migrating from CommonJS from module author section. We need same steps for plugins, store, pages, serverMiddleware and nuxt.config.js.

Step 4: Remove incompatible modules

Remove @nuxt/content (1.x): note: a v2 rewrite for nuxt 3 support is planned, or you may also use docus
Remove nuxt-vite: Bridge injects module when enabled with { bridge: { vite: true } }
Remove @nuxt/nitro: Bridge injects module
Remove @nuxtjs/composition-api: Bridge provides a nuxt 3 compatible composition-api layer.

Step 5: Ensure everything goes well

Try with both nuxt dev, nuxt build and nuxt start if everything goes as expected If there is an issue, please report it to us or to relevant module repository.

If you cannot take the risk of using experimental code, you can comment out the module and regularly check back to ensure your project stays ready for nuxt3 compatibly.

🥳 Enjoy new possibilities!

Everything goes well? Congratulations! You are welcome to enjoy new features from nuxt3 without full migration. See table in intro section for more.

... I am a module author

When users of nuxt3 use your module, a compatible module container layer from @nuxt/kit is automatically injected so as long as your code is following below guidelines, it should continue working as is.

Step 1: Test it with `@nuxt/bridge`:

Migrating to @nuxt/bridge is the first and most important step for supporting nuxt3.

If you have a fixture in your module, add @nuxt/bridge package to its config (same steps as previous section for nuxt2 projects)

Step 2: Avoid CommonJS syntax:

Nuxt natively supports TypeScript and ECMAScript Modules. In every file make sure to:

Change require('lib') to import lib from 'lib' or await import('lib').then(e => e.default || e)
Change module.exports to export default or export const
Avoid usage of __dirname and __filename as much as possible

Step 3: Ensure plugins have default export

If you inject a nuxt plugin that does not have export default (such as global Vue plugins), ensure you add export default {} to the end of it

Step 4: Avoid runtime modules

With nuxt3 and nitro project, we started to rethink how the nuxt build process should work and modules hooking into the Nuxt runtime is now considered an anti-pattern and will not work with nuxt3.

Your module should work fine by adding only to buildModules[] (instead of modules[]):

Avoid updating process.env within nuxt module and reading by a nuxt plugin. Use runtimeConfig instead
(*) Avoid depending on runtime hooks like vue-renderer:* for production
(*) Avoid adding serverMiddleware by importing them inside module. Add them by referencing to file path so that they are independent of module context

(*) Unless it is for nuxt dev purpose only and guarded with if (nuxt.options.dev) { }.

Step 5: Add module meta

Ensure your module is exporting meta object.

[TODO]

Step 6: Migrate to TypeScript (optional)

While it is not essential, most of nuxt ecosystem is shifting to use TypeScript, it is highly recommended to consider migration.

Tip: You can start migration by simply renaming .js files, to .ts. TypeScript is designed to be progressive!

Tip: You can use TypeScript syntax for nuxt 2/3 modules and plugins without any extra dependencies.

🛣️ Next Steps

While we are evolving nuxt3 and modules, you are welcome to share any ideas in Discussions section.

A brand new experience of defining nuxt modules is coming with @nuxt/kit project but it is still not ready so it is advised only to try it and not release to stable versions of your module.

Please regularly check this section for latest updates.

5.2 KiB Raw Blame History