What is the difference between a shim and a polyfill?

From what I understand:

A polyfill is code that detects if a certain "expected" API is missing and manually implements it. E.g.

if (!Function.prototype.bind) { Function.prototype.bind = ...; }

A shim is code that intercepts existing API calls and implements different behavior. The idea here is to normalize certain APIs across different environments. So, if two browsers implement the same API differently, you could intercept the API calls in one of those browsers and make its behavior align with the other browser. Or, if a browser has a bug in one of its APIs, you could again intercept calls to that API, and then circumvent the bug.

Shim

If you are familiar with the adapter pattern, then you know what a shim is. Shims intercept API calls and create an abstract layer between the caller and the target. Typically shims are used for backward compatibility. For instance the es5-shim npm package will let you write ECMAScript 5 (ES5) syntax and not care if the browser is running ES5 or not. Take Date.now as an example. This is a new function in ES5 where the syntax in ES3 would be new Date().getTime(). If you use the es5-shim you can write Date.now and if the browser you’re running in supports ES5 it will just run. However, if the browser is running the ES3 engine es5-shim will intercept the call to Date.now and just return new Date().getTime() instead. This interception is called shimming. The relevant source code from es5-shim looks like this:

if (!Date.now) {
    Date.now = function now() {
        return new Date().getTime();
    };
}

Polyfill

Polyfilling is really just a specialized version of shimming. Polyfill is about implementing missing features in an API, whereas a shim wouldn’t necessarily be as much about implementing missing features as it is about correcting features. I know these seems overly vague, but where shims are used as a more broader term, polyfill is used to describe shims that provide backward compatibility for older browsers. So while shims are used for covering up old sins, polyfills are used for bringing future enhancements back in time. As an example there is no support for sessionStorage in IE7, but the polyfill in the sessionstorage npm package will add this feature in IE7 (and older) by using techniques like storing data in the name property of the window or by using cookies.

• A shim is any piece of code that performs interception of an API call and provides a layer of abstraction. It isn't necessarily restricted to a web application or HTML5/CSS3.

• A polyfill is a type of shim that retrofits legacy browsers with modern HTML5/CSS3 features usually using Javascript or Flash.

Answering your specific question, call your directory shims if you want to keep the directory generic.