TypeScript Installation & tsconfig.json
To start writing TypeScript, you first need to install TypeScript on your computer and create a small settings file called tsconfig.json. This file tells the TypeScript compiler how to check and convert your code into JavaScript. Getting this setup right saves you from confusing errors later in real projects.
This tutorial walks you through every terminal command you need. You will install the compiler locally, generate a configuration file, understand the most important options, and learn how to compile or run your code.
What You Need Before You Start
Before you can install TypeScript, you need Node.js and npm on your computer. Node.js is a program that lets JavaScript run outside a web browser. npm (Node Package Manager) is a tool that comes with Node.js and helps you download and manage code packages, including the TypeScript compiler itself.
To check if you already have them, open your terminal (also called the command line) and run these two commands:
node --version
npm --version
You should see version numbers printed. If you get an error like "command not found," download Node.js from the official website and install it first. The TypeScript compiler needs Node.js to run.
How Do You Install TypeScript Correctly?
You can install the TypeScript compiler in two ways: globally or locally. A global install puts TypeScript on your whole computer so you can use it from any folder. A local install puts TypeScript inside one project folder only.
For learning and for real projects, always choose a local install. Here is why: different projects may need different TypeScript versions. A local install keeps each project independent and records the exact version in a file called package.json. This means anyone who downloads your project gets the same version.
Open your terminal, move into your project folder, and run:
npm install -D typescript
The -D flag (short for --save-dev) tells npm that TypeScript is a development dependency. This means the package is only needed while you are building and checking your code, not when the final website or app runs for users.
After the install finishes, verify it worked by running the tsc command through npx. npx is a tool that runs packages installed in your local project:
npx tsc --version
You should see something like Version 5.x.x. The exact number may be different, and that is fine.
How Do You Create and Understand tsconfig.json?
The tsconfig.json file is the control center for your TypeScript project. It tells the compiler which files to check, which JavaScript version to produce, and how strict the type checking should be. Without it, the compiler uses default settings that may not fit your needs.
Generate a starter file by running npx tsc --init in your project folder. This creates a tsconfig.json with many options commented out. For a beginner project, replace its contents with this minimal version:
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"strict": true,
"outDir": "./dist",
"rootDir": "./src",
"esModuleInterop": true,
"sourceMap": true
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist"]
}
What Does Each Key Option Mean?
target sets the JavaScript version that TypeScript outputs. ES2022 is a modern version supported by current browsers and Node.js. Setting this correctly lets you use modern features without problems.
module tells TypeScript which module system your JavaScript will use. NodeNext works well for modern Node.js projects. If you are using a bundler like Vite or webpack, you might use ESNext instead. For this beginner setup, NodeNext is a safe choice.
strict is the most important option for learners. When set to true, it turns on a group of strict type checks, including checking for variables that might be null and stopping you from using values without checking them first. This catches many bugs early. While it may feel annoying at first, it builds good habits.
outDir is the folder where the compiled JavaScript files go. Here, it is set to ./dist. Keeping output separate from source code keeps your project clean.
rootDir tells TypeScript where your original TypeScript source files live. Here, it is ./src. This helps the compiler understand the folder structure and can prevent errors about files being outside the expected root.
esModuleInterop makes it easier to import older CommonJS-style packages into your modern TypeScript code. CommonJS is an older way JavaScript modules were written. Without this option, importing some packages can cause type errors. Setting it to true fixes that.
sourceMap creates map files that let your browser or debugger show your original TypeScript code when you are debugging, even though the browser is actually running the compiled JavaScript. This makes finding mistakes much easier.
include and exclude control which files the compiler looks at. include here says "look at all .ts files inside src." exclude says "never look inside node_modules or the output folder."
How Do You Compile and Watch Your Code?
Once your tsconfig.json is ready, you can compile your project. Create a folder called src and add a file named index.ts with a simple message:
const message: string = "TypeScript is working!";
console.log(message);
Run the compiler:
npx tsc
TypeScript reads tsconfig.json, finds src/index.ts, checks it, and creates dist/index.js. You can run the output with Node:
node dist/index.js
The terminal prints TypeScript is working!. Notice that the compiled JavaScript has no type annotations. Types are only used for checking.
Running npx tsc every time you change a file gets tiring. Use watch mode instead. The --watch flag keeps the compiler running and recompiles automatically when you save a file:
npx tsc --watch
Now you can edit your .ts files and the JavaScript updates instantly. This is how most developers work during a project.
How Do You Run TypeScript Without Compiling First?
Sometimes you want to run a .ts file quickly without waiting for a separate compile step. You can use a tool called ts-node or a faster alternative called tsx. These tools run TypeScript directly in Node.js.
Install tsx as a development dependency:
npm install -D tsx
Then run your file:
npx tsx src/index.ts
Important: tsx does not check types. It only removes the types and runs the code. So you should still run npx tsc --noEmit to check for type errors before you finish. For beginners, using tsc --watch is often clearer because it shows you type errors directly.
Comparison: Global vs Local Install
| Feature | Global Install | Local Install (Recommended) |
|---|---|---|
| Command | npm install -g typescript |
npm install -D typescript |
| Where it lives | Whole computer | One project folder |
| Version control | Hard to lock per project | Recorded in package.json |
| Team safety | Teammates may use different versions | Everyone uses the same version |
| Best for | Quick experiments only | All real projects and learning |
Common Mistakes and Best Practices
- Installing globally instead of locally. A global install seems easier, but when you work on two projects that need different TypeScript versions, you will get confusing errors. A local install solves this by keeping versions separate.
- Forgetting that
tscalone needs atsconfig.json. If you runnpx tscin a folder withouttsconfig.json, the compiler looks for files using default rules that may not match your folder structure. Always create the config file first. - Setting
stricttofalseto "make errors go away." Turning off strict mode hides real problems. Fix the errors instead. Strict mode is your helper, not your enemy. - Putting source files outside
rootDir. If you set"rootDir": "./src"but import a file from another folder, TypeScript will give an error because the file is not under the root. Keep all source files inside the folder you declare. - Using
tsxand assuming types were checked.tsxskips type checking for speed. Always runtsc --noEmitbefore you consider the code correct.
Real-World Example: A Minimal Project
Here is a complete, small project you can build right now. It has a function that greets a user and a file that calls it.
File: src/greet.ts
// A simple function that returns a greeting
export function greet(name: string): string {
return `Hello, ${name}! Welcome to TypeScript.`;
}
File: src/index.ts
import { greet } from "./greet.js";
// TypeScript infers that message is a string
const message = greet("Student");
console.log(message);
// Output: Hello, Student! Welcome to TypeScript.
File: tsconfig.json
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"strict": true,
"outDir": "./dist",
"rootDir": "./src",
"esModuleInterop": true,
"sourceMap": true
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist"]
}
Run these commands in order:
npm install -D typescript
npx tsc
node dist/index.js
How it works: The greet function in greet.ts accepts a string and returns a string. The index.ts file imports it. Notice the import path ends with .js, not .ts. This is because NodeNext module mode expects the final JavaScript extension in imports. When you run npx tsc, TypeScript reads tsconfig.json, checks both files, and writes greet.js and index.js into dist. Running node dist/index.js executes the compiled JavaScript and prints the message. The original TypeScript types disappear in the output; they only served to catch mistakes during compilation.
Summary
- You need Node.js and npm before you can install TypeScript.
- Always use a local install with
npm install -D typescriptso each project controls its own version. - Create
tsconfig.jsonwithnpx tsc --initand replace the contents with a minimal, strict setup. - Key options to remember:
target,module,strict,outDir,rootDir,include, andexclude. - Use
npx tsc --watchduring development to recompile automatically when you save. - Tools like
tsxcan run.tsfiles directly, but they do not type-check, so runtsc --noEmitseparately.
Frequently Asked Questions
Do I need to install TypeScript globally?
No. A local install is better for almost everyone. It keeps the TypeScript version tied to your project, so teammates and future you get the same behavior. Global installs can cause version conflicts when you work on different projects that need different TypeScript versions.
What is the difference between tsc and ts-node?
tsc is the official TypeScript compiler. It checks your types and creates JavaScript files. ts-node runs TypeScript directly in Node.js without creating files first, but it may be slower. Use tsc to check and build, and use ts-node or tsx for quick experiments.
Why does TypeScript say my file is not under rootDir?
This happens when rootDir in tsconfig.json points to one folder, but your code imports a file from outside that folder. TypeScript expects all source files to live inside rootDir. Move the file inside src or change rootDir to a folder that contains everything.
What does the strict option do in tsconfig.json?
The strict option turns on a group of strict type checks, including strictNullChecks and noImplicitAny. It helps catch common bugs like using a value that might be null or forgetting to declare a type. Always keep it true for new projects.
Can I use TypeScript without tsconfig.json?
Yes, you can run npx tsc file.ts to compile a single file. But without tsconfig.json, the compiler uses default settings that may not match your project. For any real project, create a tsconfig.json so your settings are saved and shared.
Practice Exercises
Exercise 1 (Easy): Install TypeScript Locally
Create a new folder called my-ts-project. Inside it, install TypeScript as a development dependency and verify the version using npx.
Show solution
mkdir my-ts-project
cd my-ts-project
npm init -y
npm install -D typescript
npx tsc --version
npm init -y creates a package.json so npm can track your dependency. npm install -D typescript installs TypeScript locally, and npx tsc --version confirms it works.
Exercise 2 (Easy): Create a Minimal tsconfig.json
Inside my-ts-project, generate a tsconfig.json and set it to compile files from src into dist with strict mode on.
Show solution
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"strict": true,
"outDir": "./dist",
"rootDir": "./src",
"esModuleInterop": true,
"sourceMap": true
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist"]
}
This config tells TypeScript to check strict types, read files from src, and write JavaScript to dist.
Exercise 3 (Medium): Compile and Run a File
Create src/index.ts with a typed variable and a console.log. Compile it with npx tsc and run the output with Node.
Show solution
const username: string = "Riya";
console.log(`Hello, ${username}!`);
// Output: Hello, Riya!
npx tsc
node dist/index.js
npx tsc compiles src/index.ts to dist/index.js, and node dist/index.js runs the compiled JavaScript, printing the greeting.
Exercise 4 (Challenge): Use Watch Mode and Fix a Type Error
Start npx tsc --watch. Then write code that assigns a number to a string variable and read the compiler error. Fix the error so watch mode compiles successfully.
Show solution
let city: string = "Mumbai";
// city = 42; // Error: Type 'number' is not assignable to type 'string'.
city = "Delhi";
console.log(city);
// Output: Delhi
Run npx tsc --watch in one terminal. The commented line shows the error you would see if you uncommented it. Fixing it by keeping the value a string lets the compiler succeed and write dist/index.js.
Written by Shaikh Abdul Shahid
A Full-Stack Developer with experience in PHP, Laravel, JavaScript, and React.
Founder of Online Learner, sharing practical knowledge and programming tutorials.
Building and maintaining real-world web applications since 2017.
Your Feedback
Help us improve by sharing your thoughts.
Online Learner helps developers master programming, database concepts, interview preparation, and real-world implementation through structured learning paths.
Quick Links
© 2023 - 2026 OnlineLearner.in | All Rights Reserved.
