Built-in Composables
Relevant source files
The following files were used as context for generating this wiki page:
Built-in composables in Nuxt are auto-imported functions available throughout the application to manage state, handle data fetching, manipulate the document head, and interface with routing. These composables are designed to be SSR-friendly, ensuring that data is synchronized between the server and the client during hydration.
Sources: packages/schema/src/types/schema.ts:133-137, README.md:15-20
Data Fetching Composables
Nuxt provides several composables for fetching data from APIs or internal server routes. These functions handle the serialization of data from the server to the client to avoid duplicate requests during hydration.
useFetch and useAsyncData
useFetch is the most common way to fetch data. it is a wrapper around useAsyncData and $fetch. useAsyncData provides more control by accepting a custom handler function. Both support options like pick (to narrow returned keys), transform (to modify data), and default (to provide a fallback value).
Sources: packages/schema/src/types/schema.ts:1145-1153, test/fixtures/basic-types/app/app-types.ts:168-175, test/fixtures/basic-types/app/app-types.ts:544-555
$fetch
Unlike the composables, $fetch is a global helper for making network requests. In a server context, Nuxt proxies internal $fetch calls directly to the Nitro engine to avoid external HTTP overhead.
Sources: packages/nuxt/src/core/templates.ts:404-420, test/fixtures/basic-types/app/app-types.ts:74-78
Data Fetching Flow
The following diagram illustrates how Nuxt synchronizes data between server and client using these composables.
This flow ensures that data fetched during Server-Side Rendering (SSR) is immediately available to the client components.
Sources: packages/nuxt/src/core/templates.ts:311-316, packages/schema/src/types/schema.ts:1010-1014
State Management and Configuration
useState
useState creates a reactive state that is shared across components and preserved during SSR. It is an SSR-friendly alternative to ref() for global state.
Sources: packages/schema/src/types/schema.ts:1115-1120, test/fixtures/basic-types/app/app-types.ts:602-604
useRuntimeConfig and useAppConfig
- useRuntimeConfig: Accesses configuration defined in
nuxt.config. It supports private keys (server-only) and public keys (available to client). - useAppConfig: Accesses the reactive
app.configwhich is mainly for UI-related configuration.
Sources: packages/nuxt/src/core/templates.ts:311-320, packages/nuxt/src/core/templates.ts:377-385, test/fixtures/basic-types/app/app-types.ts:446-455
SEO and Head Management
useHead and useSeoMeta
Nuxt uses these composables to interact with the document head. useHead allows setting titles, scripts, styles, and meta tags. useSeoMeta is a specialized, flatter API for SEO tags.
Sources: packages/nuxt/src/app/components/welcome.vue:15-25, test/fixtures/basic/app/pages/index.vue:135-154, test/fixtures/basic-types/app/app-types.ts:468-475
| Composable | Description | Parameters |
|---|---|---|
useHead | Sets full head metadata | HeadObject, UseHeadOptions |
useSeoMeta | Specialized SEO tag management | SeoConfig |
Sources: packages/schema/src/types/schema.ts:153-170, test/fixtures/basic-types/app/app-types.ts:468-480
Routing and Navigation
useRoute and useRouter
- useRoute: Returns the current route object, containing params, query, and metadata.
- useRouter: Returns the router instance for programmatic navigation (e.g.,
router.push).
Sources: packages/nuxt/src/pages/module.ts:241-245, test/fixtures/basic-types/app/app-types.ts:317-325
definePageMeta
A macro used within pages to define metadata like layouts, middleware, and route validation. Nuxt extracts this information at build-time to configure the router.
Sources: packages/nuxt/src/pages/module.ts:21-25, packages/nuxt/src/pages/module.ts:664-670, test/fixtures/basic/app/pages/index.vue:163-168
Browser and Client Utilities
useCookie
useCookie provides a reactive interface to browser cookies. On the server, it reads/writes from request/response headers. It supports options like maxAge, expires, and httpOnly.
Sources: packages/schema/src/types/schema.ts:1091-1095, test/fixtures/basic-types/app/app-types.ts:532-535
useId
A utility to generate unique, SSR-safe IDs that match between the server and the client to avoid hydration mismatches.
Sources: [test/fixtures/basic-types/app/app-types.ts:1100-1110] (Implicit via common Nuxt API in type testing environment)
Summary of Configuration Options
Composables can be configured globally in nuxt.config.ts under the experimental.defaults section.
| Option Path | Type | Default | Description |
|---|---|---|---|
defaults.useAsyncData.deep | boolean | false | Whether to deeply watch sources in useAsyncData |
defaults.useState.resetOnClear | boolean | false (v4), true (v5) | If true, clearNuxtState resets to initial value |
defaults.useFetch.retry | number | Default retry attempts for fetch calls |