How to Set Up Your TypeScript Development Environment

Table of Contents

1. Prerequisites
2. Step 1: Install Node.js and npm
3. Step 2: Initialize a Project
4. Step 3: Install TypeScript
5. Step 4: Configure TypeScript with tsconfig.json
6. Step 5: Set Up a Build Process
7. Step 6: Code Editor Setup (VS Code)
8. Step 7: Create and Run a Sample TypeScript File
9. Step 8: Debugging TypeScript
10. Optional Tools: Linters, Formatters, and Package Managers
11. Troubleshooting Common Issues
12. Conclusion
13. References

Prerequisites

Before starting, ensure you have:

• A basic understanding of JavaScript.
• A computer running Windows, macOS, or Linux.
• Internet access to download tools.

Step 1: Install Node.js and npm

TypeScript compiles to JavaScript, which runs on Node.js. We’ll use npm (Node Package Manager) to install TypeScript and manage dependencies.

Why Node.js and npm?

• Node.js provides a runtime for executing JavaScript outside the browser.
• npm (included with Node.js) is the default package manager for installing libraries like TypeScript.

Installation Steps:

1. Visit the Node.js official website.
2. Download the LTS (Long-Term Support) version (recommended for stability).
3. Run the installer and follow the prompts (accept defaults for most users).

Verify Installation:

Open a terminal (Command Prompt, PowerShell, or Terminal) and run:

node -v   # Should output a version like v20.10.0  
npm -v    # Should output a version like 10.2.3  

If you see errors, restart your terminal or re-install Node.js. For advanced users, consider Node Version Manager (nvm) to manage multiple Node.js versions.

Step 2: Initialize a Project

Next, create a project folder and initialize it with npm to manage dependencies and scripts.

Steps:

1. Create a project folder (e.g., typescript-starter) and navigate into it:

   mkdir typescript-starter  
   cd typescript-starter  

2. Initialize the project with npm init:

   npm init -y  

   The -y flag skips prompts and uses default values. This creates a package.json file, which tracks dependencies and scripts.

What’s in package.json?

• name: Project name (e.g., typescript-starter).
• version: Project version (default: 1.0.0).
• scripts: Custom commands (we’ll add build/run scripts here later).
• dependencies: Production dependencies (libraries your app needs to run).
• devDependencies: Development-only tools (e.g., TypeScript, linters).

Step 3: Install TypeScript

TypeScript is typically installed as a dev dependency (since it’s only needed for development, not runtime).

Install TypeScript Locally:

Run this command in your project folder:

npm install --save-dev typescript  

• --save-dev adds TypeScript to devDependencies in package.json.

Verify Installation:

Check the installed TypeScript version with:

npx tsc --version  

You should see output like Version 5.2.2.

Note: npx runs the local TypeScript compiler (tsc) without globally installing it. Avoid global installs (npm install -g typescript) unless necessary, as project-specific versions are more reliable.

Step 4: Configure TypeScript with tsconfig.json

The tsconfig.json file tells the TypeScript compiler (tsc) how to transpile your TypeScript code to JavaScript. Let’s generate and customize it.

Generate tsconfig.json:

Run:

npx tsc --init  

This creates a default tsconfig.json with hundreds of commented options. We’ll focus on key settings.

Key Configuration Options:

Open tsconfig.json in your editor and update these settings (remove comments for clarity):

{  
  "compilerOptions": {  
    "target": "ES2020",        // Output JavaScript version (ES5, ES6, ES2020, etc.)  
    "module": "CommonJS",      // Module system (CommonJS for Node.js, ESNext for browsers)  
    "outDir": "./dist",        // Where to output compiled JS files (e.g., ./dist)  
    "rootDir": "./src",        // Where your TypeScript source files live (e.g., ./src)  
    "strict": true,            // Enable all strict type-checking options (RECOMMENDED)  
    "esModuleInterop": true,   // Fixes interoperability issues between CommonJS and ES modules  
    "skipLibCheck": true,      // Skip type-checking of .d.ts files (faster builds)  
    "forceConsistentCasingInFileNames": true, // Avoids case-sensitivity bugs  
    "sourceMap": true          // Generate source maps (for debugging TS in browsers/Node.js)  
  },  
  "include": ["./src/**/*"],   // Which TS files to compile (all in ./src)  
  "exclude": ["node_modules"]  // Ignore node_modules (no need to compile dependencies)  
}  

Explanation of Key Options:

• target: Determines JS features (e.g., ES2020 supports BigInt and optional chaining).
• module: CommonJS is Node.js’s default; use ESNext if building for modern browsers with a bundler (Webpack, Vite).
• outDir: Keeps compiled JS separate from source TS (cleaner project structure).
• rootDir: Ensures tsc only compiles files in ./src (avoids accidental compilation of test files).
• strict: Enables critical checks like noImplicitAny (prevents untyped variables) and strictNullChecks (avoids null/undefined bugs).
• sourceMap: Generates .map files to map compiled JS back to TS, enabling debugging.

Step 5: Set Up a Build Process

Add npm scripts to simplify compiling TypeScript. Open package.json and update the scripts section:

"scripts": {  
  "build": "tsc",                // Compile TS to JS once  
  "build:watch": "tsc --watch"   // Auto-recompile when TS files change  
}  

How to Use:

• Run npm run build to compile all TS files in ./src to ./dist.
• Run npm run build:watch to keep the compiler running; it will recompile whenever you save a TS file (great for development).

Step 6: Code Editor Setup (VS Code)

Visual Studio Code (VS Code) is the most popular editor for TypeScript, thanks to its built-in TypeScript support, IntelliSense, and debugging tools.

Install VS Code:

Download from the VS Code website.

Essential Setup:

1. Open Your Project: Launch VS Code → File > Open Folder → Select your typescript-starter folder.

2. TypeScript Extension: VS Code has built-in TypeScript support, but ensure it’s enabled:

   • Go to Extensions (Ctrl+Shift+X or Cmd+Shift+X).
   • Search for TypeScript and JavaScript Language Features (should be pre-installed).

3. Auto-Compile on Save:

   • Go to File > Preferences > Settings (Ctrl+, or Cmd+,).
   • Search for files: auto save and set to onFocusChange (optional but helpful).
   • To auto-run tsc --watch, open a terminal in VS Code (Ctrl+`orCmd+\``) and run npm run build:watch`.

4. Formatting: Enable auto-formatting with Prettier (see Optional Tools).

Step 7: Create and Run a Sample TypeScript File

Let’s test your setup with a simple TypeScript script.

1. Create a Source Folder:

First, create the src directory (matching rootDir in tsconfig.json):

mkdir src  

2. Write a TypeScript File:

Create src/index.ts with this code:

// src/index.ts  
function greet(name: string): string {  
  return `Hello, ${name}!`;  
}  

const user = "TypeScript Developer";  
const message = greet(user);  

console.log(message); // Output: Hello, TypeScript Developer!  

• name: string enforces that greet only accepts string inputs.
• : string after the function declares the return type.

3. Compile and Run:

• Run npm run build to compile src/index.ts to dist/index.js.
• Run the JS file with Node.js:

  node dist/index.js  

  You’ll see: Hello, TypeScript Developer!

Step 8: Debugging TypeScript

Debugging TypeScript directly (without reading compiled JS) is possible with source maps and VS Code’s debugger.

Configure Debugging:

1. In VS Code, open the Run and Debug tab (Ctrl+Shift+D or Cmd+Shift+D).

2. Click “create a launch.json file” → Select “Node.js” as the environment.

3. Replace the default launch.json with:

{  
  "version": "0.2.0",  
  "configurations": [  
    {  
      "type": "node",  
      "request": "launch",  
      "name": "Debug TypeScript",  
      "runtimeArgs": ["-r", "ts-node/register"], // Run TS directly with ts-node  
      "args": ["${file}"] // Debug the currently open file  
    }  
  ]  
}  

Debug Your Script:

• Install ts-node (runs TS without pre-compiling):

  npm install --save-dev ts-node  

• Open src/index.ts, set a breakpoint (click the gutter next to a line number).
• Press F5 to start debugging. The debugger will pause at your breakpoint, allowing you to inspect variables, step through code, and more.

Optional Tools: Linters, Formatters, and Package Managers

Enhance your workflow with these tools:

ESLint (Linting):

ESLint catches code errors and enforces style rules. For TypeScript, use @typescript-eslint:

npm install --save-dev eslint @typescript-eslint/eslint-plugin @typescript-eslint/parser  

Create .eslintrc.js:

module.exports = {  
  parser: "@typescript-eslint/parser",  
  extends: ["eslint:recommended", "plugin:@typescript-eslint/recommended"],  
  rules: { /* Custom rules */ }  
};  

Add a script to package.json:

"lint": "eslint src/**/*.ts"  

Prettier (Formatting):

Prettier auto-formats code for consistency. Install:

npm install --save-dev prettier eslint-config-prettier  

Create .prettierrc:

{ "singleQuote": true, "semi": true }  

Update ESLint to work with Prettier in .eslintrc.js:

extends: [  
  "eslint:recommended",  
  "plugin:@typescript-eslint/recommended",  
  "prettier" // Disables ESLint rules conflicting with Prettier  
]  

Alternative Package Managers:

• Yarn: Faster than npm. Install with npm install -g yarn, then use yarn add instead of npm install.
• pnpm: More efficient disk usage. Install with npm install -g pnpm, then use pnpm add.

Troubleshooting Common Issues

”tsc: command not found”

• Ensure TypeScript is installed locally (npm install --save-dev typescript).
• Use npx tsc or npm scripts (npm run build) instead of tsc directly.

Compilation Errors in tsconfig.json

• Check for typos (e.g., "outDir": "./dist" instead of "outDir": "./dist").
• Delete node_modules and package-lock.json, then run npm install to reset dependencies.

Debugger Not Hitting Breakpoints

• Ensure sourceMap: true in tsconfig.json.
• Verify ts-node is installed and launch.json is configured correctly.

Conclusion

You now have a fully functional TypeScript development environment! You’ve installed Node.js, set up a project, configured TypeScript, integrated VS Code, and learned to compile, run, and debug TypeScript code.

Next steps: Explore advanced TypeScript features (generics, interfaces, utility types), experiment with bundlers like Webpack, or build a full project (e.g., a Node.js API or React app with TypeScript).

References

• TypeScript Official Documentation
• Node.js Download
• VS Code TypeScript Setup
• ESLint for TypeScript
• Prettier Documentation
• ts-node GitHub