How TypeScript compiles to JavaScript - Mechanics & Internals

Overview - How TypeScript compiles to JavaScript

What is it?

TypeScript is a programming language that adds extra features like types to JavaScript. It cannot run directly in browsers or Node.js, so it needs to be converted into plain JavaScript. This conversion process is called compiling. The TypeScript compiler reads your TypeScript code and produces JavaScript code that works everywhere JavaScript runs.

Why it matters

Without compiling TypeScript to JavaScript, you couldn't use TypeScript code in real projects because browsers and servers only understand JavaScript. Compiling ensures your code is safe, easier to maintain, and compatible with all JavaScript environments. It also helps catch errors early before running the code, making development smoother and less error-prone.

Where it fits

Before learning how TypeScript compiles, you should understand basic JavaScript and what TypeScript adds, like types. After this, you can learn about configuring the compiler, using build tools, and advanced features like source maps and declaration files.

Mental Model

Core Idea

TypeScript code is transformed by a compiler into plain JavaScript code that browsers and servers can run.

Think of it like...

Imagine writing a letter in a special language only you understand (TypeScript). To send it to a friend who only understands English (JavaScript), you translate it first. The compiler is like the translator that changes your special language into English so your friend can read it.

TypeScript Source Code
       │
       ▼
  [TypeScript Compiler]
       │
       ▼
JavaScript Output Code
       │
       ▼
Runs in Browser or Node.js

Build-Up - 7 Steps

1

Foundation

What is TypeScript Compilation

Concept: Introducing the basic idea that TypeScript code is converted into JavaScript code.

TypeScript files end with .ts and contain code with extra features like types. Since browsers and Node.js only understand JavaScript, TypeScript code must be changed into JavaScript. This process is called compilation and is done by the TypeScript compiler (tsc).

Result

You get a JavaScript file (.js) that can run anywhere JavaScript runs.

Understanding that TypeScript is not directly runnable helps you see why compilation is necessary.

2

Foundation

Role of the TypeScript Compiler (tsc)

Concept: Explaining what the compiler does and how it works simply.

The TypeScript compiler reads your .ts files, checks for errors, removes type information, and produces JavaScript code. It does not add new features to JavaScript but ensures your code is safe and compatible.

Result

A JavaScript file without types but with the same logic as your TypeScript code.

Knowing the compiler removes types clarifies why JavaScript output looks like normal JavaScript.

3

Intermediate

How Types Are Removed During Compilation

🤔Before reading on: do you think types stay in the JavaScript output or are removed? Commit to your answer.

Concept: Understanding that type annotations and interfaces exist only during development and are erased in output.

TypeScript types help catch mistakes while coding but do not exist at runtime. The compiler strips out all type annotations, interfaces, and enums that don't translate directly to JavaScript. For example, a variable declared as 'let x: number' becomes 'let x' in JavaScript.

Result

JavaScript code runs without any type information, so it behaves like normal JavaScript.

Knowing types are erased explains why JavaScript output is clean and why type errors can't happen at runtime.

4

Intermediate

Configuring Compilation with tsconfig.json

🤔Before reading on: do you think the compiler always uses default settings or can you customize it? Commit to your answer.

Concept: Introducing the configuration file that controls how TypeScript compiles code.

A tsconfig.json file lets you set options like target JavaScript version (ES5, ES6), module system (CommonJS, ES Modules), and whether to generate source maps. This file tells the compiler how to produce JavaScript that fits your project needs.

Result

Customized JavaScript output that works with your environment and debugging tools.

Understanding configuration helps you control output and fix compatibility or debugging issues.

5

Intermediate

Source Maps for Debugging Compiled Code

Concept: Explaining how source maps connect compiled JavaScript back to TypeScript for easier debugging.

When you compile TypeScript, you can generate source maps. These files map the JavaScript code back to the original TypeScript lines. Debuggers use source maps to show your TypeScript code while running JavaScript, making it easier to find bugs.

Result

You can debug your original TypeScript code even though the browser runs JavaScript.

Knowing source maps bridge the gap between compiled code and source code improves debugging experience.

6

Advanced

How Declaration Files Enable Type Sharing

🤔Before reading on: do you think JavaScript files include type info or is it separate? Commit to your answer.

Concept: Understanding that TypeScript can generate separate files (.d.ts) to share type info without code.

Declaration files (.d.ts) contain only type information without JavaScript code. They let other TypeScript projects understand the types of your compiled JavaScript libraries. The compiler can generate these files automatically during compilation.

Result

Other developers can use your JavaScript code with full type safety in their TypeScript projects.

Knowing declaration files separate types from code helps you build reusable, typed libraries.

7

Expert

Compiler Internals and Incremental Compilation

🤔Before reading on: do you think the compiler recompiles everything every time or optimizes? Commit to your answer.

Concept: Exploring how the compiler works internally and speeds up repeated compilations.

The TypeScript compiler parses code into an abstract syntax tree (AST), performs type checking, and then emits JavaScript. For large projects, it uses incremental compilation to only recompile changed files, speeding up builds. It also caches type information to avoid repeated work.

Result

Faster compilation times and efficient error checking in big projects.

Understanding compiler internals explains why builds can be fast and how errors are detected precisely.

Under the Hood

The TypeScript compiler reads your source code and creates a tree-like structure called an abstract syntax tree (AST). It uses this to check types and find errors. Then it removes all type information and converts the code into JavaScript syntax. It also applies settings from tsconfig.json to decide the JavaScript version and module style. Finally, it writes the JavaScript files and optional source maps or declaration files.

Why designed this way?

TypeScript was designed to add safety and tooling to JavaScript without changing how JavaScript runs. By compiling to plain JavaScript, it ensures compatibility with all existing JavaScript environments. The separation of types and code allows gradual adoption and easy integration with JavaScript libraries. Incremental compilation was added to improve performance for large projects.

┌─────────────────────┐
│  TypeScript Source   │
│  (.ts files with     │
│  types and features) │
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│  Parser & AST       │
│  (builds code tree) │
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│  Type Checker       │
│  (finds errors)     │
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│  Code Emitter       │
│  (removes types,    │
│  generates JS)      │
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│  Output Files       │
│  (.js, .map, .d.ts) │
└─────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does TypeScript run directly in browsers? Commit to yes or no.

Common Belief: TypeScript code runs directly in browsers just like JavaScript.

Reality: Browsers do not understand TypeScript; it must be compiled to JavaScript first.

Why it matters: Trying to run TypeScript directly causes errors and confusion, blocking development.

Quick: Are types present in the JavaScript output? Commit to yes or no.

Common Belief: Type annotations remain in the compiled JavaScript code.

Reality: All type information is removed during compilation; JavaScript output has no types.

Why it matters: Expecting types at runtime leads to misunderstanding how TypeScript works and debugging issues.

Quick: Does the compiler add new JavaScript features? Commit to yes or no.

Common Belief: The TypeScript compiler adds new JavaScript features that don't exist yet.

Reality: The compiler only converts TypeScript to existing JavaScript syntax based on target settings; it does not invent new features.

Why it matters: Misunderstanding this can cause confusion about what features are safe to use in production.

Quick: Does the compiler always recompile the entire project? Commit to yes or no.

Common Belief: Every time you compile, the whole project is rebuilt from scratch.

Reality: The compiler uses incremental compilation to only recompile changed files, improving speed.

Why it matters: Not knowing this can lead to inefficient build setups and slow development cycles.

Expert Zone

1

The compiler's AST and type checker are separate stages, allowing advanced tools to hook into the process for custom analysis.

2

Declaration files (.d.ts) enable TypeScript to provide type safety for plain JavaScript libraries without modifying their code.

3

Incremental compilation relies on a cache of previous type information, which can sometimes cause stale errors if not cleaned properly.

When NOT to use

TypeScript compilation is not suitable when you need to run code directly without a build step, such as quick scripts or environments without tooling. In such cases, plain JavaScript or tools like Babel for syntax-only transpilation might be better.

Production Patterns

In production, TypeScript is often compiled as part of a build pipeline using tools like Webpack or esbuild. Source maps are generated for debugging, and declaration files are published with libraries. Incremental builds and watch mode speed up development. Strict compiler options are used to enforce code quality.

Connections

Transpilation

TypeScript compilation is a form of transpilation, converting one language version to another.

Understanding transpilation helps grasp how TypeScript fits with tools like Babel that convert modern JavaScript to older versions.

Compiler Design

TypeScript compilation follows classic compiler stages: parsing, type checking, and code generation.

Knowing compiler design principles clarifies why TypeScript compilation is efficient and how errors are detected.

Language Translation

Compiling TypeScript to JavaScript is like translating between human languages.

This cross-domain view shows how meaning is preserved while changing form, highlighting the importance of removing types like removing grammar rules.

Common Pitfalls

#1 Trying to run TypeScript files directly in the browser.

Wrong approach:

Correct approach:

Root cause:

Misunderstanding that browsers only understand JavaScript, not TypeScript.

#2 Expecting type errors at runtime in JavaScript output.

Wrong approach:

console.log(typeof myVar === 'number'); // expecting TypeScript type check here

Correct approach:

Use TypeScript during development to catch type errors; runtime JavaScript has no types.

Root cause:

Confusing compile-time type checking with runtime behavior.

#3 Not configuring tsconfig.json and getting incompatible JavaScript output.

Wrong approach:

Running tsc without tsconfig.json and targeting default ES3 output.

Correct approach:

Create tsconfig.json with "target": "ES6" to produce modern JavaScript.

Root cause:

Ignoring compiler configuration leads to unexpected output and compatibility issues.

Key Takeaways

TypeScript code must be compiled into JavaScript before running in browsers or Node.js.

The compiler removes all type information, producing clean JavaScript code.

Compiler configuration controls the JavaScript version and module system output.

Source maps connect compiled JavaScript back to TypeScript for easier debugging.

Declaration files allow sharing type information without including code.