Skip to main content
Nuxt Bridge is highly configurable, allowing you to enable or disable features as needed during your migration to Nuxt 3.

​
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 bridge/src/module.ts for latest defaults.
nuxt.config.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,

    // Enable definePageMeta macro
    // macros: {
    //   pageMeta: true
    // },

    // Enable transpiling TypeScript with esbuild
    // typescript: {
    //   esbuild: true
    // },

    // -- Default features --

    // Use legacy server instead of Nitro
    // nitro: 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 <script setup> support
    // scriptSetup: false,

    // Disable composables auto importing
    // imports: false,

    // Do not warn about module incompatibilities
    // constraints: false
  },

  vite: {
    // Config for Vite
  },
})

​
Configuration Options

​
vite

Enable Vite as your bundler instead of webpack 4: 
export default defineNuxtConfig({
  bridge: {
    vite: true
  }
})
Benefits:
  • Faster dev server startup
  • Faster hot module replacement (HMR)
  • Better development experience

​
meta

Enable Nuxt 3 compatible useHead composable: 
export default defineNuxtConfig({
  bridge: {
    meta: true
  }
})
This allows you to use the new useHead composable for managing meta tags.

​
nitro

Enable the Nitro server engine: 
export default defineNuxtConfig({
  bridge: {
    nitro: true
  }
})
Benefits:
  • Improved server performance
  • Better deployment options
  • API route improvements
  • Nuxt 3 compatibility

​
typescript

Enable TypeScript support with optional esbuild transpilation: 
export default defineNuxtConfig({
  bridge: {
    typescript: true,
    // Or with esbuild for faster transpilation
    typescript: {
      esbuild: true
    }
  }
})

​
capi

Configure Composition API support: 
export default defineNuxtConfig({
  bridge: {
    // Enable Composition API
    capi: true,
    
    // Or disable legacy Composition API support
    capi: {
      legacy: false
    }
  }
})

​
macros

Enable compiler macros like definePageMeta: 
export default defineNuxtConfig({
  bridge: {
    macros: {
      pageMeta: true
    }
  }
})

​
imports

Configure auto-imports: 
export default defineNuxtConfig({
  bridge: {
    // Enable auto-imports (default: true)
    imports: true,
    
    // Or disable
    imports: false
  }
})

​
scriptSetup

Enable <script setup> support: 
export default defineNuxtConfig({
  bridge: {
    scriptSetup: true
  }
})

​
transpile

Configure module transpilation: 
export default defineNuxtConfig({
  bridge: {
    transpile: true
  }
})

​
constraints

Control module compatibility warnings: 
export default defineNuxtConfig({
  bridge: {
    // Disable compatibility warnings
    constraints: false
  }
})

​
Migration of Specific Options

​
router.base → app.baseURL

The router.base option has been moved to app.baseURL:
nuxt.config.ts
export default defineNuxtConfig({
- router: {
-   base: '/my-app/'
- }
+ app: {
+   baseURL: '/my-app/'
+ }
})

​
build.publicPath → app.cdnURL

The build.publicPath option has been moved to app.cdnURL:
nuxt.config.ts
export default defineNuxtConfig({
- build: {
-   publicPath: 'https://my-cdn.net'
- }
+ app: {
+   cdnURL: 'https://my-cdn.net'
+ }
})
For a smooth migration, we recommend enabling features gradually:

​
Step 1: Basic Setup

export default defineNuxtConfig({
  bridge: {
    typescript: true,
    capi: true,
    scriptSetup: true,
  }
})

​
Step 2: Add Nitro

export default defineNuxtConfig({
  bridge: {
    typescript: true,
    capi: true,
    scriptSetup: true,
    nitro: true,  // Add Nitro
  }
})

​
Step 3: Enable Vite

export default defineNuxtConfig({
  bridge: {
    typescript: true,
    capi: true,
    scriptSetup: true,
    nitro: true,
    vite: true,  // Add Vite
  }
})

​
Step 4: Add Modern Features

export default defineNuxtConfig({
  bridge: {
    typescript: true,
    capi: true,
    scriptSetup: true,
    nitro: true,
    vite: true,
    meta: true,  // Add useHead support
    macros: {
      pageMeta: true  // Add definePageMeta
    }
  }
})

​
Troubleshooting

​
Module Compatibility Issues

If you encounter module compatibility warnings: 
export default defineNuxtConfig({
  bridge: {
    constraints: false  // Disable warnings
  }
})

​
Build Errors

If you encounter build errors after enabling a feature:
  1. Disable the feature temporarily
  2. Clear .nuxt directory: rm -rf .nuxt
  3. Reinstall dependencies: npm install
  4. Try enabling the feature again

​
TypeScript Errors

If you see TypeScript errors:
  1. Run nuxi prepare to regenerate types
  2. Restart your IDE/editor
  3. Check tsconfig.json extends .nuxt/tsconfig.json

​
Configuration Examples

​
Minimal Configuration

For a minimal Bridge setup: 
export default defineNuxtConfig({
  bridge: {
    typescript: true
  }
})
For a complete Bridge setup with all features: 
export default defineNuxtConfig({
  bridge: {
    typescript: {
      esbuild: true
    },
    capi: true,
    scriptSetup: true,
    imports: true,
    nitro: true,
    vite: true,
    meta: true,
    macros: {
      pageMeta: true
    }
  }
})

​
Next Steps

After configuring Bridge:
  • Test your application thoroughly
  • Gradually enable more features
  • Monitor for compatibility issues
  • Prepare for full Nuxt 3 migration