/ts-polyfill

Runtime polyfills for TypeScript libs, powered by core-js! :battery: :nut_and_bolt:

Primary LanguageTypeScriptOtherNOASSERTION

TS-Polyfill

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

npm GitHub Actions

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.

// 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):

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)