From JSON to Environment Variables: Introducing json-to-env-converter

Neenus Gabriel — Tue, 24 Dec 2024 05:25:31 +0000

Hi there! This is my first-ever article (so go easy on me in the comments 🤣). I’m excited to share a little project I’ve been working on which came out of a personal need. If you’ve ever wrestled with managing configurations in your Node.js application, you might find this small zero dependency package interesting. It’s called json-to-env-converter.

What is json-to-env-converter?

json-to-env-converter is an npm package that converts JSON objects into environment variables. It’s a lightweight tool designed to help you handle JSON-based configurations by converting them into environment variables and injecting it into process.env; it's intended for scenarios where configurations might be dynamic, nested, or sourced from APIs or external systems.

Here’s the idea: Instead of manually setting environment variables for complex or dynamic configurations, you can programmatically load them from a JSON object and access them just like any other environment variable.

Why Did I Build It?

I've recently built a secrets api and for every project that I'm personally working on; I'm calling my secrets api to get my config at runtime which is provided in json format. Also not to mention in modern and large apps config can change depending on the user location, or other dynamic factors. While .env files are great for static setups, they don’t easily handle:

Nested structures: Flattening nested JSON into environment variables can get tedious.
Dynamic sources: Loading configurations at runtime without restarting the app isn’t straightforward.

I built json-to-env-converter to explore a way to address these issues once again it was more of project for personal use and it’s definitely not meant to replace tools like dotenv, but rather to handle a slightly different use case; and I thought what's the harm in making it open source and publishing it publicly on npm and I would be so happy if anyone found use of it.

How It Works

Install the package from npm:

npm i json-to-env-converter

Here’s a simple example to show what it does:

Basic Example

import { jsonToEnv } from 'json-to-env-converter';

const config = {
  database: {
    host: 'localhost',
    port: 5432,
  },
};

jsonToEnv(config);

console.log(process.env.DATABASE_HOST); //Output: 'localhost'
console.log(process.env.DATABASE_PORT); //Output: '5432'

This takes a JSON object and converts it into environment variables. It also flattens nested keys, so database.host becomes DATABASE_HOST.

Adding a Prefix

To avoid collisions, you can add a prefix:

jsonToEnv(config, { prefix: 'MYAPP_' });

console.log(process.env.MYAPP_DATABASE_HOST); //Output: 'localhost'

A Use Case: Dynamic Configurations

One potential use case for this package is handling dynamic configurations. For example, imagine you have a global application that fetches region-specific settings at runtime. Instead of manually managing .env files for each region, you could dynamically load the right settings based on the user’s location:

const regionConfig = {
  us: {
    dbHost: 'us-db.example.com',
    apiUrl: 'https://api.us.example.com',
  },
  eu: {
    dbHost: 'eu-db.example.com',
    apiUrl: 'https://api.eu.example.com',
  },
};

const region = 'us'; // This could come from a runtime check
jsonToEnv(regionConfig[region], { prefix: 'APP_' });

console.log(process.env.APP_DBHOST); // Output: 'us-db.example.com'

This allows your app to adapt its configuration without requiring a restart or hardcoded values.

**Available Options
The jsonToEnv function accepts an optional options object with the following properties:

prefix: A string to add a prefix to the environment variable names (default: '').
envFile: A boolean to enable or disable the creation of the .env file (default: false); if enabled and the file already exists, it will be overwritten.
envFileName: A string to specify the name of the .env file (default: .env).
envFilePath: A string to specify the path where the .env file should be created (default: .).

Should You Use It?

Honestly, I’m still deciding on how broadly useful this package might be. If you’re already comfortable with .env files and static configs, you might not need this tool. But if you’re working with:

Dynamic environments where configs change at runtime
Nested JSON objects that need to be converted into flat environment variables
Programmatic configuration setups sourced from APIs or external services

and not happy with your current setup then json-to-env-converter might save you some time and worth a try.

Installation and Feedback

If you’re curious to give it a try, you can install it from npm:

npm i json-to-env-converter

I’d love to hear your thoughts, feedback, or most importantly suggestions for improvement so feel free to mention in the comments here or submit pull requests on my github repo https://github.com/neenus/json-to-env. This is a learning experience for me, and I’m excited to see where it goes.

Oh and one more thing... thanks for reading my first article!

DEV Community: Neenus Gabriel

From JSON to Environment Variables: Introducing json-to-env-converter