README.MD

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)