Setting Up the TypeScript Environment: A Beginner's Guide

Welcome to the first step of our journey. Over the next several weeks, we are going to build a robust, fully-typed task API client. To do that, we first need to ensure our machine is ready to handle TypeScript.

TypeScript is a superset of JavaScript, which means your browser cannot run it directly. Instead, we use a compiler to transform our type-safe code into standard JavaScript. In this lesson, we will initialize our project folder, install the necessary tools, and verify that our compiler works as expected.

Initializing Your Project

Before we install anything, we need a workspace. Open your terminal and create a new directory for our project. If you haven't yet configured your local workspace, you might want to review our guide on Environment Setup: Preparing Your Local Development Workspace to ensure your Git and terminal tools are ready.

Run the following commands:

Bash
mkdir task-api-client
cd task-api-client
npm init -y

The npm init -y command creates a package.json file. This file is the heart of your project; it tracks your dependencies and metadata. Think of it as the manifest for your application.

Installing the TypeScript Compiler

With our project initialized, we need to install the TypeScript compiler, known as tsc. While you could install it globally, it is best practice to install it as a devDependency within your project. This ensures that every developer working on the project uses the exact same version of TypeScript.

Run this command in your terminal:

Bash
npm install typescript --save-dev

Once this finishes, check your package.json. You will see typescript listed under devDependencies. This tells npm that we only need this package while we are writing code, not when the final application is running in a user's browser.

Running the TypeScript Compiler

Now that we have installed the compiler, let's verify it works. First, create a source file named index.ts:

TYPESCRIPT
// index.ts
const greeting: string = "Hello, TypeScript!";
console.log(greeting);

TypeScript files use the .ts extension. To compile this into JavaScript, we use the tsc command provided by our local installation. Because we installed it locally, we access it via npx:

Bash
npx tsc index.ts

If everything is configured correctly, you will see a new file generated in your directory: index.js. Open it, and you'll notice that the type annotation (: string) has been stripped away, leaving clean, standard JavaScript.

The Compilation Workflow

The workflow involves a simple cycle: you write code in .ts files, and the compiler processes them into executable .js files.

Practice Exercise

To confirm your setup, try this:

1. Open index.ts and purposefully introduce a type error. For example, try assigning a number to your greeting variable: const greeting: string = 123;.
2. Run npx tsc index.ts in your terminal.
3. Observe how the compiler stops you and reports the error in your terminal. This is exactly why we use TypeScript—it catches mistakes before they ever reach the browser.

Common Pitfalls

• Global vs. Local Installation: Avoid installing TypeScript globally (e.g., npm install -g typescript). If you have different projects requiring different versions, global installations will cause version conflicts. Always use npx or local scripts.
• Forgetting to Compile: A common mistake is editing index.ts and then refreshing the browser, wondering why the changes didn't appear. Remember: you are editing the source, but the browser is reading the compiled output. You must run tsc to update the JavaScript.
• Ignoring Errors: If the compiler gives you an error, read it. It is rarely a bug in the compiler; it is almost always a sign that your code logic is potentially unsafe.

FAQ

Do I need to compile every time I make a change? For now, yes. As we progress, we will look at "watch mode," which automatically compiles your code every time you save a file.

Is TypeScript just for big projects? Not at all. Even in small projects, the autocomplete and error-checking features make development significantly faster and less bug-prone.

Can I use modern JavaScript features? Yes. TypeScript handles the transpilation of modern features (like optional chaining or nullish coalescing) into older versions of JavaScript that browsers can understand.

Recap

In this lesson, we initialized our project with npm init, installed the TypeScript compiler locally as a devDependency, and successfully compiled our first .ts file into executable JavaScript. You've now moved from a standard JavaScript setup to a type-safe development environment.

Up next: We will learn how to configure the compiler’s behavior using tsconfig.json, which gives you granular control over how your code is checked and transformed.