Getting started with webpack - Part 8: Writing your own plugins

Introduction

In the previous post we learned how to optimize our assets before bundling them using webpack. These optimizations are very useful when deploying webpack bundled applications in production as they make our app load faster.

In this part, we will consider how to create your own webpack plugins from scratch. Chances are, you may never have to do this as there are already thousands of awesome webpack plugins you can choose from. All you have to do is search for them on Google. However, for the sake of knowledge, let’s consider how to make a webpack plugin anyway.

Let’s get started.

NOTE: Source code of the application is available on GitHub.

Prerequisites

To follow along in this series, you need the following requirements:

• Completed all previous parts of the series.
• Basic knowledge of JavaScript.
• Basic knowledge of the CLI.
• A text editor. VS Code is recommended.
• Node.js (>= 6.11.5) and npm installed locally.

Let’s continue with the series.

Setting up our project

Before we start creating our own plugin, we will be using our project code as a base. If you haven’t already, you can download the project code from GitHub. We will be using the code there as a base for the modifications we are going to make going forward. When you have downloaded the project, open Part-7 in your code editor and follow along.

The folder named Part-8 contains the already finished code for this part. If you want to follow along use part 7 as the base. If you want a source of reference, check part 8.

Before we get started, run the following command in the root of the project to install the npm dependencies:

    $ npm install

This will install all the dependencies required for our application to run. To be sure the application works as intended, run the following command below:

    $ npm run serve

This command will build the assets and run the Express server. When the build is complete, visit http://localhost:3000 and you will see the application:

Now that we have the application running, we can kill the server using ctrl+c or by closing the terminal window.

Anatomy of a webpack plugin

Plugins are the backbone of webpack. Some of the core features of webpack are actually written as plugins underneath the hood. This means plugins are exposed to the powerful API that comes with webpack.

When developing plugins for webpack, you need to know the following objects: compiler and compilation. Understanding what they do is the first step to knowing how to write plugins for webpack.

According to the documentation, the compiler object

…represents the fully configured Webpack environment. This object is built once upon starting Webpack, and is configured with all operational settings including options, loaders, and plugins. When applying a plugin to the Webpack environment, the plugin will receive a reference to this compiler. Use the compiler to access the main Webpack environment.

According to the documentation, the compilation object

…represents a single build of versioned assets. While running Webpack development middleware, a new compilation will be created each time a file change is detected, thus generating a new set of compiled assets. A compilation surfaces information about the present state of module resources, compiled assets, changed files, and watched dependencies. The compilation also provides many callback points at which a plugin may choose to perform custom actions.

If you like to read some code, here’s the source code to the compilation and compiler resources.

Let’s create the most basic plugin so you can see how it would look in the code.

Creating the most basic plugin

For our most basic plugin, we will create a plugin that spits out the obligatory Hello World text in the console when it’s called.

To get started, create a new directory in the src/js directory called plugins and in the directory, create a new HelloWorld.js file and paste the following code into it:

javascript
1// File: ./src/js/plugins/HelloWorld.js
2    class HelloWorld {
3      apply(compiler) {
4        compiler.hooks.done.tap({ name: 'HelloWorld' }, () => {
5          console.log('Hello world!');
6        });
7      }
8    };
9    
10    module.exports = HelloWorld;
Copy

Next, go to the webpack configuration file and import the plugin as seen below:

javascript
1// File: webpack.config.js
2    const HelloWorld = require('./src/js/plugins/HelloWorld');
3    
4    module.exports = {
5    
6      // [...]
7    
8      plugins: [
9        // [...]
10        
11        new HelloWorld(),
12    
13        // [...]
14      ]
15    
16    };
Copy

Above, we imported the HelloWorld plugin and then registered it as a webpack plugin by adding it to the plugins array.

Now, run the following command to build our assets:

    $ npm run dev

If all goes well, you should see the text Hello World! in the build output text.

Let’s add some options to the plugin where you can pass the message you want to be displayed instead of hard-coding it.

Open the HelloWorld.js file and replace the content with the following code:

javascript
1// File: ./src/js/plugins/HelloWorld.js
2    class HelloWorld {
3      constructor(options) {
4        this.options = options;
5      }
6      
7      apply(compiler) {
8        compiler.hooks.done.tap('HelloWorld', () => {
9          console.log(this.options.message || 'Hello World!');
10        });
11      }
12    }
13    
14    module.exports = HelloWorld;
Copy

In the code above, we have added a few things. First, we added an options property to the class. This property will be passed through the plugin constructor. We then use the message property of the options property as the message we want to log to the console.

Now open the webpack configuration file and update as seen below:

javascript
1// File: webpack.config.js
2    const HelloWorld = require('./src/js/plugins/HelloWorld');
3    
4    module.exports = {
5    
6      // [...]
7    
8      plugins: [
9        // [...]
10        
11        new HelloWorld({
12          message: 'Badge "webpack bundler bender" unlocked!',
13        }),
14    
15        // [...]
16      ]
17    
18    };
Copy

Now, let’s build again using the command below:

    $ npm run dev

Now you should see the custom message in the console:

Great! New badge ‘webpack bundler bender’ unlocked! Let’s create an actual webpack plugin and make use of some of the other webpack plugin APIs.

Creating our custom webpack plugin

For this example, we will be building a webpack plugin that lists all the bundled files and their size in a file. We can then look at the file and determine what the sizes of our bundled assets are. Let’s assume we need this particular plugin.

Let’s get started. Create a new file WebpackCustomManifestPlugin.js in the src/plugins directory. Now paste the following code into the file:

javascript
1// File: ./src/plugins/WebpackCustomManifestPlugin.js
2    class WebpackCustomManifestPlugin {
3      constructor(options) {
4        this.options = options;
5      }
6    
7      apply(compiler) {
8        // 
9      }
10    }
11    
12    module.exports = WebpackCustomManifestPlugin;
Copy

Before adding the actual functionality, let’s go to our webpack configuration file and register the plugin as we want it to be used.

Open the webpack config file and import the plugin as seen below:

javascript
1// File: webpack.config.js
2    const CustomManifestPlugin = require('./src/js/plugins/WebpackCustomManifestPlugin');
3    
4    module.exports = {
5    
6      // [...]
7    
8      plugins: [
9    
10        // [...]
11    
12        new CustomManifestPlugin({
13          outputPath: path.resolve(__dirname + '/')
14        }),
15    
16        // [...]
17      ]
18    };
Copy

As seen above, we have registered our custom plugin and passed an options object to it. The only configuration we passed to the plugin is the outputPath. This path is where we will place the generated manifest file.

Now switch to the plugin file and add the following to the class:

javascript
1// File: ./src/js/plugins/WebpackCustomManifestPlugin.js
2    const fs = require('fs');
3    const chalk = require('chalk');
4    
5    class WebpackCustomManifestPlugin {
6      constructor(options) {
7        this.validateOptions(options);
8    
9        this.options = options;
10      }
11    
12      validateOptions(options) {
13        if (!options || !options.outputPath) {
14          const msg = `Please specify an outputPath.`;
15          throw new Error(console.log(chalk.bold.bgRed('Error:'), chalk.bold.red(msg)));
16        }
17      }
18    
19      apply(compiler) {
20        // 
21      }
22    }
23    
24    module.exports = WebpackCustomManifestPlugin;
Copy

Above, we have imported chalk and fs. We will need chalk to write colorful messages to the console and fs to write to the file system. Next, we added a new method called validateOptions, which we use to validate the options passed to the plugin. Next, we call this method inside the constructor method.

Note: You might have to install the chalk package using npm by running the command: npm i chalk -D

Now, in the same file, let’s add the meat of the plugin in the apply method. Replace the apply method with the following code:

javascript
1// File: ./src/js/plugins/WebpackCustomManifestPlugin.js
2    // [...]
3    
4    class WebpackCustomManifestPlugin {
5      // [...]
6    
7      apply(compiler) {
8        const { outputPath, fileName = 'manifesto.json' } = this.options;
9    
10        compiler.hooks.done.tap('Custom Manifest', stats => {
11          const assetsManifest = [];
12          const { assets } = stats.compilation;
13    
14          Object.keys(assets).map(name => {
15            let size = assets\[name\]['_cachedSize'] / 1000;
16    
17            if (!isNaN(size)) {
18              size = Math.round(size) + ' KB';
19              assetsManifest.push({ name, size });
20            }
21          });
22    
23          try {
24            let filePath = outputPath + '/' + fileName;
25    
26            fs.writeFileSync(filePath, JSON.stringify(assetsManifest, null, 4));
27    
28            console.log(chalk.green.bold('Manifest generated'));
29          } catch (error) {
30            console.log(chalk.bold.bgRed('Exception:'), chalk.bold.red(error.message));
31          }
32        });
33      }
34    }
35    
36    // [...]
Copy

Above, we have the meat of the entire plugin. First, we tap into the done hook because we need to run the plugin when the compilation is complete. Next, we loop through the available assets and for each of them, we get the size. We then write all the assets with sizes into our manifest file and use the chalk package to write to the console on failure or success.

Now, save the file and run the following command to build the app:

    $ npm run dev 

If all goes well, you will see a manifesto.json file in the root of the application with the assets and the size of the assets. It will look something like this:

json
1[
2        {
3            "name": "assets/css/app-c7359d5814d5f7029e5c.css",
4            "size": "177 KB"
5        },
6        {
7            "name": "assets/js/app-8c115777c5531186c849.js",
8            "size": "11 KB"
9        }
10    ]
Copy

That’s it, you have created your first webpack plugin.

Conclusion

In this part of the series, we learned how we can create our very own webpack plugin. In the next part we will look into how to use webpack with some popular frameworks and libraries.

The source code for this application is available on GitHub.