Runtime Config

Nuxt.js supports env config to provide configuration via process.env. This is done by webpack's DefinePlugin.

This approach had two downsides:

  • Values are read during build time and persisted into webpack bundle. So for a change to process.env we need to rebuild which is against 12factor app design
  • It can easily mislead to expose secret keys to client-side bundle

You can learn more about why we are moving from @nuxtjs/dotenv to runtime config.

Runtime Config (2.13+)

Two new options added to nuxt.config to allow passing runtime configuration which is then accessible using context $config.

Config is added to Nuxt payload (__NUXT__.config) so there is no need to rebuild to update runtime configuration. SSR, SPA, and Static targets supported with an exception that for static target, a regenerate is necessary.

export default {
  publicRuntimeConfig: {},
  privateRuntimeConfig: {}
  • publicRuntimeConfig is available using $config in both server and client.
  • privateRuntimeConfig is only available on server using same $config (it overrides publicRuntimeConfig)


$config is available anywhere from context (including pages, store and plugins)

export default {
  asyncData ({ $config: { baseURL } }) {
  mounted() {

.env support

If you have .env file in project root directory, it will be automatically loaded using dotenv and is accessible via process.env.

process.env is updated so we can use it right inside nuxt.config for runtime config. Values are interpolated and expanded with an improved version of dotenv-expand.

.env file is also watched to reload during nuxt dev. You can customize the env path by using --dotenv <file> or disabling with --dotenv false.

Expand/Interpolation Support

Supported both for dotenv and runtime config.

Expand for runtime config happens only if there is already a key (see API_SECRET example).

Interpolation allows easy nesting env vars (see baseURL example).




export default {
  publicRuntimeConfig: {
    baseURL: process.env.BASE_URL
  privateRuntimeConfig: {
    baseURL: '${PUBLIC_URL}${BASE_URL}',
    API_SECRET: '${API_SECRET}' // similar to using process.env.API_SECRET

Note, it is possible to use a function for publicRuntimeConfig and privateRuntimeConfig but not recommended.

Caught a mistake or want to contribute to the documentation? Edit this page on GitHub!

Platinum Sponsors

Storyblok Support Us