Nuxt/docs/content/3.docs/1.usage/5.runtime-config.md

# Runtime Config

Nuxt provides an API to define the runtime config within your application and API routes.

## Exposing runtime config

To expose config and environment variables to the rest of your app, you will need to define runtime configuration in your `nuxt.config` file, using either the [`privateRuntimeConfig` or `publicRuntimeConfig` options](/docs/directory-structure/nuxt.config#privateruntimeconfig) (based on whether you want it to be accessible on the client-side part of your app or not).

**Example:**

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  publicRuntimeConfig: {
    API_BASE: '/api'
  },
  privateRuntimeConfig: {
    API_SECRET: '123'
  }
})
```

When adding `API_BASE` to the `publicRuntimeConfig`, Nuxt adds it to the pages' payload. This way we can universally access `API_BASE` in both server and browser.

### Environment Variables

The most common way to provide configuration is by using [Environment Variables](https://medium.com/chingu/an-introduction-to-environment-variables-and-how-to-use-them-f602f66d15fa).
Nuxt CLI has built-in [dotenv](https://github.com/motdotla/dotenv) support.

In addition to any process environment variables, if you have a `.env` file in your project root directory, it will be automatically loaded into `process.env` and accessible within your `nuxt.config` file and modules.

**Example:**

```sh [.env]
BASE_URL=https://nuxtjs.org
API_SECRET=api_secret_token
```

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  publicRuntimeConfig: {
    BASE_URL: process.env.BASE_URL
  },
  privateRuntimeConfig: {
    API_SECRET: process.env.API_SECRET
  }
})
```

**💡 Tip:** While it is not necessary, by using identical runtime config names as env variables, you can easily override them in production using platform environment variables.

## Accessing runtime config

### Vue app

Within the Vue part of your Nuxt app, you will need to call `useRuntimeConfig()` to access the runtime config.

**Note:** Behavior is different between client side and server side:

- On client side, only `publicRuntimeConfig` is available and the object is both writable and reactive.
- On server side, both `publicRuntimeConfig` and `privateRuntimeConfig` are merged and the object is read-only to avoid context sharing.

```vue
<template>
  <div>
    <div>Token: {{ config.API_AUTH_TOKEN }}</div>
  </div>
</template>

<script setup>
const config = useRuntimeConfig()
</script>
```

**🛑 Security note:** Never use example above if `API_AUTH_TOKEN` is a private config. Even if you use `privateRuntimeConfig`, you still have to be careful that you do not expose such config to either payload or html!

::alert{icon=👉}
**`useRuntimeConfig` only works during `setup` or `Lifecycle Hooks`**.
::

### Plugins

If you want to use the runtime confg within any (custom) plugin, you can use `useRuntimeConfig()` inside of your `defineNuxtPlugin` function.

For example:

```ts
export default defineNuxtPlugin((nuxtApp) => {
  const config = useRuntimeConfig();

  const url = process.server ? config.serverUrl : config.clientUrl;
  
  // Do something with url & isServer.
});
```

### API routes

Within the API routes, you can access runtime config by directly importing from virtual `#config`.

```ts
import config from '#config'

export default async () => {
  const result = await $fetch('https://my.api.com/test', {
    headers: {
      Authorization: `Bearer ${config.API_AUTH_TOKEN}`
    }
  })
  return result
}
```

### Typing runtime config

Currently it is possible to manually type your runtime config.

```ts [index.d.ts]
declare module '@nuxt/schema' {
  interface PublicRuntimeConfig {
    testConfig: string
  }
  interface PrivateRuntimeConfig {
    token: string
  }
}
// It is always important to ensure you import/export something when augmenting a type
export {}
```