Setting Up Your TypeScript Development Environment

Setting Up Your TypeScript Development Environment#

Setting up TypeScript properly is crucial for a smooth development experience. A well-configured environment catches errors instantly, provides excellent autocomplete, and makes your code more maintainable. This guide covers everything you need to go from zero to a production-ready TypeScript setup.

Prerequisites

Before installing TypeScript, ensure you have the following:

Required:

• Node.js (version 18.x or higher recommended)
• npm (comes with Node.js) or yarn
• A code editor (Visual Studio Code recommended)

Verify Your Installation:

node --version  # Should show v18.x.x or higher
npm --version   # Should show 9.x.x or higher

If you don't have Node.js installed, download it from nodejs.org (opens in new tab). The LTS (Long Term Support) version is recommended for most users.

Installing TypeScript

TypeScript can be installed globally on your system or locally within individual projects. Each approach has its use case.

Global Installation

Installing TypeScript globally allows you to use the tsc command anywhere on your system, which is useful for quick experiments and learning.

npm install -g typescript

Verify the installation:

tsc --version  # Should show version 5.x.x

Project-Specific Installation

For real projects, install TypeScript as a development dependency. This ensures everyone on your team uses the same TypeScript version.

# Navigate to your project directory
cd my-project
 
# Initialize npm if you haven't already
npm init -y
 
# Install TypeScript as a dev dependency
npm install --save-dev typescript

This adds TypeScript to your package.json:

{
  "devDependencies": {
    "typescript": "^5.3.0"
  }
}

You can now use TypeScript through npm scripts or npx:

npx tsc --version

Creating Your First TypeScript Project

Let's create a properly structured TypeScript project from scratch.

mkdir my-typescript-project
cd my-typescript-project

npm init -y

npm install --save-dev typescript

npx tsc --init

The tsc --init command creates a tsconfig.json file with sensible defaults and helpful comments explaining each option.

Understanding tsconfig.json

The tsconfig.json file is the heart of your TypeScript configuration. It tells the TypeScript compiler how to process your code.

Here's a recommended starter configuration:

{
  "compilerOptions": {
    /* Language and Environment */
    "target": "ES2022",
    "lib": ["ES2022"],
    
    /* Modules */
    "module": "commonjs",
    "rootDir": "./src",
    "moduleResolution": "node",
    "baseUrl": "./",
    "paths": {
      "@/*": ["src/*"]
    },
    
    /* Emit */
    "outDir": "./dist",
    "removeComments": true,
    "sourceMap": true,
    
    /* Interop Constraints */
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    
    /* Type Checking */
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    
    /* Completeness */
    "skipLibCheck": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Essential Compiler Options

Let's break down the most important options:

target Specifies which JavaScript version to compile to. Use ES2022 or ES2020 for modern environments, ES5 for older browser support.

"target": "ES2022"  // Modern JavaScript features

module Defines the module system. Use commonjs for Node.js, ES2022 or ESNext for modern bundlers.

"module": "commonjs"  // For Node.js projects
"module": "ES2022"    // For browser/bundler projects

rootDir and outDir Specify where TypeScript finds source files and where it outputs compiled JavaScript.

"rootDir": "./src",   // TypeScript source files
"outDir": "./dist"    // Compiled JavaScript output

sourceMap Generates source maps that help you debug TypeScript code in the browser or Node.js, even though it's running as JavaScript.

"sourceMap": true  // Essential for debugging

Strict Mode Options

TypeScript's strict flag enables all strict type-checking options. This is highly recommended for new projects:

"strict": true

This single flag enables:

• strictNullChecks - null and undefined must be explicitly handled
• strictFunctionTypes - function parameter types are checked contravariantly
• strictBindCallApply - bind, call, and apply are type-checked
• strictPropertyInitialization - class properties must be initialized
• noImplicitAny - variables must have explicit types when inference fails
• noImplicitThis - this must have an explicit type

You can also enable additional checks:

"noUnusedLocals": true,        // Error on unused variables
"noUnusedParameters": true,     // Error on unused function parameters
"noImplicitReturns": true,      // All code paths must return a value
"noFallthroughCasesInSwitch": true  // Switch cases must break or return

Module Resolution

For larger projects, path mapping improves import statements:

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

This allows clean imports:

// Instead of this:
import { Button } from '../../../components/Button';
 
// You can write this:
import { Button } from '@components/Button';

Configuring Your IDE

A properly configured IDE transforms your TypeScript development experience. Visual Studio Code has the best TypeScript support out of the box.

Visual Studio Code Setup

VS Code includes TypeScript support by default, but you can optimize it further.

Select TypeScript Version: Press Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux), type "TypeScript: Select TypeScript Version," and choose "Use Workspace Version" to use your project's TypeScript installation.

Essential VS Code Extensions

Install these extensions for the best experience:

ESLint Lints your TypeScript code for quality and consistency.

code --install-extension dbaeumer.vscode-eslint

Prettier Automatically formats your code on save.

code --install-extension esbenp.prettier-vscode

Error Lens Shows TypeScript errors inline next to your code, not just in the problems panel.

code --install-extension usernamehw.errorlens

Pretty TypeScript Errors Makes TypeScript error messages more readable and understandable.

code --install-extension yoavbls.pretty-ts-errors

Workspace Settings

Create a .vscode/settings.json file in your project:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.enablePromptUseWorkspaceTsdk": true,
  "files.exclude": {
    "**/.git": true,
    "**/.DS_Store": true,
    "**/node_modules": true,
    "dist": true
  }
}

This configuration:

• Formats code automatically on save
• Uses Prettier as the default formatter
• Fixes ESLint issues on save
• Uses your project's TypeScript version
• Hides build output and dependencies from the file explorer

Project Structure Best Practices

A well-organized project structure makes your code easier to navigate and maintain:

my-typescript-project/
├── src/
│   ├── index.ts          # Main entry point
│   ├── types/
│   │   └── index.ts      # Shared type definitions
│   ├── utils/
│   │   └── helpers.ts    # Utility functions
│   ├── services/
│   │   └── api.ts        # Business logic
│   └── constants/
│       └── config.ts     # Configuration constants
├── dist/                 # Compiled JavaScript (gitignored)
├── node_modules/         # Dependencies (gitignored)
├── tests/
│   └── index.test.ts     # Test files
├── .gitignore
├── package.json
├── tsconfig.json
└── README.md

Create this structure:

mkdir -p src/{types,utils,services,constants} tests
touch src/index.ts .gitignore

Add to .gitignore:

node_modules/
dist/
*.log
.DS_Store
.env

Compiling and Running TypeScript

Now that everything is set up, let's compile and run TypeScript code.

Create a simple TypeScript file (src/index.ts):

interface User {
  name: string;
  age: number;
}
 
function greetUser(user: User): string {
  return `Hello, ${user.name}! You are ${user.age} years old.`;
}
 
const user: User = {
  name: "Alice",
  age: 30
};
 
console.log(greetUser(user));

Compile the code:

npx tsc

This creates dist/index.js. The compiled JavaScript looks like this:

"use strict";
function greetUser(user) {
    return `Hello, ${user.name}! You are ${user.age} years old.`;
}
const user = {
    name: "Alice",
    age: 30
};
console.log(greetUser(user));

Run the compiled code:

node dist/index.js
# Output: Hello, Alice! You are 30 years old.

Adding Scripts to package.json

Make common tasks easier by adding npm scripts to your package.json:

{
  "name": "my-typescript-project",
  "version": "1.0.0",
  "scripts": {
    "build": "tsc",
    "watch": "tsc --watch",
    "start": "node dist/index.js",
    "dev": "tsc && node dist/index.js",
    "clean": "rm -rf dist"
  },
  "devDependencies": {
    "typescript": "^5.3.0"
  }
}

Use these scripts:

npm run build    # Compile TypeScript
npm run watch    # Compile on file changes
npm run start    # Run compiled code
npm run dev      # Compile and run
npm run clean    # Remove compiled files

For a better development experience, install ts-node to run TypeScript directly without compiling:

npm install --save-dev ts-node

Add a dev script:

"scripts": {
  "dev": "ts-node src/index.ts"
}

Now you can run TypeScript files directly:

npm run dev

Common Setup Issues and Solutions

Here are solutions to problems you might encounter:

"Cannot find module" errors Make sure moduleResolution is set to "node" in tsconfig.json and you've installed all dependencies.

Types not found for packages Install type definitions for packages that don't include them:

npm install --save-dev @types/node @types/express

VS Code not recognizing TypeScript version Select the workspace TypeScript version: Cmd+Shift+P → "TypeScript: Select TypeScript Version" → "Use Workspace Version"

Compilation errors about lib files Make sure your lib setting in tsconfig.json matches your target environment:

"lib": ["ES2022"]  // For modern environments
"lib": ["ES2015", "DOM"]  // For browser projects

Path aliases not working at runtime Path aliases only work during compilation. For Node.js, use tsconfig-paths:

npm install --save-dev tsconfig-paths

Then import it at the top of your entry file:

import 'tsconfig-paths/register';

Next Steps

You now have a fully configured TypeScript development environment! Here's what to explore next:

Immediate Next Steps:

• Write your first TypeScript code with basic type annotations
• Learn about TypeScript's primitive types and type inference
• Understand interfaces and type aliases
• Explore function types and optional parameters

As You Progress:

• Set up ESLint and Prettier for code quality
• Add testing with Jest or Vitest
• Configure a bundler (Webpack, Vite, or esbuild)
• Learn about advanced TypeScript features

Questions about your TypeScript setup? Having trouble with configuration? Leave a comment below or reach out—I'm happy to help!