Modules & type imports

Types that travel between files

A shop app isn't one long file. One file describes a product, another shows the cart, another handles checkout. In JavaScript, files share values with export and import (the import and export lesson covers how). In TypeScript, files share types the same way. Here is a file that describes a product:

1export type Product = { name: string; price: number };2 3export interface CartItem {4  product: Product;5  quantity: number;6}7 8export function formatPrice(price: number) {9  return "$" + price.toFixed(2);10}

Line 1 exports a type alias called Product: a name and a price. Lines 3 to 6 export an interface called CartItem: a product and how many of it. Lines 8 to 10 export a function, formatPrice, that turns a price like 3 into the text $3.00. The word export works the same in front of all three. Another file can now use them:

1import { Product, formatPrice } from "./product";2 3const tea: Product = { name: "Tea", price: 3 };4console.log(tea.name, formatPrice(tea.price));

Line 1 imports Product and formatPrice from "./product", which means the file product.ts in the same folder. You leave out the .ts, as you would in a project built with a tool like Vite. Line 3 uses Product as the type of tea, so TypeScript checks that the tea has a name and a price. Line 4 calls formatPrice and prints Tea $3.00. Point at Product on line 1: TypeScript shows the type it brought in from product.ts. Press Edit & run, and cart.ts runs with product.ts beside it.

One import brought in two very different things. formatPrice is a value: real code that the browser loads from product.js and runs. Product is only a type. Types are removed before the browser runs anything (the How TypeScript works lesson shows how), so product.js has no Product in it at all. This lesson is about what that means for your imports.

Exporting and importing types

To share a type, put export in front of it, as product.ts does on lines 1 and 3. To use it, import it by name. Here is a checkout file that uses the CartItem interface:

1import { CartItem, formatPrice } from "./product";2 3const item: CartItem = {4  product: { name: "Cake", price: 4 },5  quantity: 2,6};7const total = item.product.price * item.quantity;8//    ^?9console.log(formatPrice(total));

Line 1 imports the CartItem interface and the formatPrice function. Lines 3 to 6 make an item that must match CartItem: a cake at 4, twice. Line 7 multiplies the price by the quantity, and the query on line 8 shows const total: number. Line 9 prints $8.00. Inside checkout.ts, an imported type works exactly like a type written in the same file.

Two things follow. A type without export stays private to its file. And when a type changes, every file that imports it is checked against the new version. Try both: each button changes line 1 of product.ts, and TypeScript checks cart.ts against it.

1export type Product = { name: string; price: number };2 3export interface CartItem {4  product: Product;5  quantity: number;6}7 8export function formatPrice(price: number) {9  return "$" + price.toFixed(2);10}

1import { Product, formatPrice } from "./product";2 3const tea: Product = { name: "Tea", price: 3 };4console.log(tea.name, formatPrice(tea.price));

No export keeps Product inside product.ts. cart.ts gets Module '"./product"' declares 'Product' locally, but it is not exported, which means "product.ts has a Product, but keeps it to itself". export interface works just like export type: the importing file doesn't care which one it gets. Remove price changes only product.ts, yet TypeScript marks lines 3 and 4 of cart.ts. In every state the code still prints Tea $3.00, because types don't change what runs.

Every export is a type, a value, or both, and that decides what's left of it in the JavaScript. Read each row as: what a file exports, which kind of thing it is, and what the browser gets.

The last row needs an example. A class makes both a type and a value with one name:

1export class ShoppingCart {2  items: string[] = [];3  add(name: string) {4    this.items.push(name);5  }6}

Line 1 exports a class, ShoppingCart. Another file can write cart: ShoppingCart to use it as a type, and new ShoppingCart() to make a real cart when the code runs (the Classes in TypeScript lesson covers classes). Lines 2 to 5 give each cart a list of items and an add method. Exercise 6 imports it.

import type: an import that disappears

When TypeScript removes the types from cart.ts, what happens to line 1? Here is what the browser gets:

import { formatPrice } from "./product";

const tea = { name: "Tea", price: 3 };
console.log(tea.name, formatPrice(tea.price));

Line 1 has lost Product. TypeScript saw that Product is only used as a type, in line 3's : Product, so it dropped the name from the import. That's exactly right: product.js has no Product to give. formatPrice stays, because line 4 calls it. Line 3 has lost its : Product too, and the code still prints Tea $3.00.

You can also say it yourself. import type is an import that brings only types:

1import type { Product } from "./product";2import { formatPrice } from "./product";3 4const tea: Product = { name: "Tea", price: 3 };5console.log(tea.name, formatPrice(tea.price));

Line 1 imports Product with import type. Line 2 imports formatPrice with a plain import, because it's a value. Checking doesn't change: line 4 must still be a Product. When the types are removed, line 1 goes away completely, and the code prints Tea $3.00.

Why write type if TypeScript drops type imports anyway? Two reasons. Anyone reading line 1 knows at once that it loads nothing when the code runs. And some build tools can't work it out the way TypeScript did, so they need the mark; the next section shows them. The opposite mistake gets an error. Here formatPrice is imported with import type, on purpose:

1import type { Product, formatPrice } from "./product";2 3const tea: Product = { name: "Tea", price: 3 };4console.log(tea.name, formatPrice(tea.price));

TypeScript marks line 4: 'formatPrice' cannot be used as a value because it was imported using 'import type'. In plain words: "you said this import brings only types, but you're calling it like a function". Run it anyway, and the whole of line 1 is gone, so it stops with ReferenceError: formatPrice is not defined.

There's a shorter way to mix the two: put type in front of one name inside the braces, import { type Product, formatPrice } from "./product";. Try every form yourself. Type line 1 of cart.ts and watch the list under the code:

1import { Product, formatPrice } from "./product";2 3const tea: Product = { name: "Tea", price: 3 };4console.log(tea.name, formatPrice(tea.price));

With type after import, line 4 can't call formatPrice. With type in front of Product, there are no errors, and the browser's line 1 is import { formatPrice } from "./product";. Without Product in the braces, line 3 gets Cannot find name 'Product', and a misspelled path gets Cannot find module './products' or its corresponding type declarations.

The table below sums up the three forms. Each line ends in from "./product";, left out to keep the table short. Read each row as: the import line, what it brings, and what the JavaScript keeps.

verbatimModuleSyntax: what you write is what you get

The TypeScript compiler, tsc, reads every file in your project, so it knows that Product is a type. Many build tools work differently. Tools like Vite, esbuild, and SWC turn each .ts file into JavaScript on its own, one file at a time and without checking types, because that's fast (the Bundlers lesson explains what they do). A tool that sees one file can't always tell a type from a value. Here is a file where that goes wrong:

1// shop.ts passes on what product.ts exports.2export { Product, CartItem, formatPrice } from "./product";

Line 2 passes on three names from product.ts, so other files can import them all from shop.ts. This is called a re-export. TypeScript reports no errors: tsc read product.ts and knows to drop the two types. A tool that sees only this file can't know which names are types, so it keeps line 2 exactly as it is. Press Edit & run: this page removes types one file at a time too, and the browser stops with a SyntaxError saying that the module doesn't provide an export named Product.

Here is why. This is product.ts after its types are removed. Only the function is left:

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

Lines 1 to 3 are the formatPrice function, without : number. There's no Product and no CartItem, so nothing can import them from it when the code runs.

The fix is a compiler option, verbatimModuleSyntax, which you turn on in tsconfig.json (the Setting up a project lesson covers that file). "Verbatim" means "word for word". With it on, the rule is simple: an import or export without type stays in the JavaScript exactly as you wrote it, and one with type is removed. A type must never reach the browser, so TypeScript now makes you mark every type. Here is shop.ts again with the option on:

1// shop.ts passes on what product.ts exports.2export { Product, CartItem, formatPrice } from "./product";

The list under the code shows the option this example sets. TypeScript marks line 2 twice, once for each type, on purpose: Re-exporting a type when 'verbatimModuleSyntax' is enabled requires using 'export type'. In plain words: "this passes on a type, so write export type".

1// shop.ts passes on what product.ts exports.2export type { Product, CartItem } from "./product";3export { formatPrice } from "./product";

Line 2 passes on the two types with export type, and line 3 passes on formatPrice. There are no errors, and any tool can now tell what to remove: line 2 goes, line 3 stays. Now try the option on an import. Pick a way to write line 1 of cart.ts, then turn verbatimModuleSyntax on and off:

1import { Product, formatPrice } from "./product";2 3const tea: Product = { name: "Tea", price: 3 };4console.log(tea.name, formatPrice(tea.price));

With the option off, the plain import is fine, because tsc drops Product for you. With it on, tsc keeps the line word for word, and TypeScript reports 'Product' is a type and must be imported using a type-only import when 'verbatimModuleSyntax' is enabled: mark it with type. import { type Product, formatPrice } is fine either way, so it's the habit worth keeping. A new Vite project already turns verbatimModuleSyntax on in its tsconfig. An older option, isolatedModules, reports the same re-export error (the target, lib & module lesson covers it).

Modules and scripts

TypeScript, like JavaScript, has two kinds of files. A module has at least one import or export at the top level. A script has none. The difference is where the names a file declares at the top live (the Scope lesson explains scope). In a module, they stay inside the file. In a script, they go into the global scope, which every script on the page shares.

This site checks every example as a module unless it says otherwise, the way a new Vite project does with moduleDetection: "force". The next examples set moduleDetection: "auto", TypeScript's own default, so a file with no import or export is a script:

1const name = "Asha";2console.log("Hello, " + name);

Lines 1 and 2 have no import or export, so this is a script, and name would be global. But every browser page already has a global name: the browser window's own name, also called window.name. TypeScript knows it from the browser's types and marks line 1 on purpose: Cannot redeclare block-scoped variable 'name' means "this scope already has a name, and const can't make a second one". The code still prints Hello, Asha when it runs, but the error is a sign the file isn't what you meant.

1const name = "Asha";2console.log("Hello, " + name);3 4export {};

Line 4, export {};, exports nothing. But one export is enough to make the file a module, so name now belongs to this file alone, and the error is gone. It prints Hello, Asha.

Two scripts clash with each other in the same way. Here is a checkout script on its own:

1const total = 7;

Line 1 declares total, and on its own the file is fine. Now a cart script in the same project:

1const total = 3;2console.log(total);

Line 1 declares a total too. Both files are scripts, so both totals land in the same global scope, and TypeScript marks line 1: Cannot redeclare block-scoped variable 'total'. Add export {}; to either file and that file gets its own total.

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

One types file for a shop app

Real projects often keep the types that many files share in one file of their own, such as types.ts:

1export type Product = { id: number; name: string; price: number };2 3export interface CartItem {4  product: Product;5  quantity: number;6}7 8export type Order = { items: CartItem[]; paid: boolean };

Line 1 exports Product, now with an id. Lines 3 to 6 export CartItem, and line 8 exports Order: a list of cart items and whether it's paid. Every line is a type, so nothing in this file runs. tsc writes just export {}; for it: a module that exports nothing. Here is a file that uses it, in a project with verbatimModuleSyntax on:

1import type { CartItem, Order } from "./types";2 3function orderTotal(order: Order) {4  let total = 0;5  for (const item of order.items) total += item.product.price * item.quantity;6  return total;7}8 9const items: CartItem[] = [10  { product: { id: 1, name: "Tea", price: 3 }, quantity: 2 },11  { product: { id: 2, name: "Cake", price: 4 }, quantity: 1 },12];13console.log(orderTotal({ items, paid: false }));

Line 1 brings in CartItem and Order with import type, as the option requires. Lines 3 to 7 add up an order: each item's price times its quantity. Lines 9 to 12 hold two teas at 3 and one cake at 4, and line 13 prints 10. Because order.ts imports only types from types.ts, the browser never loads types.js at all. Now sort some import lines the way TypeScript would:

Common mix-ups

• "import type loads the file, then skips the types." No. The whole line is removed, so nothing is loaded for it when the code runs.
• "A type is exported in the JavaScript, like a function." No. Types are removed, so product.js exports only formatPrice. That's why a re-exported type can break in the browser.
• "Every import needs the word type." No. Only names that are types need it. A function, a constant, or a class you call with new needs a plain import, or the code can't use it.
• "No error from tsc means every build tool will make working JavaScript." No. tsc sees every file; a tool that sees one file at a time may keep a type it can't recognize. verbatimModuleSyntax makes you mark every type, so every tool gets it right.
• "verbatimModuleSyntax changes how my types are checked." No. It changes which import lines stay in the JavaScript, and asks you to mark types so that it stays safe.
• "Every .ts file is a module." No. By default, a file needs a top-level import or export. Without one it's a script, and its names are global, unless your tsconfig sets moduleDetection: "force".

Practice exercises

Most exercises are files beside product.ts from the overview, and exercise 6 sits beside shopping-cart.ts. Press Edit & run on the starter code: TypeScript checks it with those files as you type, and it runs with them. Try a guess first, then use the hints.

import type { CartItem, formatPrice } from "./product";

const item: CartItem = { product: { name: "Tea", price: 3 }, quantity: 2 };
console.log(formatPrice(item.product.price * item.quantity));

1import { type CartItem, formatPrice } from "./product";2 3const item: CartItem = { product: { name: "Tea", price: 3 }, quantity: 2 };4console.log(formatPrice(item.product.price * item.quantity));

1import { CartItem, formatPrice } from "./product";2 3const item: CartItem = { product: { name: "Cake", price: 4 }, quantity: 3 };4console.log(formatPrice(item.product.price * item.quantity));

1import { formatPrice } from "./product";2 3const item = { product: { name: "Cake", price: 4 }, quantity: 3 };4console.log(formatPrice(item.product.price * item.quantity));

1import { CartItem, Product, formatPrice } from "./product";2 3const tea: Product = { name: "Tea", price: 3 };4const item: CartItem = { product: tea, quantity: 2 };5console.log(`${tea.name} x${item.quantity}: ${formatPrice(tea.price * item.quantity)}`);

1import { type CartItem, type Product, formatPrice } from "./product";2 3const tea: Product = { name: "Tea", price: 3 };4const item: CartItem = { product: tea, quantity: 2 };5console.log(`${tea.name} x${item.quantity}: ${formatPrice(tea.price * item.quantity)}`);

1const name = "Asha";2const status = "signed in";3console.log(`${name} is ${status}`);

1const name = "Asha";2const status = "signed in";3console.log(`${name} is ${status}`);4 5export {};

1export { CartItem, Product, formatPrice } from "./product";2export const shopName = "Corner Shop";

1export { type CartItem, type Product, formatPrice } from "./product";2export const shopName = "Corner Shop";

1import type { ShoppingCart } from "./shopping-cart";2 3const cart: ShoppingCart = new ShoppingCart();4cart.add("Tea");5console.log(cart.items.length);

1import { ShoppingCart } from "./shopping-cart";2 3const cart: ShoppingCart = new ShoppingCart();4cart.add("Tea");5console.log(cart.items.length);

Check your understanding

For each question, ask two things: is this name a type or a value, and what is left of the line once the types are removed? The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• A file with a top-level import or export is a module. Its names stay inside it unless it exports them.
• Export a type alias or an interface with export, and import it by name, just like a value.
• Types are removed from the JavaScript, so a type name can't be loaded from another file when the code runs.
• import type brings only types and is removed whole. import { type X, y } marks one name.
• Tools that see one file at a time can't tell a type from a value. verbatimModuleSyntax makes you mark every type, so the JavaScript is exactly what you wrote.
• A file with no import or export is a script, and its names are global. export {}; makes it a module.

Coming next: Declaration files (.d.ts). It shows how TypeScript knows the types of JavaScript libraries that have no types of their own.