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)

{
  "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",
      "es2020.string"
    ]
  }
}

• In above example, we are targeting ES2015 so only ES2016+ polyfills are needed!

  • It's nearly 2020. You should be targeting ES2015 or higher. Yes, seriously. Insist to your customers.

  • The complete list of polyfills (including ES2015 polyfills for poor souls targeting ES5) can be found here: https://github.com/ryanelian/ts-polyfill/tree/master/lib

• Then, in the entry point of your application, import the polyfills:

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/es2020-string';

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

Alternative Techniques

• Include everything implicitly: 👌

  • EXCEPT es2018-async-iterable AND es2019-symbol because they rely on Symbol object being available at runtime. (ES015+ only)

import 'ts-polyfill';

• Include everything using a pre-built script: download then include these as <script> in your HTML (before your app script):

  • ts-polyfill.min.js (60.3 kB, 21.1 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.

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 1: Almost half of Symbol features cannot be polyfilled. Including this lib just because partial polyfill exists for it would be misleading and dangerous for the developer!

  • Example 2: 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 reduce total polyfill size by targeting ES5. (TypeScript projects usually transpile down to ES5, but core-js polyfills 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.

• es2015.reflect method Reflect.construct cannot: sets new.target meta-property, Array subclassing, RegExp subclassing, Function subclassing.