Nuxt/docs/6.bridge/3.bridge-composition-api.md

133 lines
4.4 KiB
Markdown

---
title: Legacy Composition API
description: 'Learn how to migrate to Composition API with Nuxt Bridge.'
---
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
- Remove `@vue/composition-api` from your dependencies.
- Remove `@nuxtjs/composition-api` from your dependencies (and from your modules in `nuxt.config`).
## Using `@vue/composition-api`
If you have been using just `@vue/composition-api` and not `@nuxtjs/composition-api`, then things are very straightforward.
1. First, remove the plugin where you are manually registering the Composition API. Nuxt Bridge will handle this for you.
```diff
- import Vue from 'vue'
- import VueCompositionApi from '@vue/composition-api'
-
- Vue.use(VueCompositionApi)
```
2. 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.
## 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` from your buildModules
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](/docs/bridge/nuxt3-compatible-api#usecontext-and-withcontext).
- `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](/docs/bridge/nuxt3-compatible-api#ssrref-and-shallowssrref) to replace this.
### Set `bridge.capi`
```ts
import { defineNuxtConfig } from '@nuxt/bridge'
export default defineNuxtConfig({
bridge: {
capi: true,
nitro: false // If migration to Nitro is complete, set to true
}
})
```
For each other composable you are using from `@nuxtjs/composition-api`, follow the steps below.
### useFetch
`$fetchState` and `$fetch` have been removed.
```diff
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:
```diff
- import { defineNuxtMiddleware } from '@nuxtjs/composition-api`
- export default defineNuxtMiddleware((ctx) => {})
+ export default (ctx) => {}
```
For typescript support, you can use `@nuxt/types`:
```ts
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](#definenuxtmiddleware)).
Remove the `defineNuxtPlugin` wrapper:
```diff
- import { defineNuxtPlugin } from '@nuxtjs/composition-api'
- export default defineNuxtPlugin((ctx, inject) => {})
+ export default (ctx, inject) => {}
```
For typescript support, you can use `@nuxt/types`:
```ts
import type { Plugin } from '@nuxt/types'
export default <Plugin> function (ctx, inject) {}
```
::alert{type="warning"}
While this example is valid, Nuxt 3 introduces a new defineNuxtPlugin function that has a slightly different signature.
::
:ReadMore{link="/docs/guide/directory-structure/plugins#creating-plugins"}
### `useRouter` and `useRoute`
Nuxt Bridge provides direct replacements for these composables via [`useRouter`](/docs/api/composables/use-router) and `useRoute`.
The only key difference is that [`useRoute`](/docs/api/composables/use-route) no longer returns a computed property.
```diff
- import { useRouter, useRoute } from '@nuxtjs/composition-api'
const router = useRouter()
const route = useRoute()
- console.log(route.value.path)
+ console.log(route.path)
```