app.config use cases
app.config should be used for public tokens that are determined at build time, website configuration such as theme variant and title, and any project configuration that are not sensitive.
Nuxt · Getting started · all subjects
configuration
103 notes in this subject, read out of this brain and free to use. This is page 1 of 2.
External configuration files handled by Nuxt
Nuxt uses nuxt.config.ts as the single source of truth for configurations and skips reading external configuration files. Tool configurations should be specified within nuxt.config.ts using their respective keys: Nitro uses the nitro key, PostCSS uses the postcss key, Vite uses the vite key, and webpack uses the webpack key.
External configuration files not managed by Nuxt
Some common configuration files are not managed by Nuxt and should be created separately: TypeScript (tsconfig.json), ESLint (eslint.config.js), Prettier (prettier.config.js), Stylelint (stylelint.config.js), TailwindCSS (tailwind.config.js), and Vitest (vitest.config.ts).
Configure @vitejs/plugin-vue options
Options for @vitejs/plugin-vue can be passed in nuxt.config using the vite.vue key. Options for @vitejs/plugin-vue-jsx can be passed using the vite.vueJsx key.
Configure vue-loader with webpack
When using webpack, vue-loader options can be configured using the webpack.loaders.vue key inside nuxt.config.ts.
Enable experimental Vue features
Experimental Vue features can be enabled in nuxt.config.ts using the vue key. For example, propsDestructure can be enabled with vue: { propsDestructure: true }.
reactivityTransform migration in Vue 3.4 and Nuxt 3.9
Since Nuxt 3.9 and Vue 3.4, reactivityTransform has been moved from Vue to Vue Macros, which has a Nuxt integration available.
nuxt.config.ts location and purpose
The nuxt.config.ts file is located at the root of a Nuxt project and can override or extend the application's default configuration and behavior. It exports the defineNuxtConfig function containing an object with configuration options.
TypeScript recommended for nuxt.config
While Nuxt applications do not require TypeScript, it is strongly recommended to use the .ts extension for the nuxt.config file. This provides IDE hints to avoid typos and mistakes while editing the configuration.
Environment-specific overrides in nuxt.config
Environment overrides can be configured in nuxt.config using $production, $development, and $env keys with per-environment configuration. The environment name is selected when running Nuxt CLI commands using the --envName flag, for example: nuxt build --envName staging.
runtimeConfig for environment variables
The runtimeConfig API exposes values like environment variables to the application. Keys in runtimeConfig are only available server-side by default. Keys within runtimeConfig.public and runtimeConfig.app are available client-side. Values are defined in nuxt.config and can be overridden using environment variables following the pattern NUXT_<KEY_NAME>.
useRuntimeConfig composable
Runtime configuration values are exposed to the application using the useRuntimeConfig() composable, which is globally available without import.
app.config.ts location and purpose
The app.config.ts file is located in the source directory (by default app/) and is used to expose public variables that can be determined at build time. Unlike runtimeConfig, these variables cannot be overridden using environment variables.
defineAppConfig is globally available
The defineAppConfig helper is globally available without import and is used to export an object with application configuration in app.config.ts.
useAppConfig composable
Application configuration variables are exposed to the application using the useAppConfig() composable, which is globally available without import.
runtimeConfig vs app.config comparison table
runtimeConfig vs app.config feature comparison: runtimeConfig - Client-side: Hydrated, Environment variables: Yes, Reactive: Yes, Types support: Partial, Configuration per request: No, Hot module replacement: No, Non-primitive JS types: No. app.config - Client-side: Bundled, Environment variables: No, Reactive: Yes, Types support: Yes, Configuration per request: Yes, Hot module replacement: Yes, Non-primitive JS types: Yes.
runtimeConfig use cases
runtimeConfig should be used for private or public tokens that need to be specified after build using environment variables.
MetaObject interface for head configuration
The MetaObject interface has the following properties: title (string, optional), titleTemplate (string or function, optional), templateParams (object, optional), base (optional), link (array, optional), meta (array, optional), style (array, optional), script (array, optional), noscript (array, optional), htmlAttrs (optional), and bodyAttrs (optional). This interface is used for useHead, app.head, and components.
Reactive properties in useHead
Reactivity is supported on all properties in useHead by providing a computed value, a getter, or a reactive object. This allows dynamic updates to head tags like meta descriptions using refs.
titleTemplate function example
Example of titleTemplate as a function: useHead({ titleTemplate: (titleChunk) => { return titleChunk ? `${titleChunk} - Site Title` : 'Site Title' } }). If you set the title to 'My Page' on another page, the title would appear as 'My Page - Site Title' in the browser tab. You could also pass `null` to default to 'Site Title'.
titleTemplate option for dynamic title generation
You can use the `titleTemplate` option to provide a dynamic template for customizing the title of your site. The `titleTemplate` can either be a string, where `%s` is replaced with the title, or a function. If you want to use a function for full control, it cannot be set in `nuxt.config`. It is recommended to set it within your `app.vue` file where it will apply to all pages.
Favicon path resolution workaround with runtime config
Example of building favicon href from runtime config: <script setup lang="ts"> const { cdnURL, baseURL } = useRuntimeConfig().app useHead({ link: [{ rel: 'icon', type: 'image/x-icon', href: `${cdnURL || baseURL}favicon.ico` }] }) </script>
useSeoMeta with reactive description example
Example of reactive SEO meta with useSeoMeta: <script setup lang="ts"> const description = ref('My amazing site.') useSeoMeta({ description }) </script>
useHead with reactive description example
Example of reactive meta tags with useHead: <script setup lang="ts"> const description = ref('My amazing site.') useHead({ meta: [{ name: 'description', content: description }] }) </script>
useSeoMeta example with common properties
Example of using useSeoMeta: useSeoMeta({ title: 'My Amazing Site', ogTitle: 'My Amazing Site', description: 'This is my amazing site, let me tell you all about it.', ogDescription: 'This is my amazing site, let me tell you all about it.', ogImage: 'https://example.com/image.png', twitterCard: 'summary_large_image' })
Head components in template example
Example of using head components in a template: <script setup lang="ts"> const title = ref('Hello World') </script> <template> <div> <Head> <Title>{{ title }}</Title> <Meta name="description" :content="title" /> <Style> body { background-color: green; } </Style> </Head> <h1>{{ title }}</h1> </div> </template>
Overriding default charset and viewport in app.head
Example of updating Nuxt default meta tags: export default defineNuxtConfig({ app: { head: { charset: 'utf-16', viewport: 'width=device-width, initial-scale=1, maximum-scale=1' } } })
app.head configuration example
Example of configuring app.head in nuxt.config.ts: export default defineNuxtConfig({ app: { head: { title: 'Nuxt', htmlAttrs: { lang: 'en' }, link: [{ rel: 'icon', type: 'image/x-icon', href: '/favicon.ico' }] } } })
tagPosition option for script placement
You can use the `tagPosition: 'bodyClose'` option on applicable tags to append them to the end of the `<body>` tag. Valid options are: 'head', 'bodyClose', or 'bodyOpen'. Example: useHead({ script: [{ src: 'https://third-party-script.com', tagPosition: 'bodyClose' }] })
templateParams for additional title placeholders
You can use `templateParams` to provide additional placeholders in your `titleTemplate` besides the default `%s`. Example: useHead({ titleTemplate: (titleChunk) => { return titleChunk ? `${titleChunk} %separator %siteName` : '%siteName' }, templateParams: { siteName: 'Site Title', separator: '-' } })
app.head static configuration in nuxt.config.ts
You can provide an `app.head` property in your `nuxt.config.ts` to statically customize the head for your entire app. This method does not allow you to provide reactive data. It is good practice to set tags here that won't change such as your site title default, language, and favicon. Use `useHead()` in `app.vue` if you need reactive data.
Default meta tags in Nuxt
Nuxt provides two default meta tags by default: viewport set to 'width=device-width, initial-scale=1' and charset set to 'utf-8'. Most sites won't need to override these defaults, but you can update them using keyed shortcuts in `app.head`.
CDN URL and favicon static link limitation
When you set `app.cdnURL`, assets in the `public/` directory (including `favicon.ico`) are served from that CDN. Nuxt resolves public assets against `cdnURL`, falling back to `app.baseURL`. However, a static `app.head` link such as `href: '/favicon.ico'` is a literal path and is not resolved against `cdnURL`. To point the favicon at the resolved location, build the `href` from runtime config with `useHead()` in `app.vue`.
useHead composable for reactive head tags
The `useHead` composable function supports reactive input, allowing you to manage your head tags programmatically. It accepts properties like title, meta, bodyAttrs, and script. Example: useHead({ title: 'My App', meta: [{ name: 'description', content: 'My amazing site.' }], bodyAttrs: { class: 'test' }, script: [{ innerHTML: 'console.log(\'Hello world\')' }] })
useSeoMeta composable with type safety
The `useSeoMeta` composable lets you define your site's SEO meta tags as an object with full type safety. This helps you avoid typos and common mistakes, such as using `name` instead of `property`. Example properties include: title, ogTitle, description, ogDescription, ogImage, and twitterCard.
Head meta tag components in templates
Nuxt provides the following components for defining head tags in templates: `<Title>`, `<Base>`, `<NoScript>`, `<Style>`, `<Meta>`, `<Link>`, `<Body>`, `<Html>`, and `<Head>`. Note the capitalization of these components to ensure they don't use invalid native HTML tags. `<Head>` and `<Body>` can accept nested meta tags for aesthetic reasons, but this does not affect where the nested meta tags are rendered in the final HTML.
Head components and tag deduplication
It is suggested to wrap your head components in either a `<Head>` or `<Html>` component as tags will be deduped more intuitively. If you need to duplicate tags across client-server boundaries, apply a `key` attribute on the `<Head>` component.
Extending from layers using nuxt.config extends
You can extend from a layer by adding the extends property to your nuxt.config file. You can extend from a local layer using relative paths like '../base', from an installed npm package like '@my-themes/awesome', or from a git repository like 'github:my-themes/awesome#v1'.
Layer path alias forms
Both ~~/... (recommended) and ~/... alias forms as well as relative paths like ./layers/admin are supported for referencing layers in the extends configuration.
Authentication token for private GitHub repositories
When extending from a private GitHub repository, you can pass an authentication token using the auth property in the layer configuration: ['github:my-themes/private-awesome', { auth: process.env.GITHUB_TOKEN }].
Default branch for git layers
If a branch is not specified when extending from a git repository, Nuxt will clone the main branch by default.
Override layer alias in extends
You can override a layer's alias by specifying it in the options next to the layer source using the meta.name property: ['github:my-themes/awesome', { meta: { name: 'my-awesome-theme' } }].
Controlling layer priority via extends configuration
You can control the order of ~~/layers directories from nuxt.config by referencing them in extends, with the first entry having the highest priority. Any layer in ~~/layers not listed in extends keeps its alphabetical auto-scan order, ranked below the layers you explicitly list.
Extending from layers example
Example showing how to extend from multiple sources in nuxt.config.ts: export default defineNuxtConfig({ extends: [ // Extend from a local layer '../base', // Extend from an installed npm package '@my-themes/awesome', // Extend from a git repository 'github:my-themes/awesome#v1', ], })
Overriding layer alias example
Example showing how to override a layer's alias in nuxt.config.ts: export default defineNuxtConfig({ extends: [ [ 'github:my-themes/awesome', { meta: { name: 'my-awesome-theme', }, }, ], ], })
Controlling extends priority example
Example showing how to control ~~/layers directory priority from nuxt.config.ts: export default defineNuxtConfig({ extends: [ '~~/layers/admin', // highest priority '~~/layers/features', '~~/layers/base', // lowest priority (among the listed layers) ], })
experimental.payloadExtraction configuration options
The `experimental.payloadExtraction` option controls how payloads are handled: `'client'` - payload is inlined in HTML for initial render and extracted to `_payload.json` for client-side navigation (no extra request on first load); `true` - payload extracted to separate `_payload.json` for both initial render and navigation (smaller HTML, CDN cacheable, costs one extra request on first load); `false` - payload extraction disabled, always inlined in HTML. Default is `true`, or `'client'` when `compatibilityVersion: 5` is set. Forced to `false` when `ssr: false` is set.
Configure prerender with routeRules
Use `routeRules` in `nuxt.config.ts` to configure prerendering per route: set `prerender: true` to prerender a route, `prerender: false` to skip it, or use glob patterns like `/blog/**` to match multiple routes. Example: `export default defineNuxtConfig({ routeRules: { '/rss.xml': { prerender: true }, '/this-DOES-NOT-get-prerendered': { prerender: false }, '/blog/**': { prerender: true } } })`
Configure manual prerender routes with nitro.prerender
In `nuxt.config.ts`, use `nitro.prerender.routes` to manually specify routes Nitro will fetch and pre-render during build. Use `nitro.prerender.ignore` to exclude routes you don't want to pre-render. Example: `export default defineNuxtConfig({ nitro: { prerender: { routes: ['/user/1', '/user/2'], ignore: ['/dynamic'] } } })`
Combine crawlLinks with manual prerender routes
Use `nitro.prerender.crawlLinks: true` combined with `nitro.prerender.routes` to pre-render routes the crawler cannot discover automatically, such as `/sitemap.xml` or `/robots.txt`. Example: `export default defineNuxtConfig({ nitro: { prerender: { crawlLinks: true, routes: ['/sitemap.xml', '/robots.txt'] } } })`
defineRouteRules in page files for prerendering
Use `defineRouteRules({ prerender: true })` in the `<script setup>` block of a page file to configure prerendering at the page level. This feature is experimental and requires enabling `experimental.inlineRouteRules` option in `nuxt.config`.
E2E setup() timing options
setupTimeout: Milliseconds to allow setup to complete (number, default 120000 or 240000 on Windows); teardownTimeout: Milliseconds to allow teardown (number, default 30000)
E2E setup() Nuxt config options
rootDir: Path to Nuxt app (string, default '.'); configFile: Name of configuration file (string, default 'nuxt.config')
Built-in mock: indexedDB
indexedDB is a built-in mock for the DOM environment, defaulting to false. When enabled, it uses fake-indexeddb to create a functional mock of the IndexedDB API. Configure via environmentOptions.nuxt.mock.indexedDb in vitest.config.ts.
Built-in mock: intersectionObserver
intersectionObserver is a built-in mock for the DOM environment, defaulting to true. It creates a dummy class without functionality for the IntersectionObserver API. Configure via environmentOptions.nuxt.mock.intersectionObserver in vitest.config.ts.
Set environment variables for testing with .env.test
Create a .env.test file to set environment variables that will be used during testing.
E2E setup() browser options
browser: Launch browser for testing (boolean, default false); browserOptions: object with type ('chromium', 'firefox', or 'webkit') and launch (object of options passed to playwright.launch())
E2E setup() feature options: port and host
port: Set test server port (number | undefined, default undefined); host: URL to use as test target instead of building server (string, default undefined). Useful for running tests against deployed version or already-running local server.
@nuxt/test-utils/module adds Vitest integration to Nuxt DevTools
Add '@nuxt/test-utils/module' to the modules array in nuxt.config.ts to enable Vitest integration in Nuxt DevTools for running unit tests in development.
Vitest configuration requires type module in package.json
When importing @nuxt/test-utils in vitest config, the package.json must have "type": "module" specified, or rename the vitest config file to vitest.config.mts or vitest.config.mjs.