TypeScript icon, indicating that this package has built-in type declarations

5.0.1 • Public • Published


Environment variables parser and validator used by the AdonisJS.

gh-workflow-image typescript-image npm-image license-image

Note: This package is framework agnostic and can also be used outside of AdonisJS.

The @adonisjs/env package encapsulates the workflow around loading, parsing, and validating environment variables.


Install the package from the npm packages registry as follows.

npm i @adonisjs/env

yarn add @adonisjs/env


The EnvLoader class is responsible for loading the environment variable files from the disk and returning their contents as a string.

import { EnvLoader } from '@adonisjs/env'

const lookupPath = new URL('./', import.meta.url)
const loader = new EnvLoader(lookupPath)

const envFiles = await loader.load()

The return value is an array of objects with following properties.

  • path: The path to the loaded dot-env file.
  • contents: The contents of the file.

Following is the list of loaded files. The array is ordered by the priority of the files. The first file has the highest priority and must override the variables from the last file.

Priority File name Environment Should I .gitignore it Notes
1st .env.[NODE_ENV].local Current environment Yes Loaded when NODE_ENV is set
2nd .env.local All Yes Loaded in all the environments except test or testing environments
3rd .env.[NODE_ENV] Current environment No Loaded when NODE_ENV is set
4th .env All Depends Loaded in all the environments. You should .gitignore it when storing secrets in this file


The EnvParser class is responsible for parsing the contents of the .env file(s) and converting them into an object.

import { EnvParser } from '@adonisjs/env'
const envParser = new EnvParser(`

console.log(envParser.parse()) // { PORT: '3000', HOST: 'localhost' }

The return value of parser.parse is an object with key-value pair. The parser also has support for interpolation.

By default, the parser prefers existing process.env values when they exist. However, you can instruct the parser to ignore existing process.env files as follows.

new EnvParser(envContents, { ignoreProcessEnv: true })

Validating environment variables

Once you have the parsed objects, you can optionally validate them against a pre-defined schema. We recommend validation for the following reasons.

  • Fail early if one or more environment variables are missing.
  • Cast values to specific data types.
  • Have type safety alongside runtime safety.
import { Env } from '@adonisjs/env'

const validator = Env.rules({
  PORT: Env.schema.number(),
  HOST: Env.schema.string({ format: 'host' })

The Env.schema is a reference to the @poppinss/validator-lite schema object. Make sure to go through the package README to view all the available methods and options.

The Env.rules method returns an instance of the validator to validate the environment variables. The return value is the validated object with type information inferred from the schema.


Complete example

Following is a complete example of loading dot-env files and validating them in one go.

Note: Existing process.env variables have the top most priority over the variables defined in any of the files.

import { Env } from '@adonisjs/env'

const env = await Env.create(new URL('./', import.meta.url), {
  PORT: Env.schema.number(),
  HOST: Env.schema.string({ format: 'host' })

env.get('PORT') // is a number
env.get('HOST') // is a string
env.get('NODE_ENV') // is unknown, hence a string or undefined

Env editor

The Env editor can be used to edit dot-env files and persist changes on disk. Only the .env and .env.example files are updated (if exists).

import { EnvEditor } from '@adonisjs/env/editor'

const editor = await EnvEditor.create(new URL('./', import.meta.url))
editor.add('PORT', 3000)
editor.add('HOST', 'localhost')

// Write changes on disk
await editor.save()

Known Exceptions


The exception is raised during environment variables validation exception. The exception is raised with Validation failed for one or more environment variables message.

You can access the detailed error messages using the error.cause property.

try {
} catch (error) {



Package Sidebar


npm i @adonisjs/env

Weekly Downloads






Unpacked Size

53.7 kB

Total Files


Last publish


  • julien-r44
  • romainlanz
  • virk