useAsyncData avoids double fetching during SSR
When doing server-side rendering, wrapping a custom $fetch instance with useAsyncData avoids double data fetching that would occur on both the server and client during hydration.
general-reference
388 notes in this subject, read out of this brain and free to use. This is page 3 of 7.
$fetch is a configured instance of ofetch
$fetch is a configured instance of ofetch which supports adding the base URL of your Nuxt server as well as direct function calls during SSR, avoiding HTTP roundtrips.
Custom useFetch example with JWT authentication
export const useAPI = createUseFetch({ baseURL: 'https://api.nuxt.com', onRequest ({ options }) { const { session } = useUserSession() if (session.value?.token) { options.headers.set('Authorization', `Bearer ${session.value.token}`) } }, async onResponseError ({ response }) { if (response.status === 401) { await navigateTo('/login') } }, }) This creates a custom useAPI composable that automatically includes the auth header and handles 401 redirects.
Creating a custom useFetch composable with createUseFetch
You can create a custom fetcher by calling createUseFetch with configuration options like baseURL, onRequest, and onResponseError handlers. This allows you to set default options for fetching from your API without modifying the global $fetch behavior.
$fetch is not globally configurable
The $fetch utility function is intentionally not globally configurable. This design choice ensures that fetching behavior throughout the application remains consistent and allows other integrations like modules to reliably depend on the behavior of core utilities like $fetch.
Example: Custom history mode with memory history
import type { RouterConfig } from '@nuxt/schema' import { createMemoryHistory } from 'vue-router' export default { // https://router.vuejs.org/api/interfaces/routeroptions history: base => import.meta.client ? createMemoryHistory(base) : null, /* default */ } satisfies RouterConfig
Example: Custom routes in router.options.ts
import type { RouterConfig } from '@nuxt/schema' export default { // https://router.vuejs.org/api/interfaces/routeroptions#routes routes: _routes => [ { name: 'home', path: '/', component: () => import('~/pages/home.vue'), }, ], } satisfies RouterConfig
Example: Smooth scroll behavior configuration
export default defineNuxtConfig({ router: { options: { scrollBehaviorType: 'smooth', }, }, })
Example: Adding router options file via pages:routerOptions hook
import { createResolver } from '@nuxt/kit' export default defineNuxtConfig({ hooks: { 'pages:routerOptions' ({ files }) { const resolver = createResolver(import.meta.url) // add a route files.push({ path: resolver.resolve('./runtime/router-options'), optional: true, }) }, }, })
Example: Using pages:extend hook to add and remove routes
import type { NuxtPage } from '@nuxt/schema' export default defineNuxtConfig({ hooks: { 'pages:extend' (pages) { // add a route pages.push({ name: 'profile', path: '/profile', file: '~/extra-pages/profile.vue', }) // remove routes function removePagesMatching (pattern: RegExp, pages: NuxtPage[] = []) { const pagesToRemove: NuxtPage[] = [] for (const page of pages) { if (page.file && pattern.test(page.file)) { pagesToRemove.push(page) } else { removePagesMatching(pattern, page.children) } } for (const page of pagesToRemove) { pages.splice(pages.indexOf(page), 1) } } removePagesMatching(/\.ts$/, pages) }, }, })
Case-sensitive routing with compatibility version 5
With future.compatibilityVersion: 5, routing is case-sensitive by default to match Nitro. To make routing case-insensitive, set router.options.sensitive to false.
pages:routerOptions hook for adding router options files
You can add more router options files using the pages:routerOptions hook. The hook receives an object with a files array. Files pushed to this array override earlier ones. Setting optional: true will only apply the file when page-based routing is already enabled, otherwise it switches on page-based routing.
Custom history mode via router.options function
You can optionally override history mode by defining a history function in router.options.ts that accepts the base URL and returns a history mode. If it returns null or undefined, Nuxt will fallback to the default history.
JSON serializable router options in nuxt.config
Only JSON serializable router options can be configured in nuxt.config: linkActiveClass, linkExactActiveClass, end, sensitive, strict, hashMode, and scrollBehaviorType.
pages:extend hook for modifying scanned routes
The pages:extend nuxt hook allows you to add, change, or remove pages from the scanned routes at build time. This hook is called with a pages array parameter that can be modified directly.
router.options routes do not inherit definePageMeta
When returning custom routes from the routes function in router.options.ts, Nuxt will not augment those routes with metadata defined in definePageMeta of the component. To preserve definePageMeta metadata, use the pages:extend hook instead.
Custom routes via router.options.ts routes function
You can override or extend routes by defining a routes function in router.options.ts that accepts the scanned routes and returns customized routes. If the function returns null or undefined, Nuxt will fall back to default routes.
Router options file location
Router options should be specified in a file at app/router.options.ts. This is the recommended way to customize router options. The file should export a default object that satisfies the RouterConfig type.
Smooth scroll behavior for hash links
You can enable smooth scroll behavior for hash links by setting router.options.scrollBehaviorType to 'smooth' in nuxt.config. When enabled, the browser will smoothly scroll to anchor targets when navigating to hash links.
Inspect custom events in Nuxt DevTools
Custom events can be inspected using the Nuxt DevTools Hooks panel.
Two-way event communication example
Example showing two-way communication: nuxtApp.hook('app:user:registered', (payload) => { payload.message = 'Welcome to our app!' }); const payload = { id: 1, name: 'John Doe' }; await nuxtApp.callHook('app:user:registered', payload); // payload.message will be 'Welcome to our app!'
Emit custom event example
Example: const nuxtApp = useNuxtApp(); await nuxtApp.callHook('app:user:registered', { id: 1, name: 'John Doe', });
Create custom event listener example
Example: const nuxtApp = useNuxtApp(); nuxtApp.hook('app:user:registered', (payload) => { console.log('A new user has registered!', payload) });
Two-way communication via event payload
Event payloads are passed by reference, allowing listeners to modify the payload object to send data back to the emitter. Changes made to the payload by listeners are accessible to the emitter after callHook returns.
Emit events with callHook
Events are emitted using the callHook method on nuxtApp. The syntax is await nuxtApp.callHook('event:name', payload), which notifies all listeners registered for that event.
Create custom events with hook method
Custom events are created using the hook method on nuxtApp. The syntax is nuxtApp.hook('event:name', (payload) => {}), where the payload is passed to all listeners of that event.
Nuxt event system powered by hookable
The Nuxt event system is powered by unjs/hookable, which is the same library that powers the Nuxt hooks system.
multiApp future feature for multi-app support
The future.multiApp option enables early access to experimental multi-app support in Nuxt. Progress can be followed via tracker issue #21635 on the Nuxt GitHub repository.
devLogs feature for streaming server logs
The devLogs feature streams server logs to the client during development. These logs can be handled in the dev:ssr-logs hook. It is enabled by default in development (when test mode is not active). If set to 'silent', the logs will not be printed to the browser console. It can be configured in nuxt.config.ts under features.devLogs.
compatibilityVersion for opting into Nuxt v5 behavior
The future.compatibilityVersion option enables early access to Nuxt features or flags. Setting compatibilityVersion to 5 changes defaults throughout the Nuxt configuration to opt in to Nuxt v5 behaviour, including enabling the Vite Environment API. This is configured in nuxt.config.ts under future.compatibilityVersion.
inlineStyles feature for inlining CSS in HTML
The inlineStyles feature inlines styles when rendering HTML and is currently available only when using Vite. You can pass a function that receives the path of a Vue component and returns a boolean indicating whether to inline the styles for that component. The default behavior is defined by the function (id) => id.includes('.vue'). It can be configured in nuxt.config.ts under features.inlineStyles and can be set to false or a function.
Production Build Output Independence
When building an application for production, nuxt build generates a standalone build in the .output directory that is independent of nuxt.config and Nuxt modules.
Extending Build Context vs Runtime Context
nuxt.config and Nuxt modules are used to extend the build context. Nuxt Plugins are used to extend the runtime context.
Runtime Context vs Build Context Isolation
Nuxt builds and bundles projects using Node.js but also has a runtime side. The runtime context is isolated from build-time and they are not supposed to share state, code, or context other than runtime configuration.
useNuxtApp vs tryUseNuxtApp
useNuxtApp() throws an exception if context is currently unavailable. If your composable does not always require nuxtApp, use tryUseNuxtApp() instead, which will return null instead of throwing an exception.
NuxtApp Interface - Runtime Core
When rendering a page in the browser or on the server, a shared context called nuxtApp is created. This context keeps the Vue instance, runtime hooks, and internal states like ssrContext and payload for hydration. It serves as the Runtime Core and can be accessed using the useNuxtApp() composable within Nuxt plugins and <script setup> and Vue composables.
Nuxt Interface - Builder Core
When you start Nuxt in development mode with nuxt dev or build a production application with nuxt build, a common context called nuxt is created internally. It holds normalized options merged with the nuxt.config file, some internal state, and a hooking system powered by unjs/hookable that allows different components to communicate with each other. This context is globally available through Nuxt Kit composables, and only one instance of Nuxt is allowed to run per process.
NuxtApp Interface Properties
The NuxtApp interface has the following properties: vueApp (the global Vue application), versions (an object containing Nuxt and Vue versions), hooks/hook/callHook (for calling and adding runtime NuxtApp hooks), ssrContext (only accessible on server-side, containing url, req, res, runtimeConfig, noSSR), payload (stringified and passed from server to client, containing serverRendered, data, and state), and provide (a function to provide name and value).
Runtime config example with environment variables
Example setup: Define runtimeConfig in nuxt.config.ts with apiSecret and public.apiBase properties. Override values using NUXT_API_SECRET and NUXT_PUBLIC_API_BASE environment variables. In .env file: NUXT_API_SECRET=api_secret_token and NUXT_PUBLIC_API_BASE=https://nuxtjs.org.
Using runtime config in server routes
Runtime config can be accessed in server routes using useRuntimeConfig(), allowing server routes to access both public and private configuration values.
Defining runtime config to environment variable mapping
Runtime config values must be defined in nuxt.config to ensure that arbitrary environment variables are not exposed to application code. Setting runtime config defaults to differently-named environment variables will only work during build-time and will break at runtime.
Environment variables in development vs runtime
The Nuxt CLI has built-in support for reading .env files during development, build, and generate. However, when you run your built server, the .env file will not be read, so environment variables must be set in the runtime environment.
Environment variable type casting
Environment variable values are automatically cast to their JavaScript type using destr. For example, NUXT_MY_VAR=4848e0 becomes the number 4848. To keep a value as a string, the environment variable value must contain literal double quotes. In a .env file, write NUXT_MY_VAR='"4848e0"'; when setting the variable directly in a shell or Dockerfile, ensure quotes are part of the value and not stripped by the shell.
Environment variable override naming convention
Runtime config values are automatically replaced by matching environment variables at runtime. Environment variable names must be uppercase, start with NUXT_, and use underscores to separate keys and indicate case changes. For example, runtimeConfig.apiSecret is overridden by NUXT_API_SECRET, and runtimeConfig.public.apiBase is overridden by NUXT_PUBLIC_API_BASE.
Public runtime config in Vue templates
Public runtime config is accessible in Vue templates using $config.public syntax, providing direct access without calling useRuntimeConfig().
Accessing runtime config with useRuntimeConfig
Runtime config is accessed using the useRuntimeConfig() composable. On client-side, only keys in runtimeConfig.public and runtimeConfig.app are available and the object is writable and reactive. On server-side, the entire runtime config is available but is read-only to prevent context sharing.
Runtime config definition in nuxt.config
Runtime configuration is defined in the nuxt.config file using the runtimeConfig option. Private keys are only available server-side, while keys within the public object are also exposed to the client-side.
Runtime config serialization restriction
Runtime config will be serialized before being passed to Nitro. Non-serializable items such as functions, Sets, and Maps should not be set in nuxt.config. Instead, place such code in a Nuxt or Nitro plugin or middleware.
Security warning for runtime config
Do not expose runtime config keys to the client-side by rendering them or passing them to useState, as this creates a security risk.
Using Nuxt CLI nightly version
To try the latest version of nuxt/cli from the nightly channel, use the command: npx @nuxt/cli-nightly@latest [command]
Nightly release regression risk
There is a slight chance of regressions in nightly releases not being caught during the review process and by automated tests. Therefore, Nuxt internally uses the nightly channel to double-check everything before each release.
Nightly release channel purpose
The nightly release channel allows testing Nuxt built directly from the latest commits to the repository before the next release. These releases are used to beta test new features and changes.
Latest nightly tracks Nuxt v4 with breaking changes
The latest nightly release channel is currently tracking the Nuxt v4 branch and is particularly likely to have breaking changes. To use 3.x branch nightly releases instead, opt in with nuxt@npm:nuxt-nightly@3x.
Nightly release channel automated publishing
After a commit is merged into the main branch of nuxt/nuxt and passes all tests, an automated npm release is triggered using GitHub Actions. Nightly releases use the same build and publishing method and quality standards as stable releases.
How to opt out of nightly releases
To opt out of nightly releases, update the nuxt dependency in package.json to a specific stable version like "nuxt": "^4.0.0", then remove the lockfile (package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lock or bun.lockb) and reinstall dependencies.
Nuxt hooking system powered by unjs/hookable
The Nuxt hooking system is powered by the unjs/hookable library.
Three types of Nuxt hooks: build-time, app runtime, and server runtime
Nuxt provides three main types of hooks: Nuxt Hooks which are available at build time for modules and build context, App Hooks which run at runtime and are used by plugins and composables for rendering lifecycle, and Server Hooks which run at runtime for server plugins to hook into Nitro's runtime behavior.
Server Hooks in server plugins
Server Hooks are runtime hooks available for server plugins to hook into Nitro's runtime behavior. They are accessed via nitroApp.hooks.hook() in a server plugin defined with definePlugin from nitro. Example shows hooking into 'render:html' and 'render:response' hooks to modify HTML rendering and server responses.
Nuxt Hooks defined in nuxt.config.ts
Nuxt Hooks can be defined in the nuxt.config.ts file using the hooks object. Example: export default defineNuxtConfig({ hooks: { close: () => { } } })
Custom hook definition using TypeScript module augmentation
Custom hooks can be added by extending Nuxt's hook interfaces using TypeScript module augmentation. Three interfaces can be extended: RuntimeNuxtHooks for custom app runtime hooks, NuxtHooks for custom build-time hooks (both declared in module '#app'), and NitroRuntimeHooks for custom server runtime hooks (declared in module 'nitro/types'). Each hook must return HookResult for runtime hooks or void for Nitro hooks.