Understanding and Resolving `dotenv` and TypeScript `undefined` Issues

In modern web development, environment variables play a crucial role in keeping sensitive information like API keys, database credentials, and configuration settings separate from the source code. dotenv is a popular Node.js package that loads environment variables from a .env file into process.env. TypeScript, on the other hand, is a typed superset of JavaScript that adds static type checking, enhancing code reliability and maintainability. However, when using dotenv with TypeScript, developers often encounter the issue of undefined values, which can lead to runtime errors. This blog post aims to explore the fundamental concepts behind this problem, provide usage methods, common practices, and best practices to help you handle these issues effectively.

Table of Contents#

  1. Fundamental Concepts
  2. Usage Methods
  3. Common Practices
  4. Best Practices
  5. Conclusion
  6. References

Fundamental Concepts#

dotenv#

dotenv is a zero-dependency module that loads environment variables from a .env file into process.env. A .env file typically contains key-value pairs, for example:

API_KEY=your_api_key
DB_USER=db_user
DB_PASSWORD=db_password

To use dotenv in a Node.js project, you need to install it first:

npm install dotenv

Then, in your JavaScript or TypeScript file, you can load the environment variables as follows:

import dotenv from 'dotenv';
dotenv.config();
 
// Access an environment variable
const apiKey = process.env.API_KEY;
console.log(apiKey);

TypeScript and undefined#

TypeScript is statically typed, which means it requires you to define the types of variables. When you access process.env in TypeScript, the type of process.env is NodeJS.ProcessEnv, which has a type definition like this:

interface ProcessEnv {
  [key: string]: string | undefined;
}

This means that any environment variable accessed through process.env can be either a string or undefined. If the corresponding environment variable is not set in the .env file or the environment, TypeScript will correctly infer its type as undefined.

Usage Methods#

Basic Usage#

  1. Install dotenv: 
    npm install dotenv
  2. Create a .env file: Create a .env file in the root directory of your project and add your environment variables: 
    PORT=3000
  3. Load dotenv in your TypeScript file: 
    import dotenv from 'dotenv';
dotenv.config();
 
const port = process.env.PORT;
console.log(port);

Typing Environment Variables#

To avoid dealing with undefined issues, you can create a custom type for your environment variables. For example:

import dotenv from 'dotenv';
dotenv.config();
 
// Define a custom type for environment variables
type CustomEnv = {
  PORT: string;
};
 
// Assert that process.env has the custom type
const env = process.env as CustomEnv;
 
const port = env.PORT;
console.log(port);

Common Practices#

Checking for undefined#

Before using an environment variable, it's a good practice to check if it's undefined. For example:

import dotenv from 'dotenv';
dotenv.config();
 
const apiKey = process.env.API_KEY;
if (apiKey === undefined) {
  throw new Error('API_KEY is not set in the environment.');
}
 
// Now you can safely use apiKey
console.log(apiKey);

Using Default Values#

You can provide default values for environment variables in case they are not set. For example:

import dotenv from 'dotenv';
dotenv.config();
 
const port = process.env.PORT || '3000';
console.log(port);

Best Practices#

Centralized Environment Variable Management#

Create a separate module to manage your environment variables. This makes it easier to handle and type-check them.

env.ts:

import dotenv from 'dotenv';
dotenv.config();
 
// Define a custom type for environment variables
type CustomEnv = {
  PORT: string;
  API_KEY: string;
};
 
// Assert that process.env has the custom type
const env = process.env as CustomEnv;
 
// Function to get environment variables with validation
const getEnv = (key: keyof CustomEnv): string => {
  const value = env[key];
  if (value === undefined) {
    throw new Error(`Environment variable ${key} is not set.`);
  }
  return value;
};
 
export const PORT = getEnv('PORT');
export const API_KEY = getEnv('API_KEY');

app.ts:

import { PORT, API_KEY } from './env';
 
console.log(PORT, API_KEY);

Use Environment Variables in Production#

In production, it's recommended to set environment variables directly in the deployment environment rather than relying solely on the .env file. For example, in a Docker container, you can set environment variables using the ENV instruction in the Dockerfile or the -e flag when running the container.

Conclusion#

Using dotenv with TypeScript can be tricky due to the undefined issue. However, by understanding the fundamental concepts, following the usage methods, common practices, and best practices outlined in this blog post, you can effectively manage environment variables in your TypeScript projects. Always remember to check for undefined values, provide default values when necessary, and centralize your environment variable management for better code organization and maintainability.

References#

2025-10