TS-Polyfill

Runtime polyfills for TypeScript libs, powered by core-js! 🔋 🔩

Install

npm install ts-polyfill

Getting Started

Modify your project tsconfig.json to add type definitions required.
- (Obviously, you don't need EVERYTHING. Pick the ones you actually need to minimize bandwidth!)
- In this example, we are targeting ES2015 so only ES2016 and above polyfills are needed:

{
  "compilerOptions": {
    "target": "ES2015",
    "lib": [
      "DOM",
      "DOM.Iterable",
      "ES2015",
      "ES2016.Array.Include",
      "ES2017.Object",
      "ES2017.String",
      "ES2018.AsyncIterable",
      "ES2018.Promise",
      "ES2019.Array",
      "ES2019.Object",
      "ES2019.String",
      "ES2019.Symbol",
      "ES2020.Promise",
      "ES2020.String",
      "ES2020.Symbol.WellKnown"
    ]
  }
}

It is 2020 and you should be targeting ES2015. Internet Explorer 11 and Windows 7 are no longer supported by Microsoft and no longer receive security patches.

Then, in the entry point of your application, import the polyfills.
- The complete list of available polyfills (including ES2015 polyfills for poor souls targeting ES5) can be found here: https://github.com/ryanelian/ts-polyfill/tree/master/lib

// index.ts
import 'ts-polyfill/lib/es2016-array-include';
import 'ts-polyfill/lib/es2017-object';
import 'ts-polyfill/lib/es2017-string';
import 'ts-polyfill/lib/es2018-async-iterable';   // for-await-of
import 'ts-polyfill/lib/es2018-promise';
import 'ts-polyfill/lib/es2019-array';
import 'ts-polyfill/lib/es2019-object';
import 'ts-polyfill/lib/es2019-string';
import 'ts-polyfill/lib/es2019-symbol';
import 'ts-polyfill/lib/es2020-promise';
import 'ts-polyfill/lib/es2020-string';
import 'ts-polyfill/lib/es2020-symbol-wellknown';

import 'ts-polyfill/lib/es2020-global-this';      // globalThis (no tsconfig.json lib)

Shameless self-promotion: use instapack for easy, rapid, and painless web app development using TypeScript!

Alternative Techniques

Include everything implicitly: 👌
- EXCEPT these non-essential polyfills (for portability): es2015-iterable, es2015-reflect, es2015-symbol, es2015-symbol-wellknown, es2017-typed-arrays, es2018-async-iterable, es2019-symbol, es2020-symbol-wellknown

import 'ts-polyfill';

Include everything (also with exceptions listed above) using a pre-built script: download then include these as <script> in your HTML (before your app script):
- ts-polyfill.min.js (51.85 KB, 18.37 KB gzip)
- ts-polyfill.min.js.map

FAQ

What's up with the semver?

Above version 0.0.4 (last known compatibility with TypeScript 2.8.3), we follow TypeScript version. Which means: ts-polyfill 2.9.0 is compatible with TypeScript 2.9.0 libs, and so on!

Release Cadence: We will release new version if necessary whenever new TypeScript versions are published.

Which polyfill to include to use `downlevelIteration` when targeting ES5 in TypeScript?

es2015-symbol
es2015-symbol-wellknown
es2015-iterable

Why shouldn't I just use core-js directly?

We made extra efforts to guarantee (near) 100% coverage for polyfills of corresponding libs by sweeping TypeScript libs API one-by-one.
We don't include lib polyfills which we consider to be 'unstable'
- Example: esnext.feature libs are probably unstable. We will wait for them to be marked as something like es2018.feature before attempting to polyfill them.
We will update the polyfills whenever the official TypeScript libs change. (It happens yo)
We will protect ts-polyfill consumers against breaking changes in core-js: our API will probably never change, but core-js API may change. (For example: core-js migration from version 2 to version 3)
We attempt to reduce total polyfill size by targeting ES5 instead of ES3.

What's the catch?

ES2015.Core String.prototype.normalize polyfill is GIGANTIC (140 KB) and is not included.
- If you REALLY need it, use polyfill provided by unorm library.
ES2020.BigInt lib is not included in this library. It can probably be polyfilled using a separate library which is Google's official BigInt implementation: https://github.com/GoogleChromeLabs/jsbi
ES2015 Reflect polyfills are best-effort. (15/20)
ES2015 Symbol and Well-Known Symbol polyfills are best-effort. (8/12 and 22/26)

ryanelian/ts-polyfill