The problem with dotenv that nobody talks about, and how I fixed it with kq-config.

The Problem

Every Node.js project I've worked on has the same setup:

DB_PASS=supersecret
SECRET_KEY=myjwtsecret
API_URL=http://localhost:3000
THEME=dark
PORT=3000

One .env file. Everything in one place. Server secrets, client settings, database passwords, all mixed together.

This works fine until we think: who can see what?

Your frontend code runs process.env.API_URL, works fine. But what stops it from also reading process.env.DB_PASS? In most setups, nothing. The same object holds everything.

I kept thinking: why do we give everyone access to everything?

The Idea

What if your config file had separate blocks: one for the server, one for the client, and each side could only read its own?

config.kq
├── ::shared     → merged into both
├── ::server     → server only
└── ::client     → client only

Server reads ::server. Client reads ::client. Neither can see the other's block.

I built this as an npm package called kq-config. The .kq extension stands for Konfig Query, and comes from the first and last letters of my name, Kanishq.

What it looks like

Create a single config.kq file:

@version = 1.0

::shared
  app_name = MyApp
  version  = 1.0
::end

::server
  host       = localhost
  port       = 3000
  db_host    = localhost
  db_name    = mydb
  db_user    = $ENV:DB_USER
  db_pass    = $ENV:DB_PASS
  secret_key = $ENV:SECRET_KEY
  debug      = true
  log_level  = info
::end

::client
  api_url = http://localhost:3000
  theme   = dark
  timeout = 5000
  retry   = 3
::end

Then in your code:

const { KQParser } = require("kq-config");
const path = require("path");

// Server reads ::shared + ::server only
const server = new KQParser(
  path.join(__dirname, "config.kq"),
  "server"
).load();

console.log(server.get("port"));    // 3000
console.log(server.get("db_pass")); // "supersecret" (from .env)

// Client reads ::shared + ::client only
const client = new KQParser(
  path.join(__dirname, "config.kq"),
  "client"
).load();

console.log(client.get("api_url")); // "http://localhost:3000"
console.log(client.get("db_pass")); // undefined, client can NEVER see this

The database password is invisible to the client. Not hidden by convention but blocked by design.

Note: add .env in the same path for DB_USER,DB_PASS,SECRET_KEY

Built-in .env support, no dotenv needed

kq-config automatically finds and loads .env from the same folder as your config.kq file. You don't need to install or configure dotenv:

your-project/
├── config.kq
└── .env        ← loaded automatically

// No require("dotenv").config() needed
const server = new KQParser("config.kq", "server").load();
// $ENV: variables resolved from .env automatically

Environment overrides

Create config.prod.kq with only what changes in production:

::server
  host      = 0.0.0.0
  port      = 8080
  db_host   = prod-db.example.com
  debug     = false
  log_level = warn
::end

::client
  api_url = https://api.example.com
::end

Load it based on APP_ENV:

const env = process.env.APP_ENV || "development";

const overrides = {
  production: "config.prod.kq",
  staging:    "config.staging.kq",
};

const overrideFile = overrides[env]
  ? path.join(__dirname, overrides[env])
  : null;

const server = new KQParser("config.kq", "server", overrideFile).load();

node server.js                    # development → port 3000
set APP_ENV=production&node server.js # cmd:production  → port 8080
$env:APP_ENV="production"; node server.js # powershell:production  → port 8080

Schema validation

Validate your config at startup. Fail immediately with clear errors instead of mysterious crashes later:

const server = new KQParser("config.kq", "server")
  .load()
  .validate({
    host:       { type: "string",  required: true },
    port:       { type: "number",  required: true },
    secret_key: { type: "string",  required: true },
    debug:      { type: "boolean", required: false, default: false },
    log_level:  { type: "string",  required: false, default: "info" },
  });

If anything is wrong, you get all errors at once:

KQValidationError: Config validation failed for role 'server':
  ✗ Required key 'secret_key' is missing in [server] config.
  ✗ 'port' — expected number, got string (value: "3000")

Runtime overrides

Override any value without touching any file:

$env:KQ_SERVER_PORT=9999; node server.js
$env:KQ_CLIENT_THEME="light"; node server.js

Pattern: KQ_<ROLE>_<KEY>=value. Values are automatically type-cast.

AES-256-GCM encryption — built in

This is where it gets interesting. You can store encrypted secrets directly in your config file:

Step 1 : Generate a master key:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
# 3a7bd3e2360a3d29eea436fcfb7e44c735d117c7888a8660b1e5c8c51b9ff59f

Step 2 : Encrypt your secrets:

const { KQParser } = require("kq-config");

process.env.KQ_MASTER_KEY = "3a7bd3e2...";
const enc = KQParser.encrypt("mysupersecretpassword");
// → ENC:aGVsbG8gd29ybGQ=:abc123:xyz456

Step 3 : Put it in config.kq:

::server
  db_pass = ENC:aGVsbG8gd29ybGQ=:abc123:xyz456
::end

Step 4 : Load as normal — decryption is automatic:

const server = new KQParser("config.kq", "server").load();
server.get("db_pass"); // "mysupersecretpassword" 

Even if someone gets your config.kq — they cannot read the secrets without KQ_MASTER_KEY.

Secret masking

Prevent secrets from leaking into logs:

server.all();       // { port: 3000, db_pass: "supersecret" }
server.all(true);   // { port: 3000, db_pass: "***MASKED***" } 

// Or always mask
new KQParser("config.kq", "server", null, { mask: true })

Auto type casting

Everything from a config file is a string — but kq-config automatically casts types:

So server.get("port") gives you a real number, not "3000".

Security protections built in

kq-config has professional-grade security with zero extra configuration:

• Path traversal — ../../etc/passwd attacks blocked
• Prototype pollution — __proto__, constructor keys blocked
• ReDoS — values over 10,000 chars rejected
• Memory exhaustion — files over 1MB rejected
• Null byte injection — null bytes in values blocked
• Env hijacking — .env cannot overwrite NODE_OPTIONS, PATH etc.
• Zero dependencies — no supply chain attack surface

- npm provenance — every release cryptographically signed

TypeScript support

Full type definitions included:

import { KQParser, KQSchema, KQOptions } from "kq-config";

const schema: KQSchema = {
  port:  { type: "number", required: true },
  debug: { type: "boolean", required: false, default: false },
};

const server = new KQParser("config.kq", "server")
  .load()
  .validate(schema);

const port = server.get("port") as number;

ESM and CJS

Works with both import and require:

// CommonJS
const { KQParser } = require("kq-config");

// ES Module
import { KQParser } from "kq-config";

The full feature list

• Block separation — ::server / ::client / ::shared
• Built-in .env loading — no dotenv needed
• $ENV:VAR injection — secrets never hardcoded
• ENC: encryption — AES-256-GCM built in
• Secret masking — ***MASKED*** in logs
• Raw secret detection — warns on plain secrets
• Layered overrides — dev → staging → prod
• Runtime overrides — KQ_SERVER_PORT=9999
• Schema validation — required, type, default
• Auto type casting — numbers, booleans, null
• TypeScript types — full definitions
• ESM + CJS — both supported

- Zero dependencies — nothing to audit

Install

npm install kq-config

GitHub: github.com/kanishq-9/kq-config

npm: npmjs.com/package/kq-config

Why I built this

I was tired of the same pattern in every project, one flat list of environment variables, no structure, no separation, no way to know which values are safe to expose to the frontend and which ones would be catastrophic if leaked.

The .kq format is my answer to that. One file, clear blocks, each side reads only what it needs. The encryption came from realizing that even .env files can be accidentally committed, so why not make the secrets safe to commit?

If you try it out, let me know what you think. Issues and PRs are welcome on GitHub.