Quill: a tiny config-loader nobody asked for that 2.4k people now use

Why it exists

I was on my fourth Node service in three years that had a config.ts file with the same hand-rolled process.env.X || defaults.x pattern, the same forgotten type coercion bug for booleans (process.env.FEATURE_FLAG === 'true' is the canonical wrong solution), and the same on-call incident shape: a missing env var that nobody caught because the schema lived in three engineers’ heads.

Existing libraries either did too much (full DI containers, classes for everything) or too little (just env-var parsing, no overlay). I wanted a small tool that did one job: take a typed schema, validate the environment at startup, and fail fast with a useful error message.

What it does

import { defineConfig } from 'quill';

export const config = defineConfig({
  port: { type: 'number', default: 3000 },
  databaseUrl: { type: 'string', secret: true, required: true },
  featureFlags: {
    enableNewCheckout: { type: 'boolean', default: false },
  },
});

That’s the API. Everything else is a side effect of three properties:

• Schema-driven type coercion. 'true', '1', and 'yes' all become true. 'false', '0', and 'no' all become false. Anything else throws at startup, not at the first request that reads it.
• Secrets are tagged. Anything marked secret: true is redacted in console.log(config), in error messages, and in the structured logger output. You don’t have to remember.
• A quill check CLI. Reads your schema, reads your .env, tells you what’s missing, what’s typed wrong, and what’s set but unused. Runs in CI. Catches drift before it becomes a 3am page.

How it grew

I shipped 1.0 on a Sunday. Posted it once. Forgot about it for two months. When I came back, four people had filed issues, two of which were real. I fixed them, shipped 1.1, and that was the entire growth strategy for the first year.

The only thing I did intentionally was write good error messages. Most of the early adopters told me — unprompted — that they tried it because the README’s “what happens when X is missing” example was funny, and stayed because the actual error matched the example.

What I learned about maintaining OSS

• Most issues are not bugs; they are mismatched expectations. I now respond to every issue with a question first, not an answer.
• Saying no is a feature. Quill has had three “could you also support…” asks turn into long thoughtful threads where the answer was no, and the asker said “actually, you’re right, I’ll keep that out of my code too.”
• The contributors are smarter than me. Someone added Deno support in a 200-line PR I would have spent a weekend bikeshedding the interface for. I merged it.

Concrete outcome

• 2.4k weekly downloads on npm, steady for the past 9 months.
• 38 unique contributors across 87 merged PRs.
• Used in production at three companies who told me directly. Probably more I haven’t heard from.
• One CVE filed and patched within 14 hours, against a transitive dependency. No reports of exploitation.
• Zero scope creep. It still does exactly what 1.0 did, just better.