Home

Awesome

<!-- SHADOW_SECTION_LOGO_START --> <div><img alt="Logo" src="https://raw.githubusercontent.com/wessberg/Polyfiller/master/documentation/asset/logo-color-text.png" height="80" /></div> <!-- SHADOW_SECTION_LOGO_END --> <!-- SHADOW_SECTION_DESCRIPTION_SHORT_START -->

Never worry about polyfills again.

<!-- SHADOW_SECTION_DESCRIPTION_SHORT_END --> <!-- SHADOW_SECTION_BADGES_START -->

<a href="https://npmcharts.com/compare/%40wessberg%2Fpolyfiller?minimal=true"><img alt="Downloads per month" src="https://img.shields.io/npm/dm/%40wessberg%2Fpolyfiller.svg" /></a> <a href="https://www.npmjs.com/package/%40wessberg%2Fpolyfiller"><img alt="NPM version" src="https://badge.fury.io/js/%40wessberg%2Fpolyfiller.svg" /></a> <img alt="Dependencies" src="https://img.shields.io/librariesio/github/wessberg%2Fpolyfiller.svg" /> <a href="https://github.com/wessberg/polyfiller/graphs/contributors"><img alt="Contributors" src="https://img.shields.io/github/contributors/wessberg%2Fpolyfiller.svg" /></a> <a href="https://github.com/prettier/prettier"><img alt="code style: prettier" src="https://img.shields.io/badge/code_style-prettier-ff69b4.svg" /></a> <a href="https://opensource.org/licenses/MIT"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-yellow.svg" /></a> <a href="https://www.patreon.com/bePatron?u=11315442"><img alt="Support on Patreon" src="https://img.shields.io/badge/patreon-donate-green.svg" /></a>

<!-- SHADOW_SECTION_BADGES_END --> <!-- SHADOW_SECTION_DESCRIPTION_LONG_START -->

Description

<!-- SHADOW_SECTION_DESCRIPTION_LONG_END -->

This is a web service that returns a minified and encoded bundle of only the polyfills your users need. It's like polyfill.io, but it has additional polyfills such as Web Components, Pointer Events, and much more. It is also potentially faster since all unique polyfill combinations are cached in memory and returned immediately as requested. And, it supports different kinds of encodings for the smallest possible network bandwidth overhead, including Brotli and Gzip. The web service is hosted and live at https://polyfill.app/api. It is free to use, and there are no quota limits. See the Hosting section for details on how to host it yourself, if you want to.

<!-- SHADOW_SECTION_FEATURES_START -->

Features

<!-- SHADOW_SECTION_FEATURES_END --> <!-- SHADOW_SECTION_FEATURE_IMAGE_START --> <!-- SHADOW_SECTION_FEATURE_IMAGE_END -->

Supporters

Polyfiller is kindly supported by and relies heavily on BrowserStack for cross-browser testing to ensure maximum cross-browser compatibility.

<a href="https://www.browserstack.com"><img alt="BrowserStack" src="https://raw.githubusercontent.com/wessberg/Polyfiller/master/documentation/asset/browserstack.png" height="60" /></a>

Polyfiller is kindly supported by JetBrains for software development tools:

<a href="https://www.jetbrains.com/?from=Polyfiller"><img alt="Supported by JetBrains" src="https://raw.githubusercontent.com/wessberg/Polyfiller/master/documentation/asset/jetbrains.png" height="150" /></a>

<!-- SHADOW_SECTION_BACKERS_START -->

Backers

Become a sponsor/backer and get your logo listed here.

<a href="https://usebubbles.com"><img alt="Bubbles" src="https://uploads-ssl.webflow.com/5d682047c28b217055606673/5e5360be16879c1d0dca6514_icon-thin-128x128%402x.png" height="70" /></a><a href="https://www.xerox.com"><img alt="Xerox" src="https://avatars.githubusercontent.com/u/9158512?s=200&v=4" height="70" /></a><a href="https://changelog.me"><img alt="Trent Raymond" src="https://avatars.githubusercontent.com/u/1509616?v=4" height="70" /></a><a href="https://scrubtheweb.com"><img alt="scrubtheweb" src="https://avatars.githubusercontent.com/u/41668218?v=4" height="70" /></a><a href="https://github.com/hjoelh"><img alt="Joel" src="https://avatars.githubusercontent.com/u/68335961?v=4" height="70" /></a>
Bubbles<br><strong>Twitter</strong>: @usebubblesXeroxTrent RaymondscrubthewebJoel

Patreon

<a href="https://www.patreon.com/bePatron?u=11315442"><img alt="Patrons on Patreon" src="https://img.shields.io/endpoint.svg?url=https%3A%2F%2Fshieldsio-patreon.vercel.app%2Fapi%3Fusername%3Dwessberg%26type%3Dpatrons" width="200" /></a>

<!-- SHADOW_SECTION_BACKERS_END --> <!-- SHADOW_SECTION_TOC_START -->

Table of Contents

<!-- SHADOW_SECTION_TOC_END --> <!-- SHADOW_SECTION_INSTALL_START -->

Install

npm

$ npm install @wessberg/polyfiller

Yarn

$ yarn add @wessberg/polyfiller

pnpm

$ pnpm add @wessberg/polyfiller
<!-- SHADOW_SECTION_INSTALL_END -->

Polyfiller is already hosted at https://polyfill.app/api as a free web service, but you can install it, for example if you want to host it yourself. See the Hosting section for more details on that.

<!-- SHADOW_SECTION_USAGE_START -->

Usage

<!-- SHADOW_SECTION_USAGE_END -->

Polyfiller can be used both in a Browser, Worker, and Node environment. By default, the assumed environment is Browser.

Usage in a Browser

Place a <script> tag inside your index.html file with a src pointing at https://polyfill.app/api/polyfill. In the following example, polyfills for ES2015 and Shadow DOM are requested:

<!-- An example of requesting polyfills for an ES2015 environment as well as Web Component support
-->
<script crossorigin src="https://polyfill.app/api/polyfill?features=es,web-components"></script>

A targeted bundle will be returned that only contains the specific polyfills the browser needs! When a browser (or robot) visits your site, Polyfiller evaluates the user agent against Caniuse and decides what is supported and what isn't. It is up to you to decide which polyfills you need, but the web service will automatically make sure to include every dependency of those polyfills, but only if the browser doesn't already support them. See this or this section for details on how to use Polyfiller from Web Workers/ServiceWorkers and Node.

You can provide options to Polyfiller via query parameters such as minify and sourcemap to adjust the received payload to your liking.

Examples

Example 1:

In this example:

<script crossorigin src="https://polyfill.app/api/polyfill?minify&sourcemap&features=es,intersection-observer|force,intl|locale=en"></script>

Example 2:

This example shows how you can add support for Web Components:

<script crossorigin src="https://polyfill.app/api/polyfill?features=template,shadow-dom,custom-elements"></script>

For your convenience, the web-components alias requests those three features.

<script crossorigin src="https://polyfill.app/api/polyfill?features=web-components"></script>

Example 3:

For your convenience, a few libraries are included that isn't strictly polyfills but are closely related to compatibility: In this example:

<script crossorigin src="https://polyfill.app/api/polyfill?features=systemjs,regenerator-runtime"></script>

Web Service API Reference

GET /api/polyfill?features=[...features]

Retrieves a bundle of polyfills. Polyfiller will use the incoming Accept-Encoding headers of the request to decide if the response should be Brotli encoded, Gzip encoded or not encoded at all.

Parameter overview

ParameterDescription
featuresA comma-separated string of all the features you want to include in your bundle (if required by the browser). Each feature may receive zero or more options. Some options are supported for all features while others only support specific features.
contextCan be either window, worker, or node. Use this to instruct Polyfiller to optimize polyfills for the given environment, as well as to exclude polyfills that doesn't support the given context.
sourcemapIf given, or if it has a value of true, Polyfiller will be instructed to generate SourceMaps. Use this in development for better stack traces.
minifyIf given, Polyfiller will send back a minified Polyfill bundle.

feature

A feature has a name and may receive zero or more options. For example, intl is a feature name, and so is custom-elements. See the Feature name section for the full list of possible feature names.

Option

An option is some data associated with a feature. It is associated with a feature using the | (pipe) operator. For example, here's how to associate the force option with a feature: animation|force.

Some options apply to all features while others only apply to specific features. For example: intl|locale=en

The force option

By default, features that are already supported by the browser sending the request to the web service won't be polyfilled. That would be a waste of network bandwidth and parsing cost for your users. However, sometimes you may want to force a polyfill, even for browsers that support a feature. In order to do so, associate the force option with a feature. For example: animation|force This will force-apply a polyfill for Web Animations.

The locale option for Intl

This option only works with intl, intl.core, intl.list-format, or intl.relative-time-format. The Intl family of polyfills rely on locale data for them to work. There are over 600 different locale files shipped. Sending all of them back over the network would take way too much bandwidth. Instead, if you just ask for the intl, intl.core, intl.list-format, or intl.relative-time-format features, they will be returned without any locale data.

To add one or more locales, use the locale option. For example: intl|locale=en

This will return a bundle of Intl-related polyfills along with locale data for the en (English) language code. You can ask for as many you want by separating the locales with the ~ operator. For example: intl|locale=en~da~fr This will return a bundle of Intl-related polyfills along with locale data for en (English), da (Danish), and fr (French).

The variant option for SystemJS

SystemJS comes in two base versions, a minimal version called s, and a more feature-complete version called system. By default, the system variant will be used. You can decide which one to use with the variant option.

For example: systemjs|variant=s selects the s variant, while systemjs|variant=system selects the system variant.

Extra options for Zone

Zone.js, which is supported by Polyfiller, can be configured with some extra options to enhance its operation or support interoperability with more APIs:

OptionDescription
errorGenerates more readable Stack traces when using Zone
shadydomMakes Zone compatible with the ShadyDOM polyfill.
mediaqueryPatches the Media Query API
fetchPatches the Fetch API.
resizeobserverPatches the ResizeObserver API.

Extra options for shadow-dom

OptionDescription
experimentalYou can pass the experimental option to shadow-dom (or any of its aliases such as web-components) to base it on some experimental features that may reduce bugs in older browsers such as IE and Edge <= 15.
litIf you're going to be using Lit, you can also pass the lit option to shadow-dom (or any of its aliases such as web-components) to include its polyfill support layer.

Usage in a Web Worker/Service Worker

You can also request polyfills from a Worker. It is highly recommended that you pass in the context query parameter with a value of worker to instruct Polyfiller to optimize polyfills for a Worker environment, as well as to not include any polyfills that won't work in a Worker environment.

// Provide a context query parameter with a value of 'worker' to avoid polyfills that doesn't support that environment
importScripts("https://polyfill.app/api/polyfill?features=es,intl,web-animations&context=worker");

Usage in Node

You can also request polyfills from Node, if that's a thing you want to do. It is highly recommended that you pass in the context query parameter with a value of node to instruct Polyfiller to optimize polyfills for a Node environment, as well as to not include any polyfills that won't work in a Node environment.

(async () => {
	// Remember to provide a user agent header if you want anything meaningful back
	const response = await fetch("https://polyfill.app/api/polyfill?features=intl&context=node");
	const text = await response.text();
	// Apply the polyfills
	new Function(text)();
})();
<!-- SHADOW_SECTION_CONTRIBUTING_START -->

Contributing

Do you want to contribute? Awesome! Please follow these recommendations.

<!-- SHADOW_SECTION_CONTRIBUTING_END --> <!-- SHADOW_SECTION_MAINTAINERS_START -->

Maintainers

<a href="mailto:frederikwessberg@hotmail.com"><img alt="Frederik Wessberg" src="https://avatars2.githubusercontent.com/u/20454213?s=460&v=4" height="70" /></a>
Frederik Wessberg<br><strong>Twitter</strong>: @FredWessberg<br><strong>Github</strong>: @wessberg<br>Lead Developer
<!-- SHADOW_SECTION_MAINTAINERS_END --> <!-- SHADOW_SECTION_FAQ_START -->

FAQ

<!-- SHADOW_SECTION_FAQ_END -->

What's the difference from polyfill.io

These two services are very much alike. In fact, Polyfiller depends on the library behind polyfill.io for some of the polyfills! Polyfiller exists for two reasons:

Hosting

Polyfiller is already hosted at https://polyfill.app/api as a free web service, but feel free to host it yourself. The server is built with support for both HTTP2 and HTTP. The environment variable HTTP2=[true|false] decides whether a HTTP2 server will be hosted or not. If you use a load balancer and something like nginx in a reverse proxy setup, please know that nginx doesn't support HTTP2 via its proxy module, so you have to use HTTP1.1 there. Thankfully, it is as easy as setting HTTP2=false before launching the server and setting HTTPS=false.

Logo

All credits go to Andreas Mehlsen (@andreasbm) for the awesome logo design.

<!-- SHADOW_SECTION_LICENSE_START -->

License

MIT © Frederik Wessberg (@FredWessberg) (Website)

<!-- SHADOW_SECTION_LICENSE_END -->

Feature names

Here's a full list of all possible feature names. Note that these will be deduplicated. For example, if you request es.object, but also request es, es.object will only be included once as part of es. And, if you request performance.now, date.now will also be included since the polyfill depends on it. You don't have to worry about dependencies.

Bold-formatted polyfills are aliases for one or several other related features.