How to Install TypeScript and Set Up a Project

If you want to try TypeScript out, setting up your first project is easier than you might think. In this post, we’ll walk through the steps to set up a TypeScript project from scratch — even if you’ve never used it before.

---

💻 Expected Environment

To follow this guide smoothly, make sure you have the following:

• Operating System: Windows, macOS, or Linux
• Terminal/Command Line:
  • Windows: PowerShell, Windows Terminal, or Git Bash
  • macOS/Linux: Default terminal
• Node.js and npm (Node Package Manager): Install the latest LTE version following Beginner’s Guide to Node.js: Step-by-Step Learning Path. I am using v24.11.1.
• A Code Editor: Visual Studio Code (recommended for TypeScript)

Once these are set up, you can use the same commands across all systems —
for example, mkdir my-typescript-app works perfectly in Windows, macOS, and Linux.

---

🧰 Step 1: Check Node.js version

You can check the Node.js version by running:

node -v

If you don’t see a version number, download and install it as mentioned in the expected environment section.

---

📦 Step 2: Create a New Project Folder

Create a new folder for your project and move into it:

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

---

📁 Step 3: Initialize a Node Project

Next, set up your project with a package.json file:

npm init -y

This file keeps track of your project dependencies and scripts.

---

⚙️ Step 4: Install TypeScript

Now, install TypeScript as a development dependency:

npm install typescript --save-dev

💡 Note 1 – About the --save-dev flag:
The --save-dev flag tells npm (Node Package Manager) to install TypeScript as a development dependency — meaning it’s only needed while developing or building your project, not when running it in production.

In other words:

• Tools like TypeScript, testing libraries, or linters are installed with --save-dev
• Libraries that your app needs to run (like React or Express) are installed without the flag, using just npm install package-name

This helps keep your production environment clean and lightweight.

To check if TypeScript installed correctly, run:

npx tsc -v

You should see a version number like 5.x.x.

💡 Note 2 – About the npx tsc -v command:

• npx lets you run commands from locally installed npm packages without needing a global installation.
• tsc is the TypeScript compiler, and the -v option shows the installed version number.
• This confirms that TypeScript is properly installed in your project.

---

🧩 Step 5: Create a TypeScript Configuration File

The configuration file, tsconfig.json, tells TypeScript how to compile your code.
You can create one easily by running:

npx tsc --init

This generates a tsconfig.json file with many options.
For beginners, you can keep most defaults, but make sure these key lines are set:

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

💡 Note – About the npx tsc --init command:

• npx runs the local TypeScript compiler from your project (no global install needed).
• tsc stands for the TypeScript Compiler.
• The --init flag tells the compiler to create a default configuration file called tsconfig.json.
• This file defines how TypeScript should compile your code — for example:
  • Which JavaScript version to target (like ES6)
  • Where to save the compiled files (outDir)
  • Whether to enforce strict type checking
• The tsconfig.json file is only needed during development or build time, not in production.
  In production, only the compiled JavaScript files (usually inside the dist folder) are required to run your app.

---

📝 Step 6: Write Your First TypeScript File

Create a new folder called src and a file inside it named index.ts.

🧩 Command (Cross-Platform)

macOS / Linux / Windows (WSL):

mkdir src
touch src/index.ts

Windows (PowerShell):

mkdir src
New-Item src/index.ts -ItemType File

After creating the file, open it and add this simple TypeScript code:

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

console.log(greet("TypeScript"));

💡 Note – About the touch Command:

• The touch command works on macOS, Linux, and Windows (WSL).
• On standard Windows PowerShell, you can use: New-Item src/index.ts -ItemType File
• You can also use Git Bash on Windows if you prefer Linux-style commands.

---

🛠️ Step 7: Compile TypeScript to JavaScript

TypeScript doesn’t run directly in browsers or Node.js — it must be compiled into JavaScript.

Run this command:

npx tsc

This compiles your code and creates a dist folder with a file named index.js.

---

▶️ Step 8: Run Your Code

Now run your compiled JavaScript file using Node.js:

node src/index.js

You should see:

Hello, TypeScript!

🎉 Congratulations — you’ve just created and run your first TypeScript project!

---

💡 Bonus 1: Add a Build Script

To make compiling easier, add this line to your package.json under "scripts":

"scripts": {
  "build": "tsc"
}

Now you can simply run:

npm run build

---

💡 Bonus 2: Adding a dist Folder

When you compile your TypeScript code using npx tsc or npm run build,

npx tsc

TypeScript converts your .ts files into .js files.
By default, it places the compiled files in the same folder as your source code (for example, inside src/).

However, many projects prefer to keep compiled JavaScript files in a separate folder — often named dist — to keep the source code and output organized.

To do this, open your tsconfig.json file and inside the "compilerOptions" section, add these lines:

{
  "compilerOptions": {
    "rootDir": "./src",
    "outDir": "./dist"
  }
}

Then recompile your code using npx tsc or npm run build

Your project will now look like this:

src/
  index.ts
dist/
  index.js
  index.js.map
  index.d.ts
  index.d.ts.map

---

These extra files are created automatically by TypeScript to make debugging, development, and reuse of your code easier — so it’s perfectly normal to see them in your dist folder.

💡 Note – About the Files in the dist Folder:

• index.js → The compiled JavaScript file that runs on Node.js or browsers.
• index.js.map → A source map that helps you debug TypeScript code directly in browser or editor tools.
• index.d.ts → A type definition file that describes your code’s types for use in other TypeScript projects.
• index.d.ts.map → A source map for the type definitions.

---

🧠 Summary

Here’s what you did:

1. Installed Node.js and TypeScript
2. Created a project folder and initialized package.json
3. Set up tsconfig.json
4. Wrote and compiled a .ts file
5. Ran the output JavaScript file

Now you have a basic TypeScript setup ready for small projects or even modern frameworks like React, Angular, or Next.js.