You own the tsconfig for a package published to npm and for the application that consumes it. How do you decide `target` and `lib` for each, and what does the TypeScript compiler explicitly not do for you?

## The question behind the question `target` and `lib` look like build trivia, but they encode a support commitment: which runtimes are allowed to execute this code, and which APIs may that code assume. Two contexts pull in opposite directions. ## Applications: describe the deployment, exactly An application knows where it runs, so both settings are answerable from evidence rather than caution. - **`target` follows the oldest runtime you deploy to.** For a server, that is the minimum supported Node major. For a browser app, it is your support baseline — and if a bundler or Babel step performs the final downleveling anyway, `tsc`'s `target` can be modern and the downlevel decision lives in one place instead of two. Duplicating the decision across two tools is a common source of confusion, so pick where it lives and document it. - **`lib` should describe that same environment plus the polyfills you genuinely load.** Widening `lib` past reality is how compile-clean code reaches a browser that cannot run it. Narrowing `lib` below reality is a legitimate tool: a Node-only package that omits `"DOM"` gets a compile error the moment someone reaches for `document`, instead of a crash in production. The honest framing is that `lib` is a **promise about the runtime**. Keep it true and the checker is your first line of defence; make it aspirational and you have disabled that defence without noticing. ## Libraries: your emit runs in someone else's environment A published package cannot see the runtime, which changes the tradeoff. **Arguments for a low target.** Your `dist` runs anywhere, including consumers who do not transpile `node_modules`. That has historically been the safe default. **Arguments against.** Downleveling is expensive and permanent for your consumers: at ES5 every `async` function becomes a state machine, every class becomes prototype wiring, and iteration goes through helpers. That code is larger, slower, and harder to debug — and modern consumers pay for compatibility they never needed. It also introduces its own runtime dependencies (a `Promise` polyfill for downleveled `async`, `Symbol.iterator` for downleveled iteration), which pushes obligations onto consumers who did not ask for them. **The middle positions.** Publish a modern `target` and state the minimum supported runtime in your README, so the commitment is explicit rather than implied by a config file. Or ship more than one build if the audience genuinely spans both worlds — accepting the maintenance and dual-package complexity that comes with it. Whichever you choose, `target` is a public API decision, not an internal one, and it belongs in a changelog when it moves. ## What the compiler will not do — the two hard limits **It never polyfills.** This is the sentence to lead with. `target` rewrites *syntax*; it does not supply *library code*. Downleveled `async`/`await` calls `Promise` at runtime; downleveled iteration calls `Symbol.iterator`. If those are missing, the code throws. `lib` cannot help — it is type-only and emits nothing. Polyfills are a runtime concern, satisfied by a package such as `core-js` loaded before your code, and their presence is what makes a wide `lib` truthful. **Your `lib` leaks into your published types.** A `.d.ts` that mentions `AsyncIterable<T>`, `ReadableStream` or `structuredClone` requires the *consumer's* `lib` to declare those names. If a consumer compiles with a narrower `lib`, your types fail to resolve in their build even though your JavaScript runs fine. So a library's `lib` is part of its contract in two directions: what it may use internally, and what it obliges consumers to have configured. Keeping the public surface expressed in widely available types — and pushing exotic ones behind narrower internal boundaries — is the discipline that avoids surprising consumers. ## A decision procedure worth stating out loud 1. **Name the runtimes.** Not "old browsers" — a Node major, a browser baseline, with the data behind it. 2. **Set `target` to the lowest of those**, unless a downstream tool owns downleveling, in which case set it modern and say where the decision lives. 3. **Set `lib` to that runtime's real capabilities**, then widen only where a polyfill is actually loaded, and narrow deliberately (dropping `"DOM"` in server code) to enforce boundaries. 4. **For a library, re-check the public `.d.ts`** for types your consumers may not have configured. 5. **Revisit on a schedule.** Baselines age; a `target` chosen for a browser matrix from three years ago is silently taxing every user today. ## What separates a principal answer Not the config values — the framing. Treating `target` as a support commitment with a cost borne by consumers, `lib` as a truth claim that the checker enforces only if you keep it honest, and both as decisions that need an owner, a rationale, and a review date.