Getting Started

Manage environment variables professionally in your Thunder application using the built-in Env utility.

When developing any application, it is an excellent practice to manage environment variables in a clean and consistent manner. Thunder provides a first-class Env utility class that makes reading, listing, and checking environment variables straightforward - with both synchronous and asynchronous support out of the box.

Setting Up Environment Variables

Create a .env file at the root of your project. This file serves as the global environment configuration for your Thunder application:

.env

DATABASE_URL=mongodb://username:password@localhost:27017/my-db
ENV_TYPE=development
JWT_SECRET=your_super_secret_key

The .env file is automatically loaded by Thunder at startup. You do not need any additional configuration to enable this behaviour.

Never commit your .env file to version control. Add it to your .gitignore immediately to prevent accidental exposure of sensitive credentials.

Supported Env Files

Thunder loads multiple env files depending on the active environment, which lets you keep environment-specific overrides separate from your defaults:

File	When it's loaded
`.env`	Always loaded (default)
`.env.development`	Loaded in development
`.env.production`	Loaded in production
`.env.test`	Loaded in test

Reading Environment Variables

Thunder exposes the Env utility class to access your environment variables from anywhere in your application. Both synchronous and asynchronous methods are supported.

import { Env, EnvType } from "@/core/utils/env.ts";

Async Methods (with fallback support)

import { Env } from "@/core/utils/env.ts";

const dbUrl  = await Env.get("DATABASE_URL");       // string
const debug  = await Env.enabled("DEBUG");          // boolean
const port   = await Env.number("PORT");            // number
const hosts  = await Env.list("ALLOWED_HOSTS");     // string[]

Sync Methods (no fallback)

import { Env } from "@/core/utils/env.ts";

const dbUrl = Env.getSync("DATABASE_URL");
const debug = Env.enabledSync("DEBUG");

Silent Mode

By default, Env.get throws when a variable is missing. Pass true as the second argument to receive undefined instead of throwing:

const optional = await Env.get("OPTIONAL_VAR", true); // string | undefined

Checking the Current Environment

Use Env.is() together with the EnvType enum to branch on the active environment:

import { Env, EnvType } from "@/core/utils/env.ts";

if (Env.is(EnvType.DEVELOPMENT)) {
  // development-only logic
}

if (Env.is(EnvType.PRODUCTION)) {
  // production-only logic
}

API Reference

Method	Type	Description
`Env.get(key, silent?)`	`async`	Retrieves a variable. Pass `silent = true` to return `undefined` instead of throwing.
`Env.getSync(key)`	`sync`	Synchronously retrieves a variable (no fallback).
`Env.enabled(key)`	`async`	Returns the variable parsed as a boolean.
`Env.enabledSync(key)`	`sync`	Synchronous boolean variant.
`Env.number(key)`	`async`	Returns the variable parsed as a number.
`Env.list(key)`	`async`	Returns the variable parsed as a `string[]`.
`Env.is(type)`	`sync`	Returns `true` when the active environment matches the given `EnvType`.

Additional utility methods are available in @/core/utils/env.ts. You are encouraged to explore that file for the full API surface of the Env class.

Environment Variables

On this page