How "include" and "exclude" works in webpack loader

Question

Update&Answer:

My misunderstand was:

All the imported/required files will be transformed by loader.

However, some imported/required files are not necessary to be transformed. For example, js files in "node_module" have been processed. So there is no need to be transformed again by Babel loader. That is basically why we need "exclude: /node_modules/" in loader.

Similarly, if you know what files to be transformed by a loader, you can use "include".

Simply put, entry.js will include all the imported/required files. But among these files, only a few of them need to be transformed. That is why "loader" introduces "include" and "exclude".

---

I am still not quite clear about the reasons why we need use "include" or "exclude" in loader of webpack.

Because the entry js file will always need to include its imported/required js files recursively. All the imported/required files will be transformed by loader. If that is the case, why do we need "include" or "exclude" in loader?

One common case is "exclude: /node_modules/". The thing that confuses me is that if the entry js file need some files from the node_modules and then we exclude the node_modules. Then the final bundle file will not contain the requied file from node_modules. In that case, the final bundle.js will not work correctly. Am I missing anything here?

module.exports = {
  entry: [
    './index.js'
  ],
  output: {
    path: path.join(__dirname,"public"),
    filename: 'bundle.js'
  },
  module: {
    loaders: [{
      test: /\.js$/,
      loader: 'babel',
      exclude: /node_modules/,
      query: {
          presets: ['es2015']
        }
    }]
  }
}; 

Thanks

Derek

Answer 1

Why do you need to customize webpack include/exclude settings at all if webpack bundles (or externalizes) all dependencies anyway?

This seems to be the OP's main question. The gist of my answer is similar to previous answers: because of bundler performance. Everything that is required/imported will be bundled or externalized. exclude does not change that, but only excludes files from transformation according to module.rules. You generally do not want to transform all bundled dependencies (e.g. node_modules), since those are usually already in a "very digestible" format for your application, thus not requiring an extra transformation pass. In short: if possible try to avoid transformation, or: "exclude good, include bad".

However, while this type of performance optimizations aims to reduce bundling time, it is not a perfect solution. In discussions about run-time performance optimization (will link when I find them again), you will find that it can be advantageous to transform (i.e. include) everything if the loader works to help improve global (cross-module) run-time performance optimization.

Another example of where it might be advantageous to include an already transformed library: imagine some library was transformed to replace async functions with a dependency on the dreaded regeneratorRuntime, which, in addition to slowing things down during runtime is notorious for causing a lot of pain. In that case, if you don't want that dependency, you might (with some effort) be able to get webpack to include, consume and transform its raw source files to re-compile with your own webpack config and keep the async functions, while still excluding most other node_modules.

How does "include" and "exclude" work in webpack loader?

The phrasing of the question title might lead some (such as myself) to come here from Google in order to better understand how to customize their webpack.config's include and exclude options since relevant official documentation is somewhat scattered. In short:

1. exclude and include (and test and resource) are documented here.
2. They are Conditions, which are documented here.
   • As you can see from that documentation, Conditions (i.e. include/exclude) can be functions or even arrays of functions, or mixture of function, regex, string etc.
   • I found the function bit particularly interesting. You can use that not only to better customize your conditions, but also to debug webpack resolution problems. It allows you to log and clearly understand all included/excluded files, as they are picked up by webpack's resolution algorithm. You can use functions like so:

     {
       test: /\.js$/,
       // ...
       include(resourcePath, issuer) {
         console.log(`  included: ${path.relative(context, resourcePath)} (from ${issuer})`);
         return true; // include all
       }
     }
     

3. The two parameters to those functions (resourcePath and issuer) are documented here.
   • Here, they also mention that the resourcePath is the resolved path (not relative path nor name).

PS: While the use of functions for include/exclude is technically (kind of) documented, it is clearly not very obvious, as can be seen from the many many votes on this github issue comment.

Answer 2

The problem is that without that exclude (or an include) webpack would traverse through the dependencies when you point to them at your code and process them. Even though that could work, it would come with a heavy performance penalty.

I prefer to set up an include myself (allowlist over denylist/blocklist) as that gives me more control over the behavior. I include my application directory and then add more items to the include based on the need. This allows me to make exceptions easily and process bits from node_modules if absolutely needed.

Answer 3

The answers so far haven't really answered your core question. You want to know how your bundled app still manages to function even though its dependencies have been 'excluded'.

Actually, those 'include' and 'exclude' properties are telling the loaders whether to include/exclude the files described (such as the contents of node_modules), not webpack itself.

So the 'excluded' modules you import from node_modules will be bundled - but they won't be transformed by babel. This is usually the desired behaviour: most libraries are already transpiled down to ES 5.1 (or even ES 3), and so wasting CPU cycles parsing them with babel (for instance) is pointless at best. At worst, as in the case of large single-file libraries like jQuery, it can throw an error and bring your build to a crashing halt. So we exclude node_modules.