Adding polyfills and ponyfills to your Stencil components 🐴

The Stencil compiler already has some polyfills which are pre-baked-in to your components for things like CSS variable support, but what if you need to add on additional support for the components you make?

There are two ways to add missing API functionality — you can either add a shim which patches the native API (polyfill) or bring in the same functionality through a module and use it like an external library (ponyfill).

In this article we will cover how to include both methods, and include an opinionated view on what scenario(s) would be best suited for each one.

Getting started

Let’s get started by creating a brand new Stencil project. In this example we will use the Stencil component starter.

npm init stencil
ionic-pwa
  app
> component

After you have created your project, open the source code in your favourite code editor.

Adding backwards compatibility for Array.prototype.fill()

During a project I found that I needed to pre-fill an array with values before using it. We could solve this by iterating through the array in a for loop and populating each entry, or we could use the handy fill() function on our Array object to do the hard work for us… improving readability on our code and also writing less.

Across the browsers, fill() is already widely supported on the major players… however if you have requirements for your component(s) to work on unsupported browsers like IE11 you will run into a bit of trouble in testing.

In this example we will provide support for this method across our entire component library, so if we need to use it we don’t have to worry about loading it in per-component. There is a great polyfill for the fill() method on the MDN Web Docs which we can use already. Let’s create a new file in our project at src/polyfills/fill.ts and drop in the polyfill code.

Now that we have this in our project, we need to include it across all of our components. We could manually write imports on each component where we need to use it, or alternatively we can bring the polyfill in globally.

In Stencil, we can bring in a global script using the globalScript property of stencil.config.ts . As this only takes a single file, we need to create a script which imports our polyfill and any other scripts we wish to include together.

Let’s create another file in our project at src/global/global.ts which will serve as our entry point. Inside this file we will need to include our polyfill, which can be done like this:

import "../polyfills/fill-polyfill";

We now have our fill polyfill included in our global script, but the script is not yet being loaded. In stencil.config.ts we need to add:

globalScript: "src/global/global.ts"

And that is all there is to it! We can now relax knowing that our fill() method has been polyfilled, allowing our component to work on IE11.

Adding (forwards) compatibility for the ResizeObserver API

Sometimes we want to work with the latest and greatest APIs, working at the forefront of what the web has to offer (That’s why you’re building web components with Stencil, right?). Unfortunately this has its caveats, as we have to wait months, sometimes years for these new APIs to be supported across the browsers we need to provide support for.

In another post, we looked at how we could create responsive components. While it would be great to make all of our components responsive using this API, it isn’t always going to be completely necessary — so we will bring in support for this API through a ponyfill. As of writing the ResizeObserver isn’t widely adopted across browsers, so we cannot be sure that the spec won’t change until now and if/when it gets supported. By ponyfilling it, this ensures that even if the spec changes, we have consistent functionality across all supported browsers for our component.

First we can install resize-observer-polyfill via npm:

npm install resize-observer-polyfill --save

Now that we have this available in our project, we can import it in to our component’s code ./src/components/my-component/my-component.tsx.

import ResizeObserver from "resize-observer-polyfill";

From here we can use the imported ResizeObserver much like any other third party library we import. Take a look at Creating responsive components in Stencil using the ResizeObserver API for a full guide on how to use this API.

Fill ’em up!

You now have all the smarts you need to provide wider browser support for the components you are building. These are just a handful of ways to provide backwards/forwards support in the browser, feel free to add more ways in the responses below!