Composition API in Bridge

Learn how to migrate from legacy Composition API packages to Nuxt Bridge’s built-in Composition API support.

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.

Before

<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:

Before

import { ssrRef } from '@nuxtjs/composition-api'

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

Context Access

Replace useContext with specific composables:

Before

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