Self-host Polyfill.io

When you develop a web application and want to support older browsers but also want to use the latest browser-features, you often need polyfills that implement new features in older browsers. One common approach with polyfills is to bundle them together with the application. The problem is that this increases the bundle size, and users with modern browsers have to download code their browser does not need.

An alternative is the Polyfill.io service. It's a service developed and maintained by the Financial Times. You send a request to the service and get the requested polyfills, but only if your browser does not natively support the features.

In the simplest case, you insert a script tag like this into your HTML page:

<script src="https://polyfill.io/v3/polyfill.min.js?features=fetch"></script>

This returns the polyfill for the Fetch API. On most browsers, this returns an empty script, but on an older browser like IE11, this returns the polyfill code.

Polyfill.io analyzes the User-Agent HTTP request header to determine what code it has to send back.

You can also request multiple polyfills by listing them separately with a comma. This script tag requests the Fetch API and Promise polyfill.

<script src="https://polyfill.io/v3/polyfill.min.js?features=fetch%2CPromise"></script>

The Polyfill.io website provides an URL builder, where you can select your required polyfills and get a polyfill.io URL that you can embed into your site.

One issue with Polyfill.io is that your application depends on a third-party service you don't have any control over. This may be fine when the application already depends on many other external services.

But when Polyfill.io is the only external dependency, this might be an issue. Or you develop an in-house web application, where you have to support older browsers, and the employees only have limited or no access to the Internet.

Fortunately, this issue can be solved by installing Polyfill.io on your server. The source code is publicly available on GitHub, and it's written in JavaScript and Node.js. Therefore, it should run on any platform where a Node.js runtime is available.

Installing ¶

Here is a description of how you can install Polyfill.io. I show here the Docker installation, but you can also directly install Polyfill.io on your host machine. Just run the commands in the Dockerfile on the target machine.

First, make sure that Docker is installed. You find installation instructions for different operating systems here: https://docs.docker.com/engine/install/

Dockerfile ¶

Create a Dockerfile with the following content. You can save this file in any directory.

FROM node:lts-alpine

RUN apk add --no-cache --update bash
RUN apk add --no-cache --update --virtual build git python3 make gcc g++
WORKDIR /polyfill

ARG POLYFILL_SERVICE_VERSION=4.49.5
ARG NODE_ENV='production'
ENV PORT 8801

RUN wget https://github.com/Financial-Times/polyfill-service/archive/v$POLYFILL_SERVICE_VERSION.tar.gz -P /tmp \
  && tar -xzf /tmp/v$POLYFILL_SERVICE_VERSION.tar.gz -C /polyfill/ --strip-components=1 \
  && rm -f /tmp/v$POLYFILL_SERVICE_VERSION.tar.gz

RUN npm install -g patch-package
RUN npm ci --no-audit

RUN sed -i.bak -e 's,^node,exec node,' start_server.sh && \
        mv start_server.sh /bin/ && \
        chmod a+x /bin/start_server.sh && \
        apk del build

EXPOSE ${PORT}

CMD ["/bin/start_server.sh", "server/index.js"]

Assign the latest Polyfill.io version to the POLYFILL_SERVICE_VERSION argument. Check out the release page of Polyfill.io to find the latest version number

Build ¶

Build the Docker image and tag it. In this example, I tag the image with the name polyfillservice.

docker build -t polyfillservice .

Run ¶

I recommend running the Docker image in the foreground to see if everything works.

docker run polyfillservice

Stop the container with Ctrl+C.

Now we can run the image in the background with the following command.

docker run -d -p 3006:8801 polyfillservice

In this example, I map the internal port 8801 to the host port 3006.

Test if everything works with curl. This command should return a bunch of JavaScript code.

curl https://polyfill.io/v3/polyfill.min.js

This concludes the installation of Polyfill.io with Docker.