The polyfill property of package.json indicates what features need to be polyfilled in older browsers. The polyfill property should not include the polyfills required for dependencies of the given package (they should have their own polyfill property).
Many packages in npm can be used in browsers. Many of them use methods that are not available in older browsers though. Still others inline the code for the polyfills, or require large libraries like underscore instead of using the builtin methods that the language provides.
The problem with including polyfills or workarounds in the libraries is that it forces even consumers who don't wish to support older browsers to still include these polyfills. It also creates fragmentation as many different libraries may require the same functionality to be polyfilled (you don't want 10 slightly different JSON parsers in your project).
Clearly the package consumer shouldn't have to manually figure out which polyfills are required. The "polyfill" package.json property allows package authors to specify the features that may require polyfilling up front, without having to worry about including a specific implementation of those polyfills with the library. Package consumers can then figure out which polyfills are required programatically, and automatically generate an appropriate polyfill.
Consider the following module for doubling a list of numbers:
index.js
module.exports = double;
function double(numbers) {
return numbers.map(function (val) {
return val * 2;
});
}Rather than complicating a simple module by requiring underscore to use _.map or by including a polyfill for Array.prototype.map inline (potentially duplicating effor required by many modules), we can simply specify that it will need that polyfill, and consumers can decide whether or not they want to support browsers that don't have that feature.
The resulting package.json looks like:
{
"name": "doubler",
"version": "1.0.0",
"polyfill": ["Array.prototype.map"]
}The IDs of features are case-insensitive and shoudl be taken from one of the following (in this order of precidence):