Lesson 2.2: Installation and Configuration

Duration: 60 minutes

Learning Objectives

By the end of this lesson, you will be able to:

• Install TypeScript globally and locally in a project
• Initialize a TypeScript project with tsconfig.json
• Understand essential tsconfig.json options
• Set up a project structure for TypeScript development

Installing TypeScript

TypeScript needs to be installed using npm (Node Package Manager). You can install it globally (available everywhere) or locally (specific to a project).

Global Installation

Install TypeScript globally to use it from any directory:

npm install -g typescript

Verify the installation:

tsc --version
# Output: Version 5.x.x (or similar)

The tsc command is the TypeScript Compiler - the tool that converts TypeScript to JavaScript.

Local Installation (Recommended)

For projects, install TypeScript as a development dependency:

# Create a new project folder
mkdir my-typescript-project
cd my-typescript-project

# Initialize npm project
npm init -y

# Install TypeScript locally
npm install --save-dev typescript

This creates a package.json with TypeScript listed under devDependencies:

{
  "name": "my-typescript-project",
  "version": "1.0.0",
  "devDependencies": {
    "typescript": "^5.0.0"
  }
}

Why Local Installation?

• Version consistency: Every team member uses the same TypeScript version
• Project isolation: Different projects can use different versions
• Reproducible builds: npm install sets up everything automatically

Creating tsconfig.json

The tsconfig.json file tells TypeScript how to compile your code. Create it with:

npx tsc --init

This generates a tsconfig.json with many options (most commented out). Here is a simplified starting configuration:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

Let us understand each option.

Essential Compiler Options

target

Specifies which JavaScript version to compile to.

"target": "ES2020"

module

Defines how modules are handled.

"module": "commonjs"

strict

Enables all strict type-checking options.

"strict": true

This single option enables:

• noImplicitAny - Error on expressions with implied any type
• strictNullChecks - Null and undefined are distinct types
• strictFunctionTypes - Stricter function type checking
• And more...

Always use strict: true for new projects. It catches more bugs.

outDir and rootDir

Control where source files are and where compiled files go.

"rootDir": "./src",
"outDir": "./dist"

my-project/
├── src/           <- rootDir (TypeScript files)
│   ├── index.ts
│   └── utils.ts
├── dist/          <- outDir (compiled JavaScript)
│   ├── index.js
│   └── utils.js
└── tsconfig.json

esModuleInterop

Allows default imports from CommonJS modules.

"esModuleInterop": true

Without it:

// Must use this syntax
import * as express from 'express';

With it:

// Can use cleaner syntax
import express from 'express';

skipLibCheck

Skips type checking of declaration files (.d.ts).

"skipLibCheck": true

This speeds up compilation. Type errors in external libraries will not block your build.

Project Structure

A well-organized TypeScript project looks like this:

my-project/
├── src/
│   ├── index.ts        # Entry point
│   ├── types/          # Custom type definitions
│   │   └── index.ts
│   ├── utils/          # Utility functions
│   │   └── helpers.ts
│   └── services/       # Business logic
│       └── user.ts
├── dist/               # Compiled output (generated)
├── node_modules/       # Dependencies (generated)
├── package.json
├── package-lock.json
└── tsconfig.json

Setting Up the Structure

# Create directories
mkdir -p src/types src/utils src/services

# Create entry point
touch src/index.ts

Complete Project Setup Walkthrough

Let us create a TypeScript project from scratch.

Step 1: Create Project Directory

mkdir learn-typescript
cd learn-typescript

Step 2: Initialize npm

npm init -y

Step 3: Install TypeScript

npm install --save-dev typescript

Step 4: Create tsconfig.json

npx tsc --init

Step 5: Update tsconfig.json

Replace the generated file with a cleaner configuration:

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

Step 6: Create Source Directory

mkdir src

Step 7: Add npm Scripts

Update package.json to add useful scripts:

{
  "name": "learn-typescript",
  "version": "1.0.0",
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js",
    "dev": "tsc --watch"
  },
  "devDependencies": {
    "typescript": "^5.0.0"
  }
}

Now you can use:

• npm run build - Compile TypeScript to JavaScript
• npm start - Run the compiled code
• npm run dev - Watch for changes and recompile automatically

Additional Useful Options

sourceMap

Generates .map files for debugging.

"sourceMap": true

This lets you debug TypeScript code directly in browsers or VS Code, even though JavaScript runs.

declaration

Generates .d.ts type definition files.

"declaration": true

Useful when creating libraries that others will use with TypeScript.

noEmitOnError

Prevents output when there are errors.

"noEmitOnError": true

Ensures you only get compiled files when your code is error-free.

resolveJsonModules

Allows importing JSON files.

"resolveJsonModules": true

import config from './config.json';

console.log(config.apiUrl);

VS Code Integration

VS Code has excellent TypeScript support built-in. For the best experience:

1. Use Workspace TypeScript Version

Press Cmd/Ctrl + Shift + P, type "TypeScript: Select TypeScript Version", and choose "Use Workspace Version".

2. Recommended Extensions

• ESLint: Linting for TypeScript
• Prettier: Code formatting
• Error Lens: Inline error display

3. Settings for TypeScript

Add to .vscode/settings.json:

{
  "typescript.preferences.importModuleSpecifier": "relative",
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-prettier"
}

Exercises

Exercise 1: Create a Project

Set up a new TypeScript project called "typescript-practice":

1. Create the folder
2. Initialize npm
3. Install TypeScript
4. Create tsconfig.json
5. Set up the src folder

# Step 1
mkdir typescript-practice
cd typescript-practice

# Step 2
npm init -y

# Step 3
npm install --save-dev typescript

# Step 4
npx tsc --init

# Step 5
mkdir src
touch src/index.ts

Exercise 2: Configure tsconfig.json

Create a tsconfig.json that:

• Compiles to ES2020
• Uses strict mode
• Outputs to a "build" folder
• Sources from a "source" folder

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "outDir": "./build",
    "rootDir": "./source"
  },
  "include": ["source/**/*"],
  "exclude": ["node_modules"]
}

Exercise 3: Add npm Scripts

Add these scripts to package.json:

• compile - runs the TypeScript compiler
• watch - runs compiler in watch mode
• run - runs the compiled index.js

{
  "scripts": {
    "compile": "tsc",
    "watch": "tsc --watch",
    "run": "node dist/index.js"
  }
}

Common Configuration Patterns

For Node.js Backend

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "strict": true,
    "esModuleInterop": true,
    "outDir": "./dist",
    "rootDir": "./src"
  }
}

For Frontend (with bundler)

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "lib": ["ES2020", "DOM"],
    "strict": true,
    "jsx": "react-jsx",
    "noEmit": true
  }
}

For Library

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

Key Takeaways

1. Install TypeScript locally for project-specific version control
2. Use tsconfig.json to configure how TypeScript compiles your code
3. Enable strict: true for maximum type safety
4. Separate source and output with rootDir and outDir
5. Add npm scripts for convenient compilation commands
6. VS Code integration provides excellent TypeScript support out of the box

Resources

Next Lesson

Now that you have TypeScript set up, let us write your first TypeScript program.

Continue to Lesson 2.3: First TypeScript Program