---
navigation.icon: IconFile
title: app.config.ts
head.title: 'app.config.ts'
description: Nuxt 3 provides the app.config file to expose reactive configuration within your application.
---

# App Config File

Nuxt 3 provides an `app.config` config file to expose reactive configuration within your application with the ability to update it at runtime within lifecycle or using a nuxt plugin and editing it with HMR (hot-module-replacement).

You can easily provide runtime app configuration using `app.config.ts` file. It can have either of `.ts`, `.js`, or `.mjs` extensions.

```ts [app.config.ts]
export default defineAppConfig({
  foo: 'bar'
})
```

::alert{type=warning}
Do not put any secret values inside `app.config` file. It is exposed to the user client bundle.
::

## Defining App Config

To expose config and environment variables to the rest of your app, you will need to define configuration in `app.config` file.

**Example:**

```ts [app.config.ts]
export default defineAppConfig({
  theme: {
    primaryColor: '#ababab'
  }
})
```

When adding `theme` to the `app.config`, Nuxt uses Vite or webpack to bundle the code. We can universally access `theme` both when server-rendering the page and in the browser using [useAppConfig](/docs/api/composables/use-app-config) composable.

```js
const appConfig = useAppConfig()

console.log(appConfig.theme)
```

### Manually Typing App Config

Nuxt tries to automatically generate a TypeScript interface from provided app config.

It is also possible to type app config manually. There are two possible things you might want to type.

#### Typing App Config Input

`AppConfigInput` might be used by module authors who are declaring what valid _input_ options are when setting app config. This will not affect the type of `useAppConfig()`.

```ts [index.d.ts]
declare module 'nuxt/schema' {
  interface AppConfigInput {
    /** Theme configuration */
    theme?: {
      /** Primary app color */
      primaryColor?: string
    }
  }
}

// It is always important to ensure you import/export something when augmenting a type
export {}
```

#### Typing App Config Output

If you want to type the result of calling `useAppConfig()`, then you will want to extend `AppConfig`.

::alert{type=warning}
Be careful when typing `AppConfig` as you will overwrite the types Nuxt infers from your actually defined app config.
::

```ts [index.d.ts]
declare module 'nuxt/schema' {
  interface AppConfig {
    // This will entirely replace the existing inferred `theme` property
    theme: {
      // You might want to type this value to add more specific types than Nuxt can infer,
      // such as string literal types
      primaryColor?: 'red' | 'blue'
    }
  }
}

// It is always important to ensure you import/export something when augmenting a type
export {}
```

### App Config Merging Strategy in Layers

Nuxt uses a custom merging strategy for the `AppConfig` within the layers of your application.
This strategy is implemented using a [Function Merger](https://github.com/unjs/defu#function-merger), which allows defining a custom merging strategy for every key in `app.config` that has an array as value.

::alert{type=warning}
The Function Merger should only be used in the base `app.config` of your application.
::

Here's an example of how you can use:

::code-group

```ts [layer/app.config.ts]
export default defineAppConfig({
  // Default array value
  array: ['hello'],
})
```

```ts [app.config.ts]
export default defineAppConfig({
  // Overwrite default array value by using a merger function
  array: () => ['bonjour'],
})
```

::