The TypeScript file (.ts, .mts, .cts)

The basics

What is a TypeScript file?

Anatomy

What's inside a TypeScript file

A TypeScript file is JavaScript with extra syntax that describes types: what kind of value each variable, parameter and function result holds. Here is a short module, part by part. Everything that isn't plain JavaScript disappears before the code runs.

import type { User } from "./user.ts";
import { formatName } from "./format.ts";

// One of three allowed values
type Role = "admin" | "editor" | "viewer";

interface Account {
  user: User;
  role: Role;
  lastLogin?: Date;
}

export function greet(account: Account): string {
  const name: string = formatName(account.user);
  return account.lastLogin
    ? `Welcome back, ${name}`
    : `Welcome, ${name}`;
}

export function first<T>(items: readonly T[]): T | undefined {
  return items[0];
}

const roles = ["admin", "editor"] as const satisfies readonly Role[];

1. 1import type { User } from "./user.ts";

   A type-only import

   Brings in a type, not a value, so it can be removed completely. Node.js needs the type keyword here, or it looks for a value called User at run time and fails.

2. 2import { formatName } from "./format.ts";

   A value import

   An ordinary ES module import. Writing the .ts extension is what Node.js, Deno and Bun expect; for tsc it needs a setting, explained below.

3. 3type Role = "admin" | "editor" | "viewer";

   A type alias with a union

   Role may only be one of three strings. A typo such as "admim" is a compile error instead of a bug found later.

4. 4interface Account { … }

   An interface

   Describes the shape of an object: which properties it has and their types. Interfaces produce no JavaScript at all.

5. 5lastLogin?: Date;

   An optional property

   The ? means the property may be missing, so the compiler makes you check for it before use.

6. 6greet(account: Account): string

   Parameter and return types

   The colon annotations say what goes in and what comes out. Calling greet with the wrong object, or using its result as a number, is caught before running.

7. 7const name: string = …

   A variable annotation

   Optional most of the time: TypeScript infers that name is a string from what's assigned to it.

8. 8first<T>(items: readonly T[]): T | undefined

   A generic function

   T stands for whatever type the caller passes, so first([1, 2]) returns a number and first(["a"]) a string.

9. 9as const satisfies readonly Role[]

   `as const` and `satisfies`

   as const keeps the exact values instead of widening them to string[]; satisfies checks them against a type without changing it.

Under the hood

How a .ts file becomes running code

import { formatName } from "./format.ts";

// One of three allowed values








export function greet(account         )         {
  const name         = formatName(account.user);
  return account.lastLogin
    ? `Welcome back, ${name}`
    : `Welcome, ${name}`;
}

export function first   (items              )                {
  return items[0];
}

const roles = ["admin", "editor"]                                   ;

{
  "compilerOptions": {
    "noEmit": true,
    "target": "esnext",
    "module": "nodenext",
    "rewriteRelativeImportExtensions": true,
    "erasableSyntaxOnly": true,
    "verbatimModuleSyntax": true
  }
}

Extensions

.ts vs .mts vs .cts vs .d.ts vs .tsx

Project files

tsconfig.json: the file that sets up a project

{
  "compilerOptions": {
    "target": "es2022",
    "module": "nodenext",
    "strict": true,
    "outDir": "dist",
    "declaration": true,
    "sourceMap": true
  },
  "include": ["src"]
}

Related formats

TypeScript vs JavaScript files

History

TypeScript versions

Same extension

Is my .ts file TypeScript or a video?

Troubleshooting

The TypeScript errors people hit most, and what they mean

How to

How to open and edit a TypeScript file, and is it safe?

Free downloads

Sample TypeScript files to download

Free sample TypeScript files for testing compilers, runtimes, editors, linters, upload filters and MIME types. Except the one with a deliberate error, each passes tsc --noEmit in strict mode, and each runnable one runs with node (22.18+), tsx and Bun, with the same output.

Loading…

What's inside sample-app.ts

The file is commented: open it in a text editor and each numbered comment marks one of these parts. Run it with node sample-app.ts to see its three lines of output.

1. Comments 1 and 2: annotations and an interface

   Typed const and let variables, then a Product interface with a readonly property and an optional tags list.

2. Comments 3 and 4: union and object types

   A Status that can only be "pending", "paid" or "shipped", and an Order type built from the others.

3. Comments 5 to 7: functions

   Parameter and return types, a generic firstOrDefault<T>, and narrowing with typeof and === null, where TypeScript knows the exact type inside each branch.

4. Comment 8: `as const` and `satisfies`

   A catalogue checked against Product without losing its exact values, with accented product names to show UTF-8 text.

5. Comment 9: a class

   A Basket with both kinds of privacy: private (checked only by the compiler) and #totalCents (enforced by JavaScript at run time).

6. Comments 10 and 11: async code and output

   A function returning Promise<Order>, then the output: Ada's Café: 2 × Thé vert, 1 × Crème brûlée = €12.25 and two more lines.

All sample TypeScript files

• Commented sample program

  sample-app.ts · 3.3 KB (3,351 bytes)

  Types, interfaces, unions, generics, narrowing, satisfies, a class with private fields and async code, with numbered comments explaining each part. Uses only erasable syntax, so Node.js can run it directly.

  • Checking a runtime or bundler handles modern TypeScript
  • Teaching the building blocks of TypeScript
  DownloadOpen

• ES module that imports another (.mts)

  sample-main.mts · 1.1 KB (1,103 bytes)

  Imports a type with import type and values with an explicit .mts extension from sample-shapes.mts, and uses top-level await. Download both files to the same folder and run node sample-main.mts.

  • Testing module resolution and `.ts` extensions in imports
  • Checking `rewriteRelativeImportExtensions` output (`.mts` becomes `.mjs`)
  DownloadOpen

• Module that sample-main.mts imports

  sample-shapes.mts · 879 bytes

  Exports two types (a discriminated union of shapes) and two values. On its own it runs but prints nothing.

  • Testing import resolution
  • A minimal TypeScript ES module
  DownloadOpen

• Declaration file (.d.ts)

  sample-types.d.ts · 1.1 KB (1,144 bytes)

  Types only: a global variable, an overloaded function, a declare module for an untyped package and an addition to the browser's Window interface.

  • Testing tools that must treat `.d.ts` files differently
  • Showing what a declaration file looks like
  DownloadOpen

• File with one deliberate type error

  sample-type-error.ts · 1018 bytes

  Clearly labelled at the top. It runs with node and prints a wrong total, while tsc --noEmit rejects it with error TS2345. Shows that runtimes don't check types.

  • Checking a CI step or editor reports type errors
  • Demonstrating type stripping vs type checking
  DownloadOpen

• 100 KB TypeScript file (CRLF)

  sample-100kb.ts · 100 KB (102,400 bytes)

  A typed table of the Roman numerals 1 to 3,999 and a parser that checks every one, saved with Windows (CRLF) line endings and padded with comments to exactly 102,400 bytes.

  • Upload and size-limit tests
  • Line-ending handling in tools and diffs
  DownloadOpen

Ways to test with them

• Type stripping vs checking: run sample-type-error.ts with node, then with tsc --noEmit. The first prints a result; the second must fail with TS2345.
• MIME types: put sample-app.ts online and check the Content-Type your server sends. If it's video/mp2t, browsers may try to play it instead of showing the code.
• Module resolution: download sample-main.mts and sample-shapes.mts together and run them with Node.js, tsx, Deno and Bun, or compile them with tsc --rewriteRelativeImportExtensions --module nodenext.
• Upload filters and limits: some filters treat .ts as video. sample-100kb.ts is exactly 102,400 bytes, for testing a limit at the boundary.

Free to use for testing, teaching and demos, commercially or not, with no attribution needed. A link back to this page is always appreciated.

Questions

TypeScript files, frequently asked