Migrating JavaScript to TypeScript

A shop app that moves one file at a time

A small shop app is written in JavaScript. It has four files: format.js formats prices, api.js loads products from the server, cart.js adds up the cart, and checkout.js runs the checkout page. The team wants TypeScript, but they can't stop selling for a month to rewrite everything. Here are two of the files:

1export function cartTotal(cart) {2  return cart.reduce((sum, item) => sum + item.cents * item.quantity, 0);3}

Line 1 exports cartTotal, which takes a cart. Line 2 adds up each item's cents times its quantity. Prices are in cents, so 300 means $3.00.

1import { cartTotal } from "./cart";2 3const cart = [{ name: "Tea", cents: 300, qty: 2 }];4const total = cartTotal(cart);5//    ^?6console.log(total);

Line 1 imports cartTotal from cart.js. With a bundler like Vite, an import can leave out the file's extension. Line 3 makes a cart with two teas, but spells the quantity qty. Line 4 adds it up, and line 6 prints NaN, "not a number", because item.quantity is undefined.

TypeScript is already checking both files, with the settings this lesson starts from (you'll write them in step 1). It reports nothing. The query on line 5 shows why: total is any, the type that switches checking off. cartTotal doesn't say what a cart is, so TypeScript can't tell that qty is wrong. This lesson moves the app to TypeScript in small steps, and the app keeps working after every one of them:

Step 1: let TypeScript read the JavaScript

The first change touches no code at all. The project gets a tsconfig.json (Setting up a project covers the file):

1{2  "compilerOptions": {3    "allowJs": true,4    "checkJs": true,5    "strict": false,6    "noEmit": true,7    "target": "es2022",8    "module": "esnext",9    "moduleResolution": "bundler"10  },11  "include": ["src"]12}

• Line 3, allowJs, makes the .js files part of the project, so .ts files can import them.
• Line 4, checkJs, reports errors inside .js files too. Types in JavaScript files showed both options in detail.
• Line 5 keeps strict checks off for now, so renaming a file doesn't bring a flood of errors.
• Line 6 says "check only, write no files". The bundler keeps building the app exactly as before.
• Lines 7 to 9 describe where the code runs (target, lib & module), and line 11 includes the src folder.

Read each row of the table as: this setting, why it's there on day one, and when it changes.

Bundlers like Vite remove types without checking them (Type checking vs type stripping explains why), so the team adds a script that runs the checker:

1{2  "scripts": {3    "dev": "vite",4    "build": "vite build",5    "typecheck": "tsc"6  }7}

Lines 3 and 4 are the scripts the app already had. Line 5 adds typecheck: npm run typecheck runs tsc, which reads tsconfig.json, checks every file, and writes nothing. If checkJs finds more errors than the team can fix this week, they turn it off, or put // @ts-nocheck at the top of the noisiest files. Either way, the app hasn't changed.

Step 2: rename one file at a time

Now the files move, one at a time. Which one first? Look at what imports what, and start with the files that import nothing:

Once a file has types, every file that imports it is checked against them, even files that are still JavaScript (with checkJs on). Try it with cart.js and the checkout from the overview:

1export function cartTotal(cart) {2  return cart.reduce((sum, item) => sum + item.cents * item.quantity, 0);3}

1import { cartTotal } from "./cart";2 3const cart = [{ name: "Tea", cents: 300, qty: 2 }];4const total = cartTotal(cart);5//    ^?6console.log(total);

Step 2 only renames the file. With strict off, nothing new is reported, and checkout.js needs no change, because its import on line 1 has no extension. Step 3 adds a CartItem type to cart.ts, and the bug from the overview is found in checkout.js: line 4 passes items with qty, and CartItem asks for quantity. The query on line 5 now says total is a number. Step 4 fixes the spelling, and the total is 600.

Two habits keep each rename safe:

• Change only the name and the types. If a rename also rewrites code, a mistake is hard to spot. Make that a separate change.
• Merge each file on its own. A small change is quick to check, and the rest of the team keeps working.

What renaming finds

Some code that's fine in a .js file gets errors in a .ts file, even with strict off. TypeScript is more forgiving with JavaScript files, because so much JavaScript is written this way. Switch the same code between the two:

1function greet(name, greeting) {2  return `${greeting ?? "Hello"}, ${name}!`;3}4 5const order = {};6order.id = 7;7order.total = 750;8 9console.log(greet("Asha"));10console.log(order.id);

As shop.js, there are no errors. Renamed to shop.ts, lines 6, 7, and 10 get Property 'id' does not exist on type '{}' (or 'total'): line 5 made order with no properties, so its type has none. Line 9 gets Expected 2 arguments, but got 1: in a .ts file every parameter is expected unless it's marked optional with ?. The fixed version builds the order in one go on line 5 and marks greeting? optional on line 1. It prints Hello, Asha! and 7, the same as before.

These two are the errors renaming finds most often. Neither is a bug in the running code; each is a place where the code didn't say what it meant. The fixes are small, and they don't change what the code does.

Step 3: type the edges first

An edge is a place where data enters your code from outside, or passes between files:

• a reply from the server, after JSON.parse or response.json();
• values from localStorage, a form field, or the URL;
• the parameters of functions other files call, like cartTotal.

JSON.parse and response.json() give back any, and so does a parameter with no type while strict is off, like cart in cart.js. any spreads to everything made from it. One type at the edge stops that. Here is api.ts, which turns the server's reply into products:

1type Product = { id: number; name: string; cents: number };2 3const reply = '[{ "id": 1, "name": "Tea", "cents": 300 }, { "id": 2, "name": "Cake", "cents": 450 }]';4const products = JSON.parse(reply);5//    ^?6const labels = products.map((item) => `${item.nmae}: ${item.cents}`);7//    ^?8console.log(labels.join(", "));

Line 1 describes a Product, and line 3 is the reply as text. With No type at the edge, line 4 gives products the type any, and the query on line 7 shows labels is any too, so the typo nmae on line 6 goes through. Product[] at the edge changes only line 4. You wrote one type, and TypeScript worked out that labels is a string[] and marked the typo: Property 'nmae' does not exist on type 'Product'. Typo fixed prints Tea: 300, Cake: 450.

The type on line 4 is a promise about the reply, not a check: if the server sends something else, nothing stops it while the page runs. Typing fetch & JSON shows how to check a reply before you trust it. Even as a promise, it's worth writing first: the code inside your app gets real types from it, often with no annotations of its own.

Step 4: raise strictness with a to-do list

When every file is .ts, strict is still off. Strict mode options showed how to turn its checks on one at a time: noImplicitAny first, then strictNullChecks. In a big app, a check can find more errors than anyone can fix in one go. Waiting until they're all fixed leaves the check off for everyone, so new code gets the same mistakes. The other way is to turn the check on now and mark each leftover error as a to-do:

1type User = { name: string; email?: string };2const stock = new Map([["tea", 5], ["cake", 2]]);3 4function emailDomain(user: User) {5  return user.email.split("@")[1];6}7 8function stockLabel(product: string) {9  return stock.get(product).toString();10}11 12console.log(emailDomain({ name: "Asha", email: "asha@example.com" }));13console.log(stockLabel("tea"));

Step 2 turns on strictNullChecks, and lines 5 and 9 are marked. Step 3 puts a // @ts-expect-error comment above each, with TODO(strict) and a reason. A comment like this, which gives TypeScript an instruction, is called a directive. It hides the error on the next line, and the check now protects every new line of code. Step 4 shows what makes this a good to-do list: someone fixes line 11, and TypeScript marks the comment on line 10 with Unused '@ts-expect-error' directive. Step 5 deletes it, and one to-do is left.

To see the whole list, search the project for TODO(strict), with your editor's search or git grep. Each fix makes the list shorter. // @ts-ignore would hide errors too, but it never tells you when the error under it is gone, so the list would fill up with stale items (Types in JavaScript files compares the two).

When the last to-do is gone and no .js files are left, the tsconfig.json gets simpler:

1{2  "compilerOptions": {3    "strict": true,4    "noEmit": true,5    "target": "es2022",6    "module": "esnext",7    "moduleResolution": "bundler"8  },9  "include": ["src"]10}

Line 3 turns on the whole strict group. allowJs, checkJs, and "strict": false are gone. Everything else is the same as on day one.

The shop's migration plan

Here is the whole plan for the shop app, as the team might write it down. Each row is one step that can be merged on its own. Read each row as: the step, what changes, and what stays the same.

Each card below is one line from a .js file. Sort them by what happens when the file is renamed to .ts, with strict still off. Each card is checked on its own.

Common mix-ups

• "We have to stop and rewrite the app in TypeScript." No. With allowJs, JavaScript and TypeScript files work side by side, and you move one file at a time while the app keeps shipping.
• "Renaming a file to .ts changes what it does." No. The bundler removes the types, and the same JavaScript runs. Every example in this lesson prints the same output before and after.
• "allowJs checks my JavaScript files." No. It lets TypeScript read them, so their types reach the files that import them. checkJs is what reports errors inside them.
• "Start with the main file, since it matters most." No. The main file imports everything, so it would only see any. Start with the files that import nothing.
• "Once every file ends in .ts, the migration is done." No. With strict off, any can still hide mistakes. Raising strictness is the last step.
• "A type on the server reply checks the reply." No. It's a promise TypeScript believes. Checking the reply while the page runs is your code's job.

Practice exercises

Each exercise lists the settings it's checked with under the code, and some name their own file, like report.ts. Press Edit & run to change the code: the errors update as you type.

1import { firstName } from "./users";2 3const greeting = firstName({ name: "Asha Rao" });4console.log(greeting);

1import { firstName } from "./users";2 3const greeting = firstName({ name: "Asha Rao" });4//    ^?5console.log(greeting);

function shippingFor(country, express) {
  return express ? 10 : country === "IN" ? 0 : 5;
}

console.log(shippingFor("IN"));

1function shippingFor(country: string, express?: boolean) {2  return express ? 10 : country === "IN" ? 0 : 5;3}4 5console.log(shippingFor("IN"));

1const settings = {};2settings.theme = "dark";3settings.fontSize = 16;4console.log(`${settings.theme} ${settings.fontSize}`);

1const settings = { theme: "dark", fontSize: 16 };2console.log(`${settings.theme} ${settings.fontSize}`);

1type Product = { id: number; name: string; cents: number };2 3const reply = '[{ "id": 1, "name": "Tea", "cents": 300 }, { "id": 2, "name": "Cake", "cents": 450 }]';4const products = JSON.parse(reply);5const total = products.reduce((sum, item) => sum + item.cent, 0);6console.log(total);

1type Product = { id: number; name: string; cents: number };2 3const reply = '[{ "id": 1, "name": "Tea", "cents": 300 }, { "id": 2, "name": "Cake", "cents": 450 }]';4const products: Product[] = JSON.parse(reply);5const total = products.reduce((sum, item) => sum + item.cents, 0);6console.log(total);

1const stock = new Map([["tea", 5]]);2 3function stockLabel(product: string) {4  // @ts-expect-error TODO(strict): a product that isn't in stock5  return (stock.get(product) ?? 0).toString();6}7 8console.log(stockLabel("jam"));

1const stock = new Map([["tea", 5]]);2 3function stockLabel(product: string) {4  return (stock.get(product) ?? 0).toString();5}6 7console.log(stockLabel("jam"));

1function lineTotal(item, quantity) {2  return item.cents * quantity;3}4 5console.log(lineTotal({ name: "Tea", cents: 300 }, 2));

1type Product = { name: string; cents: number };2 3function lineTotal(item: Product, quantity: number) {4  return item.cents * quantity;5}6 7console.log(lineTotal({ name: "Tea", cents: 300 }, 2));

Check your understanding

Some questions name the settings they assume. The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• A migration is a series of small steps, and the app keeps working after each one.
• Step 1 adds a tsconfig.json with allowJs, strict off, and noEmit, plus a script that runs tsc.
• Rename one file at a time, starting with the files that import nothing. Change only names and types, not what the code does.
• In a .ts file, {} has no properties and every parameter is expected, even with strict off.
• Type the edges where data comes in first. One type there gives types to the code after it.
• Raise strictness one check at a time, marking leftovers with @ts-expect-error TODO(strict). TypeScript tells you when one is done.

Coming next: Reading type errors. It reads long compiler messages from the bottom up, like the ones a migration brings, and fixes the most common ones.