Cjs

Right, so you’ve built something genuinely useful—or at least, you’ve built something that compiles without throwing seven hundred type errors. Congratulations. Now comes the fun part: making other people’s computers run it. This isn’t just about slapping some files in a zip folder and calling it a day. We’re building a proper package, the kind you’d publish to npm or use across a dozen microservices without wanting to tear your hair out. Let’s get this done properly.

Right, so you’ve decided to live in a world where your environment variables aren’t just mysterious string | undefined gremlins hiding in your process.env object. Good choice. It’s a small piece of TypeScript hygiene that pays off massively by turning runtime configuration errors into compile-time squiggles. Let’s get it done properly. The core problem is that process.env is, by default, typed by Node.js’s built-in types as a ProcessEnv interface where every property is optional (string | undefined). This is the technically correct, safety-first stance for the Node.js library itself, but it’s infuriating for us because we know we’ve set DATABASE_URL in our .env file. We want to access process.env.DATABASE_URL and have TypeScript know it’s a string, period.

Right, let’s talk about one of the first things that will make you want to throw your laptop out a window when you move from writing simple scripts to a real TypeScript application: the dreaded ../../../ import. You know the one. It’s like a little map of your file structure slowly driving you insane. We’re going to fix that with path aliases, and in the process, we’ll demystify how Node.js even finds your code. This isn’t just about convenience; it’s about sanity.

Right, let’s talk about running your TypeScript code. Because tsc is great and all, but constantly compiling to a dist directory and then running it feels like building a ship in a bottle. You just want to run the darn thing. You have three main choices for this, and each has its own particular brand of genius and madness. The Old Guard: ts-node ts-node is the veteran. It’s been around the block, it’s seen things, and it just works. Under the hood, it’s a clever hack. It registers a hook with Node.js that says, “Hey, anytime someone tries to require a .ts or .tsx file, call me first.” It then grabs the TypeScript source, compiles it on the fly in memory, and hands the compiled JavaScript back to Node to execute.

Right, let’s talk about the single most common source of confusion and hair-pulling in modern Node.js development: the great module schism. You’ve got these two systems, CommonJS (CJS) and ES Modules (ESM), living in an awkward, tense truce inside your Node.js project. It’s like your in-laws are visiting, and one insists on using forks while the other brought their own ceremonial chopsticks. They can coexist, but you have to be very careful how you set the table.

Right, let’s talk about the one npm package you absolutely cannot avoid if you’re writing TypeScript for Node.js: @types/node. You’ve probably already installed it a dozen times without thinking, like a digital pack of gum at the checkout counter. But what is it, really? It’s not a library. It’s not even code. It’s a giant, sprawling set of type definitions—a massive .d.ts file—that tells TypeScript, “Hey, all those globals like process, require, setTimeout, and the entire fs module? Here’s exactly what they look like.”

Right, let’s get our hands dirty. You’re not here to drag and drop files in some bloated IDE wizard that generates 50 files you don’t understand. We’re going to build this from the ground up, the way it should be: with intention and control. This is the foundation, and a shaky foundation here will cause migraines later. Trust me, I’ve been there. First, make a directory for your project and cd into it. This isn’t a tutorial on using your terminal, but if you’re fuzzy on that, now’s the time to get cozy with it. You can’t avoid the command line in this line of work, and anyone who tells you otherwise is trying to sell you something.