Transpilers & polyfills

New code, old browsers

JavaScript gets new features every year. But many people still use older browsers. They use them on old phones, work laptops, and smart TVs. Some use them inside apps that show web pages; these built-in browsers are called WebViews.

An older browser may not understand your newest code. This lesson shows the tools that close that gap.

So the rule is short:

• New syntax needs a transpiler. Syntax is the way code is written, like the ?. sign.
• A missing API needs a polyfill or a ponyfill. An API is a built-in function or object, like Array.prototype.at. A ponyfill is a helper function you call yourself; you'll see one below.
• Some features change how the engine works. The engine is the part of the browser that runs JavaScript. No tool can add those features to an old browser. You need a different design, or you stop supporting that browser.

The table below compares four tools. Read each row as: "this tool changes this, for example like this."

This lesson builds on three earlier lessons: JavaScript history, engines & runtimes, and manuals & specs. In the tooling path, it comes after bundlers and before types for JavaScript.

First, here is the kind of code a transpiler fixes. This code prints Asha. ?. is called optional chaining. It reads name only if user.profile is not null or undefined.

An old browser can't read the ?. sign at all. It stops with a syntax error before any of the code runs.

const user = { profile: { name: "Asha" } };
console.log(user.profile?.name);

The next block does the same job in older code. It is a simpler version of what a transpiler writes:

• Line 1 uses var, the older way to make a variable.
• Line 2 reads user.profile once and saves it in profile.
• Line 3 checks that profile is not null and not undefined. void 0 is an old way to write undefined. Only then does it read profile.name.

It also prints Asha. Saving the profile first matters when reading it runs code. For example, a getter is a property that runs a function each time you read it. It should run only once here, just like in the new code.

var user = { profile: { name: "Asha" } };
var profile = user.profile;
console.log(profile === null || profile === void 0 ? void 0 : profile.name);

Now the profile is missing. user.profile?.name gives undefined. Then ?? takes over. ?? is called nullish coalescing. It gives the value on its right when the left side is null or undefined. So this prints Guest.

Both ?. and ?? came in ES2020, the 2020 version of JavaScript. A browser older than that needs both of them rewritten.

const user = { profile: null };
console.log(user.profile?.name ?? "Guest");

A real transpiler doesn't just search and replace text. It works in three steps:

1. Parse: read the code and build a tree of its parts. This tree is called an AST (abstract syntax tree).
2. Transform: change the parts of the tree that need it.
3. Generate: print new code from the changed tree.

Because it works on the tree, the transpiler knows that ?? inside a string is just text, not code. Plain search and replace can't tell the difference.

The step-through below uses acorn, a real JavaScript parser, to build the tree. Then it rewrites one small ?? expression. It is much smaller than a real tool like Babel, so you can see each step.

1const settings = { label: null };Run2const label = settings.label ?? "Untitled";3console.log(label);

A target is the oldest JavaScript version your output must work in. The tool rewrites everything that is newer than the target.

With an ES5 target (JavaScript from 2009), all of these need rewriting:

• arrow functions and classes
• spread (...items) and template literals (strings in backticks)
• default values for parameters
• ?. and ??

With an ES2019 target, most of those can stay as they are. But ?. and ?? still need rewriting, because they came in ES2020. Pick a target below and compare the output.

1const tax = 0.08;2const format = (name, amount = 0) => `${name}: $${amount.toFixed(2)}`;3class Cart {4  constructor(items = []) {5    this.items = [...items];6  }7  total() {8    return this.items?.reduce((sum, item) => sum + (item.price ?? 0), 0) ?? 0;9  }10}11const cart = new Cart([{ price: 12 }, {}]);12console.log(format("Total", cart.total() * (1 + tax)));

1var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {2    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {3        if (ar || !(i in from)) {4            if (!ar) ar = Array.prototype.slice.call(from, 0, i);5            ar[i] = from[i];6        }7    }8    return to.concat(ar || Array.prototype.slice.call(from));9};10var tax = 0.08;11var format = function (name, amount) {12    if (amount === void 0) { amount = 0; }13    return "".concat(name, ": $").concat(amount.toFixed(2));14};15var Cart = /** @class */ (function () {16    function Cart(items) {17        if (items === void 0) { items = []; }18        this.items = __spreadArray([], items, true);19    }20    Cart.prototype.total = function () {21        var _a, _b;22        return (_b = (_a = this.items) === null || _a === void 0 ? void 0 : _a.reduce(function (sum, item) { var _a; return sum + ((_a = item.price) !== null && _a !== void 0 ? _a : 0); }, 0)) !== null && _b !== void 0 ? _b : 0;23    };24    return Cart;25}());26var cart = new Cart([{ price: 12 }, {}]);27console.log(format("Total", cart.total() * (1 + tax)));

In a real app, you usually don't write a year as the target. Instead, many tools read Browserslist. Browserslist is a shared list of the browsers you support. Babel, Autoprefixer, eslint-plugin-compat, and other tools all read it.

You write a short query, and Browserslist turns it into a list of browser versions. For example:

• defaults: a starting list that the Browserslist team keeps up to date.
• > 0.5%: browsers used by more than 0.5% of people.
• not dead: leave out browsers that no longer get updates.

A comma between queries adds more browsers. and keeps only the browsers that match both sides.

{
  "browserslist": ["defaults"]
}

This is a setting, not a program, so there is nothing to run. Before you change defaults, look at the browsers it gives you and compare them with your users.

You will meet four main transpilers:

• Babel is the oldest. It has the most plugins, which are add-ons that add more rewrites. Its @babel/preset-env setting reads your targets and picks the rewrites for you. It can also add polyfills.
• SWC is written in the Rust language, so it is very fast. Next.js uses it, and this site is built with Next.js.
• TypeScript removes type notes from your code. It can also rewrite syntax for the target you choose.
• esbuild is a very fast bundler that can also rewrite syntax for a target.

Read each row of the table as: "this tool is good at this, and it fits these projects."

Fast tools don't all do the same job. This site's code editor uses another fast tool called Sucrase. In the playground below, Sucrase does two things:

• It removes TypeScript types.
• It turns JSX into plain function calls. JSX is HTML-like tags written inside JavaScript, as in React.

In this playground, Sucrase is set to leave new JavaScript syntax like ?. and ?? as it is. So Sucrase alone can't make code work in old browsers. For that you still need Babel, SWC, TypeScript, or esbuild.

type User = { name?: string | null };
const user: User = { name: null };
const label = user.name ?? "Guest";
const view = <strong>{label?.toUpperCase()}</strong>;
console.log(label, view.type);

const _jsxFileName = "";
const user = { name: null };
const label = user.name ?? "Guest";
const view = React.createElement('strong', {__self: this, __source: {fileName: _jsxFileName, lineNumber: 4}}, label?.toUpperCase());
console.log(label, view.type);

// babel.config.js
module.exports = {
  presets: [
    ["@babel/preset-env", {
      targets: "> 0.5%, last 2 versions, not dead",
      useBuiltIns: "usage",
      corejs: "3.38"
    }]
  ]
};

This is a build setting, not code for the browser. Line by line:

• Line 5, targets, lists the browsers as a Browserslist query.
• Line 6, useBuiltIns: "usage", adds polyfills only for features your code uses.
• Line 7, corejs, says which version of the core-js polyfill package you installed. Make it match your installed version; 3.38 is just an example.

In a Next.js app, let Next.js and SWC do the rewriting. Add your own Babel setup only if you need a plugin that only Babel has. Switching to Babel can make builds slower and change the output.

Sometimes the browser can read your code, but a built-in function is missing. A polyfill helps here. A safe polyfill does three things:

• It checks whether the browser already has the feature.
• It adds the feature only when it is missing.
• It copies the real feature's details as closely as it can. For example, the new method should not show up when code lists an object's properties.

This small teaching version adds at to a small object called methods. It doesn't touch the real Array.prototype. at(-1) means "the last item".

const methods = {};
if (!("at" in methods)) {
  Object.defineProperty(methods, "at", {
    value(index) { return this[index < 0 ? this.length + index : index]; }
  });
}
console.log(methods.at.call(["tea", "milk"], -1));

• Line 2 checks for at. If it is already there, the code skips adding it.
• Line 3 adds at with Object.defineProperty. This function adds a property and lets you set its details.
• Line 4 turns a negative index into a position counted from the end.
• Line 7 runs at on the list ["tea", "milk"]. It uses .call(), which runs a function with a chosen this. It prints milk.

This tiny method skips some unusual cases from the specification. So don't use it as a real Array.prototype.at polyfill. The step-through below adds range checks. It also keeps the new method hidden from lists of properties; this is called non-enumerable. For a real app, use a polyfill that someone keeps up to date.

1function installAtPolyfill(proto) {2  if ("at" in proto) return "native kept";3  Object.defineProperty(proto, "at", {4    value(index) {5      const length = this.length >>> 0;6      const relative = Math.trunc(index) || 0;7      const key = relative < 0 ? length + relative : relative;8      return key < 0 || key >= length ? undefined : this[key];9    },10    configurable: true,11    writable: true12  });13  return "polyfill installed";14}15 16const fakePrototype = {};Run17const list = Object.assign(Object.create(fakePrototype), {18  0: "alpha",19  1: "omega",20  length: 221});22console.log(installAtPolyfill(fakePrototype));23console.log(list.at(-1));24console.log(Object.keys(fakePrototype).includes("at"));

When at already exists, the check on line 2 leaves it alone. So this code prints native. Replacing a built-in method that already works can break other code. The browser's own version is also usually faster.

const methods = { at() { return "native"; } };
if (!("at" in methods)) {
  Object.defineProperty(methods, "at", { value() { return "replacement"; } });
}
console.log(methods.at());

Sometimes only your own code needs the last item. Then a ponyfill is enough. A ponyfill is a normal helper function. It doesn't change any shared object.

This code prints milk. But unlike a polyfill, it doesn't make cart.at(-1) work for other code.

const cart = ["tea", "milk"];
const last = (items) => items[items.length - 1];
console.log(last(cart));

Real polyfills follow the specification closely and are kept up to date. core-js is the most widely used package of JavaScript polyfills.

Babel's @babel/preset-env can add core-js imports for you when useBuiltIns: "usage" is on. It reads your code and imports only the polyfills your target browsers seem to need. It can miss some uses:

• a method called through a name made while the code runs, like list[name]()
• code inside a package that Babel doesn't process

Every polyfill costs time: the browser must download it, read it, and run it. So check what your final bundle contains. Remove polyfills for features your supported browsers already have. Keep the ones that the older browsers you support still need.

Every browser sends a user-agent string: a line of text with its name and version. Guessing features from it doesn't work well:

• Browsers copy parts of each other's names.
• Company versions of a browser can be older than their version number suggests.
• WebViews inside apps get updates at different times.
• A feature can be turned off.

Feature detection asks the browser directly. Is this method there? Can this syntax be read? Does CSS support this property and value?

On a profile page, you can check for at and use a fallback if it is missing. Nothing shared gets changed:

• Line 2 checks whether user.names.at is a function.
• If it is, line 3 uses at(-1).
• If not, line 4 uses length - 1, the position of the last item.

Both ways pick the last name, so this prints Nia.

const user = { names: ["Asha", "Nia"] };
const lastName = typeof user.names.at === "function"
  ? user.names.at(-1)
  : user.names[user.names.length - 1];
console.log(lastName);

The next code checks two things. In a current browser, both lines print true.

1function supportsOptionalChainingSyntax() {2  try {3    new Function("const item = {}; return item?.name ?? 'none';");4    return true;5  } catch {6    return false;7  }8}9 10console.log(typeof Array.prototype.at === "function");11console.log(supportsOptionalChainingSyntax());

• Line 10 uses typeof to check that Array.prototype.at is a function. typeof gives a value's type as a string, like "function".
• Line 3 uses new Function to make a function from a fixed piece of text. If the browser can't read ?. or ??, this throws an error. Then the catch on line 5 catches it, and line 6 returns false.

A few more things to know:

• "name" in object only checks that a property exists. typeof also tells you whether it can be called.
• A strict Content Security Policy is a page rule that limits what scripts may do. It can block new Function. Then the check returns false even in a browser that knows the syntax. So for syntax your app needs, set build targets instead.
• For CSS, @supports and CSS.supports("container-type", "inline-size") ask the same kind of question.

How real projects put it together

A real build starts with a support policy: a decision about which browsers you support. To decide, ask:

• Which browsers do your users have?
• How much extra old-style code can you send them?
• Do your users open your pages inside apps, in older WebViews?

Then the tools turn that policy into rewrites, polyfills, and fallbacks:

1. Write modern code and tests.
2. Choose your target browsers with Browserslist. Use Baseline, your analytics, and what you promised customers.
3. Let Babel, SWC, TypeScript, or esbuild rewrite the syntax for those browsers.
4. Add checked polyfills or ponyfills for features those browsers lack.
5. Check for risky features in your code, and keep a fallback for features no tool can add.

A transpiler keeps your code's meaning, mistakes included. Say a timeout of zero means "no timeout". Then use ??, not ||:

• Line 2 prints 0. ?? only replaces null and undefined, so it keeps the zero.
• Line 3 prints 1000. || replaces any falsy value, which is a value that counts as false, like 0 or "". So the zero is lost.

Transpiled code keeps this same difference.

const settings = { timeout: 0 };
console.log(settings.timeout ?? 1000);
console.log(settings.timeout || 1000);

Older apps often used differential serving: sending different files to different browsers.

• Browsers that understand type="module" load the modern file and skip the other one.
• Older browsers skip the module tag and load the nomodule file instead.

Today most people use browsers that update themselves, so this is less common. You will still see it in older apps.

<script type="module" src="/app-modern.js"></script>
<script nomodule src="/app-legacy.js"></script>

These tags belong in an HTML page next to built script files, so there is nothing to run here. Always check the files your build really sends, not just your settings.

What can't be transpiled or polyfilled?

These tools help a lot, but they can't do everything:

• A syntax error can only be avoided by rewriting the code before the browser reads it.
• A missing function can often be added.
• Some features depend on how the engine works inside. Examples are security rules, garbage collection (freeing memory that nothing uses), and device hardware. No code can add those.

Read each row of the table as: "for this kind of problem, use this fix, for example here."

Common misconceptions

• “Babel makes everything work everywhere.” Babel rewrites syntax. Missing functions still need polyfills. And some engine features can't be added at all.
• “A polyfill can fix syntax.” If the browser can't read a sign like ?., it stops before any code runs. So the polyfill never runs either.
• “Baseline means I can ignore my users.” Baseline tells you about the main browsers. Your own users, and what you promised them, still matter.
• “Automatic polyfills don't need checking.” Polyfills added for you are still code from someone else. Check their size, where they come from, who owns them, and what ends up in your files.
• “Checking the browser name is good enough.” A feature check still works when a browser copies another's name, gets patched, or runs inside an app. Names and version numbers don't.

Read each row as: "when someone says this, ask this question, then do this instead."

Key takeaways

• A transpiler rewrites code in three steps: read it into a tree (parse), change the tree (transform), and print new code (generate).
• New syntax must be transpiled before an old browser reads it. Missing functions need a polyfill or a ponyfill while the page runs.
• Browserslist says which browsers you support. Baseline and caniuse tell you what those browsers can do.
• Babel, SWC, TypeScript, and esbuild do similar jobs, but their plugins and output differ.
• A safe polyfill checks first, never replaces a built-in method, stays hidden from property lists, and comes from a source you trust.
• Some features, like every part of Proxy or exactly when WeakRef lets go of an object, can't be added to old engines.

Up next: Types for JavaScript. There, JSDoc and TypeScript catch mistakes before your build tools ever touch the code.