Skip to main content
The Env module re-exports all functionality from @adonisjs/env, providing type-safe environment variable management with validation schemas.

​
Import

import { Env } from '@adonisjs/core/env'
import type { EnvParser, EnvEditor } from '@adonisjs/core/env'

​
Overview

The Env module provides classes and utilities for managing environment variables with type safety and validation. It ensures that your application has all required environment variables with the correct types before startup.

​
Classes

​
Env

The main environment variable management class with built-in validation.

​
Static Methods

create
Creates a new Env instance with validation schema.
​
appRoot
URL
required
The root directory URL of your application (typically new URL('../', import.meta.url))
​
schema
object
required
An object defining validation rules for environment variables using Env.schema methods
​
return
Promise<Env>
A promise that resolves to an Env instance with validated environment variables
const env = await Env.create(new URL('../', import.meta.url), {
  NODE_ENV: Env.schema.enum(['development', 'production', 'test'] as const),
  PORT: Env.schema.number(),
  HOST: Env.schema.string({ format: 'host' }),
  APP_KEY: Env.schema.string()
})

​
Instance Methods

get
Retrieves a validated environment variable value.
​
key
string
required
The environment variable name
​
return
any
The validated and type-cast environment variable value
const port = env.get('PORT') // Returns number
const nodeEnv = env.get('NODE_ENV') // Returns 'development' | 'production' | 'test'

​
Validation Schema

​
Env.schema

Provides validation methods for different types of environment variables.

​
string

Validates a string environment variable.
​
options
object
Optional configuration object
​
format
string
Format validation: ‘url’, ‘host’, ‘email’, etc.
​
choices
string[]
Allowed string values
APP_NAME: Env.schema.string()
APP_URL: Env.schema.string({ format: 'url' })
HOST: Env.schema.string({ format: 'host' })

​
number

Validates a number environment variable.
​
options
object
Optional configuration object
PORT: Env.schema.number()
MAX_CONNECTIONS: Env.schema.number()

​
boolean

Validates a boolean environment variable.
​
options
object
Optional configuration object
DEBUG: Env.schema.boolean()
ENABLE_CACHE: Env.schema.boolean()

​
enum

Validates an enum environment variable with allowed values.
​
choices
array
required
Array of allowed values (use as const for TypeScript literal types)
NODE_ENV: Env.schema.enum(['development', 'production', 'test'] as const)
LOG_LEVEL: Env.schema.enum(['debug', 'info', 'warn', 'error'] as const)

​
Types

​
EnvParser

Type for the environment parser instance. 
type EnvParser = {
  get<K extends string>(key: K): any
  // Additional parser methods
}

​
EnvEditor

Type for editing environment files programmatically. 
type EnvEditor = {
  set(key: string, value: string): void
  unset(key: string): void
  // Additional editor methods
}

​
Example Usage

import { Env } from '@adonisjs/core/env'

// Define and validate environment variables
const env = await Env.create(new URL('../', import.meta.url), {
  NODE_ENV: Env.schema.enum(['development', 'production', 'test'] as const),
  PORT: Env.schema.number(),
  HOST: Env.schema.string({ format: 'host' }),
  APP_KEY: Env.schema.string(),
  DATABASE_URL: Env.schema.string({ format: 'url' }),
  DEBUG: Env.schema.boolean(),
  LOG_LEVEL: Env.schema.enum(['debug', 'info', 'warn', 'error'] as const)
})

// Access validated variables with type safety
const port = env.get('PORT') // number
const host = env.get('HOST') // string
const isDebug = env.get('DEBUG') // boolean
const nodeEnv = env.get('NODE_ENV') // 'development' | 'production' | 'test'

​
Notes

  • Environment variables are validated at application startup
  • Validation failures prevent the application from starting
  • Type information is preserved for better IDE autocomplete
  • Environment files (.env) are automatically loaded from the app root
  • The Env instance is typically available via dependency injection in your application