Installing TypeScript: Setting Up Your First Project

Table of Contents

• Introduction
• Prerequisites
• Installing TypeScript Globally
• Setting Up a New TypeScript Project
• Understanding tsconfig.json
• Writing Your First TypeScript Program
• Compiling TypeScript to JavaScript
• Running the JavaScript Output
• Using TypeScript Locally in a Project (Best Practice)
• Setting Up TypeScript with Node.js
• Common Issues and Troubleshooting
• Conclusion

Introduction

Once you understand the advantages of using TypeScript over JavaScript, the next step is setting up a working TypeScript environment.
In this article, we will cover how to install TypeScript, configure your first project, understand key setup files, and compile and run your TypeScript code. Whether you are setting up a simple practice project or laying the foundation for a large-scale application, this guide will walk you through everything you need to get started the right way.

Prerequisites

Before you start installing TypeScript, make sure you have the following tools installed on your machine:

• Node.js (version 12 or later recommended)
  Node.js comes bundled with npm (Node Package Manager), which you’ll use to install TypeScript.

To check if Node.js and npm are installed, run:

node -v
npm -v

If not installed, you can download Node.js from the official website.

Installing TypeScript Globally

The most straightforward way to install TypeScript is by using npm to install it globally. A global installation allows you to access the TypeScript compiler (tsc) from anywhere on your system.

To install TypeScript globally:

npm install -g typescript

Once installed, verify that TypeScript is installed correctly:

tsc -v

You should see a version number like 5.2.3, confirming that the installation was successful.

Setting Up a New TypeScript Project

Now, let’s create a simple TypeScript project from scratch.

1. Create a new folder for your project:

mkdir typescript-first-project
cd typescript-first-project

2. Initialize a Node.js project (optional but recommended):

npm init -y

This creates a basic package.json file, which helps manage dependencies later.

3. Initialize a TypeScript configuration file:

tsc --init

This generates a tsconfig.json file, which controls how the TypeScript compiler behaves.

At this point, your folder structure should look like this:

/typescript-first-project
|-- package.json
|-- tsconfig.json

Understanding tsconfig.json

The tsconfig.json file is the heart of any TypeScript project. It defines the compiler options, files to include or exclude, and the overall behavior of the project.

Here’s a sample snippet from a freshly created tsconfig.json:

{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "strict": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "esModuleInterop": true
  }
}

Key fields to note:

• target: The JavaScript version output (e.g., es5, es6, esnext).
• module: Module system (e.g., commonjs, es6).
• strict: Enables all strict type-checking options.
• outDir: Directory where compiled JavaScript files will be placed.
• rootDir: Directory containing the source TypeScript files.

You can customize these settings depending on the needs of your project.

Writing Your First TypeScript Program

Let’s create our first simple TypeScript file.

1. Create a new folder called src:

mkdir src

2. Inside the src folder, create a file named index.ts:

touch src/index.ts

3. Open index.ts and add the following code:

function greet(name: string): void {
  console.log(`Hello, ${name}!`);
}

greet('World');

Here:

• We defined a function greet that takes a string type argument.
• void means the function does not return any value.

Compiling TypeScript to JavaScript

To convert your TypeScript code into JavaScript, run the TypeScript compiler:

tsc

This command reads the tsconfig.json file and compiles all .ts files found in the src folder into .js files in the dist folder.

After compilation, your folder structure should look like:

/typescript-first-project
|-- /src
|   |-- index.ts
|-- /dist
|   |-- index.js
|-- package.json
|-- tsconfig.json

Running the JavaScript Output

Now that you have compiled JavaScript, you can run the output using Node.js:

node dist/index.js

You should see the following output:

Hello, World!

Congratulations! You just created, compiled, and ran your first TypeScript program.

Using TypeScript Locally in a Project (Best Practice)

Instead of installing TypeScript globally, it’s often better to install it locally to each project. This ensures consistency across different machines and team members.

To install TypeScript as a development dependency:

npm install --save-dev typescript

You can then use npx to run the local version:

npx tsc

This approach is highly recommended for professional projects.

Setting Up TypeScript with Node.js

If you are using TypeScript with Node.js, you might also want to install type definitions for Node:

npm install --save-dev @types/node

This package provides type information for Node.js core modules like fs, path, and http, allowing you to use them in your TypeScript files without issues.

You may also want to modify your tsconfig.json to include "moduleResolution": "node" for smoother development.

Common Issues and Troubleshooting

Here are a few common problems you might face:

• tsc: command not found: Ensure TypeScript is installed globally, or use npx tsc.
• Output files not generated: Check that your tsconfig.json specifies the correct rootDir and outDir.
• Node.js can’t find module: Ensure you run the compiled .js files, not .ts files.
• Permission errors on Linux/macOS: You may need to prefix commands with sudo if permission issues arise during installation.

Conclusion

Setting up TypeScript is a straightforward process once you understand the tools and workflow. By installing TypeScript, initializing a tsconfig.json file, writing your first TypeScript program, and compiling it to JavaScript, you have taken the crucial first steps into the world of statically typed JavaScript development.

Proper project setup lays the foundation for scalable, maintainable, and error-free applications. Whether you are building a small tool or a massive enterprise-grade application, investing a little time upfront in setting up TypeScript correctly will save you countless hours down the line.