Core Code
Core Code Modern Dev Handbook

Setting Up TypeScript

Learn how to install and configure TypeScript for real-world projects. Proper setup ensures reliable compilation, strict type checking, and a scalable development workflow.
On this page

How TypeScript Works

TypeScript does not run directly in the browser or Node.js. Instead, it compiles to standard JavaScript. This means your development workflow includes an extra step: writing TypeScript, then compiling it into JavaScript before execution. The compiler checks types and reports errors during this process.

Installing TypeScript

The recommended way to use TypeScript in modern projects is through npm. Install it locally inside your project to ensure consistent versions across environments.

npm init -y
npm install typescript --save-dev

This installs TypeScript as a development dependency, meaning it is required during development but not shipped to production.

Creating a tsconfig.json File

The tsconfig.json file controls how TypeScript compiles your project. It defines compiler options, included files, strictness rules, and output directories.

npx tsc --init

This generates a default configuration file. You can then customize it for your project’s needs.

Understanding Key Compiler Options

  • target: Specifies which JavaScript version to compile to.
  • module: Defines the module system (ESM, CommonJS, etc.).
  • rootDir: The source directory for TypeScript files.
  • outDir: Where compiled JavaScript files are emitted.
  • strict: Enables strict type checking for maximum safety.

A Practical tsconfig Example

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "CommonJS",
    "rootDir": "./src",
    "outDir": "./dist",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

This configuration enables strict type checking and separates source code from compiled output, which is essential in production environments.

Compiling TypeScript

To compile your project manually, run:

npx tsc

This reads your tsconfig.json file and outputs compiled JavaScript into the configured directory.

Watch Mode for Development

During development, you usually want automatic recompilation whenever a file changes.

npx tsc --watch

Watch mode improves productivity by continuously checking types and compiling updated files.

Project Structure Best Practice

A clean separation between source and build output improves maintainability.

project/
  src/
    index.ts
  dist/
  tsconfig.json
  package.json

Never edit compiled files in the dist directory. Treat them as generated output.

Using TypeScript with Node.js

For backend development, you can compile first and then run the generated JavaScript with Node:

node dist/index.js

Alternatively, tools like ts-node allow you to run TypeScript directly during development.

Editor Integration

Modern editors such as VS Code have built-in TypeScript support. Once TypeScript is installed, your editor provides autocomplete, error highlighting, and intelligent navigation automatically.

Common Setup Mistakes

  • Not enabling strict mode in production projects.
  • Mixing compiled files with source files.
  • Installing TypeScript globally and causing version mismatches.
  • Ignoring compiler warnings instead of fixing them.

Production Mindset

TypeScript setup is not just about making it work. It is about configuring a predictable, strict, and scalable environment from the beginning. A well-configured project reduces bugs, simplifies onboarding, and improves long-term maintainability.

Basic Types →