Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ryanelian/ts-polyfill
Runtime polyfills for TypeScript libs, powered by core-js! :battery: :nut_and_bolt:
https://github.com/ryanelian/ts-polyfill
es2015 es6 javascript polyfill promise standard-library typescript
Last synced: 3 days ago
JSON representation
Runtime polyfills for TypeScript libs, powered by core-js! :battery: :nut_and_bolt:
- Host: GitHub
- URL: https://github.com/ryanelian/ts-polyfill
- Owner: ryanelian
- License: other
- Created: 2018-04-23T19:55:31.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2021-01-09T17:37:00.000Z (about 4 years ago)
- Last Synced: 2025-01-02T16:16:58.960Z (22 days ago)
- Topics: es2015, es6, javascript, polyfill, promise, standard-library, typescript
- Language: TypeScript
- Homepage:
- Size: 1.52 MB
- Stars: 142
- Watchers: 4
- Forks: 7
- Open Issues: 7
-
Metadata Files:
- Readme: README.MD
- License: LICENSE
Awesome Lists containing this project
README
# TS-Polyfill
> Runtime polyfills for TypeScript libs, powered by [core-js](https://github.com/zloirock/core-js)! :battery: :nut_and_bolt:
[](https://www.npmjs.com/package/ts-polyfill) [](https://github.com/ryanelian/ts-polyfill/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:
```json
{
"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](https://support.microsoft.com/en-us/help/17621/internet-explorer-downloads).
- 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
```ts
// 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](https://github.com/ryanelian/instapack) for easy, rapid, and painless web app development using TypeScript!**
## Alternative Techniques
- Include everything implicitly: :ok_hand:
- 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`
```ts
import 'ts-polyfill';
```
- Include everything (also with exceptions listed above) using a pre-built script: download then include these as `` in your HTML (before your app script):
- [ts-polyfill.min.js](https://github.com/ryanelian/ts-polyfill/raw/master/dist/ts-polyfill.min.js) (51.85 KB, 18.37 KB gzip)
- [ts-polyfill.min.js.map](https://github.com/ryanelian/ts-polyfill/raw/master/dist/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](https://github.com/ryanelian/ts-polyfill/blob/master/src/es2015-core.ts).
- 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](https://github.com/Microsoft/TypeScript/tree/master/lib) 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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/normalize) polyfill is **GIGANTIC** (140 KB) and is not included.
- **If you REALLY need it,** use polyfill provided by [unorm](https://github.com/walling/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)