> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nuxt/nuxt/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```ts nuxt.config.ts theme={null}
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.

<Note>
  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.
</Note>

### Environment Overrides

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

```ts nuxt.config.ts theme={null}
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:

```bash theme={null}
nuxt build --envName staging
```

<Note>
  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.
</Note>

### 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.

<CodeGroup>
  ```ts nuxt.config.ts theme={null}
  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',
      },
    },
  })
  ```

  ```ini .env theme={null}
  # This will override the value of apiSecret
  NUXT_API_SECRET=api_secret_token
  ```
</CodeGroup>

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

```vue app/pages/index.vue theme={null}
<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.

```ts app/app.config.ts theme={null}
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:

```vue app/pages/index.vue theme={null}
<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](https://nitro.build)      | ~~`nitro.config.ts`~~   | Use `nitro` key in `nuxt.config`   |
| [PostCSS](https://postcss.org)    | ~~`postcss.config.js`~~ | Use `postcss` key in `nuxt.config` |
| [Vite](https://vite.dev)          | ~~`vite.config.ts`~~    | Use `vite` key in `nuxt.config`    |
| [webpack](https://webpack.js.org) | ~~`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](https://www.typescriptlang.org) | `tsconfig.json`       | [More Info](https://nuxt.com/docs/4.x/directory-structure/tsconfig)           |
| [ESLint](https://eslint.org)                 | `eslint.config.js`    | [More Info](https://eslint.org/docs/latest/use/configure/configuration-files) |
| [Prettier](https://prettier.io)              | `prettier.config.js`  | [More Info](https://prettier.io/docs/configuration.html)                      |
| [Stylelint](https://stylelint.io)            | `stylelint.config.js` | [More Info](https://stylelint.io/user-guide/configure/)                       |
| [TailwindCSS](https://tailwindcss.com)       | `tailwind.config.js`  | [More Info](https://tailwindcss.nuxtjs.org/tailwindcss/configuration/)        |
| [Vitest](https://vitest.dev)                 | `vitest.config.ts`    | [More Info](https://vitest.dev/config/)                                       |

## 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`

```ts nuxt.config.ts theme={null}
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:

```ts nuxt.config.ts theme={null}
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:

```ts nuxt.config.ts theme={null}
export default defineNuxtConfig({
  vue: {
    propsDestructure: true,
  },
})
```

<Note>
  Since Nuxt 3.9 and Vue 3.4, `reactivityTransform` has been moved from Vue to Vue Macros which has a [Nuxt integration](https://vue-macros.dev/guide/nuxt-integration.html).
</Note>