The Definitive Guide to Environment Variables in Nuxt 4

In this tutorial, we are going to set up different environmental variables in our Nuxt 4 project. Environmental variables are the key aspect of security. Nuxt provides a clean way to do so without rebuilding our apps for each existing variable change.

Creating .env files and defining the variables

Create the .env file in your root project directory. This is for local/default variables setup.

Note that the .env file must be git ignored for security reasons. Later in this article, we will show how to use these environment variables for deployment. We are using some sample variable examples.

bash

# Private keys (Server-side only)
NUXT_API_SECRET=secure_key
NUXT_BASE_URL=https://api.example.com

# Public keys (Available to Client & Server)
NUXT_PUBLIC_BASE_URL=https://api.example.com

Tips: Here, prefixing variables with NUXT_ will automatically map them to the configuration.

Configuring `nuxt.config.ts`

Let's configure those variables in our config file so that they can be accessible at runtime.

bash

export default defineNuxtConfig({
  runtimeConfig: {
    // Keys within here are only available server-side i.e nitro server
    apiSecret: '', // Can be overridden by NUXT_API_SECRET
    baseUrl: ''

    // Keys within public are available for both(Browser + Server)
    public: {
      baseUrl: '/default-api' // Can be overridden by NUXT_PUBLIC_BASE_URL
    }
  }
})

Here, values placed inside the public will be available for the browser, and the Nirto server, and the values outside of public will be available for the server only. Also note that the apiSecret will be overridden by our env file variable NUXT_API_SECRET.

Why use `runtimeConfig` over `process.env`?

process.env is static once the app is built, so we cannot change the variables with deployment. For different deployment providers, there will be options to set up these environmental variables. The changes in environment variables will not reflect in the app; it needs to be rebuilt.

runtimeConfig will allow changes to the values at runtime(i.e docker, pm2 deploy, cloudflare), which doesn't require a rebuild.

Implementation in our Code

In order to access those variables in our app code base, Nuxt provides the useRuntimeConfig() composiable.

In Vue Components

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

// Accessing public variables
console.log(config.public.baseUrl)

// Accessing private variables (Will be undefined on the client)
console.log(config.baseUrl) 
</script>

In Server Routes (Nitro)

export default defineEventHandler(async (event) => {
  const config = useRuntimeConfig();
  
  const response = await $fetch(`${config.baseUrl}/data`, {
    headers: { Authorization: `Bearer ${config.apiSecret}` }
  });

  return response;
});

Deployment and Production

While deploying our Nuxt app with a different provider, we need to set up these environment variables.

Set Up in Process Manager(PM2)

Deploying an app with pm2 with an environmental variable in production is a good way to secure your application. Here is the full tutorial on installing and setting up Process Manager(PM2) for Nuxt deployment.

Inside ecosystem.config.cjs we will be creating those variables.

module.exports = {
  apps: [
    {
      name: 'csbyte',
      port: '3000',
      exec_mode: 'cluster',
      instances: 'max',
      script: './.output/server/index.mjs',
      env: {
        NUXT_API_SECRET: 'prod_key_123',
        NUXT_BASE_URL: 'https://backend.csbyte.com'
        NUXT_PUBLIC_BASE_URL: 'https://csbyte.com'
      }
    }
  ]
}

For Cloudflare

Go to Workers & Pages > Select your Project > Settings > Variables and Secrets

Using Node Native Way

If you are deploying and running your app in a native way without using any providers, we need to be more careful with this.

Suppose you do have .env.production file and you wanna try to build with the native way:

bash

npx nuxi build --dotenv .env.production

This will not work with our current environment setup. i.e. Nuxt does read the .env.production file during the build process, but it will not update those values in the production server's execution memory.

So, while running the app(Runtime)

bash

node .output/server/index.mjs

It will use the fallback default values or undefined. Nuxt does this to support the cloud architecture (like Docker or pm2 and Cloudflare Workers), where a traditional filesystem .env file doesn't exist or shouldn't be hardcoded.

In order to work this, either we need to use process.env to update our Nuxt runtime config, which requires rebuilding for each config variable change(Not recommended), or explicitly supply the config file while running the app.

Here is the example for explicitly providing the runtime config file:

bash

node --env-file=.env.production .output/server/index.mjs

This will use the production environmental file and use the variables at runtime. This is a very good practice, so that we can securely add the files to the production server and prevent exposing the privacy to git or other development teams.

By utilizing runtimeConfig the NUXT_ prefix, we ensure that our Nuxt 4 application is secure, type-safe, and ready for any deployment environment and providers.

Creating .env files and defining the variables

Configuring nuxt.config.ts

Why use runtimeConfig over process.env?

Implementation in our Code

In Vue Components

In Server Routes (Nitro)

Deployment and Production

Set Up in Process Manager(PM2)

For Cloudflare

Using Node Native Way

Configuring `nuxt.config.ts`

Why use `runtimeConfig` over `process.env`?