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 (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'
  },
  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. 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 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.

<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:

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.

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/schema' {
  interface PublicRuntimeConfig {
    testConfig: string
  }
  interface PrivateRuntimeConfig {
    token: string
  }
}
// It is always important to ensure you import/export something when augmenting a type
export {}

3.8 KiB Raw Blame History