target, lib & module

Three settings that describe where your code runs

A shop page shows the newest item in the cart. The code is plain JavaScript that every current browser runs. Yet in this project, TypeScript marks it, on purpose here:

1const cart = ["tea", "cake", "jam"];2const newest = cart.at(-1);3console.log(`Newest item: ${newest}`);

Line 1 makes a cart of three items. Line 2 reads the last one with .at(-1), a method that counts from the end of an array. Line 3 prints Newest item: jam when it runs. TypeScript marks line 2:

• Property 'at' does not exist on type 'string[]' means "as far as I know, arrays have no at method".
• Try changing the 'lib' compiler option to 'es2022' or later names the fix. The code is fine; the project's settings say .at() doesn't exist.

This example is checked with the setting "lib": ["es2021", "dom"], which says "the code runs where JavaScript stops at the 2021 edition". .at() came in 2022. That's what this lesson is about: the settings in tsconfig.json that describe where your code will run. Here are the ones that matter, in a typical browser project:

1{2  "compilerOptions": {3    "target": "es2022",4    "lib": ["es2022", "dom", "dom.iterable"],5    "module": "esnext",6    "moduleResolution": "bundler",7    "strict": true8  },9  "include": ["src"]10}

• Line 3, target, picks the edition of JavaScript tsc writes. Older editions mean tsc rewrites more of your code.
• Line 4, lib, lists the built-in things TypeScript knows about: methods like .at(), and the browser's document.
• Lines 5 and 6, module and moduleResolution, say how import and export are written, and how TypeScript finds the file an import names.

target: which JavaScript tsc writes

JavaScript gets a new edition every year: ES2015, ES2016, and so on (ES is short for ECMAScript, the language's official name). Each edition adds syntax, like ?. in ES2020. target names the oldest edition your users' browsers understand. When your code uses newer syntax, tsc rewrites it into older syntax that does the same thing. This is called downleveling (the How new syntax is downleveled lesson shows how). Here is a small class that picks a page theme:

1type Settings = { theme?: { color: string } };2 3class ThemePicker {4  fallback = "light";5  pick(settings: Settings) {6    return settings.theme?.color ?? this.fallback;7  }8}9 10const picker = new ThemePicker();11console.log(`Theme: ${picker.pick({})}`);

• Line 1 says Settings may have a theme with a color.
• Line 4 is a class field: fallback is set on every new ThemePicker, written inside the class body (Class basics covers fields).
• Line 6 reads the color with ?., which stops at a missing theme, and falls back with ?? (both are in Nullish coalescing & optional chaining).
• Line 11 picks a theme for empty settings and prints Theme: light.

Now pick a target and read what tsc writes for each one:

1type Settings = { theme?: { color: string } };2 3class ThemePicker {4  fallback = "light";5  pick(settings: Settings) {6    return settings.theme?.color ?? this.fallback;7  }8}9 10const picker = new ThemePicker();11console.log(`Theme: ${picker.pick({})}`);

var ThemePicker = /** @class */ (function () {
    function ThemePicker() {
        this.fallback = "light";
    }
    ThemePicker.prototype.pick = function (settings) {
        var _a, _b;
        return (_b = (_a = settings.theme) === null || _a === void 0 ? void 0 : _a.color) !== null && _b !== void 0 ? _b : this.fallback;
    };
    return ThemePicker;
}());
var picker = new ThemePicker();
console.log("Theme: ".concat(picker.pick({})));

Start at es5 and go up. The output shrinks as the target gets newer, because there's less to rewrite. At es2022 it's your code without its types. Every version prints Theme: light: downleveling changes how the code is written, not what it does. The table below lists when the syntax you use most arrived. Read each row as: the edition, what it added, and what tsc does when your target is older.

Here is the catch. target rewrites syntax: the symbols and keywords of the language. It never adds methods. Here is what tsc writes for the overview's code with "target": "es2017":

const cart = ["tea", "cake", "jam"];
const newest = cart.at(-1);
console.log(`Newest item: ${newest}`);

It's the same three lines. cart.at(-1) on line 2 is a method call, which is ordinary syntax, so nothing needs rewriting. In a browser without .at(), like one from 2020, line 2 stops the code:

TypeError: cart.at is not a function

A missing method needs a polyfill, a piece of code that adds it while the page runs (the Transpilers & polyfills lesson covers both). TypeScript never adds polyfills.

Two more facts about target. If you leave it out, TypeScript 5.9 uses es5, which rewrites almost everything; TypeScript 6.0 uses the newest edition instead and deprecates es5, so write the target you want. And if a bundler like Vite builds your page, it ignores this setting and uses its own: build.target in Vite's settings. In such a project, target still matters for checking, as the next section shows.

lib: which built-in types TypeScript knows

TypeScript doesn't look inside a browser to see which methods exist. It reads lib files: files that describe, in types, everything JavaScript and the browser have built in. Each edition of JavaScript has one, and so does the browser's page. Here is the part of lib.es2022.array.d.ts that describes .at() (the comment is shortened):

1interface Array<T> {2  /**3   * Returns the item located at the specified index.4   */5  at(index: number): T | undefined;6}

Line 1 adds to the Array type. Line 5 says an array has a method at that takes a number and gives back an item or undefined. There's no code here that finds the item; it's only a description. The lib setting picks which of these files TypeScript reads:

• "es2022" describes JavaScript up to the 2022 edition: Array, Math, Promise, .at(), and so on.
• "dom" describes the browser's page: document, elements, events, fetch, and console.
• "dom.iterable" adds looping with for...of over lists the page gives you, like document.querySelectorAll("li"). In TypeScript 6.0 it's part of "dom".

When you write lib, your list replaces the whole default. Try four lists on the same code. It reads the newest item, then writes it into every row of a list on the page:

1const cart = ["tea", "cake", "jam"];2const newest = cart.at(-1);3 4const rows = document.querySelectorAll("li");5for (const row of rows) {6  row.textContent = newest ?? "";7}8console.log(`Updated ${rows.length} rows`);

With all three entries, there are no errors. Drop to es2021 and line 2 is marked, as in the overview. Leave out dom.iterable and the for...of loop on line 5 is marked. Leave out dom and TypeScript can't find document or even console. In every case, press Edit & run: the code still fills the rows and prints Updated 3 rows, because the browser has all of these things. lib only changes what TypeScript believes.

That cuts both ways. A lib entry the browser doesn't really have hides a crash, as the TypeError above showed. So pick lib to match the oldest browser you support, or add a polyfill for each newer method you use.

When you leave lib out, TypeScript picks it from target: "target": "es2022" gives you es2022, dom, and dom.iterable (and three smaller ones you won't need to think about). Code that runs in Node, not a browser, leaves out dom and adds Node's own types with "types": ["node"], after installing the @types/node package.

module and moduleResolution: how imports work

Real projects split code into files that import from each other (the Import & export lesson covers the syntax). The shop keeps its price formatting in one file:

1export function formatPrice(price: number) {2  return `$${price.toFixed(2)}`;3}

Line 1 exports formatPrice, and line 2 turns a number like 7 into $7.00. Another file imports it. Pick a module setting to see how tsc writes that import:

1import { formatPrice } from "./format";2 3export function cartLabel(total: number) {4  return `Total: ${formatPrice(total)}`;5}6 7console.log(cartLabel(7));

import { formatPrice } from "./format";
export function cartLabel(total) {
    return `Total: ${formatPrice(total)}`;
}
console.log(cartLabel(7));

In cart.ts, line 1 imports formatPrice, line 3 exports cartLabel, and line 7 prints Total: $7.00. With esnext and preserve, the output keeps import and export: these are ES modules, the form browsers and bundlers read. With commonjs, it uses require and exports, the form Node used before ES modules (the CommonJS vs ES modules lesson compares them).

module also tells TypeScript what the place your code runs can do, so it changes checking even when tsc writes nothing. This file waits for prices with await outside any function, which only newer module forms allow. It's checked with "module": "es2015", and the error is on purpose:

1import { formatPrice } from "./format";2 3const prices = await Promise.resolve([3, 4]);4console.log(formatPrice(prices[0] + prices[1]));

Line 3 waits for a list of two prices, and line 4 prints their total, $7.00. TypeScript marks line 3: Top-level 'await' expressions are only allowed when the 'module' option is set to 'es2022', 'esnext', and a few more. In plain words: await at the top of a file came with ES2022 modules, and es2015 modules don't have it. With this lesson's default, esnext, the error is gone.

The second setting, moduleResolution, is how TypeScript finds the file an import names. Bundlers and Node find files differently, so TypeScript has a mode for each:

• "bundler" works like Vite: "./format" is enough, because the bundler tries endings like .ts and .js itself.
• "nodenext" works like Node (the Module resolution lesson explains Node's rules). In an ES module, Node wants the whole file name. "module": "nodenext" sets it for you.

Try both. The project has cart.ts, format.ts, and a package.json with "type": "module", which tells Node the files are ES modules. Type a path on line 1:

1import { formatPrice } from "./format";2 3console.log(formatPrice(3));

With nodenext, ./format gets Relative import paths need explicit file extensions in ECMAScript imports, and the message suggests ./format.js. That surprises everyone the first time: the file you wrote is format.ts. But tsc turns it into format.js, and that's the file Node loads. tsc never changes the paths you write, so you write the name the file will have. While checking, TypeScript knows that ./format.js means format.ts.

The table below matches the two settings to where your code runs. Read each row as: the situation, then the two settings.

Bundlers and isolatedModules

tsc reads your whole project at once. Fast build tools don't. Vite, esbuild, SWC, and Babel turn each .ts file into JavaScript on its own, without looking at the files it imports (the Bundlers & build tools lesson covers what they do). That's what makes them fast. But some TypeScript code can only be compiled correctly by looking at another file. Here is a types.ts with a type and a function:

1export type CartItem = { name: string; price: number };2 3export function formatPrice(price: number) {4  return `$${price.toFixed(2)}`;5}

Line 1 exports a type, CartItem. Line 3 exports a function, formatPrice. Many projects add an index.ts that passes on everything from a folder, so other files import from one place. Pick how index.ts passes them on:

1export { CartItem, formatPrice } from "./types";

export { formatPrice } from "./types";

export { CartItem, formatPrice } from "./types";

With the first button, tsc and the one-file tool disagree. tsc read types.ts, knew CartItem is only a type, and left it out. The one-file tool kept it, and a browser stops with:

SyntaxError: The requested module './types.js' does not provide an export named 'CartItem'

types.js has no CartItem: types don't exist in JavaScript. The setting "isolatedModules": true fixes this before it happens. It tells TypeScript: "warn me about anything a tool that sees one file at a time would get wrong". It doesn't change what tsc writes. The second button shows the warning, and the last two show the fix: mark the type with type, so any tool can remove it from this file alone.

The table below lists the three cases TypeScript's documentation gives for isolatedModules. Read each row as: the code, the message, and what to write instead.

Vite's own documentation says to set isolatedModules to true. Many projects go one step further with "verbatimModuleSyntax": true, which turns isolatedModules on and also asks you to mark every imported type with type. The Modules & type imports lesson covers it.

The output settings of a Vite checkout page

Here are the output settings Vite's TypeScript starter gives a new checkout page (the vanilla-ts template, shortened to the lines this lesson covers):

{
  "compilerOptions": {
    "target": "es2023",
    "module": "esnext",
    "lib": ["ES2023", "DOM"],
    "types": ["vite/client"],
    "skipLibCheck": true,

    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "verbatimModuleSyntax": true,
    "moduleDetection": "force",
    "noEmit": true
  },
  "include": ["src"]
}

• Line 3, target: ES2023. Vite ignores it when it builds, but TypeScript still uses it for checking.
• Line 4, module: esnext, ES modules, the form Vite reads.
• Line 5, lib: ES2023 and the page. Line 6, types, adds Vite's own types, like import.meta.env. Line 7, skipLibCheck, skips checking the type files of installed packages, which saves time.
• Line 9, moduleResolution: bundler, so imports can leave out the ending. Line 10 allows imports that end in .ts, because Vite reads those files itself.
• Line 11, verbatimModuleSyntax, makes Vite's one-file compiling safe. Line 12, moduleDetection, treats every file as a module, even one with no import.
• Line 13, noEmit: tsc only checks. Vite writes the JavaScript.

The template is made for TypeScript 6.0, where "DOM" includes DOM.Iterable. With TypeScript 5.9, its lib line has a gap. Here is checkout code with the template's lib, checked with 5.9, and the error is on purpose:

1const rows = document.querySelectorAll("li");2for (const row of rows) {3  row.textContent = row.textContent?.toUpperCase() ?? "";4}5console.log(`Updated ${rows.length} rows`);

Line 1 finds every row of the list. Lines 2 to 4 write each row's text in capitals, and line 5 prints Updated 3 rows. TypeScript marks the loop on line 2: Type 'NodeListOf<HTMLLIElement>' must have a '[Symbol.iterator]()' method. In plain words: "I don't know this list can be looped over". Add "DOM.Iterable" to lib, and the same code has no errors:

1const rows = document.querySelectorAll("li");2for (const row of rows) {3  row.textContent = row.textContent?.toUpperCase() ?? "";4}5console.log(`Updated ${rows.length} rows`);

Every message in this lesson points at one setting. Sort the problems below by what fixes them.

Common mix-ups

• "An older target makes .at() work in old browsers." No. target rewrites syntax like ?.. Methods stay as you wrote them, and a browser without them throws a TypeError.
• "Adding es2023 to lib makes .toSorted() work everywhere." No. lib is a description for TypeScript. It adds nothing to the browser.
• ""lib": ["es2022"] adds ES2022 to what I had." No. Your list replaces the default. Without "dom" in it, document and console are gone.
• "With noEmit, target and module don't matter." No. They still decide the default lib and checks like top-level await.
• "tsc turns ./format into ./format.js for Node." No. tsc writes your import paths as they are. With nodenext, you write ./format.js yourself.
• "isolatedModules changes the JavaScript tsc writes." No. It only adds warnings about code that tools compiling one file at a time would get wrong.

target and lib are the easiest pair to mix up. The table compares them. Read each row as a question, then each setting's answer.

Practice exercises

Some exercises are TypeScript code, checked with the settings they name; others are a tsconfig.json to fix. For code, press Edit & run on the starter: the errors update as you type. Try a guess first, then use the hints.

1const prices = [4, 3, 5];2const cheapestFirst = prices.toSorted();3console.log(cheapestFirst);

1const prices = [4, 3, 5];2const cheapestFirst = prices.toSorted();3console.log(cheapestFirst);

1type Settings = { theme?: { color: string } };2 3function themeColor(settings: Settings) {4  return settings.theme?.color ?? "light";5}6console.log(themeColor({}));

1type Settings = { theme?: { color: string } };2 3// "target": "es2020" or newer keeps line 5 as it is.4// "target": "es2019" or older rewrites ?. and ?? into checks.5function themeColor(settings: Settings) {6  return settings.theme?.color ?? "light";7}8console.log(themeColor({}));

1import { formatPrice } from "./format";2 3console.log(formatPrice(4));

1import { formatPrice } from "./format.js";2 3console.log(formatPrice(4));

1export { CartItem, formatPrice } from "./types";

1export type { CartItem } from "./types";2export { formatPrice } from "./types";

1type Order = { id: number; paid: boolean };2 3const orders: Order[] = [4  { id: 1, paid: true },5  { id: 2, paid: false },6  { id: 3, paid: true },7];8const lastPaid = orders.findLast((order) => order.paid);9console.log(lastPaid?.id);

1type Order = { id: number; paid: boolean };2 3const orders: Order[] = [4  { id: 1, paid: true },5  { id: 2, paid: false },6  { id: 3, paid: true },7];8const paidOrders = orders.filter((order) => order.paid);9const lastPaid = paidOrders[paidOrders.length - 1];10console.log(lastPaid?.id);

{
  "compilerOptions": {
    "target": "es2022",
    "lib": ["es2022", "dom"],
    "module": "esnext",
    "moduleResolution": "bundler",
    "outDir": "dist",
    "strict": true
  },
  "include": ["scripts"]
}

{
  "compilerOptions": {
    "target": "es2022",
    "lib": ["es2022"],
    "types": ["node"],
    "module": "nodenext",
    "outDir": "dist",
    "strict": true
  },
  "include": ["scripts"]
}

Check your understanding

For each question, ask which setting is involved: target for syntax, lib for built-in methods, module and moduleResolution for imports. The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• target picks which JavaScript tsc writes. Older targets rewrite newer syntax; no target adds methods.
• lib lists the built-ins TypeScript believes exist. Your list replaces the default, so keep dom for a page.
• In TypeScript 5.9, looping over a NodeList needs dom.iterable; 6.0 puts it inside dom.
• module decides how imports are written and which module features are allowed, like top-level await.
• moduleResolution bundler lets you leave out endings; nodenext wants ./format.js.
• Bundlers compile one file at a time. isolatedModules warns about code they'd get wrong; export type fixes it.

Coming next: Type checking vs type stripping. Vite, esbuild, and Node run TypeScript without checking it, so you'll see where tsc still fits, from your editor to CI.