Api-Design

Right, so you’ve written your beautiful library, your types are a work of art, and you’ve run tsc and tsd and everything passes. You’re feeling pretty good, right? Don’t. You’ve only tested your types in situ, from the source. The real world is a much, much darker place. Your meticulously crafted .d.ts files get bundled, transformed, and ultimately consumed by a user’s project in ways that can make a complete mockery of your original intentions. This is where @arethetypeswrong/cli (or attw for short) comes in—it’s the final, brutal honesty your library needs before it faces the public.

Now, let’s talk about something that seems like it should be simple but is, in fact, a delightful little minefield: keeping your type definitions in sync with your actual library code. You’ve just shipped a fantastic new feature in my-awesome-lib@2.1.0. You’re feeling great. Then you get the issue: “Types are broken!!1!” You forgot to update the index.d.ts file. We’ve all been there. It’s the equivalent of putting on a sharp suit and then forgetting to wear pants.

Right, let’s talk about the exports field. This is where we graduate from “just publishing some files” to actually building a proper, thoughtful library. If you’re still using the old "main" and "types" fields, I’m not mad, just disappointed. It’s like using a flip phone in 2024—it works, but you’re missing out on a world of security, control, and sanity. The exports field in your package.json is your library’s bouncer. It explicitly tells the outside world (and TypeScript) which entry points are public and how to find them. Everything else? It’s off-limits. This is called “package encapsulation,” and it’s the single best way to avoid the dreaded “hey, why can my users import this internal file I never meant to expose?” problem. We’ve all been there. It’s not fun.

Right, so you’ve decided to be a proper library author. Congratulations, and my condolences. You’re about to enter the special hell of making your beautiful TypeScript code play nicely with the entire JavaScript ecosystem’s messy, decades-spanning module system. The goal is simple: someone using old-school require() in a CommonJS (CJS) app should be able to use your library, and someone using shiny import in an ESM app should be able to use it too, all without them ever knowing about the duct tape and baling wire you used behind the scenes.

Right, let’s talk about one of the most common ways we, as library authors, accidentally create a hostile environment for our users: overly narrow types. You’ve poured your soul into crafting a beautiful, robust API, and then you ruin it by telling the user, “No, you can’t do it that way,” when their way is perfectly valid. It’s the library equivalent of being a pedantic dinner guest who corrects everyone’s grammar. Don’t be that person.

Right, so you’ve built your library. It’s a masterpiece of type-safe engineering. But if you just ship the raw .ts files or, heaven forbid, the compiled .js without a map, you’re leaving your users in the dark. They get a any-shaped box and have to guess what’s inside. That’s not very friendly. The solution is the Declaration File (.d.ts), and getting it right is what separates the pros from the amateurs.

Alright, let’s talk about designing a public API. This is where you move from writing code for yourself to writing code for everyone else. It’s the contract you sign with your users, promising not to be a jerk and break their entire codebase with a surprise update at 2 AM. TypeScript is our not-so-secret weapon here, letting us write that contract in iron-clad, type-safe ink. But with great power comes great responsibility to not design something truly idiotic.