Nuxt•2d ago

How to exactly use nuxt-bridge

I'm trying to use nuxt-bridge to make our application more compatible with Nuxt 3. I'm trying to follow the documentation but it is not very clear. I did the Nuxt and Vue updates prior to installing Nuxt bridge so thankfully I'm already on: - Nuxt 2.18.1 - Vue 2.7.16 And I did steps described on that page: https://nuxt.com/docs/4.x/bridge/overview I have: 1. installed the bridge and nuxi packages. 2. added defineNuxtConfig inside nuxt.config.js 3. added bridge: false to the config 4. updated the commands to use nuxt2 instead of nuxt At this point application seems to work normally as before. But now what? As soon as I change bridge: false to anything else, even empty object {} bunch of stuff fails. For example, the first step in the docs is to enable typescript option. So I tried it. I removed typescript packages described here https://nuxt.com/docs/4.x/bridge/typescript I updated the config to:

`
  bridge: {
    typescript: true,
    nitro: false
  }

And tried adding "extends": "./.nuxt/tsconfig.json", But application complains that I have to remove @nuxtjs/composition-api, but I didn't yet enable the option about composition api which is the next step? So what is the exact order of operation? Do I actually need to do everything at the same time despite bridge saying otherwise? Please help

Nuxt

Migrate to Nuxt Bridge: Overview v4

Reduce the differences with Nuxt 3 and reduce the burden of migration to Nuxt 3.

Nuxt

Migrate to Nuxt Bridge: TypeScript v4

Learn how to use TypeScript with Nuxt Bridge.

14 Replies

kapa.ai•2d ago

Hi @anj. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave: ---------------------- You're on the right track with your migration, and your confusion is understandable—Nuxt Bridge migration can be tricky due to the interplay of features and dependencies. Here’s a step-by-step clarification based strictly on the official documentation: --- 1. Initial Setup (What you’ve done so far) - Upgraded Nuxt and Vue to the latest Nuxt 2 and Vue 2.7.x. - Installed @nuxt/bridge and nuxi. - Updated your nuxt.config to use defineNuxtConfig and set bridge: false. - Changed your npm scripts to use nuxt2 commands. - Confirmed your app works as before.
This is the correct starting point.
Nuxt Bridge Overview --- 2. Enabling Bridge Features: Order Matters Nuxt Bridge is designed to let you enable features one at a time, but some features have dependencies or require you to remove conflicting packages first. #### TypeScript - When you enable bridge: { typescript: true }, you must remove @nuxt/typescript-build, @nuxt/typescript-runtime, and nuxt-ts from your dependencies, as Bridge replaces them. - You also need to update your tsconfig.json to extend from ./.nuxt/tsconfig.json as described in the docs. - However, enabling TypeScript support may also trigger checks for other legacy packages, such as @nuxtjs/composition-api or @vue/composition-api, because Bridge expects to manage the Composition API itself.
Bridge TypeScript Docs #### Composition API - If you have @nuxtjs/composition-api or @vue/composition-api installed, you must remove them before enabling Bridge’s Composition API support (bridge: { capi: true }). - Bridge will auto-import Composition API features for you, and you should remove any manual plugin registration for these packages. - If you enable TypeScript first, Bridge may still check for these packages and require their removal, even if you haven’t enabled capi yet.
Bridge Composition API Migration --- 3. Recommended Migration Order Based on the docs, the safest order is: 1. Remove legacy Composition API packages (@nuxtjs/composition-api, @vue/composition-api) and any related plugins or module entries in your config. 2. Enable Bridge features one at a time in your nuxt.config: - Start with typescript: true if you want TypeScript support. - Then enable capi: true for Composition API support. - Enable other features (like meta, nitro, etc.) as needed. 3. Update your codebase to remove any usage of the removed packages and migrate to Bridge/nuxt3-compatible APIs as described in the migration docs. You do not need to enable all features at once, but you must remove conflicting packages before enabling related Bridge features.
Bridge Overview
Legacy Composition API Migration --- 4. If You See Errors - Errors about @nuxtjs/composition-api mean you must remove it before enabling any Bridge features that touch the Composition API or TypeScript. - After removing, re-run npm install (or your package manager), then try enabling the Bridge feature again. --- 5. Summary Table | Step | Action | |------|--------| | 1 | Remove @nuxtjs/composition-api and @vue/composition-api from dependencies and config | | 2 | Remove @nuxt/typescript-build, @nuxt/typescript-runtime, nuxt-ts if enabling TypeScript | | 3 | Enable bridge: { typescript: true } and/or bridge: { capi: true } | | 4 | Update tsconfig.json as per docs | | 5 | Migrate code to use Bridge/nuxt3 APIs | --- In short:
You must remove @nuxtjs/composition-api and related packages before enabling TypeScript or Composition API features in Bridge, even if you haven’t enabled the capi option yet. The migration is incremental, but some steps (like removing conflicting packages) are prerequisites for enabling certain features. If you follow this order, you should be able to enable Bridge features one by one and migrate your codebase incrementally, as intended by the Bridge documentation. --- If you need more detailed help with a specific error message, please share the error and I can help interpret it based on the docs! ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•2d ago

<@502515984926638081> Kapa.ai is still learning and improving, please let me know how I did by reacting below.

___anj___OP•2d ago

@kapa.ai I already removed @vue/composition-api in scope of upgrading Vue to version 2.7 previously. I still have @nuxtjs/composition-api. Can I just remove it without setting any options in nuxt bridge? Are there any other unexpected changes that I need to make prior to using bridge? Why the order is not clearly documented in the nuxt docs?

kapa.ai•2d ago

Let me check the knowledge base for you again. One moment! :books: ---------------------- Yes, you can remove @nuxtjs/composition-api from your project before enabling any options in Nuxt Bridge. The official documentation states that you should remove both @vue/composition-api and @nuxtjs/composition-api from your dependencies and from your modules in nuxt.config when migrating to Nuxt Bridge. This is a required step, especially if you plan to enable Bridge features like TypeScript or the Composition API, as Bridge will provide its own implementation and auto-imports for these features. There is no indication in the docs that you must set any Bridge options before removing these packages—they should simply be removed as part of the migration process Legacy Composition API. As for other unexpected changes:
- If you were manually registering the Composition API plugin, you should also remove that plugin file, since Nuxt Bridge will handle this for you. - After removing these packages, you can proceed to enable Bridge features incrementally as needed. Regarding the documentation order:
The docs do provide a migration sequence, but they do not always explicitly state the dependencies between steps or the exact order for every scenario. This can lead to some confusion, especially when certain features (like TypeScript or Composition API support) require the removal of legacy packages before enabling related Bridge options. The migration steps are outlined, but the interdependencies are sometimes implied rather than clearly listed Bridge Overview. In summary:
- You can and should remove @nuxtjs/composition-api before enabling Bridge features. - Remove any manual plugin registration for the Composition API. - No other unexpected changes are required before using Bridge, but always check for other legacy packages that might conflict with Bridge features. - The documentation could be clearer about the exact order, but the main requirement is to remove conflicting packages before enabling Bridge features. ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•2d ago

<@502515984926638081> Kapa.ai is still learning and improving, please let me know how I did by reacting below.

___anj___OP•2d ago

@kapa.ai I still have some dependencies that use @nuxtjs/composition-api and I can not simply remove them. After removing composition api from buildModules I get this errors:

[friendly-errors 12:08:05 PM] Can't reexport the named export 'watch' from non EcmaScript module (only default export is available)
[friendly-errors 12:08:05 PM] 

[friendly-errors 12:08:05 PM]  ERROR  in ./node_modules/@nuxtjs/composition-api/dist/runtime/index.mjs

[friendly-errors 12:08:05 PM] Can't reexport the named export 'watchEffect' from non EcmaScript module (only default export is available)
[friendly-errors 12:08:05 PM]

[friendly-errors 12:08:05 PM] Can't reexport the named export 'watch' from non EcmaScript module (only default export is available)
[friendly-errors 12:08:05 PM] 

[friendly-errors 12:08:05 PM]  ERROR  in ./node_modules/@nuxtjs/composition-api/dist/runtime/index.mjs

[friendly-errors 12:08:05 PM] Can't reexport the named export 'watchEffect' from non EcmaScript module (only default export is available)
[friendly-errors 12:08:05 PM]

kapa.ai•2d ago

Let me check the knowledge base for you again. One moment! :books: ---------------------- The errors you are seeing (Can't reexport the named export 'watch' from non EcmaScript module...) occur because some of your dependencies still rely on @nuxtjs/composition-api, which is not fully compatible with the ESM (EcmaScript Module) build system that Nuxt Bridge and Nuxt 3 use. The Nuxt Bridge migration guide explicitly states that you must remove @nuxtjs/composition-api from your dependencies and modules, as Bridge provides its own Composition API implementation and auto-imports Legacy Composition API. However, if you have dependencies that require @nuxtjs/composition-api, you are in a difficult position. The knowledge sources do not provide a workaround for this scenario. The documentation suggests that for full Bridge compatibility, all dependencies must be updated to not require @nuxtjs/composition-api. There is no mention of a supported way to keep @nuxtjs/composition-api alongside Bridge, and the errors you are seeing are a direct result of this incompatibility. In summary:
- You must remove @nuxtjs/composition-api for Bridge to work correctly. - If your dependencies require it, those dependencies are not yet compatible with Nuxt Bridge or Nuxt 3. - The knowledge sources do not provide a workaround for this; you will need to wait for those dependencies to update, or consider replacing them with alternatives that support Nuxt Bridge. If you need to proceed with Bridge, all dependencies must be compatible with the new Composition API provided by Bridge. If this is not possible, you may need to delay your migration until your dependencies are updated. ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•2d ago

<@502515984926638081> Kapa.ai is still learning and improving, please let me know how I did by reacting below.

___anj___OP•this hour

@kapa.ai So if I can not get rid of the 3rd party package and they will for sure not update it to support bridge/nuxt 3 I'm basically stuck and bridge has no use for me? It is claiming to provide a shim for the imports, so why 3rd party packages do not work with that shim?

kapa.ai•this hour

Let me check the knowledge base for you again. One moment! :books: ---------------------- You are correct in your understanding: if you have a third-party package that depends on @nuxtjs/composition-api and that package will not be updated to support Nuxt Bridge or Nuxt 3, you are effectively blocked from migrating to Bridge or Nuxt 3 while using that dependency. The Nuxt Bridge documentation does state that it provides a "shim" for most imports from @nuxtjs/composition-api to give you time to migrate your own code. However, it also notes that some composables have been removed and do not have replacements, and that the shim is not a complete compatibility layer for all possible usages. The shim is primarily intended to help you migrate your own code incrementally, not to guarantee compatibility for all third-party packages that depend on @nuxtjs/composition-api Legacy Composition API Migration. If a third-party package is importing or re-exporting named exports from @nuxtjs/composition-api in a way that is not compatible with the ESM build system or with the Bridge shim, you may encounter the errors you described. The knowledge sources do not provide a workaround for this scenario, nor do they guarantee that all third-party packages will work with the shim. In summary:
- The Bridge shim is designed to help migrate your own code, not to ensure all third-party packages will work. - If a third-party package is not compatible and will not be updated, you are indeed blocked from using Bridge or Nuxt 3 with that package. - The knowledge sources do not mention a solution for this situation. If you are in this situation, you will need to either: - Find an alternative package that supports Nuxt Bridge/Nuxt 3, or - Remain on Nuxt 2 until you can remove or replace the incompatible dependency. ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•this hour

<@502515984926638081> Kapa.ai is still learning and improving, please let me know how I did by reacting below.

___anj___OP•this hour

@kapa.ai what would make the dependency compatible with bridge? I could patch the package but you need to provide a way to make the package compatible with bridge.

kapa.ai•this hour

Let me check the knowledge base for you again. One moment! :books: ---------------------- To make a dependency compatible with Nuxt Bridge, you need to ensure that it does not rely on @nuxtjs/composition-api and is compatible with the ESM (EcmaScript Module) system that Bridge and Nuxt 3 use. The official documentation provides guidance for library authors and migration steps: Key Steps to Make a Package Compatible with Bridge 1. Remove Dependency on @nuxtjs/composition-api: - The package should not import or re-export from @nuxtjs/composition-api. Instead, it should use the Composition API provided by Vue 2.7+ (which is built-in) or rely on the auto-imports provided by Nuxt Bridge. 2. Migrate to ESM: - The package should use ESM syntax (import/export) instead of CommonJS (require/module.exports). - If the package is distributed as ESM, ensure files use the .mjs extension or set "type": "module" in package.json as recommended in the Library Author Guide. 3. Update Exports: - Use named exports rather than default exports to reduce CJS/ESM conflicts. - Avoid re-exporting named exports from non-ESM modules, as this causes the "Can't reexport the named export" error you encountered. 4. Avoid Node.js-only APIs: - The package should not depend on Node.js built-ins or CommonJS-only dependencies, to ensure compatibility with Nuxt Bridge and future Nuxt 3 environments. 5. Use Nuxt Bridge/Vue 2.7+ APIs: - If the package needs to use the Composition API, it should import from vue (for Vue 2.7+) or rely on Nuxt Bridge's auto-imports, not from @nuxtjs/composition-api. 6. Test with Nuxt Bridge: - After making these changes, test the package in a Nuxt Bridge project to ensure there are no import/export or runtime errors. Example: Fixing a Package If the package currently does something like:

// BAD: This will break with Bridge/ESM
export { ref, watch, computed } from '@nuxtjs/composition-api'

// BAD: This will break with Bridge/ESM
export { ref, watch, computed } from '@nuxtjs/composition-api'

You should change it to:

// GOOD: Use Vue's built-in Composition API (Vue 2.7+)
export { ref, watch, computed } from 'vue'

// GOOD: Use Vue's built-in Composition API (Vue 2.7+)
export { ref, watch, computed } from 'vue'

Or, if you need to support both Nuxt 2 and 3, consider using vue-demi as suggested in the migration docs, which provides compatibility for both Vue 2 and 3 environments Module Authors Migration. Summary - Remove all usage of @nuxtjs/composition-api. - Use ESM syntax and proper export patterns. - Import Composition API features from vue (for Vue 2.7+) or use vue-demi for cross-version support. - Test the package in a Nuxt Bridge project. If you patch the package following these steps, it should become compatible with Nuxt Bridge Library Author Guide Module Migration. If you encounter specific ESM import/export issues, refer to the troubleshooting section for additional fixes, such as ensuring all exports are valid ESM exports Troubleshooting ESM Issues. If you need more detailed help with a specific code snippet, feel free to share it! ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•this hour

<@502515984926638081> Kapa.ai is still learning and improving, please let me know how I did by reacting below.

Gaming

Programming

How to exactly use nuxt-bridge

Did you find this page helpful?