Note: On the 18th of June 2020, Nuxt released v2.13 which includes Nuxt.js runtime config a new way of handling environment variables - This will be reflected in this post in due course.

What is a .env file?

A .env file or dotenv file is a simple text configuration file for controlling your Applications environment constants. Between Local, Staging and Production environments, the majority of your Application will not change. However in many Applications there are instances in which some configuration will need to be altered between environments. Common configuration changes between environments may include, but not limited to, URL's and API keys.

What do .env files look like?

.env files are line delimitated text files, meaning that each new line represents a single variable. By convention .env variable names are uppercase words separated by underscores. Variable names are followed directly by an = which, in turn is followed directly by the value, for example:

VARIABLE_NAME=value

How to use .env files in Nuxt

Install the dotenv module

To use .env files in Nuxt, you'll first need to install install the Nuxt dotenv module. To install the module, open your terminal and navigate to the root of your project. From the root of your project run the following command:

npm install @nuxtjs/dotenv

Register the dotenv module

Once the module has installed, you'll need to register it. To register the module, open your nuxt.config.js file and navigate to the buildModules array and add: @nuxtjs/dotenv like so:

buildModules: [
    '@nuxtjs/dotenv'
],

Create your .env file

Once you've registered your module, you can create your .env file. Open your project in your favourite code editor and in the root of your project create a new file called .env. Once the .env file is created, you're ready to create your first .env variable. Open the .env file and create a test variable:

TEST_VARIABLE=Hello world

NOTE: You will need to restart your Application to have access to your variables

Access your .env variables in your Application

Once you've successfully installed the dotenv module and created your .env file, referencing the variables in your Application is easy. To make sure your .env file is working as expected, open your Nuxt home page (/pages/index.vue) and create/ navigate to your mounted hook. Within the mounted hook, you'll want to console.log() your .env variable. To reference .env files you'll need the name of the variable you'd like to reference prefixed with process.env., for example:

mounted() {
    console.log(process.env.TEST_VARIABLE)
}

Upon mounting, your Application will log, Hello world to your console.

Customising your .env variable prefix

Not everyone likes the process.env. prefix, personally I choose to stick with this default, however if you'd prefer something different, it's straight forward to set that up in Nuxt. Begin by creating a new file in the root of your domain called env.js. Within this env.js file you'll want to export a object with key value pairs referencing your .env file variables. For example, in your .env you may have a number of Google API keys and ID's like so:

GOOGLE_MAPS_API_KEY=xxxxxxxxxxxxxx
GOOGLE_TAG_MANAGER_KEY=xxxxxxxxxxxxxx

You may then reference them in your env.js file like so:

export default {
    googleMapsApiKey: process.env.GOOGLE_MAPS_API_KEY,
    googleTagManagerKey: process.env.GOOGLE_TAG_MANAGER_KEY
}

Or if you'd prefer to organise your variables by groups, you may decide to create a google property group all of your Google keys together, like so:

export default {
    google: {
        mapsApiKey: process.env.GOOGLE_MAPS_API_KEY,
        tagManagerKey: process.env.GOOGLE_TAG_MANAGER_KEY
    }
}

To access your new env.js variables in your Nuxt application, simply import env.js your file and reference your variable, for example, should you want to log your mapsApiKey to the console on mount, you could do this:

<script>
    import ENV from '@/env'

    export default {
        mounted() {
            console.log(ENV.google.mapsApiKey)
        }
    }
</script>

Do NOT commit your .env file to Git

Your .env will likely contain sensitive information such as API secrets, database usernames and passwords, amongst other things and it's important to keep this information secure.

Adding .env to .gitignore

If you are using Git, find your .gitignore file and on a new line add .env, this will ensure Git does not store your .env file, keeping your sensitive information safe.

Identifying .env variables when .env is Git ignored

You might be asking: "If you ignore the .env, how will developers be aware of what .env files are necessary to run your Application?". Thankfully there's a simple solution, if you've chosen to create an env.js file, that may suffice, however it is common practice when using .env files to create a committable .env.example file. Your .env.example file should be an exact replica of your .env file but with blank variable values. This will allow developers pulling down fresh installations of your Application to quickly understand what variables are needed to begin working on your project.

If you don't want to copy your .env file manually you can generate it from your terminal by navigating to the root of your project and using the following command:
sed 's/=.*/=/' .env > .env.example

NOTE: If you're using Windows you may need to run the command through a terminal emulator like ConEmu

Conclusion

.env files are fantastic for environment specific variables and are a great way of protecting sensitive information, I highly recommend you consider using them in your next project.

If you’ve found this article useful, please follow me on Medium, Dev.to and/ or Twitter.