tfdotenv

Load Terraform terraform.tfvars files into process.env as a side-effect import.

Overview

tfdotenv automatically loads variables from your Terraform terraform.tfvars file into Node.js process.env, making them available throughout your application. This eliminates the need to duplicate environment variables between your Terraform configuration and your Node.js application.

Features

• 🚀 Zero configuration - Just import and go
• 📁 Smart project detection - Automatically finds your project root
• 🔒 Conflict detection - Prevents overwriting existing environment variables
• 🏗️ Terraform syntax support - Handles HCL variable syntax including strings, numbers, booleans, objects, and arrays
• 📂 Subdirectory support - Works from any subdirectory within your project
• ⚡ Side-effect import - Loads variables immediately when imported

Installation

npm install tfdotenv

Usage

Basic Usage

Simply import the config module at the top of your application:

import "tfdotenv/config";

// Your terraform variables are now available in process.env
console.log(process.env.DATABASE_URL);
console.log(process.env.API_PORT);

Or with CommonJS:

require("tfdotenv/config");

// Your terraform variables are now available in process.env
console.log(process.env.DATABASE_URL);
console.log(process.env.API_PORT);

Project Structure

Your project should have the following structure:

your-project/
├── package.json
├── terraform/
│   └── terraform.tfvars
└── src/
    └── index.js

Example terraform.tfvars

# terraform/terraform.tfvars
DATABASE_URL = "postgresql://localhost:5432/mydb"
API_PORT = 3000
DEBUG_MODE = true
ENVIRONMENT = "development"
SECRET_KEY = "my-secret-key-123"
MAX_CONNECTIONS = 100

# Complex objects and arrays are also supported
database_config = {
  host = "localhost"
  port = 5432
  ssl = true
}

feature_flags = ["feature1", "feature2", "feature3"]

Example Usage

import "tfdotenv/config";
import express from "express";

const app = express();
const port = process.env.API_PORT || 3000;

app.get("/", (req, res) => {
  res.json({
    environment: process.env.ENVIRONMENT,
    debug: process.env.DEBUG_MODE === "true",
    database: process.env.DATABASE_URL,
  });
});

app.listen(port, () => {
  console.log(`Server running on port ${port}`);
});

How It Works

1. Project Root Detection: The module automatically finds your project root by looking for a package.json file, starting from the current working directory and traversing up the directory tree.

2. File Location: It looks for terraform/terraform.tfvars relative to your project root.

3. HCL Parsing: The Terraform HCL syntax is parsed using the hcl-to-json library, which converts Terraform variable syntax to JavaScript objects.

4. Environment Variable Injection: All variables from the tfvars file are injected into process.env as strings.

5. Conflict Prevention: If an environment variable with the same name already exists, the module throws an error to prevent accidental overwrites.

Variable Type Handling

All Terraform variables are converted to strings when loaded into process.env:

| Terraform Type | Example Value | process.env Value | | -------------- | ------------- | ------------------- | | String | "hello" | "hello" | | Number | 42 | "42" | | Boolean | true | "true" | | Object | {key="val"} | "[object Object]" | | Array | ["a", "b"] | "a,b" |

For complex objects and arrays, you may need to parse them:

import "tfdotenv/config";

// For objects, you might need to parse them differently
const dbConfig = JSON.parse(process.env.database_config.replace(/=/g, ":"));

// For arrays
const features = process.env.feature_flags.split(",");

Error Handling

The module will throw errors in the following cases:

1. Duplicate Environment Variables: If a variable from tfvars already exists in process.env

   Error: Environment variable "API_PORT" already defined

2. Invalid HCL Syntax: If the terraform.tfvars file contains invalid HCL syntax

   Error: Failed to load terraform variables: [parsing error details]

API

The module doesn't export any functions - it works purely as a side-effect import. Simply importing it will automatically load your Terraform variables.

Requirements

• Node.js 14 or higher
• A terraform/terraform.tfvars file in your project root
• A package.json file to identify your project root

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests (npm test)
5. Commit your changes (git commit -am 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Testing

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Watch mode
npm run test:watch

License

MIT

Related

• dotenv - Load environment variables from .env file
• Terraform - Infrastructure as Code tool