Welcome, future TypeScript wizard! Are you ready to embark on an exciting journey from zero to mastery in TypeScript? We’re going to build a solid foundation, starting right here with the absolute basics, and gradually work our way up to advanced patterns and production-ready best practices. No prior TypeScript experience? No problem! Just bring your curiosity and a basic understanding of JavaScript.

In this very first chapter, we’ll dive straight into the practical side of things. You’ll learn how to set up your development environment, write your very first TypeScript program, and understand the fundamental concept that makes TypeScript so powerful: types. By the end of this chapter, you’ll have successfully compiled and run a simple typed program, feeling confident about your first steps into the TypeScript universe!

Why does this matter? Because TypeScript isn’t just a fancy add-on; it’s a superpower for JavaScript developers! It helps you catch errors before your code even runs, makes your projects more maintainable, and provides incredible tooling support. Think of it as giving your JavaScript code a super-strong safety net and a crystal ball to predict potential issues.

What is TypeScript, Anyway?

Before we jump into code, let’s quickly understand what TypeScript actually is. Imagine JavaScript, but with a super-friendly guardian angel watching over your code, making sure you don’t accidentally assign a number where a piece of text is expected. That guardian angel is TypeScript!

TypeScript is a superset of JavaScript, which means any valid JavaScript code is also valid TypeScript code. It adds static type definitions to JavaScript, allowing you to describe the shape of your data and the types of values your variables will hold. The magic happens when TypeScript’s compiler (tsc) takes your .ts files and “transpiles” them back into plain, runnable JavaScript (.js) files that browsers and Node.js can understand.

Why go through this extra step? Because those type definitions allow TypeScript to perform powerful checks before your code ever runs. This means fewer bugs, clearer intentions in your code, and a much smoother development experience, especially as your projects grow larger and more complex. It’s like having an intelligent assistant constantly reviewing your code for potential mistakes!

Setting Up Your TypeScript Playground

Alright, enough talk! Let’s get our hands dirty and set up your development environment. This is where the real fun begins!

Step 1: Install Node.js

TypeScript relies on Node.js and its package manager, npm, for installation and managing dependencies. If you don’t have Node.js installed yet, now’s the time!

Action:

  1. Head over to the official Node.js website: https://nodejs.org/en/download/current
  2. Download and install the LTS (Long Term Support) version for your operating system. As of December 5th, 2025, the latest stable Node.js version is v25.2.1.

Why? Node.js provides the JavaScript runtime environment outside of a browser, and npm (Node Package Manager) is how we’ll install TypeScript.

After installation, open your terminal or command prompt and verify that Node.js and npm are correctly installed by running these commands:

node -v
npm -v

You should see version numbers similar to v25.2.1 and 10.x.x respectively.

Step 2: Create Your Project Folder

Let’s create a dedicated folder for our first TypeScript project. This keeps things organized!

Action:

  1. Open your terminal or command prompt.

  2. Navigate to a directory where you want to store your projects.

  3. Create a new folder and enter it:

    mkdir my-first-typescript-app
cd my-first-typescript-app

Why? Good project hygiene starts early!

Step 3: Initialize Your Project with npm

We’ll use npm to manage our project’s dependencies. The npm init command creates a package.json file, which is like a manifest for your project, listing its name, version, scripts, and dependencies.

Action:

  1. While still inside your my-first-typescript-app folder in the terminal, run:

    npm init -y

Why the -y? It tells npm to accept all the default values for the package.json prompts, making the process quicker. You’ll now have a package.json file in your folder.

Step 4: Install TypeScript

Now for the star of the show! We’ll install TypeScript as a development dependency for our project.

Action:

  1. In your terminal, run the following command:

    npm install --save-dev typescript

    Or, using the shorthand:

    npm install -D typescript

Why --save-dev or -D? This tells npm that TypeScript is a development dependency. This means it’s needed for developing and compiling our code, but not for running the final JavaScript output in production.

What to observe:

  • npm will download and install TypeScript.
  • A new folder named node_modules will appear in your project directory. This is where all installed packages live.
  • Your package.json file will now have a devDependencies section, listing typescript and its version. As of December 5th, 2025, the latest stable TypeScript version is 5.9.3. So you’ll likely see something like "typescript": "^5.9.3".

Your First TypeScript Program: Hello, Typed World!

It’s time to write some code! We’ll start with the classic “Hello, World!” program, but with a TypeScript twist.

Step 1: Create Your First TypeScript File

Every TypeScript file ends with the .ts extension.

Action:

  1. Open your my-first-typescript-app folder in your favorite code editor (VS Code is highly recommended for TypeScript!).
  2. Create a new file named hello.ts inside this folder.

Step 2: Write Your First Typed Code

Let’s add a simple message, but this time, we’ll tell TypeScript what type of data our message variable will hold.

Action:

  1. Add the following code to your hello.ts file:

    let greeting: string = "Hello, TypeScript!";
console.log(greeting);

Explanation of the new code:

  • let greeting:: We declare a variable named greeting, just like in JavaScript.
  • : string: This is the TypeScript magic! We’re explicitly telling TypeScript that the greeting variable is expected to hold a string (a sequence of characters). This is called a type annotation.
  • = "Hello, TypeScript!";: We assign a string value to our greeting variable.

What if I don’t add : string? TypeScript is smart! In this simple case, it would use type inference to automatically figure out that greeting is a string because you assigned a string literal to it. However, explicitly adding type annotations, especially for function parameters and return values (which we’ll see later), makes your code clearer and helps TypeScript catch more errors. For now, let’s keep it explicit to learn!

Step 3: Compile Your TypeScript Code

Remember, browsers and Node.js don’t understand .ts files directly. We need to compile our hello.ts into hello.js. We use the TypeScript compiler, tsc, for this. Since tsc is installed locally within our project’s node_modules, we use npx to run it.

Action:

  1. Go back to your terminal, still in the my-first-typescript-app folder.

  2. Run the TypeScript compiler:

    npx tsc hello.ts

What to observe:

  • If everything went well, you won’t see any output in the terminal (no news is good news in compilation!).
  • Check your project folder. You’ll now see a new file: hello.js.

Take a peek at hello.js: Open hello.js in your code editor. You’ll notice it looks exactly like the TypeScript code, but without the type annotation:

let greeting = "Hello, TypeScript!";
console.log(greeting);

This demonstrates that TypeScript’s primary job is to add types for development-time checks, and then remove them when compiling to plain JavaScript.

Step 4: Run Your JavaScript Code

Now that we have our plain JavaScript file, we can run it using Node.js.

Action:

  1. In your terminal, run the compiled JavaScript file:

    node hello.js

What you should see:

Hello, TypeScript!

Congratulations! You’ve just written, compiled, and run your very first TypeScript program! 🎉

Experimenting with Types: Catching Errors Early!

Let’s see TypeScript’s error-catching power in action. What happens if we try to assign a number to our string variable?

Action:

  1. Open your hello.ts file again.

  2. Modify the code to try and assign a number to greeting:

    let greeting: string = "Hello, TypeScript!";
console.log(greeting);

greeting = 123; // Uh oh, trying to assign a number to a string!

What to observe (in your code editor):

  • Your code editor (especially VS Code) will immediately highlight 123 with a red squiggly line.
  • Hovering over it will show an error message like: “Type ’number’ is not assignable to type ‘string’.”

This is TypeScript doing its job! It’s telling you right as you’re typing that there’s a type mismatch. This instant feedback is incredibly valuable, preventing many common bugs that would otherwise only appear at runtime in plain JavaScript.

Action:

  1. Try to compile this erroneous hello.ts file:

    npx tsc hello.ts

What you should see (in the terminal): The compiler will output the same error message you saw in your editor, confirming the type mismatch:

hello.ts:4:10 - error TS2322: Type 'number' is not assignable to type 'string'.

4 greeting = 123; // Uh oh, trying to assign a number to a string!
           ~~~

This is fantastic! TypeScript caught the error before we even tried to run the code. Now, go ahead and remove the erroneous line greeting = 123; to fix your hello.ts file.

Mini-Challenge: Your First Variables!

Let’s put your new knowledge to the test with a small challenge!

Challenge:

  1. In your hello.ts file, declare two new variables:
    • One named age that explicitly holds a number. Assign your actual age (or any number!) to it.
    • One named isStudent that explicitly holds a boolean. Assign true or false to it.
  2. Log both age and isStudent to the console.
  3. Try to assign a string to your age variable and observe the error.
  4. Remove the error, compile, and run your program!

Hint:

  • Remember the type annotations: : number and : boolean.
  • Use console.log() to display the values.

What to observe/learn:

  • How easy it is to declare variables with explicit types.
  • How quickly TypeScript catches type mismatches, preventing potential runtime errors.
Click for Solution (but try it yourself first!)
let greeting: string = "Hello, TypeScript!";
console.log(greeting);

// My challenge solution!
let age: number = 30; // Declaring 'age' as a number
let isStudent: boolean = true; // Declaring 'isStudent' as a boolean

console.log("My age is:", age);
console.log("Am I a student?", isStudent);

// // Uncomment the line below to see the error!
// age = "thirty"; // Error: Type 'string' is not assignable to type 'number'.

Common Pitfalls & Troubleshooting

Even simple steps can sometimes trip us up. Here are a couple of common issues beginners face and how to fix them:

  1. “Cannot find name ’tsc’.” or “command not found: tsc”

    • Pitfall: You might have forgotten to install TypeScript in your project, or you’re trying to run tsc directly without npx when it’s a local dependency.
    • Solution: Make sure you ran npm install -D typescript in your project folder. Always use npx tsc <filename.ts> when TypeScript is installed locally.

  2. Trying to run .ts files directly with node

    • Pitfall: You might instinctively try node hello.ts. Node.js only understands .js files by default.
    • Solution: Remember the two-step process: First, compile your .ts file to .js using npx tsc hello.ts. Then, run the compiled .js file using node hello.js. (Later, we’ll introduce ts-node for a smoother experience, but it’s crucial to understand the compilation step first!).

  3. Misinterpreting TypeScript error messages

    • Pitfall: TypeScript errors can look intimidating at first.
    • Solution: Don’t panic! Focus on the core message, usually starting with “Type ‘X’ is not assignable to type ‘Y’”. This tells you exactly what type was expected and what type was provided. The line number also helps you pinpoint the issue. Your editor’s hover-over messages are often the most digestible.

Summary: What We’ve Accomplished

Phew! You’ve covered a lot in this first chapter, and you should be incredibly proud! Here’s a quick recap of what you’ve learned:

  • TypeScript’s Purpose: It’s a superset of JavaScript that adds static types to help catch errors early and improve code quality.
  • Environment Setup: You’ve successfully installed Node.js (v25.2.1), initialized an npm project, and installed TypeScript (v5.9.3) as a development dependency.
  • Your First .ts File: You created hello.ts and wrote basic TypeScript code.
  • Type Annotations: You learned how to explicitly tell TypeScript the type of a variable using : string, : number, and : boolean.
  • Compilation: You used npx tsc <filename.ts> to compile your TypeScript code into plain JavaScript.
  • Execution: You ran the compiled JavaScript file using node <filename.js>.
  • Early Error Detection: You witnessed TypeScript’s power in catching type-related errors before runtime, both in your editor and during compilation.

You’ve built a solid foundation! In the next chapter, we’ll dive deeper into TypeScript’s configuration, explore more fundamental types, and introduce how to automate our compilation process for a smoother workflow. Get ready for more type-checking adventures!