TypeScript Introduction and Setup

Definition in Simple Words

TypeScript is a superset of JavaScript. That means all valid JavaScript is valid TypeScript, plus TypeScript adds features like static typing and compile-time checks.

You write .ts files, then the TypeScript compiler (tsc) converts them into .js files.

---

How the Compilation Pipeline Works

graph TD A[Write .ts file] --> B[Type Checking] B --> C[Transpile to .js] C --> D[Run in Browser or Node.js]

Key idea

• Type errors are found before runtime.
• Runtime still executes JavaScript, not TypeScript.

---

Install and Verify

npm install -g typescript
tsc --version

If your project already has TypeScript in devDependencies, prefer local execution:

npx tsc --version

---

Initialize a Project

tsc --init

This creates tsconfig.json, which controls TypeScript behavior.

---

Most Important tsconfig Options

{
  "compilerOptions": {
    "strict": true,
    "target": "ES2020",
    "module": "ESNext",
    "outDir": "./dist",
    "rootDir": "./src",
    "moduleResolution": "Bundler",
    "skipLibCheck": true
  },
  "include": ["src"]
}

strict

Enables strong type checks. This is the most important option for real projects.

target

Decides what JavaScript version gets generated.

module

Controls module syntax in output.

outDir

Output folder for compiled JavaScript.

---

strict Mode Breakdown

When strict is true, TypeScript enables checks like:

• noImplicitAny
• strictNullChecks
• strictFunctionTypes
• strictBindCallApply

These checks prevent many bugs in large codebases.

Best practice

Keep strict: true from day one. Turning it on later in a big codebase is much harder.

Caution

If you disable strict checks too often, TypeScript starts behaving like plain JavaScript and you lose its biggest value.

---

Understanding tsconfig.json in Detail

The tsconfig.json file is a configuration file that tells TypeScript how to compile your code. Think of it as the rulebook for the TypeScript compiler.

What does it control?

• Which JavaScript version to output (ES2020, ES2015, etc.)
• Module system (CommonJS, ESM, etc.)
• Where to find source files
• Where to put compiled JavaScript
• How strict type checking should be
• Which files to include or exclude

Key Requirement

TypeScript will only work properly if tsconfig.json exists in your project root. Without it, the compiler won’t know your preferences.

---

Structure of tsconfig.json

A complete tsconfig.json has three main sections:

{
  "compilerOptions": {
    // Controls how TypeScript compiles code
  },
  "include": ["src"],       // Which files to compile
  "exclude": ["node_modules", "dist"]  // Which folders to skip
}

1. compilerOptions

These are settings that control the compilation behavior:

{
  "compilerOptions": {
    "strict": true,
    "target": "ES2020",
    "module": "ESNext",
    "outDir": "./dist",
    "rootDir": "./src",
    "moduleResolution": "node",
    "declaration": true,
    "sourceMap": true,
    "noImplicitAny": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true,
    "allowJs": true,
    "forceConsistentCasingInFileNames": true
  }
}

2. include

Specifies which files TypeScript should compile:

{
  "include": [
    "src/**/*",           // All files in src folder
    "src/**/*.ts",        // Only .ts files
    "tests/**/*.test.ts"  // Include test files
  ]
}

3. exclude

Tells TypeScript which folders/files to ignore:

{
  "exclude": [
    "node_modules",
    "dist",
    "build",
    "**/*.spec.ts",
    "**/*.test.ts"
  ]
}

---

Essential Compiler Options Explained

strict

Master switch for all strict type checking. When true, enables: noImplicitAny, strictNullChecks, strictFunctionTypes, strictBindCallApply, strictPropertyInitialization, noImplicitThis.

target

What JavaScript version to output. Common values: “ES2020”, “ES2015”, “ES2022”. Higher targets = smaller output but less browser support.

module

Output module system. “ESNext” = modern import/export, “CommonJS” = require/module.exports.

moduleResolution

How to resolve import paths. “node” = npm-style resolution, “bundler” = for bundlers like webpack.

outDir

Folder where compiled .js files go. Usually ”./dist” or ”./build”.

rootDir

Tells TypeScript where source files start. Map folder structure: src/ → dist/

Less Known But Important Options

{
  "compilerOptions": {
    "declaration": true,              // Generate .d.ts files for type info
    "sourceMap": true,                // Generate .map files for debugging
    "noImplicitAny": true,            // Error if type can't be inferred
    "noUnusedLocals": true,           // Error on unused variables
    "noUnusedParameters": true,       // Error on unused function params
    "noImplicitReturns": true,        // Error if not all code paths return
    "allowJs": true,                  // Allow .js files in project
    "checkJs": false,                 // Disable type checking in .js files
    "forceConsistentCasingInFileNames": true,  // Error on mismatched import casing
    "resolveJsonModule": true,        // Allow JSON imports
    "esModuleInterop": true,          // Compatibility for CommonJS modules
    "skipLibCheck": true              // Skip type checking of .d.ts files
  }
}

---

Common Project Setups

Setup for Node.js Backend

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "CommonJS",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "moduleResolution": "node",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}

Setup for Modern Web Project

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "moduleResolution": "bundler",
    "allowJs": true,
    "skipLibCheck": true
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}

---

How to Use tsconfig.json Effectively

1. Compile Entire Project

# Uses tsconfig.json automatically
npx tsc

# Verbose output to see what's happening
npx tsc --listFiles

2. Watch Mode

npx tsc --watch
# or
npx tsc -w

Very useful during development. The compiler runs every time you save a .ts file.

3. Compile Specific File

# Even when using tsconfig.json
npx tsc src/main.ts

4. Check for Errors Without Compiling

npx tsc --noEmit

Useful in CI/CD pipelines to catch type errors without generating files.

5. Find Configuration Issues

npx tsc --showConfig

Shows the final merged configuration that TypeScript is using.

---

Best Practices for tsconfig

1. Always use strict mode

Start with "strict": true. Turning it on later in a big project is painful.

2. Separate development and production configs

You can have multiple tsconfig files:

// tsconfig.json (base)
{
  "extends": "./tsconfig.base.json",
  "include": ["src"]
}

// tsconfig.prod.json (production)
{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "sourceMap": false,    // No debug files in production
    "declaration": true    // Export type definitions
  }
}

Then compile with: npx tsc --project tsconfig.prod.json

3. Use path mapping for clean imports

Instead of: import helper from "../../../utils/helper"

Use:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@utils/*": ["src/utils/*"],
      "@types/*": ["src/types/*"]
    }
  }
}

Then: import helper from "@utils/helper"

4. Gradually enable strict checks if inheriting code

If you’re adding TypeScript to existing JavaScript:

{
  "compilerOptions": {
    "strict": false,           // Start permissive
    "noImplicitAny": true,     // Enable one rule at a time
    "allowJs": true,
    "checkJs": false
  }
}

Gradually move to full strict mode.

5. Use declaration files for third-party libraries

If a library doesn’t have types, create your own:

src/
  types/
    mylib.d.ts   // Type definitions for untyped library

Then reference in tsconfig:

{
  "compilerOptions": {
    "typeRoots": ["./node_modules/@types", "./src/types"]
  }
}

---

File Patterns: include vs exclude

Pattern Syntax

{
  "include": [
    "src/**/*",           // Everything in src (recursive)
    "src/**/*.ts",        // Only .ts files
    "src/pages/*.ts",     // Only files directly in pages/
    "src/**/*.{ts,tsx}"   // Both .ts and .tsx files
  ],
  "exclude": [
    "**/node_modules/**",
    "**/dist/**",
    "**/*.test.ts",
    "**/*.spec.ts"
  ]
}

Common Pattern Examples

{
  "include": [
    "src/**/*",
    "tests/**/*.test.ts"
  ],
  "exclude": [
    "node_modules",
    "dist",
    "build",
    ".git",
    ".vscode"
  ]
}

---

Debugging tsconfig Issues

Problem: “File not being compiled”

Check:

1. Is it in the include pattern?
2. Is it excluded by exclude?
3. Run: npx tsc --listFiles to see all files being processed

Problem: “Wrong output structure”

Check:

• rootDir correctly points to source root
• outDir is where you expect output
• File structure: src/utils/helper.ts → dist/utils/helper.js

Problem: “Module resolution failing”

Check:

• moduleResolution setting (usually "node" or "bundler")
• baseUrl for path mapping
• paths configuration for aliases

Get Full Configuration

npx tsc --showConfig -p .

Shows the complete final configuration being used.