Your Config File Is a Lie

Every six months, a new build tool promises you'll never write a config file again. And every six months, you end up writing one anyway. Sometimes two.

I'm not here to dunk on any tool in particular. Okay, that's not entirely true. But the pattern is what bothers me more than any specific offender. The pitch goes: smart defaults, convention over configuration, it just works. Then you try to do something slightly off the golden path — say, alias a directory, or swap a plugin — and suddenly you're reading a GitHub issue from 2023 where someone named tsx_wizard_42 explains that you need to eject, patch a loader, and pray.

The problem isn't configuration

Configuration is fine. Configuration is how you tell a computer what you actually want instead of what someone in a San Francisco office assumed you wanted.

The problem is hidden configuration. Defaults that live in source code you never see, buried three packages deep in node_modules. When those defaults match your needs, great. When they don't, you're reverse-engineering someone else's opinions about directory structure. That's worse than writing a config file. At least a config file is honest about what it is.

Convention over configuration killed nuance

Rails popularized the phrase. And Rails got it mostly right — because Rails had one strong opinion about every decision. You put models here. Views there. Routes go in this file. Fine.

But modern JS tooling tries to have it both ways. Convention over configuration! Also here are 200 plugins. Also you can override anything. Also if you override the wrong thing, nothing works and the error message says "Cannot resolve module." Good luck.

What we actually need isn't fewer config files. It's config files that make sense. Small ones. Documented ones. Config files where you can read each line and understand what it does without opening four browser tabs.

I keep a file in every project called WHY.md that explains the non-obvious config choices. Three lines per decision. It has saved me more time than any zero-config tool ever has.

Write config files. Document them. Move on.