Types in JavaScript files

A JavaScript file that checks itself

A checkout page adds 5 to a price for shipping. The price comes from a form, and a form gives you text. The project is plain JavaScript: no .ts files and no build step. TypeScript can still check it:

1// @ts-check2 3/** @param {number} price */4function addShipping(price) {5  return price + 5;6}7 8const priceFromForm = "20";9console.log(addShipping(priceFromForm));

Line 1, // @ts-check, is a comment that asks TypeScript to check this file. Line 3 is a JSDoc comment: a comment that starts with /**. Its @param {number} price says the parameter price must be a number. Lines 4 to 6 add 5 to it. Line 8 holds the price as text, the way a form gives it. Line 9 passes that text to addShipping, and TypeScript marks it, on purpose here:

• Argument of type 'string' is not assignable to parameter of type 'number' means "you're passing text to a parameter that has to be a number". An argument is the value you pass in a call.
• ts(2345) is the error's number, the same as in a .ts file.

The file is still JavaScript. The browser sees two comments, skips them, and runs the file as it is. "20" + 5 joins the two (the Type conversion lesson explains why), so line 9 prints 205. The check happens only in your editor, and in tsc when you run it.

If JSDoc is new to you, the JavaScript lesson Types for JavaScript introduces it. This lesson looks at it from TypeScript's side: what gets checked, which settings turn it on, and how it compares with a .ts file.

Turning on checking for one file

Editors like VS Code run TypeScript on JavaScript files too. They use it for autocomplete and for the types you see when you point at a name. But they don't report type errors in a .js file unless the file asks. The simplest way to ask is one comment on line 1. Try the three choices:

1// Shipping for the checkout page2 3/** @param {number} price */4function addShipping(price) {5  return price + 5;6}7 8const priceFromForm = "20";9console.log(addShipping(priceFromForm));

With A plain comment, nothing is marked, although the bug is still there. // @ts-check marks line 9. // @ts-nocheck turns reporting off for this file. Each time, the code prints 205: these comments change what TypeScript says, never what JavaScript does.

The comment only counts at the top of the file, before any code. Other comments and blank lines may come before it. Here it comes too late:

1const shopName = "Tea Corner";2// @ts-check3 4/** @type {number} */5const itemCount = "3";6console.log(shopName, itemCount);

Line 1 is code, so the // @ts-check on line 2 is only a comment. Line 5 breaks its own JSDoc, which says itemCount is a number, and nothing is marked. Line 6 prints Tea Corner 3. Press Edit & run and swap lines 1 and 2: line 5 gets Type 'string' is not assignable to type 'number'.

Once a file is checked, TypeScript works out types from values, the way it does in a .ts file. This is called inference (Annotations & inference covers it):

1// @ts-check2 3const cart = { items: 2, total: 7 };4cart.items = "3";5console.log(cart.totl);

There's no JSDoc here. Line 3 makes a cart, and TypeScript works out that items and total are numbers. Line 4 stores text in items: Type 'string' is not assignable to type 'number'. Line 5 misspells total, and the message ends with the fix: Did you mean 'total'? Both errors are on purpose. When it runs, line 5 prints undefined.

Function parameters are different. A value tells TypeScript its type, but a parameter has no value until someone calls the function:

1// @ts-check2 3function addShipping(price) {4  return price + 5;5}6 7console.log(addShipping("20"));8console.log(addShipping());

Line 3's price has no type, so TypeScript gives it the type any, which means "anything goes, check nothing" (any, unknown & never covers it). This page checks with strict on, so TypeScript reports it: Parameter 'price' implicitly has an 'any' type. Without strict, you wouldn't even get that.

Line 7 passes text and line 8 passes nothing, and neither is marked. In a JavaScript file, a parameter with no JSDoc is also optional, because plain JavaScript lets you leave arguments out. They print 205 and NaN. A JSDoc type fixes all three problems, and that's the next section.

Writing types with @type and @param

A JSDoc comment starts with /** and sits right above what it describes. It has these parts:

• Tags that start with @, like @param, which name what is being described.
• A type in curly braces, like {number}. Inside the braces you write a TypeScript type: number, string[], or "light" | "dark".

Here is a function with three tags:

1// @ts-check2 3/**4 * @param {number} price5 * @param {number} [percent=10]6 * @returns {string}7 */8function salePrice(price, percent = 10) {9  return (price - (price * percent) / 100).toFixed(2);10}11 12const label = salePrice(20);13//    ^?14console.log(label);

Line 4 says price is a number. Line 5 says percent is a number too: the square brackets make it optional, and =10 notes its default. Line 6, @returns {string}, says what the function gives back; toFixed(2) on line 9 turns a number into text with two decimals. Line 12 calls salePrice(20), so percent is 10, and the query on line 13 shows const label: string. Line 14 prints 18.00.

Point at salePrice on line 8 to see the type TypeScript built from the comment: function salePrice(price: number, percent?: number): string. That's exactly what TypeScript syntax gives:

1function salePrice(price: number, percent: number = 10): string {2  return (price - (price * percent) / 100).toFixed(2);3}4 5const label = salePrice(20);6//    ^?7console.log(label);

Line 1 holds the same three facts as the comment: a number price, a number percent that is 10 when left out, and a string result. The query on line 6 gives the same answer, const label: string, and line 7 prints 18.00.

@type gives a variable its type. To give a name to an object shape, write @typedef with one @property per property. It does the job of a type alias (Type aliases & interfaces):

1// @ts-check2 3/**4 * @typedef {object} CartItem5 * @property {string} name6 * @property {number} price7 */8 9/** @type {CartItem[]} */10const cart = [11  { name: "Tea", price: 3 },12  { name: "Cake", price: "4" },13];14console.log(cart.length);

Lines 3 to 7 name the shape CartItem: a string name and a number price. Line 9 says cart is a list of them. Line 12 gives the cake the text "4", so TypeScript marks it, on purpose: Type 'string' is not assignable to type 'number'. Line 14 prints 2.

Last, the JSDoc way to say "trust me" about a value, the job as does in TypeScript (Type assertions). Write the @type comment right before the value, and put the value in brackets:

1// @ts-check2 3const couponBox = /** @type {HTMLInputElement} */ (document.querySelector("#coupon"));4//    ^?5console.log(couponBox.value);

Line 3 looks up the coupon box. On its own, document.querySelector("#coupon") gives Element | null, because TypeScript can't tell from an id what kind of element it will find. The comment and the brackets around the call say it's an HTMLInputElement, the browser's type for an <input>, and the query on line 4 shows TypeScript believes it. Line 5 prints tea10, the value in this lesson's coupon box. Leave out the brackets and the comment is ignored. Like as, nothing checks this while the page runs.

The table below puts each JSDoc form beside its TypeScript form. Read each row as: what you want to say, how a .js file says it, and how a .ts file says it.

checkJs and allowJs for a whole project

A // @ts-check at the top of every file gets tiring. A project can turn checking on in its tsconfig.json instead (Setting up a project introduced that file):

{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": true,
    "strict": true,
    "noEmit": true
  },
  "include": ["src"]
}

Line 3, allowJs, lets .js files be part of the project. Line 4, checkJs, reports type errors in all of them, as if each began with // @ts-check. Line 5 turns on the strict checks, and line 6 says "only check, don't write any files". Line 8 includes everything in the src folder.

The two options do different jobs. Many projects have both kinds of file. Here a TypeScript file imports a JavaScript one, which has no // @ts-check. Pick a setting:

1import { addShipping } from "./shipping.js";2 3const total = addShipping(20);4//    ^?5console.log(total);6console.log(addShipping("20"));

1/** @param {number} price */2export function addShipping(price) {3  return price + 5;4}5 6/** @param {number} price */7export function shippingLabel(price) {8  return "$" + price.toFixd(2);9}

With Neither, checkout.ts can't see inside shipping.js. TypeScript reports Could not find a declaration file for module './shipping.js' on line 1, and total is any, so the wrong call on line 6 goes through. allowJs brings shipping.js into the project: its JSDoc types reach checkout.ts, total is a number, and line 6 is marked. allowJs + checkJs also reports what's wrong inside shipping.js: line 8 misspells toFixed. Setting only checkJs gives the same result as setting both, because allowJs turns on by itself when checkJs is set.

A single file can still opt out. // @ts-nocheck at its top wins over checkJs:

1// @ts-nocheck2 3/** @type {number} */4const itemCount = "3";5console.log(itemCount);

The list under the code shows this example sets checkJs: true. Line 4 breaks its @type, but line 1 turns reporting off for this file, so nothing is marked, and line 5 prints 3. That's handy for an old file you plan to fix later. Until you do, it isn't checked at all.

The table below lists every switch in this lesson. Read each row as: what you write, where it goes, and what it does.

@ts-expect-error and @ts-ignore in JavaScript

In Your first typed program you met two comments that hide one line's error. They work the same way in a checked JavaScript file. Say the old coupon form still sends prices as text, and you can't change it yet:

1// @ts-check2 3/** @param {number} price */4function addShipping(price) {5  return price + 5;6}7 8// @ts-expect-error: the old coupon form still sends text9console.log(addShipping("20"));

Line 8 says "the next line has an error, and I know", with the reason after the colon. Line 9 still passes text, but its error is hidden, so the list is empty. It still prints 205: hiding an error never fixes it. Now someone fixes line 9:

1// @ts-check2 3/** @param {number} price */4function addShipping(price) {5  return price + 5;6}7 8// @ts-expect-error: the old coupon form still sends text9console.log(addShipping(20));

Line 9 now passes the number 20 and prints 25. There's nothing left to hide, so TypeScript marks line 8 itself: Unused '@ts-expect-error' directive. A directive is a comment that gives TypeScript an instruction. The error reminds you to delete the comment.

// @ts-ignore in its place would stay quiet, and would also hide any new mistake that ever lands on line 9. That's why @ts-expect-error with a reason is the better choice, in JavaScript files as in TypeScript files. Both hide one line; // @ts-nocheck hides a whole file. Reach for them in this order: fix the code first, then @ts-expect-error with a reason, and the other two only for a short time.

A settings panel with no build step

Small sites, browser extensions, and scripts often ship their .js files exactly as written. JSDoc lets them keep that and still be checked. Here is a settings panel. The reader types a font size in a box, which holds 18 on this lesson's page:

1// @ts-check2 3/**4 * @typedef {object} Settings5 * @property {"light" | "dark"} theme6 * @property {number} fontSize7 */8 9/** @type {Settings} */10const settings = { theme: "dark", fontSize: 16 };11 12const sizeBox = /** @type {HTMLInputElement} */ (document.querySelector("#font-size"));13settings.fontSize = sizeBox.value;14settings.theme = "blue";15console.log(settings.fontSize + 2);

Lines 3 to 7 name the Settings shape: a theme that is "light" or "dark" (Literal types covers types like these), and a number fontSize. Line 10 makes the settings. Line 12 reads the box with the JSDoc cast from earlier. Line 13 stores the box's value, which is always text, where a number goes. Line 14 picks a theme that doesn't exist. Both are marked on purpose. Run it, and line 15 prints 182, because "18" + 2 joins text.

1// @ts-check2 3/**4 * @typedef {object} Settings5 * @property {"light" | "dark"} theme6 * @property {number} fontSize7 */8 9/** @type {Settings} */10const settings = { theme: "dark", fontSize: 16 };11 12const sizeBox = /** @type {HTMLInputElement} */ (document.querySelector("#font-size"));13settings.fontSize = Number(sizeBox.value);14settings.theme = "light";15console.log(settings.fontSize + 2);

Line 13 turns the text into a number with Number(…), and line 14 picks "light". No errors are left, and line 15 prints 20. The browser still runs this exact file, comments and all.

Common mix-ups

One mix-up is worth seeing in code. TypeScript's own syntax doesn't belong in a .js file:

1// @ts-check2 3let total: number = 7;4console.log(total);

Line 3 writes : number, which is TypeScript syntax. TypeScript says Type annotations can only be used in TypeScript files. The browser can't run the file at all: it stops with a SyntaxError before line 4. In a .js file, types go in JSDoc comments.

• "JSDoc comments change what my code does." No. They're comments, and the browser skips them. addShipping("20") prints 205 with or without them.
• "// @ts-check works anywhere in the file." No. It has to come before any code. After a line of code, it's only a comment.
• "allowJs checks my JavaScript files." No. It lets them into the project, so TypeScript files can use their types. checkJs or // @ts-check reports their errors.
• "To get type checking, I have to rename my files to .ts." No. A .js file with JSDoc and // @ts-check is checked too, with no build step.
• "A JSDoc cast checks the element." No. /** @type {HTMLInputElement} */ (…) is trusted, like as. If the element isn't an input box, nothing warns you.
• "@ts-ignore and @ts-expect-error are the same." No. Both hide the next line's error, but only @ts-expect-error tells you when there's nothing left to hide.

Practice exercises

Every exercise is a JavaScript file. When you fix code, press Edit & run on the starter code: TypeScript checks it as a .js file while you type, and the console shows what it prints. Try a guess first, then use the hints.

// @ts-check

/** @type {{ name: string, price: number }[]} */
const cart = [
  { name: "Tea", price: 3 },
  { name: "Cake", price: "4" },
];

1// @ts-check2 3/** @type {{ name: string, price: number }[]} */4const cart = [5  { name: "Tea", price: 3 },6  { name: "Cake", price: "4" }, // line 6: the price is text7];

1// @ts-check2 3/**4 * @param {number} count5 * @returns {string}6 */7function itemLabel(count) {8  return count === 1 ? "1 item" : `${count} items`;9}10 11const label = itemLabel(3);12console.log(label);

1// @ts-check2 3/**4 * @param {number} count5 * @returns {string}6 */7function itemLabel(count) {8  return count === 1 ? "1 item" : `${count} items`;9}10 11const label = itemLabel(3);12//    ^?13console.log(label);

1/** @param {number} quantity */2function addToCart(quantity) {3  return quantity + 1;4}5 6console.log(addToCart("2"));

1// @ts-check2 3/** @param {number} quantity */4function addToCart(quantity) {5  return quantity + 1;6}7 8console.log(addToCart(2));

1// @ts-check2 3function formatPrice(price) {4  return "$" + price.toFixed(2);5}6 7console.log(formatPrice(4.5));

1// @ts-check2 3/** @param {number} price */4function formatPrice(price) {5  return "$" + price.toFixed(2);6}7 8console.log(formatPrice(4.5));

// @ts-check

/** @param {number} price */
function addShipping(price) {
  return price + 5;
}

// @ts-expect-error: the old coupon form still sends text
console.log(addShipping(20));

1// @ts-check2 3/** @param {number} price */4function addShipping(price) {5  return price + 5;6}7 8console.log(addShipping(20));

1// @ts-check2 3const couponBox = document.querySelector("#coupon");4console.log(couponBox.value.toUpperCase());

1// @ts-check2 3const couponBox = /** @type {HTMLInputElement} */ (document.querySelector("#coupon"));4console.log(couponBox.value.toUpperCase());

Check your understanding

For each question, keep two moments apart: what TypeScript says before the code runs, and what the browser does when it runs the file. The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• TypeScript can check plain .js files. The types go in JSDoc comments, so the browser runs the file unchanged.
• // @ts-check before any code checks one file; checkJs in tsconfig.json checks them all; // @ts-nocheck opts one file out.
• allowJs lets .js files into a project, so TypeScript files can import them and use their JSDoc types.
• @param, @returns, @type, and @typedef hold TypeScript types in curly braces.
• /** @type {T} */ (value), with the brackets, is the JSDoc form of as, and it's just as unchecked.
• Prefer @ts-expect-error with a reason over @ts-ignore: it tells you when the error it hides is gone.

Coming next: Typing the DOM. It covers the types of the page itself: elements, what querySelector gives back, and the null a lookup can return.