Transpilers & polyfills

The compatibility gap

Modern JavaScript moves faster than the devices your users keep in their pockets, corporate laptops, embedded WebViews, and smart TVs. The code you write is one side of the gap. The syntax and APIs a user’s browser can parse and run are the other side.

The practical rule is short: syntax needs transpiling; APIs need polyfills or ponyfills; features with engine-level semantics may need a different design or a higher browser requirement.

This lesson connects the history from JavaScript history, the runtime model from engines & runtimes, and the standards mindset from manuals & specs. It also sits between bundlers and types for JavaScript in the tooling path.

A real transpiler does not search and replace random text. It parses tokens into an abstract syntax tree, runs transforms over nodes, and prints new source. That is why tools can preserve strings, comments, and nested expressions more safely than a regular expression replacement.

The step-through below uses acorn to parse a real AST and rewrites one simple ?? expression from node positions. It is deliberately tiny, so you can see the pipeline without pretending it is Babel.

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

Compilers need a target. If you target ES5, arrow functions, classes, spread, template literals, default parameters, optional chaining, and nullish coalescing all need attention. If you target ES2019, many of those are already parseable, but ?. and ?? still need rewriting.

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)));

The target is usually not a raw ECMAScript year in application projects. Build tools often read Browserslist, a shared query format used by Babel, Autoprefixer, eslint-plugin-compat, and other tools. Queries such as defaults or > 0.5%, last 2 versions, not dead turn product support policy into a set of browser versions.

# package.json
"browserslist": [
  "defaults",
  "> 0.5%",
  "last 2 versions",
  "not dead"
]

Babel is the long-running JavaScript transform platform. Its @babel/preset-env preset combines your targets with syntax transforms and, when configured, polyfill injection. SWC is written in Rust and powers Next.js transforms in this site. TypeScript strips types and can downlevel syntax by target. esbuild is a very fast bundler and transform tool with target-based syntax lowering.

Fast tools are not identical. Sucrase, used by this site’s code editor, is excellent for quick TypeScript and JSX transforms. In this playground it strips TypeScript and lowers JSX but intentionally leaves modern JavaScript syntax alone, so it is not a replacement for a Babel, SWC, TypeScript, or esbuild compatibility pass.

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"
    }]
  ]
};

In a Next.js app, you usually let Next’s SWC pipeline handle framework transforms. You add custom Babel only when you truly need Babel-specific plugins, because switching compilers can change build performance and output.

Once a browser can parse your code, it might still lack an API. That is where a polyfill helps. A safe polyfill checks for the native feature, defines only when missing, and tries to match platform details such as property attributes and edge cases.

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"));

Real production polyfills are maintained against the specification. core-js is the ecosystem workhorse for many JavaScript standard-library polyfills. Babel’s @babel/preset-env can inject imports from core-js when useBuiltIns: "usage" is enabled, meaning it scans your code and imports only the polyfills it thinks are needed for the target browsers.

User-agent strings are messy: browsers spoof each other, enterprise builds lag, embedded WebViews patch unevenly, and capabilities can be disabled. Feature detection asks the environment directly: is the method present, does this syntax parse, or does CSS support a property-value pair?

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());

Use typeof for globals, "name" in object for properties, and try/catch with new Function when you need to know whether syntax parses. For CSS, @supports and CSS.supports("container-type", "inline-size") answer the same kind of question in the style layer.

How this appears in real projects

A production build starts with a support policy: which browsers matter, how much legacy code you can ship, and whether your audience includes old WebViews. Then tooling turns that policy into transforms, polyfills, and delivery strategy.

1. Write modern source and tests.
2. Set targets with Browserslist, Baseline guidance, analytics, and product promises.
3. Let Babel, SWC, TypeScript, or esbuild transpile syntax for those targets.
4. Add audited polyfills or ponyfills for APIs your target browsers lack.
5. Feature-detect risky paths and keep a fallback for features you cannot emulate.

Differential serving was once a common optimization: ship a modern bundle to browsers that understand type="module" and a legacy bundle to nomodule browsers. It is less central now that evergreen browsers dominate, but you will still see the pattern in older apps and compatibility discussions.

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

What cannot be transpiled or polyfilled?

Compatibility tools are powerful, not magical. A parser error can only be avoided by changing source before the browser sees it. A missing function can often be added. But some features depend on engine internals, security boundaries, garbage collection, or platform devices.

Common misconceptions

• “Babel makes everything work everywhere.” Babel rewrites syntax. It needs polyfills for APIs and cannot recreate every engine feature.
• “A polyfill can fix syntax.” If the browser cannot parse a token, no runtime code gets a chance to run.
• “Baseline means I can ignore my users.” Baseline is a web-platform signal. Your analytics and support promises still matter.
• “Usage-based polyfills require no review.” Generated imports are still dependencies. Review size, source, ownership, and what gets shipped.
• “User-agent sniffing is good enough.” Capability checks survive forks, patches, and embedded browsers better than names and version strings.

Key takeaways

• Transpilers are source-to-source compilers: parse, transform AST, generate JavaScript.
• Syntax must be transpiled before old browsers parse it; APIs need runtime polyfills or ponyfills.
• Browserslist expresses product support policy; Baseline and caniuse provide compatibility evidence.
• Babel, SWC, TypeScript, and esbuild overlap, but their plugin ecosystems and outputs differ.
• Safe polyfills feature-detect, avoid clobbering natives, define non-enumerable methods, and come from trusted supply chains.
• Some features, such as full `Proxy` or `WeakRef` semantics, cannot be faithfully patched into old engines.

Up next: Types for JavaScript, where JSDoc and TypeScript catch mistakes before compatibility tooling ships your code.