Configuration

Nuxt is configured with sensible defaults to make you productive.

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

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.

nuxt.config.ts

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.

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 Overrides

You can configure fully typed, per-environment overrides in your nuxt.config:

nuxt.config.ts

export default defineNuxtConfig({
  $production: {
    routeRules: {
      '/**': { isr: true },
    },
  },
  $development: {
    //
  },
  $env: {
    staging: {
      //
    },
  },
})

To select an environment when running a Nuxt CLI command, simply pass the name to the --envName flag:

nuxt build --envName staging

If you’re authoring layers, you can also use the $meta key to provide metadata that you or the consumers of your layer might use.

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 and runtimeConfig.app (which is used by Nuxt internally) are also available client-side.

Those values should be defined in nuxt.config and can be overridden using environment variables.

nuxt.config.ts

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',
    },
  },
})

These variables are exposed to the rest of your application using the useRuntimeConfig() composable:

app/pages/index.vue

<script setup lang="ts">
const runtimeConfig = useRuntimeConfig()
</script>

App Configuration

The app.config.ts file, located in the source directory (by default app/), is used to expose public variables that can be determined at build time. Contrary to the runtimeConfig option, these cannot be overridden 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.

app/app.config.ts

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

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

app/pages/index.vue

<script setup lang="ts">
const appConfig = useAppConfig()
</script>

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 whether you should use one or the other, here are some guidelines:

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

Feature	runtimeConfig	app.config
Client-side	Hydrated	Bundled
Environment variables	✅ Yes	❌ No
Reactive	✅ Yes	✅ Yes
Types support	✅ Partial	✅ Yes
Configuration per request	❌ No	✅ Yes
Hot module replacement	❌ No	✅ Yes
Non-primitive JS types	❌ No	✅ Yes

External Configuration Files

Nuxt uses nuxt.config.ts file as the single source of truth for configurations and skips reading external configuration files. During the course of building your project, you may have a need to configure those. The following table highlights common configurations and, where applicable, how they can be configured with Nuxt.

Name	Config File	How To Configure
Nitro	nitro.config.ts	Use nitro key in nuxt.config
PostCSS	postcss.config.js	Use postcss key in nuxt.config
Vite	vite.config.ts	Use vite key in nuxt.config
webpack	webpack.config.ts	Use webpack key in nuxt.config

Here is a list of other common config files:

Name	Config File	How To Configure
TypeScript	tsconfig.json	More Info
ESLint	eslint.config.js	More Info
Prettier	prettier.config.js	More Info
Stylelint	stylelint.config.js	More Info
TailwindCSS	tailwind.config.js	More Info
Vitest	vitest.config.ts	More Info

Vue Configuration

With Vite

If you need to pass options to @vitejs/plugin-vue or @vitejs/plugin-vue-jsx, you can do this in your nuxt.config file:

• vite.vue for @vitejs/plugin-vue
• vite.vueJsx for @vitejs/plugin-vue-jsx

nuxt.config.ts

export default defineNuxtConfig({
  vite: {
    vue: {
      customElement: true,
    },
    vueJsx: {
      mergeProps: true,
    },
  },
})

With webpack

If you use webpack and need to configure vue-loader, you can do this using webpack.loaders.vue key inside your nuxt.config file:

nuxt.config.ts

export default defineNuxtConfig({
  webpack: {
    loaders: {
      vue: {
        hotReload: true,
      },
    },
  },
})

Enabling Experimental Vue Features

You may need to enable experimental features in Vue, such as propsDestructure. Nuxt provides an easy way to do that in nuxt.config.ts, no matter which builder you’re using:

nuxt.config.ts

export default defineNuxtConfig({
  vue: {
    propsDestructure: true,
  },
})

Since Nuxt 3.9 and Vue 3.4, reactivityTransform has been moved from Vue to Vue Macros which has a Nuxt integration.