Skip to main content
Nuxt Bridge provides access to Composition API syntax. It is specifically designed to be aligned with Nuxt 3. Because of this, there are a few extra steps to take when enabling Nuxt Bridge, if you have been using the Composition API previously.

​
Remove Modules

Before enabling Bridge’s Composition API, remove these packages:
  • Remove @vue/composition-api from your dependencies
  • Remove @nuxtjs/composition-api from your dependencies (and from your modules in nuxt.config)
package.json
{
  "dependencies": {
-   "@vue/composition-api": "^1.7.2",
-   "@nuxtjs/composition-api": "^0.33.1"
  }
}

​
Using @vue/composition-api

If you have been using just @vue/composition-api and not @nuxtjs/composition-api, then things are very straightforward.

​
Remove Manual Registration

First, remove the plugin where you are manually registering the Composition API. Nuxt Bridge will handle this for you.
plugins/composition-api.js
- import Vue from 'vue'
- import VueCompositionApi from '@vue/composition-api'
-
- Vue.use(VueCompositionApi)

​
Auto-imports

Otherwise, there is nothing you need to do. However, if you want, you can remove your explicit imports from @vue/composition-api and rely on Nuxt Bridge auto-importing them for you. 
<script>
import { ref, computed } from '@vue/composition-api'

export default {
  setup() {
    const count = ref(0)
    const doubled = computed(() => count.value * 2)
    
    return { count, doubled }
  }
}
</script>

​
Migrating from @nuxtjs/composition-api

Nuxt Bridge implements the Composition API slightly differently from @nuxtjs/composition-api and provides different composables (designed to be aligned with the composables that Nuxt 3 provides). Because some composables have been removed and don’t yet have a replacement, this will be a slightly more complicated process.

​
Remove @nuxtjs/composition-api Module

You don’t have to immediately update your imports yet - Nuxt Bridge will automatically provide a ‘shim’ for most imports you currently have, to give you time to migrate to the new, Nuxt 3-compatible composables, with the following exceptions:
  • withContext has been removed. See below for alternatives.
  • useStatic has been removed. There is no current replacement. Feel free to raise a discussion if you have a use case for this.
  • reqRef and reqSsrRef, which were deprecated, have now been removed entirely. Follow the instructions below regarding ssrRef to replace this.

​
Set bridge.capi

Enable Composition API support in your nuxt.config:
nuxt.config.ts
import { defineNuxtConfig } from '@nuxt/bridge'

export default defineNuxtConfig({
  bridge: {
    capi: true,
    nitro: false, // If migration to Nitro is complete, set to true
  },
})

​
Composable Changes

​
useFetch

$fetchState and $fetch have been removed. 
const {
- $fetch,
- $fetchState,
+ fetch,
+ fetchState,
} = useFetch(() => { posts.value = await $fetch('/api/posts') })

​
defineNuxtMiddleware

This was a type-helper stub function that is now removed. Remove the defineNuxtMiddleware wrapper:
middleware/auth.ts
- import { defineNuxtMiddleware } from '@nuxtjs/composition-api'
- export default defineNuxtMiddleware((ctx) => {})
+ export default (ctx) => {}
For TypeScript support, you can use @nuxt/types: 
import type { Middleware } from '@nuxt/types'

export default <Middleware> function (ctx) { }

​
defineNuxtPlugin

This was a type-helper stub function that is now removed. You may also keep using Nuxt 2-style plugins, by removing the function (as with defineNuxtMiddleware). Remove the defineNuxtPlugin wrapper:
plugins/my-plugin.ts
- import { defineNuxtPlugin } from '@nuxtjs/composition-api'
- export default defineNuxtPlugin((ctx, inject) => {})
+ export default (ctx, inject) => {}
For TypeScript support, you can use @nuxt/types: 
import type { Plugin } from '@nuxt/types'

export default <Plugin> function (ctx, inject) {}
While this example is valid, Nuxt 3 introduces a new defineNuxtPlugin function that has a slightly different signature.

​
useRouter and useRoute

Nuxt Bridge provides direct replacements for these composables via useRouter and useRoute. The only key difference is that useRoute no longer returns a computed property. 
- import { useRouter, useRoute } from '@nuxtjs/composition-api'

  const router = useRouter()
  const route = useRoute()

- console.log(route.value.path)
+ console.log(route.path)

​
Migration Examples

​
Before: @nuxtjs/composition-api

<template>
  <div>
    <p>{{ count }}</p>
    <button @click="increment">Increment</button>
  </div>
</template>

<script>
import { defineComponent, ref, useFetch, useContext } from '@nuxtjs/composition-api'

export default defineComponent({
  setup() {
    const { $axios } = useContext()
    const count = ref(0)
    
    const { fetch } = useFetch(async () => {
      const data = await $axios.$get('/api/count')
      count.value = data.count
    })
    
    const increment = () => {
      count.value++
    }
    
    return {
      count,
      increment,
      fetch
    }
  }
})
</script>

​
After: Nuxt Bridge

<template>
  <div>
    <p>{{ count }}</p>
    <button @click="increment">Increment</button>
  </div>
</template>

<script setup>
const { $axios } = useNuxtApp()
const count = ref(0)

const { fetch } = useFetch(async () => {
  const data = await $axios.$get('/api/count')
  count.value = data.count
})

const increment = () => {
  count.value++
}
</script>

​
State Management

With Bridge, use useState for shared state: 
import { ssrRef } from '@nuxtjs/composition-api'

export default {
  setup() {
    const counter = ssrRef(0, 'counter')
    return { counter }
  }
}

​
Context Access

Replace useContext with specific composables: 
import { useContext } from '@nuxtjs/composition-api'

const { $axios, redirect, route, store } = useContext()

​
Migration Checklist

  • Remove @vue/composition-api from dependencies
  • Remove @nuxtjs/composition-api from dependencies and modules
  • Remove manual Composition API registration
  • Enable bridge.capi in nuxt.config
  • Update useFetch usage
  • Remove defineNuxtMiddleware wrappers
  • Remove defineNuxtPlugin wrappers
  • Update useRoute (remove .value)
  • Replace useContext with specific composables
  • Replace ssrRef with useState

​
Next Steps

After migrating your Composition API usage:
  • Configure Bridge settings
  • Enable TypeScript for better type safety
  • Explore other Nuxt 3 features available in Bridge