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

Runtime Config

Nuxt provides a runtime config API to share within App 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 publicRuntimeConfig or privateRuntimeConfig options. Based on whether you want it to be accessible on the client-side part of your app or not.

Example:

export default defineNuxtConfig({
 publicRuntimeConfig: {
   API_BASE: '/api'
 },
 privateRunimeConfig: {
   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 using Environment Variables. Nuxt CLI has built-in 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:

BASE_URL=https://nuxtjs.org
API_SECRET=api_secret_token

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 object is writable + reactive
• On Server-Side, both publicRuntimeConfig and privateRuntimeConfig are merged and object is readonly to avoid context sharing

<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 have to be still careful you do not expose such config to either payload or html!

API routes

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

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.

declare module '@nuxt/kit' {
  interface PublicRuntimeConfig {
    testConfig: string
  }
  interface PrivateRuntimeConfig {
    token: string
  }
}
// It is always important to ensure you import/export something when augmenting a type
export {}