How TypeScript Works

The five stages

First, write TypeScript source. A .ts file holds ordinary TypeScript code. A .tsx file is used when the source also contains JSX, the markup-like syntax used by tools such as React. JSX needs a suitable project configuration and transformation. Neither extension alone tells a browser how to run the source.

Second, check types: a checker reads the source and its dependencies, infers types where it can, and reports diagnostics for mismatches. Third, compile or transpile: a tool transforms source into JavaScript, removing type-only syntax and, depending on settings, transforming newer language or JSX syntax. Fourth, collect the resulting .js files. Fifth, execute that JavaScript in a compatible browser or runtime such as Node.js. A successful transformation is not proof that a full type check ran.

• TypeScript introduction
• Compare with JavaScript

See the source and the JavaScript it produces

The .ts source below declares that greet accepts and returns a string. With the settings shown later on this page, TypeScript 5.8.3 emits the JavaScript shown immediately after it. The : string annotations disappear, while the function body and call remain. The strict setting adds a "use strict" directive to this script. Running the .js file prints Hello, Codectionary.

The last line of the output is a source-map reference because sourceMap is enabled. It is a comment pointing development tools to a separate .js.map file; it does not perform a runtime type check. Exact whitespace and transformations can change with compiler versions or settings, so compare semantics and configuration rather than assuming every compiler prints identical text.

TypeScript source: src/greeting.ts

function greet(name: string): string {
  return "Hello, " + name;
}

console.log(greet("Codectionary"));

JavaScript output: dist/greeting.js

"use strict";
function greet(name) {
    return "Hello, " + name;
}
console.log(greet("Codectionary"));
//# sourceMappingURL=greeting.js.map

What the checker catches

Change the call to greet(42) and run a full project type check. The checker reports that a number cannot be passed where a string is expected. The check happens before execution; the annotation does not put an if statement into the emitted JavaScript. TypeScript may still emit files after a diagnostic unless the build is configured to stop emission, for example with noEmitOnError.

A single-file transpiler can erase types without checking how that file interacts with other files. Codectionary’s interactive TypeScript preview uses this faster transformation, so its Run button is not a substitute for a project type check. When testing a real project, check types and then test what the JavaScript does.

• Strict type checking
• Type inference

What tsc and tsconfig.json do

tsc is the TypeScript compiler command. A tsconfig.json file describes the project files and compiler options. In this small example, include selects source files, strict enables a group of stronger checks, target chooses the JavaScript language level, module chooses the module format, and outDir places emitted files in dist. The configuration below also requests source maps and prevents emission when the compiler finds errors.

After installing TypeScript locally in a project, run npx tsc --version to see the compiler actually used. With the sample file in src/greeting.ts and the configuration below at the project root, npx tsc --project tsconfig.json --noEmit performs a check without writing JavaScript. Run npx tsc --project tsconfig.json to check and emit. Avoid passing a source filename alongside --project: the project configuration supplies the included files.

Example tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "strict": true,
    "outDir": "dist",
    "sourceMap": true,
    "noEmitOnError": true
  },
  "include": ["src/**/*.ts"]
}

Check, then produce JavaScript

npx tsc --version
npx tsc --project tsconfig.json --noEmit
npx tsc --project tsconfig.json

• tsconfig.json basics
• Strict mode options

Run the result in the right environment

A browser can load dist/greeting.js from a script element in an HTML page. Node.js can run a suitable emitted file with node dist/greeting.js. The example uses console.log, which both environments provide. A program using document needs a browser page; code using Node-specific file APIs needs Node.js or another compatible environment. TypeScript types do not add those APIs.

The module option matters when a project imports or exports files. The example has no imports, so its output works as a simple script. In larger projects, choose a module format and resolution rules that match the browser, bundler or Node.js configuration you will actually use. Do not assume a .js file from one project can be copied into every environment unchanged.

Run the emitted file with Node.js

node dist/greeting.js

• Node.js on Windows
• Node.js on macOS
• Node.js on Linux

How source maps help debugging

The sourceMap option creates a .js.map file alongside emitted JavaScript. It maps positions in the running JavaScript back to the TypeScript source so a debugger can show familiar .ts lines. Source maps help you investigate runtime errors; they do not change runtime behaviour, check types or validate data. Whether a browser or debugger can use the map depends on how the files are served and configured.

Can a runtime run .ts directly?

Some modern Node.js releases can run .ts files containing erasable type syntax by stripping those types. This path does not type-check the program, does not read tsconfig.json, and does not support every TypeScript feature or .tsx file. Other runtimes and tools have their own support and limitations. Check the specific runtime version and feature set before using direct execution.

Ordinary browser script loading should use JavaScript output rather than assume that a .ts file with annotations will run. For a portable beginner workflow, keep checking, transformation and execution as distinct steps. Even when a runtime strips types automatically, run a checker separately if you want static feedback.

• Review types and runtime validation
• JavaScript and TypeScript compared

What to practise next

Change the greeting to accept a second string parameter. Predict the checker feedback when the call omits it; then update the call and confirm the JavaScript output still prints the message you expect. Repeat with a number argument and compare the compiler diagnostic with what the emitted code would do at runtime.

Once this path is clear, study basic types and type inference. Move to interfaces for object shapes, then return to tsconfig.json when you have a real multi-file project.

• Basic types
• Type inference
• Interfaces
• Compiler configuration

Syntax

TypeScript source (.ts or .tsx) → type check → JavaScript output (.js) → browser or Node.js

Examples

function greet(name: string): string {
  return "Hello, " + name;
}

console.log(greet("Codectionary"));

Best practices

• Check the full project separately from simply transforming source files.
• Match target and module settings to the runtime and build tools you actually use.
• Use source maps to inspect original source during debugging, not as a correctness check.
• Validate untrusted values at runtime even when source code has TypeScript types.

Runtime & versions

Compiled to JavaScript. Feature availability depends on the language and runtime version used by your project; consult the official reference below.

Related TypeScript documentation

Specifications & further reading

• TypeScript Handbook: The Basics
• TypeScript Handbook: JSX and .tsx files
• TypeScript Handbook: What is a tsconfig.json?
• TypeScript TSConfig: sourceMap
• TypeScript TSConfig: noEmitOnError
• Node.js documentation: Modules: TypeScript