useRuntimeConfig

Usage

<script setup lang="ts">
const config = useRuntimeConfig()
</script>

export default defineEventHandler((event) => {
  const config = useRuntimeConfig(event)
})

Define Runtime Config

The example below shows how to set a public API base URL and a secret API token that is only accessible on the server.

We should always define runtimeConfig variables inside nuxt.config.

export default defineNuxtConfig({
  runtimeConfig: {
    // Private keys are only available on the server
    apiSecret: '123',

    // Public keys that are exposed to the client
    public: {
      apiBase: process.env.NUXT_PUBLIC_API_BASE || '/api'
    }
  }
})

Access Runtime Config

To access runtime config, we can use useRuntimeConfig() composable:

export default defineEventHandler((event) => {
  const config = useRuntimeConfig(event)

  // Access public variables
  const result = await $fetch(`/test`, {
    baseURL: config.public.apiBase,
    headers: {
      // Access a private variable (only available on the server)
      Authorization: `Bearer ${config.apiSecret}`
    }
  })
  return result
}

In this example, since apiBase is defined within the public namespace, it is universally accessible on both server and client-side, while apiSecret is only accessible on the server-side.

Environment Variables

It is possible to update runtime config values using a matching environment variable name prefixed with NUXT_.

Using the .env File

We can set the environment variables inside the .env file to make them accessible during development and build/generate.

NUXT_PUBLIC_API_BASE = "https://api.localhost:5555"
NUXT_API_SECRET = "123"

app namespace

Nuxt uses app namespace in runtime-config with keys including baseURL and cdnURL. You can customize their values at runtime by setting environment variables.

app.baseURL

By default, the baseURL is set to '/'.

However, the baseURL can be updated at runtime by setting the NUXT_APP_BASE_URL as an environment variable.

Then, you can access this new base URL using config.app.baseURL:

export default defineNuxtPlugin((NuxtApp) => {
  const config = useRuntimeConfig()

  // Access baseURL universally
  const baseURL = config.app.baseURL
})

app.cdnURL

This example shows how to set a custom CDN url and access them using useRuntimeConfig().

You can use a custom CDN for serving static assets inside .output/public using the NUXT_APP_CDN_URL environment variable.

And then access the new CDN url using config.app.cdnURL.

export default defineEventHandler((event) => {
  const config = useRuntimeConfig(event)

  // Access cdnURL universally
  const cdnURL = config.app.cdnURL
})