Runtime Configs in Nuxt.js

Configuration management can be a pain. Find out how Nuxt seamlessly integrates your sensitive credentials and configuration into your projects.

Josh Deltener
May 7, 2021

Stay in the Nuxt loop!

Get notified when we release new tutorials, lessons, and other expert Nuxt content.

We all know that Nuxt has a config file called nuxt.config.js. But have you tried to access that file in components, or tried to fetch your own values? It can be challenging! What many people don't know is Nuxt actually has a built-in method of storing configs that not only separates public and private, but also exposes those configs automatically to your plugins, components, and pages.

They are called Runtime Configs, and they are pretty sweet. Nuxt has one property for public and another for private.

publicRuntimeConfig:{},
privateRuntimeConfig: {}

You have access to public configs in public (client) areas, and both public and private configs on the server. If a key is in both configs, then the private config will override the public one.

Learn Nuxt.js with the Mastering Nuxt course
See Course

How does Nuxt pull this off? It makes sure that when it builds the server bundles it includes both public and private configs and when it builds the client bundle it excludes the private configs. It also references .env files at runtime to allow overrides in both contexts (again making sure only the server bundles have access to the private configs)

This only makes sense when you use Server Side Rendering (universal mode). It's the only mode where server data is truly kept away from the browser.

Lets see what this looks like.

publicRuntimeConfig:{
    myApp:{
      publicTest: "public",
      bothTest: "public"

    }
  },
  privateRuntimeConfig:{
    myApp:{
      privateTest: "private",
      bothTest: "private",
    }
  },

These configurations are exposed through a global plugin called this.$config. We can see what these look like by adding a console.log to a created hook in a page.

created(){
  console.log(this.$config)
}

Here is the output from the terminal. Notice it contains both the public and private configs with the private one overwriting the value in the bothTest.

myApp: {
  publicTest: 'public',
  bothTest: 'private',
  privateTest: 'private'
}

Now let's check out the browser's console. This will show us the config that's exposed to the client.

Runtime Configs in Nuxt.js

Nice! The config client-side has no knowledge of the private config! Not only is our privateTest property not available, but the bothTest also only contains the public value just like we wanted.

Runtime configs have 1 more trick up their sleeve, they can even use .env files! All you have to do is use process.env.whatever and your value will be available in the config.

PRIVATE_VALUE="private env!"
privateRuntimeConfig:{
    myApp:{
      privateTest: process.env.PRIVATE_VALUE,
      bothTest: process.env.PRIVATE_VALUE,
    }
  },

Server-side, you can see these values are updates just as we expected.

myApp: {
  publicTest: 'public',
  bothTest: 'private env!',
  privateTest: 'private env!'
}

You may think this is some type of magic webpack substitution but that's not the case here! If you build your app then update the .env file, then start the app, it will still have the correct info!

Using .env files is really handy when you don't want your secrets inside of your version control system.

As you can see, the Nuxt configuration system is not only easy to use, but versatile as well.

Learn Nuxt.js with the Mastering Nuxt course
See Course
Josh Deltener
Josh is a true Nuxt Master. He has over 30 years of development experience and currently works as director of front-end technology at RealTruck. He is also a Nuxt ambassador and contributor.