timkor / nuxt-polyfill

Ease adding polyfills to your Nuxt.js project

nuxt-polyfill

Ease adding polyfills to your Nuxt.js project.

Requires Nuxt >= 2

Features

• ✔ Easy to configure
• ❔ Lazy load polyfills only if needed by using Feature Detection
• ⚡️ Aims to be as fast as possible
• 🔧 Supports any polyfill as NPM package or JS file
• ⭐️ Supports polyfills from polyfill.io
• Detect function can be called before loading the features
• Polyfills are not included in the bundle but loaded separately

Getting started

npm install nuxt-polyfill

Add the module to your nuxt.config.js:

export default {
    
    // Configure polyfills:
    polyfill: {
        features: [
            /* 
                Feature without detect:

                Note: 
                  This is not recommended for most polyfills
                  because the polyfill will always be loaded, parsed and executed.
            */
            {
                require: 'url-polyfill' // NPM package or require path of file
            },

            /* 
                Feature with detect:

                Detection is better because the polyfill will not be 
                loaded, parsed and executed if it's not necessary.
            */
            {
                require: 'intersection-observer',
                detect: () => 'IntersectionObserver' in window,
            },

            /*
                Feature with detect & install:

                Some polyfills require a installation step
                Hence you could supply a install function which accepts the require result
            */
            {
                require: 'smoothscroll-polyfill',

                // Detection found in source: https://github.com/iamdustan/smoothscroll/blob/master/src/smoothscroll.js
                detect: () => 'scrollBehavior' in document.documentElement.style && window.__forceSmoothScrollPolyfill__ !== true,

                // Optional install function called client side after the package is required:
                install: (smoothscroll) => smoothscroll.polyfill()
            }
        ]
    },
    
    // Add it to the modules section:
    modules: [
        'nuxt-polyfill',
    ]
}

Note: You need to install the NPM packages manually.

In order to run this example:

npm i url-polyfill intersection-observer smoothscroll-polyfill

Useful polyfill links (including detection functions):

• https://github.com/Financial-Times/polyfill-library

Documentation

feature.name

Type String. Not required.

feature.require

Type String. NPM package or require path of JS file.

feature.detect

Type Function. Detection function, should return a Boolean.

feature.install

Type Function. Installation function. First argument is the default export in the required file/package.

feature.include

Type Boolean. Default: false Specify if the polyfill will be included into the default bundle. This will make sure the polyfill is downloaded together with the rest of your application. This might reduce page speed.

Note: If you care about Pagespeed you should choose the value of this flag carefully. It depends on the size and the probability of the availability of native support. If a polyfill's bundle size is really small and/or a polyfill is more likely required (because current support is bad), you should set this flag to true. Otherwise it's best to lazy load it.

feature.mode

Not supported yet. Only client polyfills are supported.

Roadmap

• Support for server side polyfills
• Support for require array (necessary for Intl polyfill)

nuxt-polyfill's Issues

Error - Could not resolve module

I installed the package using npm install nuxt-polyfill and added it to nuxt.config

However, when I try to run the app, I keep getting the error - cannot find module nuxt-polyfill

It's installed correctly in node_modules - however, I don't think nuxt is looking for module in node_modules. Can you help?

Question - How to use for IE 11 ?

Hello,

I'm having hard time making my app run on IE 11. This module seems interesting, but I can't figure how to configure it.

My error on IE 11 is : "object doesn't support property or method from"

How can I configure your module to detect this error and import the correct polyfill ?

Thanks in advance !

pollyfill.io example?

Is there an example anywhere of how to use this with pollyfill.io?

Sorry if there is and/or i'm being thick

A demo of a local file would be good

I was getting these errors:

friendly-errors 15:42:24  ERROR  Failed to compile with 1 errors
friendly-errors 15:42:24 This relative module was not found:
friendly-errors 15:42:24 
friendly-errors 15:42:24 * ./vendor/polyfills/nodelist-foreach.js in ./.nuxt/nuxt-polyfill/vendor/polyfills/nodelist-foreach.js.js

Until I changed this:

  polyfill: {
    features: [
      {
        require: "vendor/polyfills/nodelist-foreach",
        detect: function() {
          return window.NodeList && !NodeList.prototype.forEach;
        }
      }
    ]
  }

To:

  polyfill: {
    features: [
      {
        require: `${__dirname}/vendor/polyfills/nodelist-foreach`,
        detect: function() {
          return window.NodeList && !NodeList.prototype.forEach;
        }
      }
    ]
  }

Not sure if that's the best way though and an example might help others

Polyfill Object.entries

Hi! First thank you for this awesome module. It makes polyfilling much easier.
I want to polyfill Object.entries, using this npm package:
https://www.npmjs.com/package/object.entries

What's wrong with my code?

 {
        require: 'object.entries',
        detect: () => 'entries' in window.Object,
        install: entries => entries.shim(),
 }

Download on specific page

Hi, I guess it would be useful if users could download specific polyfills on specific paths or pages.
Example of the nuxt config:

export default {
  polyfill: {
    features: [
      {
        require: 'url-search-params-polyfill',
        detect: () => 'URLSearchParams' in window,
        pages: [
          '/auth/:id',
          '/some-other/'
        ]
      }
    ]
  }
}

Why? Because in this example I don't use 'url-search-params-polyfill' everywhere, so I guess it'd be better if we could save user's traffic. Thanks!