.TS File Format – File structure

Encoding and shape

The compiler reads a file as UTF-8 unless a byte order mark says otherwise. It accepts the UTF-8 mark and the UTF-16 big-endian and little-endian marks. The mark is not copied into the output unless emitBOM is set. Output line endings follow newLine, which is lf or crlf.

A file may start with a #! line, which the compiler keeps as the first line of the JavaScript it writes. Everything else is read in order:

SourceFile:
    [Hashbang] {Comment | TripleSlashDirective} {Statement}

Statement:
    any JavaScript statement
    InterfaceDeclaration | TypeAliasDeclaration | EnumDeclaration
    NamespaceDeclaration | AmbientDeclaration
    ImportEqualsDeclaration | ExportAssignment | NamespaceExportDeclaration

The grammar blocks on these pages are informal summaries of what the compiler accepts. The extra statements are covered on their own pages: interfaces and aliases, enums, namespaces, import = and export =, and ambient declarations.

The extensions

With allowJs the compiler also reads .js, .jsx, .mjs and .cjs. With resolveJsonModule it reads .json imports.

Scripts and modules

A file is either a script, whose top-level names are global and shared with every other script, or a module, which has its own scope. Two scripts that both declare const x conflict. The moduleDetection option decides which a file is.

When the option is not set, the default is force if module is one of the Node.js modes and auto otherwise. In auto mode, a file with nothing to import or export can write export {} to become a module.

The module format of the emitted code is a separate matter, covered in Modules and namespaces.

Triple-slash directives

A triple-slash directive is a single-line comment holding one XML tag. It works only at the top of a file, with nothing before it but comments and other directives. After the first statement it is an ordinary comment (Handbook: Triple-Slash Directives).

Since 5.5 the compiler does not write these directives into its output unless they carry preserve="true", and it no longer generates them in declaration files.

/// <reference types="node" />
/// <reference lib="es2022" />
/// <reference path="./globals.d.ts" preserve="true" />

export const start = process.hrtime.bigint();

Comment directives

Files with JSX can also set the factory per file with pragma comments.

tsconfig.json

A tsconfig.json file marks the root of a project. It is JSON that also allows comments and trailing commas (TSConfig reference). The compiler looks for one in the working directory and then in each parent.

A file imported by a file in the project is part of the project even if exclude matches it. In path fields, ${configDir} (5.5) stands for the folder of the project’s own config file, which helps in shared base files.

Since 6.0, running tsc foo.ts in a folder that has a tsconfig.json is an error, TS5112. tsc --ignoreConfig foo.ts compiles the file with the command-line options alone.

{
  "compilerOptions": {
    "module": "nodenext",
    "target": "esnext",
    "outDir": "dist",
    "rootDir": "src",
    "declaration": true,
    "verbatimModuleSyntax": true
  },
  "include": ["src"]
}

Type erasure and emit

The compiler checks types and writes JavaScript, and the two steps are independent: by default it writes the output even when the checks fail, unless noEmitOnError is set. Types never affect the behaviour of the program. Most TypeScript syntax is erased completely, while a few forms generate code.

// Source
export enum Direction { Up, Down }

export class Point {
  constructor(public x: number, private readonly y = 1) {}
}

const size = (input as unknown as number)!;

// Output with target es2022
export var Direction;
(function (Direction) {
    Direction[Direction["Up"] = 0] = "Up";
    Direction[Direction["Down"] = 1] = "Down";
})(Direction || (Direction = {}));
export class Point {
    x;
    y;
    constructor(x, y = 1) {
        this.x = x;
        this.y = y;
    }
}
const size = input;

The output also depends on target, which lowers newer JavaScript syntax for older runtimes, and on module, which sets the import and export forms. jsx controls how JSX is transformed. With declaration the compiler also writes a declaration file, and with sourceMap a .js.map file.