Installing a TypeScript Toolchain Without Losing Your Mind

Nothing in this book runs on its own. Every program you write here needs two things installed on your computer first: something to turn your TypeScript into JavaScript, and something to actually run the JavaScript once it exists. Neither one takes long, and both are the same steps whether you’re on a Mac, Windows, or Linux.

If you’ve heard that setting up a programming language is where people give up before they’ve written a single line, that reputation comes from other languages, the ones that need a different set of instructions for every operating system and a lot of luck. This part of TypeScript is mercifully boring, and boring is exactly what you want from it.

What’s actually happening

A .ts file is a text file. Your computer can’t run it, the same way it can’t run a shopping list. Something has to translate it first.

That something is the TypeScript compiler. It reads your text and writes out a plain JavaScript file, and it’s the JavaScript that actually runs. So the loop is: you write TypeScript, the compiler turns it into JavaScript, Node runs the JavaScript. You’ll do that loop a few hundred times before this book is over.

The compiler is called tsc, short for TypeScript Compiler. The runtime is called Node.js. Both are free, and installing them is where this chapter is going.

Installing Node.js

Go to nodejs.org and download the installer marked LTS (long-term support). Skip the one marked “Current”, it changes more often than you need it to. Run the installer and click through the defaults. It’s an ordinary installer, the kind you’ve clicked through for other software your whole life.

Open a terminal. On macOS that’s Terminal (press ⌘-space, type “terminal”, hit return). On Windows it’s PowerShell or Windows Terminal, both in the Start menu. On Linux you already know where yours is. Then check the install worked:

node -v

You should see a version number, something like v22.14.0. The exact number will keep climbing after this book is written, and that’s fine, any recent version does everything here.

npm installs alongside Node automatically. Check that too:

npm -v

Another version number. npm is how you’re about to install the TypeScript compiler, and it’s how every later chapter in this book installs anything else it needs.

A place to keep your code

Your terminal is always sitting in a folder, and it only sees the files in that folder. Make yourself one and go into it:

mkdir ts-book
cd ts-book

mkdir makes a directory. cd changes into it. Run pwd if you ever want the terminal to tell you where it currently thinks it is, and you’ll want that more often than you’d expect.

Now run:

npm init -y

This writes a file called package.json, describing this folder as a project. Open it if you’re curious, it’s a small block of text. You don’t need to understand it yet, chapter 20 explains it properly. Right now all it does is give the next command somewhere to write down what it installs.

Install the compiler:

npm install typescript

This downloads TypeScript into a new node_modules folder and records it in package.json. node_modules gets big fast, and you’ll never open it by hand, that’s normal.

Writing and running your first program

Create a file called hello.ts in that folder:

console.log("Hello, world");

Compile it:

npx tsc hello.ts

Nothing prints. That’s success, not failure, the compiler only speaks up when something’s wrong, which is the whole subject of the next chapter. Look in the folder and you’ll find a new file sitting next to the one you wrote, hello.js. Open it:

"use strict";
console.log("Hello, world");

Almost identical to what you typed. That’s normal for a program this small. TypeScript’s real job doesn’t show up until you start giving it types to check, which starts next chapter. For now, run the file that actually does something:

node hello.js

Hello, world

That’s the whole loop you’ll repeat for the rest of this book: write a .ts file, compile it, run the .js file that comes out. Two commands, not one. It’s more typing than some languages need, and it’s exactly what’s really happening every time, which is the trade this book keeps making.

Breaking it on purpose

One more thing before you go, and it’s the useful one.

Open hello.ts, misspell console as consol, save, and compile again:

consol.log("Hello, world");

npx tsc hello.ts

hello.ts(1,1): error TS2552: Cannot find name 'consol'. Did you mean 'console'?

A file, a line, a column, and the compiler guessing what you meant, correctly. Compilers suggest fixes more often than people expect, and TypeScript is better at it than most. Fix the spelling, compile again, and confirm node hello.js still prints your message.

When it goes wrong