Declaration files (.d.ts)

Types for JavaScript that has none

Much of the code a frontend app uses is plain JavaScript: an older file in your own project, or a package from npm. Plain JavaScript has no types. Here is a small library that formats prices:

export function formatPrice(price, currency = "$") {
  return currency + price.toFixed(2);
}

Lines 1 to 3 export formatPrice. It takes a price and a currency sign, "$" unless you pass another, and gives back text like $3.00. Nothing says that the price must be a number, or that the result is text. Here is a TypeScript file that uses it:

1import { formatPrice } from "./price-format";2 3const label = formatPrice(3);4//    ^?5console.log(label);

Line 1 imports formatPrice, and TypeScript marks it on purpose: Could not find a declaration file for module './price-format'. The rest of the message, implicitly has an 'any' type, means "I don't know its types, so I'll allow anything". The query on line 4 shows it: label is any, the type that switches checking off. The code still runs and prints $3.00.

The fix is a declaration file: a file whose name ends in .d.ts and that holds only types. Put one beside the JavaScript file, with the same name:

1// Types for price-format.js, which has none of its own.2export declare function formatPrice(price: number, currency?: string): string;

Line 1 is a comment. Line 2 says that price-format exports a function called formatPrice, which takes a number and an optional currency, and gives back a string. The word declare means "this exists, but its code is somewhere else", so the line ends with ; and has no body. Now cart.ts is checked:

1import { formatPrice } from "./price-format";2 3const label = formatPrice(3);4//    ^?5console.log(label);

The import on line 1 has no error, and the query on line 4 says const label: string. When you import ./price-format, TypeScript looks for price-format.ts first, then for price-format.d.ts, and finds the types there. The browser still runs price-format.js and prints $3.00.

A declaration file is something TypeScript believes. It never reads the JavaScript to check that the .d.ts is right. Pick what price-format.d.ts says, and watch what TypeScript makes of cart.ts:

1import { formatPrice } from "./price-format";2 3const label = formatPrice(3);4//    ^?5console.log(label);

price: string makes TypeScript mark correct code, because the declaration is wrong: Argument of type 'number' is not assignable to parameter of type 'string'. returns number is worse. TypeScript reports nothing and calls label a number, while the code really makes text.

What a .d.ts file holds

A declaration file holds declarations: each one says that something exists and what its type is, but not how it works. Here is price-format.d.ts with two more:

1export declare function formatPrice(price: number, currency?: string): string;2 3export declare const defaultCurrency: string;4 5export interface PriceOptions {6  currency: string;7  decimals: number;8}

• Line 1 declares a function: its parameters and return type, then ; where the body would be.
• Line 3 declares a constant, defaultCurrency, and says it holds text. It doesn't say which text: the value is in the JavaScript.
• Lines 5 to 8 are an interface, written exactly as in a .ts file, because an interface is only a type anyway.

In a .d.ts, declare after export is optional, and you'll see real files written both ways. Code that runs is never allowed. Here is the same file with two lines of code in it, on purpose:

1export declare const defaultCurrency: string = "$";2 3export function formatPrice(price: number, currency = "$"): string {4  return currency + price.toFixed(2);5}

Line 1 gives the constant a value, and TypeScript says Initializers are not allowed in ambient contexts. An ambient context is TypeScript's name for a place that only describes things, like a .d.ts file or anything after declare; an initializer is the = "$" part. Line 3 gives the function a body: An implementation cannot be declared in ambient contexts, which means "no working code in a description".

You've been using declaration files since your first TypeScript line. TypeScript comes with files like lib.es5.d.ts, which declares Math, and lib.dom.d.ts, which declares document and every other browser feature:

1const biggest = Math.max(3, 4);2//                   ^?3const button = document.querySelector("button");4//    ^?5console.log(biggest, button);

The query on line 2 points at max and shows (method) Math.max(...values: number[]): number: any number of numbers in, a number out. The query on line 4 shows that querySelector("button") gives an HTMLButtonElement or null. Neither answer comes from running anything. Both come from declarations, and line 5 prints 4 null here, because this page has no button.

The table below compares the two kinds of TypeScript file. Read each row as a question, then the answer for each.

Types for packages: @types and DefinitelyTyped

Packages from npm (the npm lesson covers installing them) get their types in one of three ways. Some ship their own .d.ts files and name them in the types field of their package.json. Some have none, and people outside the project wrote them instead. And some have no types anywhere. Say your shop celebrates an order with canvas-confetti, a popular package written in plain JavaScript:

1import confetti from "canvas-confetti";2 3confetti({ particleCount: 100, spread: 70 });

Line 1 gets the same error as before, on purpose, with a second line of advice. The list under the code shows the whole message: Try `npm i --save-dev @types/canvas-confetti` if it exists, or add a .d.ts file of your own. Line 3 fires 100 pieces of confetti spread over 70 degrees; press Edit & run, then Show page, to see them.

DefinitelyTyped is a large project on GitHub where people write declaration files for JavaScript packages. Each one is published on npm as @types/ plus the package's name. You install it as a dev dependency, because only TypeScript needs it, never the browser:

npm install canvas-confetti
npm install --save-dev @types/canvas-confetti

Line 1 installs the package itself. Line 2 installs its types into node_modules/@types/canvas-confetti, where TypeScript looks for them by itself, with nothing to set up. Here is a shortened version of what that package holds, written for this lesson: the real file declares the same function, with more options and comments.

1export interface Options {2  particleCount?: number;3  spread?: number;4  colors?: string[];5}6 7export default function confetti(options?: Options): Promise<undefined> | null;

Lines 1 to 5 describe the options object, with every option optional. Line 7 declares the package's default export: a function that takes those options and gives back a promise, or null in old browsers. With it installed, main.ts is checked:

1import confetti from "canvas-confetti";2 3const done = confetti({ particleCount: 100, spread: 70 });4//    ^?

No errors, and the query on line 4 shows const done: Promise<undefined> | null. Press Edit & run and change 100 to "lots": TypeScript marks it, because the types say particleCount is a number.

A package with a scope in its name, like @babel/core, gets types named with two underscores instead of the slash: @types/babel__core. The table below sums up where a package's types can come from. Read each row as: where the types are, what you install, and an example.

Writing a declaration for a package

When nobody has written types for a package, you write them yourself. For a file in your own project, you put a .d.ts beside it, as in the overview. For a package, you can't put files inside node_modules, because the next install would remove them. Instead you write declare module with the package's name, in a .d.ts anywhere in your project, often a types folder. Say your shop uses shop-analytics, a small package (made up for this lesson) that sends events to the shop's server and has no types:

1declare module "shop-analytics" {2  export function track(event: string, data?: Record<string, string | number>): void;3}

Line 1 says: everything up to the closing brace on line 3 describes the package called "shop-analytics". Line 2 says it exports track, which takes an event name and optional data, and gives back nothing, which TypeScript writes as void. Record<string, string | number> means an object whose values are text or numbers. You only need to declare the parts of a package you use. Try three versions of this file:

1import { track } from "shop-analytics";2 3track("add-to-cart", { product: "Tea", price: 3 });4track(42);

The short form, declare module "shop-analytics";, is a quick way to make the error go away while you write real types: it says the package exists, and makes everything in it any. With the full declaration, line 4 gets Argument of type 'number' is not assignable to parameter of type 'string', because track needs an event name.

Letting tsc write declarations

When you write a library in TypeScript, you never write its .d.ts by hand. One compiler option makes tsc write it for you, beside each .js file:

{
  "compilerOptions": {
    "declaration": true,
    "outDir": "dist"
  }
}

Line 3, "declaration": true, turns it on (the Setting up a project lesson covers tsconfig.json). Line 4 puts what tsc writes in a dist folder. Here is a library file:

1export type Currency = "$" | "€" | "£";2 3const cache = new Map<number, string>();4 5export function formatPrice(price: number, currency: Currency = "$") {6  if (!cache.has(price)) cache.set(price, price.toFixed(2));7  return currency + cache.get(price);8}

Line 1 exports a type with three currency signs. Line 3 makes a cache that only this file uses. Lines 5 to 8 export formatPrice, which keeps each formatted price in the cache. With declaration on, tsc writes this beside price-format.js:

1export type Currency = "$" | "€" | "£";2export declare function formatPrice(price: number, currency?: Currency): string;

• Line 1 is the Currency type, copied as it is.
• Line 2 is formatPrice without its body. The default = "$" became ?, which means "you can leave it out", and the return type tsc worked out, string, is now written down.
• The cache isn't there at all. It isn't exported, so code that uses the library never sees it.

tsc can do the same for a library written in JavaScript with JSDoc comments, which describe types in comments (the Types for JavaScript lesson covers JSDoc). Here is price-format.js with its types in a comment:

/**
 * @param {number} price
 * @param {string} [currency]
 * @returns {string}
 */
export function formatPrice(price, currency = "$") {
  return currency + price.toFixed(2);
}

Lines 2 to 4 say that price is a number, currency is an optional string, and the function returns a string. This command makes a .d.ts from it, and no .js:

npx tsc price-format.js --allowJs --declaration --emitDeclarationOnly --outDir types

--allowJs lets tsc read JavaScript, --declaration asks for .d.ts files, --emitDeclarationOnly skips writing JavaScript, and --outDir types puts the result in a types folder. It writes formatPrice(price: number, currency?: string): string. Last, a library tells TypeScript where its declarations are, in its package.json:

{
  "name": "price-format",
  "main": "./dist/price-format.js",
  "types": "./dist/price-format.d.ts"
}

Line 3, main, is the JavaScript that runs. Line 4, types, is the declaration file TypeScript reads. That's the first row of the table above: a package that ships its own types.

Types for an old coupons file

A shop's checkout still uses an old JavaScript file that applies coupon codes. Rewriting it in TypeScript can wait; describing it takes one line. Here is the file:

export function applyCoupon(total, code) {
  if (code === "SAVE10") return (total * 0.9).toFixed(2);
  return total.toFixed(2);
}

Line 2 takes 10% off when the code is SAVE10, and line 3 keeps the total as it is otherwise. Both lines use toFixed(2), which gives back text with two decimals. So the declaration says the function returns a string:

1export declare function applyCoupon(total: number, code: string): string;

1import { applyCoupon } from "./coupons";2 3const total = applyCoupon(10, "SAVE10");4//    ^?5console.log("You pay $" + total);

Line 3 applies SAVE10 to a total of 10. The query on line 4 shows const total: string, which matches what coupons.js really gives back, and line 5 prints You pay $9.00. Now sort some lines by whether they can go in a .d.ts file:

Common mix-ups

• "A .d.ts file makes the JavaScript safe." No. It only tells TypeScript the types. The JavaScript runs exactly as before, and a wrong .d.ts lets mistakes through.
• "TypeScript checks the .d.ts against the JavaScript." No. It never reads the JavaScript. With returns number, it called a text result a number.
• "@types packages are part of the browser's download." No. They hold only types, so the browser never gets them. That's why they are dev dependencies.
• "declare module "x"; adds types for the package." No. The short form only quiets the error. Everything from the package is any, so nothing is checked.
• "I have to write a .d.ts for my own TypeScript library." No. Turn on declaration, and tsc writes it from your code.
• "Every package needs an @types package." No. Many, like axios, ship their own types. Install @types only when TypeScript says it can't find a declaration file.

Practice exercises

Several exercises use coupons.js from the practical section, with a coupons.d.ts beside it. Press Edit & run on the starter code: TypeScript checks it with those files as you type. Try a guess first, then use the hints.

export declare const shopName: string;

export declare function cartTotal(prices: number[]): number;

export function formatTotal(total: number): string {
  return "$" + total.toFixed(2);
}

1export declare const shopName: string;2 3export declare function cartTotal(prices: number[]): number;4 5export declare function formatTotal(total: number): string;

1import { applyCoupon } from "./coupons";2 3const total = applyCoupon(20, "NONE");4console.log(total);

1import { applyCoupon } from "./coupons";2 3const total = applyCoupon(20, "NONE");4//    ^?5console.log(total);

1export function applyCoupon(total: number, code: string): string {2  if (code === "SAVE10") return (total * 0.9).toFixed(2);3  return total.toFixed(2);4}

1export declare function applyCoupon(total: number, code: string): string;

1import { applyCoupon } from "./coupons";2 3console.log(applyCoupon(10, "SAVE10"));

1export declare function applyCoupon(total: number, code: string): string;

1import { applyCoupon } from "./coupons";2 3const total = applyCoupon(10, "SAVE10");4console.log(total + 1);

1import { applyCoupon } from "./coupons";2 3const total = applyCoupon(10, "SAVE10");4console.log(Number(total) + 1);

1const TAX_RATE = 0.2;2 3export function withTax(price: number) {4  return price * (1 + TAX_RATE);5}

1export declare function withTax(price: number): number;

Check your understanding

For each question, keep two things apart: what the .d.ts tells TypeScript, and what the JavaScript really does when it runs. The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• A .d.ts file holds only types and declarations, for code that lives somewhere else. Nothing in it runs.
• declare means "this exists, but its code is somewhere else", so a declared function has no body.
• TypeScript comes with declaration files for JavaScript and the browser, like lib.dom.d.ts.
• A package either ships its own types, has an @types package from DefinitelyTyped, or needs a declaration you write with declare module.
• TypeScript believes a .d.ts without reading the JavaScript, so keep hand-written declarations honest.
• For your own TypeScript library, declaration: true makes tsc write the .d.ts files.

Coming next: Globals & module augmentation. It uses declare for global variables, adds fields to Window, and extends another package's types.