What is a polyfill

July 30th, 2018 4 min read

by Everaldo Coelho
by Everaldo Coelho
No translations available.Add translation

A few weeks back I found a bug with IE where all the user saw was a blank white page. If you've been around for a while in the wonderful world of the client-side SPA, you'll probably know what was wrong without thinking twice. That's right. It was a JavaScript error before client-side rendering happened.

Considering it the bug only rears its head in Internet Explorer, my first guess is a problem with polyfills. Yep! That was it!

Uncaught TypeError: contacts.includes is not a function

But we're transpiling our code with Babel! Doesn't that mean that I can use all the latest and greatest JavaScript I want without having to worry about whether the browser supports it? Nope! Let's learn more...

Polyfills vs Code Transforms

JavaScript is constantly evolving thanks to the efforts of people in and around the TC39. Some of the evolutions rely on new syntax (like arrow functions) which allows me to do this:

const addOne = num => num + 1
if (addOne(2) > 2) {
  console.log('Math. Wow!')

Often, we can use this syntax in our source code so long as we convert it to syntax that can run in the browser (for example, by using a transpiler such as babel: example transpiled in the browser with babel-preset-env).

Some other of these new features rely on new APIs, like Array.prototype.includes which allows me to do this:

const contacts = ['Brooke', 'Becca', 'Nathan', 'Adam', 'Michael']
if (contacts.includes('Rachel')) {
  console.log('You have a Rachel!')

With these, if you run them through babel's env preset the includes function is not transpiled because it's not a syntax issue, but a built-in API one and babel's env preset only includes transforms for syntax transformations. You could write your own babel plugin (like this) to transform the code, but for some APIs it just wouldn't be practical because the transformed version would be significantly complex.

A polyfill is code which will make the currently running JavaScript environment support features which it does not. For example, a (imperfect) polyfill for includes might look something like this (refer to MDN for a real polyfill):

if (!Array.prototype.includes) {
  Array.prototype.includes = function includes(searchElement) {
    return this.indexOf(searchElement) !== -1

The if statement is there to make this a "gated" polyfill. That means that if the functionality already exists, the polyfill code will not override the pre-existing behavior. You may consider this to be desirable, but it's actually the reason that includesis not called contains on String.prototype (TL;DR: some versions of mootools implemented contains in a gated fashion but the implementation is different from how includes works so the TC39 had to change the name to not break tons of websites).

The part that assigns Array.prototype.includes to a function is called "monkey-patching" 🐒 By applying this to the prototype, we're adding includes support to all arrays in the app (learn more about prototypes here). Effectively, the polyfill's job is to make it so I can use the JavaScript feature without worrying about whether it's supported by the environment in which my code is running (like IE 10 for example).

Where to get transforms and polyfills

With syntax transforms, I recommend babel-preset-env. It's actually fairly straightforward. For polyfills, the most popular one is core-js. You might also look at babel-polyfill which uses core-js and a custom regenerator runtime to support generators and async/await the way that babel transpiles it. Polyfills are sometimes referred to as "shims" and you may be interested in the js-shims by airbnb (which I've been told are more spec-compliant than core-js).


So what did I do to fix my IE10 bug? Well, one thing that really bugs me is that I have to ship all this code for polyfills to all browsers even if they do support these features. But a few years ago I heard of a service that was able to ship polyfills that are relevant only to the browser requesting them. I created my own endpoint that uses the module that powers that service and I'll write about that next week!

I hope this is helpful! Good luck!

P.S. You may have heard of something called a "ponyfill." Ponyfills are similar to polyfills except they don't monkey-patch, instead they're just the function by itself and allow you to call them directly. Learn more about ponyfills. In general, I'm more in favor of ponyfills, though you just can't get away from polyfills completely because often your dependencies are relying on built-ins that your browsers don't support.

Kent C. Dodds
Written by Kent C. Dodds

Kent C. Dodds is a JavaScript software engineer and teacher. Kent's taught hundreds of thousands of people how to make the world a better place with quality software development tools and practices. He lives with his wife and four kids in Utah.

Learn more about Kent

If you found this article helpful.

You will love these ones as well.