Runtime Config
Nuxt provides a runtime config API to expose config within your application and server routes with the ability to update them at runtime using environment variables.
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 the runtimeConfig option.
Example:
nuxt.config.ts
export default defineNuxtConfig({
runtimeConfig: {
// The private keys which are only available within server-side
apiSecret: '123',
// Keys within public, will be also exposed to the client-side
public: {
apiBase: '/api'
}
}
})
When adding apiBase
to the runtimeConfig.public
, Nuxt adds it to each page payload. We can universally access apiBase
in both server and browser.
const runtimeConfig = useRuntimeConfig()
console.log(runtimeConfig.apiSecret)
console.log(runtimeConfig.public.apiBase)
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.
Runtime config values are automatically replaced by matching environment variables at runtime.
Example:
.env
NUXT_API_SECRET=api_secret_token
NUXT_PUBLIC_BASE_URL=https://nuxtjs.org
nuxt.config.ts
export default defineNuxtConfig({
runtimeConfig: {
apiSecret: '',
public: {
apiBase: '', // Or a default value
}
},
})
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 the client-side and server-side:
- On the client-side, only keys in
public
are available, and the object is both writable and reactive.
The entire runtime config is available on the server-side, but it is read-only to avoid context sharing.
<template>
<div>
<div>Check developer console!</div>
</div>
</template>
<script setup>
const config = useRuntimeConfig()
console.log('Runtime config:', config)
if (process.server) {
console.log('API secret:', config.apiSecret)
}
</script>
🛑 Security note: Be careful not to expose runtime config keys to the client-side by either rendering them or passing them to useState
.
👉
useRuntimeConfig
only works during setup
or Lifecycle Hooks
.
Plugins
If you want to use the runtime config within any (custom) plugin, you can use useRuntimeConfig()
inside of your defineNuxtPlugin
function.
For Example:
export default defineNuxtPlugin((nuxtApp) => {
const config = useRuntimeConfig()
console.log('API base URL:', config.public.apiBase)
});
Server Routes
You can access runtime config within the server routes as well using useRuntimeConfig
.
export default async () => {
const result = await $fetch('https://my.api.com/test', {
headers: {
Authorization: `Bearer ${useRuntimeConfig().apiSecret}`
}
})
return result
}
Manually Typing Runtime Config
Nuxt tries to automatically generate a typescript interface from provided runtime config using unjs/untyped
It is also possible to type your runtime config manually:
index.d.ts
declare module '@nuxt/schema' {
interface RuntimeConfig {
apiSecret: string
public: {
apiBase: string
}
}
}
// It is always important to ensure you import/export something when augmenting a type
export {}