Installing and Using dotenv in TypeScript

Table of Contents#

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

Fundamental Concepts#

Environment Variables#

Environment variables are dynamic values that can affect the behavior of a running process. They are used to store configuration data such as API keys, database connection strings, and application secrets. By separating these values from the source code, you can keep sensitive information secure and easily change the configuration without modifying the code.

dotenv#

dotenv is a zero-dependency module that loads environment variables from a .env file into process.env. The .env file is a simple text file where each line represents a key-value pair in the format KEY=VALUE.

TypeScript#

TypeScript is a statically typed superset of JavaScript that compiles to plain JavaScript. It adds optional static typing to JavaScript, which helps catch errors early in the development process and improves code maintainability.

Installation#

Step 1: Create a TypeScript Project#

If you haven't already, create a new TypeScript project. You can use npm or yarn to initialize a new project:

mkdir typescript-dotenv-example
cd typescript-dotenv-example
npm init -y

Step 2: Install TypeScript and Related Dependencies#

Install TypeScript and the necessary type definitions:

npm install typescript @types/node --save-dev

Step 3: Initialize TypeScript Configuration#

Create a tsconfig.json file with the following command:

npx tsc --init

Step 4: Install dotenv#

Install the dotenv package:

npm install dotenv

Usage Methods#

Step 1: Create a .env File#

Create a .env file in the root directory of your project and add some environment variables:

DB_HOST=localhost
DB_PORT=5432
DB_USER=myuser
DB_PASSWORD=mypassword

Step 2: Load Environment Variables in TypeScript#

In your TypeScript file, import and configure dotenv at the top of the file:

import dotenv from 'dotenv';
 
// Load environment variables from .env file
dotenv.config();
 
// Access environment variables
const dbHost = process.env.DB_HOST;
const dbPort = process.env.DB_PORT;
const dbUser = process.env.DB_USER;
const dbPassword = process.env.DB_PASSWORD;
 
console.log(`Database Host: ${dbHost}`);
console.log(`Database Port: ${dbPort}`);
console.log(`Database User: ${dbUser}`);
console.log(`Database Password: ${dbPassword}`);

Step 3: Compile and Run the TypeScript Code#

Compile the TypeScript code to JavaScript using the tsc command:

npx tsc

Run the generated JavaScript code:

node dist/index.js

Common Practices#

Error Handling#

When accessing environment variables, it's important to handle the case where a variable is not defined. You can use optional chaining or provide default values:

import dotenv from 'dotenv';
 
dotenv.config();
 
const dbHost = process.env.DB_HOST || 'localhost';
const dbPort = process.env.DB_PORT ? parseInt(process.env.DB_PORT, 10) : 5432;
 
console.log(`Database Host: ${dbHost}`);
console.log(`Database Port: ${dbPort}`);

Using Type Assertions#

TypeScript doesn't know the exact type of environment variables, so you may need to use type assertions to specify the type:

import dotenv from 'dotenv';
 
dotenv.config();
 
const dbPort = parseInt(process.env.DB_PORT as string, 10);
console.log(`Database Port: ${dbPort}`);

Best Practices#

Keep .env Files Secure#

Never commit your .env file to version control. Add it to your .gitignore file to prevent sensitive information from being exposed:

.env

Use Different .env Files for Different Environments#

Create separate .env files for development, testing, and production environments. You can use a tool like cross-env to specify which .env file to use:

npm install cross-env --save-dev

{
  "scripts": {
    "start:dev": "cross-env NODE_ENV=development dotenv -e .env.development node dist/index.js",
    "start:prod": "cross-env NODE_ENV=production dotenv -e .env.production node dist/index.js"
  }
}

Validate Environment Variables#

Before using environment variables, validate them to ensure they have the correct format and values. You can use a library like joi for validation:

npm install joi

import dotenv from 'dotenv';
import Joi from 'joi';
 
dotenv.config();
 
const envSchema = Joi.object({
  DB_HOST: Joi.string().required(),
  DB_PORT: Joi.number().integer().required(),
  DB_USER: Joi.string().required(),
  DB_PASSWORD: Joi.string().required()
}).unknown();
 
const { error, value } = envSchema.validate(process.env);
 
if (error) {
  throw new Error(`Environment variable validation error: ${error.message}`);
}
 
const dbHost = value.DB_HOST;
const dbPort = value.DB_PORT;
const dbUser = value.DB_USER;
const dbPassword = value.DB_PASSWORD;
 
console.log(`Database Host: ${dbHost}`);
console.log(`Database Port: ${dbPort}`);
console.log(`Database User: ${dbUser}`);
console.log(`Database Password: ${dbPassword}`);

Conclusion#

Integrating dotenv with TypeScript is a straightforward process that allows you to manage environment variables effectively in your TypeScript projects. By following the steps outlined in this blog post, you can ensure type safety, handle errors, and implement best practices for managing environment variables. Remember to keep your .env files secure and validate your environment variables to prevent potential issues in your application.

References#

• dotenv npm package
• TypeScript Documentation
• Joi Validation Library
• cross-env npm package