How to Set Up a TypeScript Project

In our last discussion, we explored why TypeScript is such a powerful tool for catching errors. Now we face the next practical question: how do we actually start using it?

It seems like a simple question, but it leads to an important decision. When we install a tool like TypeScript, should we install it for our entire computer, or just for the single project we're working on? Does this choice even matter in the long run?

Let's walk through the options together. Understanding this choice is a key step in building professional, maintainable software.

The Global Path: An Easy Start

One common way to install TypeScript is "globally," using the command npm install -g typescript. This makes the TypeScript compiler, a command-line tool often called tsc, available everywhere on our system. It feels convenient.

But what happens a few months from now? Let's say we start a new project that needs a newer version of TypeScript. If we upgrade our global installation, we risk breaking our old project.

This creates a fragile setup. We can't be sure that a project we wrote a year ago will still work, because a core tool it depends on has changed. How can we make our projects more robust and independent?

The Local Path: Building for Consistency

A more reliable approach is to install TypeScript "locally," meaning it only exists inside our project's folder. This might seem less convenient at first, but it solves our consistency problem.

When we install TypeScript locally, our project's package.json file keeps a record of the exact version used. When a teammate—or our future self—sets up the project, they get the identical version. This makes our project self-contained and predictable.

This is the foundation of building software in a team. It ensures that "it works on my machine" is true for everyone.

Let's Set Up a Project Together

Let's build a new project with a local TypeScript setup. First, we create a directory and tell the Node.js package manager (npm) to initialize it.

mkdir our-ts-project
cd our-ts-project
npm init -y

The npm init -y command creates a package.json file, which acts as our project's configuration file. Now, let's add TypeScript as a "development dependency."

npm install -D typescript

We use the -D flag because TypeScript is a tool for development. It's not needed to run the final compiled code.

But if the tool is installed locally, how do we run it? We use npx, a tool included with npm that can find and run commands from our project's local dependencies. We can check our setup by running:

npx tsc --version

This command will run the local TypeScript compiler and show us its version, confirming our setup is working correctly.

Understanding the TypeScript Workflow

Next, we need to give the TypeScript compiler a set of rules to follow. We can create a default rulebook, called tsconfig.json, with a simple command.

npx tsc --init

This file tells TypeScript how to compile our code. For now, the default settings are perfect.It's also a good practice to keep our original source code separate from the compiled JavaScript output.

Let's create two folders.

mkdir src
mkdir dist

We will write our TypeScript code in the src folder. Let's create our first file at src/index.ts and add some simple code:

function greet(name: string): string {
  return `Hello, ${name}!`;
}

const message = greet("TypeScript");
console.log(message); // Hello, TypeScript!

This simple example defines a function that takes a name of type string and returns a string. The TypeScript compiler can check this for us, preventing bugs if we accidentally pass a different type of data.

Making Our Work Easier

To compile our code, we can run npx tsc. This reads our tsconfig.json and translates all files from src into JavaScript inside dist.

Typing this command repeatedly can be tedious. We can create shortcuts, or "scripts," in our package.json file.

{
  "scripts": {
    "build": "tsc",
    "watch": "tsc --watch"
  }
}

Now, we can simply run npm run build to compile our project. Even better, npm run watch will tell TypeScript to automatically recompile our code every time we save a file. This creates a smooth and efficient development workflow.

With this foundation, we are ready to write code with the full power of our editor's features, like autocompletion and error-checking, all working in harmony with our project's specific TypeScript version.

Support ExplainThis

If you found this content helpful, please consider supporting our work with a one-time donation of whatever amount feels right to you through this Buy Me a Coffee page, or share the article with your friends to help us reach more readers.

Creating in-depth technical content takes significant time. Your support helps us continue producing high-quality educational content accessible to everyone.