3.configuration.md

Configuration

By default, Nuxt is configured to cover most use cases. The nuxt.config.ts file can override or extend this default configuration, and provide custom variables.

Nuxt configuration

The nuxt.config.ts file is located at the root of a Nuxt project and can override or extend the application's behavior.

A minimal configuration file exports the defineNuxtConfig function containing an object with your configuration. The defineNuxtConfig helper is globally available without import.

export default defineNuxtConfig({
  // My Nuxt config
})

This file will often be mentioned in the documentation, for example to add custom scripts, register modules or change rendering modes.

::alert{type=info} Every configuration option is described in the Configuration Reference. ::

::alert{type=info} You don't have to use Typescript to build an application with Nuxt. However, it is strongly recommended to use the .ts extension for the nuxt.config file. This way you can benefit from hints in your IDE to avoid typos and mistakes while editing your configuration. ::

Environment variables and private tokens

The runtimeConfig API exposes values like environment variables to the rest of your application. By default, these keys are only available server-side. The keys within runtimeConfig.public are also available client-side.

Those values can be overriden at build time or after by a .env file at the root of your project.

::code-group

export default defineNuxtConfig({
  runtimeConfig: {
    // The private keys which are only available server-side
    apiSecret: '123',
    // Keys within public are also exposed client-side
    public: {
      apiBase: '/api'
    }
  }
})

# This will override the value of apiSecret
NUXT_API_SECRET=api_secret_token

::

These variables are exposed to the rest of your application using the useRuntimeConfig composable.

<script setup>
const runtimeConfig = useRuntimeConfig()
</script>

:ReadMore{link="/guide/going-further/runtime-config"}

App configuration

The app.config.ts file, also located at the root of a Nuxt project, is used to expose public variables that can be determined at build time. Contrary to the runtimeConfig option, these can not be overriden using environment variables.

A minimal configuration file exports the defineAppConfig function containing an object with your configuration. The defineAppConfig helper is globally available without import.

defineAppConfig({
  title: 'Hello Nuxt'
  theme: {
    dark: true,
    colors: {
      primary: '#ff0000'
    }
  }
})

These variables are exposed to the rest of your application using the useAppConfig composable.

<script setup>
const appConfig = useAppConfig()
</script>

:ReadMore{link="/guide/directory-structure/app.config"}

runtimeConfig VS app.config

As stated above, runtimeConfig and app.config are both used to expose variables to the rest of your application. To determine wether you should use one or the other, here are some guidelines:

Usage

• app.config : Public tokens that are determined on build time, website configuration such as theme variant, title and any public project config that is determined on build time.
• runtime config: Private tokens or tokens that need to be specified after build using environment variables.

Pros and Cons

runtimeConfig

Pros	Cons
✅ Can be overriden with environement variables	❌ Adds to page load
✅ Fully dynamic for a server-deployment that needs to change config after build	❌ Only accepts JS primitive types
✅ Private tokens

app.config

Pros	Cons
✅ More efficient	❌ Cannot be overriden with environement variables
✅ Better typed	❌ Cannot be changed after build
✅ Any JS variable type