repository·main·Indexed 20 days ago
https://github.com/nuxt-community/composition-apiA module that provides the Vue Composition API for Nuxt 2, bridging the gap between the Composition API pattern and Nuxt-specific features. It includes support for the Nuxt fetch hook (v2.12+), access to Nuxt context (router, app, store), vue-meta integration via useMeta, and SSR-friendly refs with ssrRef. The package is written in TypeScript and supports <script setup> via unplugin-vue2-script-setup. Users are recommended to migrate to Nuxt Bridge for native Composition API support.
@nuxtjs/composition-api is a module that enables the use of the Vue Composition API within a Nuxt.js environment, while providing integration with Nuxt-specific features.
Important Migration Note: If you are starting a new project or looking to upgrade, it is strongly recommended to use Nuxt Bridge instead, as it provides native Composition API support.
@nuxtjs/composition-api module provides a way to use the Vue Composition API within Nuxt 2 applications. It extends the standard Composition API with Nuxt-specific features, enabling seamless integration with Nuxt's lifecycle and ecosystem.When running in production mode, any ref declared in the global state of your application (such as within Nuxt plugins or state/store files used as a Vuex replacement) is persisted across different user requests.
To avoid leaking data from one user request to another, do not declare reactive refs in the global scope of your application. Instead, ensure state is scoped to the request lifecycle (e.g., within a component or a function called during the request).
When setting up the module, keep the following in mind:
@vue/composition-api as a plugin. You do not need to enable it separately.@vue/composition-api methods and hooks directly from @nuxtjs/composition-api instead of installing the Vue package separately.script setup, follow the instructions for unplugin-vue2-script-setup to ensure better IDE auto-complete.If a route is not pre-generated (which includes running in dev mode), useStatic follows these rules:
nuxtState. This prevents the client from re-running the same API request. The result is cached between requests.In both scenarios, the return value of useStatic is a reactive ref that starts as null and is filled once the factory function or JSON fetch resolves.
When using nuxt build && nuxt generate --no-build to generate the whole app or specific routes, useStatic provides the following optimizations:
useStatic factory function is saved to a JSON file and copied into the /dist directory.Fallback Behavior: If the JSON file does not exist (e.g., the page was not pre-generated), the original factory function will execute on the client-side.
WARNING If you are pre-generating only specific pages, you may need to increase
generate.intervalin your Nuxt configuration.
The module provides several enhancements for using the Composition API in Nuxt:
router, app, and store directly within the setup() function.vue-meta properties within setup().ssrRef, a drop-in replacement for ref that handles automatic SSR stringification and hydration.<script setup> via unplugin-vue2-script-setup configuration.The module provides several key capabilities for Nuxt 2 developers:
fetch() hook (available in Nuxt v2.12+).router, app, and store directly within the setup() function.vue-meta properties from within setup().ssrRef, a drop-in replacement for ref that handles automatic SSR stringification and hydration.To ensure that reactive values match between the server and the client, ssrPromise requires a unique key.
@nuxtjs/composition-api/module to your Nuxt buildModules, a Babel plugin is automatically injected to handle key generation.ssrPromise call.@nuxtjs/composition-api/dist/babel-plugin to your Babel plugins configuration.Warning: Without a unique key, ssrPromise is only suitable for one-off operations. For repeated use, you must provide your own unique key to avoid collisions.
The useMeta() helper allows you to interact with Nuxt head properties directly within the setup() function or the onGlobalSetup method. This enables you to dynamically set or reactively update the page title and other meta tags using the Composition API.
To enable useMeta, you must satisfy two conditions:
head: {} object within your component definition.defineComponent function exported from @nuxtjs/composition-api instead of the standard Vue defineComponent.title from useMeta() and assign values to their .value property.useMeta() to set initial meta values.useMeta() that returns a meta object. This allows the head properties to react to changes in local state (e.g., a ref).import { defineComponent, useMeta, ref } from '@nuxtjs/composition-api'
export default defineComponent({
// Required to activate useMeta
head: {},
setup() {
// 1. Destructuring and direct assignment
const { title } = useMeta()
title.value = 'My page'
// 2. Providing an initial value
const { title: initialTitle } = useMeta({ title: 'My page' })
// 3. Setting multiple meta tags at once
useMeta({ title: 'My page' })
// 4. Using a function for reactive/computed meta
const message = ref('Hello')
useMeta(() => ({ title: message.value }))
},
})Several helper functions in @nuxtjs/composition-api—specifically shallowSsrRef, ssrPromise, ssrRef, and useAsync—use a key to pass JSON-encoded information from the server to the client. By default, the library generates a key based on the line number where the function is called.
If you use these functions inside a global composable, every call to that composable will share the same line number, causing them to share the same key. This results in state leakage where updating one instance affects all others. To prevent this, you must provide a unique key as the second optional parameter (e.g., using a route path) for every unique call.
// INCORRECT: Shared key due to same line number in global composable
function useMyFeature() {
const feature = ssrRef('')
return feature
}
const a = useMyFeature()
const b = useMyFeature()
b.value = 'changed'
// On client-side, a's value will also be initialized to 'changed'
// CORRECT: Providing a unique key (e.g., a path)
function useMyFeature(path: string) {
const content = useAsync(
() => fetch(`https://api.com/slug/${path}`).then(r => r.json()),
path // 'path' acts as the unique key
)
return {
content,
}
}@nuxtjs/composition-api to Nuxt Bridge if possible. You can follow the official Bridge migration guide to perform the upgrade.