DEV Community: Fogel

Potential issues with barrel files in Jest

Fogel — Wed, 22 May 2024 09:02:23 +0000

Introduction

In the previous article, Potential issues with barrel files in Webpack, we discussed the potential issues of using barrel files in Webpack. In this article, we will focus on the issues of using them in Jest tests.

For a comprehensive understanding of barrel files and their use cases, I recommend reading the previous article.

Barrel files in Jest

Unlike Webpack, Jest does not have a tree shaking feature. This means that when you import modules through barrel files, Jest will include all the exported modules from barrel files in your tests, even those that are not used. This behavior can lead to two significant issues: slow performance and unexpected test results.

Issues

1. Performance Impact

One of the most common complaints from developers who use Jest often report slow test execution times when their code includes barrel files #1. While this might not be noticeable in smaller projects, it becomes a significant issue in larger ones.

This issue arises because Jest needs to load all the modules exported from a barrel file, regardless of their usage. This can significantly increase loading time, especially if the barrel file contains numerous modules.

Example

To illustrate this issue, let's consider the perf-impact example repository.
In this repository, we want to test the Javascript file indirect-import.js that imports only the Reexported1 specifier from a barrel file index.js, which re-exports 100 modules.

Let's create a test for this file named indirect-import.test.js and run npm run test and observe the performance.

The test execution takes an average of 2.865 seconds, which is significant for a single test. Imagine the time it would take for hundreds of tests relying on barrel files!

Why is it slow? When importing from barrel files, Jest loads all the modules, even unused ones, impacting performance.
We need a solution for this poor test performance.

Solution

One solution could be to avoid using barrel files altogether, but this would negatively impact our developer experience.

Another solution can be using a tool that will automatically transform indirect imports to direct imports.
To address this, I developed a Babel plugin, babel-plugin-transform-barrels, that transforms indirect imports (through barrel files) into direct imports.

Let's apply the babel-plugin-transform-barrels plugin solution as follows:

Clone the perf-impact repository to a new perf-impact-with-barrel-plugin repository.
Install the babel-plugin-transform-barrels plugin.
Copy the babelTransform.js file into the folder config\jest.
Adapt the babelTransform.js file to the current repository.
In the jest.config.js file, reference the transform object to the babelTransform.js file instead of the regularTransform.js file.
Run the command npm run test.

Now, see that the test time dropped from 2.865 seconds to 1.31 seconds, which is a reduction of more than 50%. This improvement is very significant!

Note
The above steps have been implemented in the perf-impact-with-barrel-plugin repository.

Now that we’ve addressed the performance issue, let’s move on to the next issue.

2. Unexpected Test Results

Another issue can arise when we import a module from a barrel file that contains unused modules, some of these unused modules can affect the test results in unexpected ways.

Example

To illustrate this issue, let's consider the unexpected-results example repository.
In this repository, we want to test the Javascript file indirect-import.js that imports only FirstReexported specifier from a barrel file index.js, which re-exports all the specifiers from the Reexported and DropFiles modules.

Let's create a test for this Javascript file named indirect-import.test.js and run npm run test.

We can see that the test failed. As we can see in the details of the test's result, the failure is caused by the module DropFiles.

But why did the test fail because of an unused module that we didn't want to import? As mentioned earlier, when we import from a barrel file, all the re-exported modules will be loaded, even the unused modules.

Again, the barrel file caused a problem for us!

Solution

The solution here is the same as the previous example of perf-impact. We need to transform the imports from indirect imports (through barrel files) to direct imports.

Let's do the same steps as the previous example.

Let's apply the babel-plugin-transform-barrels plugin solution as follows:

Clone the unexpected-results repository to a new unexpected-results-with-barrel-plugin repository.
Install the babel-plugin-transform-barrels plugin.
Copy the babelTransform.js file into the folder config\jest.
Adapt the babelTransform.js file to the current repository.
In the jest.config.js file, reference the transform object to the babelTransform.js file instead of the regularTransform.js file.
Run the command npm run test.

Now we can see that the test passes successfully!

Note
The above steps have been implemented in the unexpected-results-with-barrel-plugin repository.

Summary

While using barrel files can offer benefits for developer experience, it can also lead to performance issues and unexpected test results in Jest. To resolve them, use the babel-plugin-transform-barrels plugin, which transforms indirect imports (through barrel files) into direct imports.

This plugin effectively maintains developer experience with test performance and reliability.

I hope this article has provided you a deeper understanding of the issues with using barrel files in Jest and how the babel-plugin-transform-barrels can be a valuable tool in your testing toolkit.

Boost Your Webpage Load Performance with the new Webpack plugin

Fogel — Thu, 05 Oct 2023 13:50:28 +0000

Introduction

A website’s initial loading speed can significantly impact user experience and SEO. Slow loading times can bother many users.
To address this issue, I’ve developed a new Webpack plugin called html-webpack-preload-react-router. This plugin improves the initial loading speed of a website by reading the react router plain objects and then preloading only the essential async chunk files and performing data fetching. All of that occurs in parallel during the initial load.

Background

When using react router with code splitting (lazy loading) the process of loading a website is:

Downloading and executing the initial HTML file.
The HTML fetches and executes only the initial Javascripts and CSS chunks.
The react router code examines the current URL path and runs loader method if defined.
The react router code examines the current URL path and fetching and executing only the relevant chunk files based on element property.

Each step involves a network request and happens sequentially. It is a waste of time! In this article we show a solution that 2nd, 3rd and 4th steps will be parallelized network requests, which significantly reducing loading times and improving user experience.

A regular initial webpage loading example

Before I show the solution I want to show through a basic example the network waterwall of the traditional react webpage like we described in the Background section.

In this example, the Products component is code splitted through lazy loading.

products.route.js

//...
const Products = lazy(() =>
  import(/* webpackChunkName: 'Products' */ "./Products")
);
//...

So Let's see in DevTools the network waterwall when we navigate to https://regular-81820.web.app/products.

We see that there are 4 network requests in a row and this we want to parallelize as much as possible.

The solution

After I read the great article by Almog Gabay on Client-Side Rendering (CSR), particularly the Preloading Async pages section, I tought to myself why not using react router plain objects for another purposes like preloading with help from Webpack? The idea was to have a single array of plain objects serving multiple purposes - routing and preloading. After experimenting with various edge cases, I successfully created a stable Webpack plugin. This plugin generates an HTML file that handles preloading of async chunk files derived from React Router’s plain objects and also preloads data from the database (this feature is currently limited to GET requests).

A new webpack plugin - html-webpack-preload-react-router

The plugin html-webpack-preload-react-router is easy to install and setup. It gets as an argument the path for the entry route of the website.
In each object of react router plain objects we need to give the chunk name in a property called chunkName. The value needs to be the same value of the magic comment webpackChunkName of import().
In addition, because we make a fetching from database, we can preload also the data by configure the property data.
It will be easier to understand throughout an example.

A preloading initial webpage loading example

Let's use the same website example of A regular initial webpage loading example.
And do the following steps:

Install the plugin.

npm install --save-dev html-webpack-preload-react-router

Configure the webpack.config.js file:

webpack.config.js

   const HtmlWebpackPlugin = require("html-webpack-plugin");
+  const ReactRouterPreloadChunksPlugin = require("html-webpack-preload-react-router");
+  const entryRouteFilename = path.resolve(`./src/pages/entryRoute.route.js`);
   module.exports = {
      //...
      plugins: [
         new MiniCssExtractPlugin(),
         //...
+        new ReactRouterPreloadChunksPlugin({
+           entryRoute: entryRouteFilename,
+        }),
      ]
      //...
   };

Add chunkName property for each object in the routing of react router plain objects.

products.route.js

   export const productsRoutes = [
     {
       path: "",
+      chunkName: "Products",
       id: "products",
       loader: () => fetch("https://dummyjson.com/products").then((res) => res.json()),
       element: <Products />,
       children: [
         {
           path: ":productid",
+          chunkName: "Product",
           element: <Product />,
         },
       ],
     },
   ];

Add data property for each object in the routing of react router plain objects that fetch a data.

products.route.js

   export const productsRoutes = [
     {
       path: "",
       chunkName: "Products",
       id: "products",
       loader: () =>
         fetch("https://dummyjson.com/products").then((res) => res.json()),
       element: <Products />,
       children: [
         {
           path: ":productid",
           chunkName: "Product",
           element: <Product />,
         },
       ],
+      data: {
+        url: "https://dummyjson.com/products",
+        crossorigin: "anonymous",
+      },
     },
   ];

So let's see in DevTools the network waterwall when navigating to https://preloading-ea687.web.app/products:

Now we can see in the DevTools that there are 2 network group requests (instead 4 in a row), each group has network requests in parallel (first is products and second are main.9aa6dd.js, Products.023320.js and products in parallel). This is because the HTML is using preloading for async chunk files according to the URL path. It improves our website's performance!

Bonus - Navigation bar

After we saw that we can use react router plain objects for 2 purposes of routing and preloading, I found a third purpose of using - navigation bar.
In each object of the react router plain objects we need to give the link text in a property called linkText.

It will be easier to understand throughout an example.

A navigation bar example

Let's use the same website example of A preloading initial webpage loading example.
And do the following steps:

Change the react router plain objects entryRoute:

entryRoute.route.js

   export const entryRoute = [
     {
       path: "",
       element: <Layout />,
+      id: "links",
+      loader: () => entryRoute[0].children,
       //...
     },
   ];

Change the Layout component for reading link texts from the react router plain objects entryRoute:

Layout.js

   //...
   function Layout() {
+    let links = useRouteLoaderData("links");
     return (
       <nav>
         <ul>
-          <li>
-            <Link to="/">Home</Link>
-          </li>
-          <li>
-            <Link to="/about">About</Link>
-          </li>
-          <li>
-            <Link to="/products">Products</Link>
-          </li>
+          {links.map((link) => {
+            return (
+              <li>
+                <Link to={link.path?.replace("/*", "")}>{link.linkText}</Link>
+              </li>
+            );
+          })}
         </ul>
       </nav>
       //...
     );  
   }

Now we can see that the navigation bar works the same but use the data from react router plain objects. It is easier to maintain a single source of truth rather than 3 different sources.

Summary

In this article, we tried a new webpack plugin html-webpack-preload-react-router , which collaborates seamlessly with React Router’s plain objects. It generates a production html file that preloads async chunk files and fetched data based on the current URL path. It parallelizes network requests, which makes our webpage load faster! Additionally, React Router’s plain objects can be utilized for the navigation bar.

In short, now we can use the react router plain objects as a single source of truth for 3 purposes:

Routing.
Preloading async chunk files and fetched data from database (GET requests).
Navigation.

It makes our website's code easy to understand and maintained and improve the performance of initial loading webpages in our website.

I hope you enjoyed to read my article and hope you will try my new Webpack plugin html-webpack-preload-react-router.

Potential issues with barrel files in Webpack

Fogel — Tue, 18 Jul 2023 12:09:37 +0000

Introduction

Barrel files make the development more convenient, but how do they impact the bundle files generated by Webpack?

In this article, we will discuss the question above. I will demonstrate how to configure Webpack to work with barrel files and dynamic import and how it's recommended to create modules. As incorrect config of Webpack can lead to different issues, some of them being performance issues as a result of unused code and others being visual issues.

We will examine several solutions and go through a process together to find the optimal solution.

This article assumes familiarity with optimization configuration of Webpack. Therefore, If you're new to this topic, I recommend reading my previous article on Tree shaking in Webpack before continuing reading this article.

TL;DR

If you utilize barrel files with code splitting and employ regular CSS imports in your projects, I highly recommend using the babel-plugin-transform-barrels plugin instead of manually configuring sideEffects. This plugin will help prevent unexpected visual issues on your webpage and effectively reduce the size of your bundle files.

Furthermore, if code splitting is part of your development approach, I suggest creating modules with only one export each, whenever possible. This practice significantly decreases the size of your bundle files.

Additionally, for code splitting scenarios, I highly recommend leveraging the splitChunks configuration as explained in this article. This configuration allows for the elimination of duplicate code of common modules found in different chunks and will create a common chunk for common modules, resulting in optimized bundle files.

What are barrel files (index.js)?

Before we dive into the issues and because most of them were caused by barrel files, I want to explain what barrel files are and their appropriate use cases. I will focus on the advantages, but you can learn more about their advantages and disadvantages in the Additional Resources section below.

A barrel is a file that re-exports other modules' exports into a single file. In my opinion, it is better to use one level of barrel files in the folder structure. It's not recommended to create a barrel file for every folder.

Developers use barrel files (index.js) for the following development purposes:

It makes the code more readable by shortening import path and decreasing the number of lines of code.

Example

Without barrel files

import { Button } from './components/Button/Button'
import { Avatar } from './components/Avatar/Avatar'
import { List } from './components/List/List'

With barrel files

import { Button, Avatar, List } from './components'

When creating a third-party library and wanting to make specific functions public for consumers.

The following quote from yuchant on Github issue provides a good explanation:

Barrel files are effectively an API. A specific interface that distinguishes private vs public code.
Changes in the module's internal structure don't affect the library's consumers.

Additional Resources:

Are TypeScript Barrel Files an Anti-pattern?

Barrel files in Webpack

After we have seen the advantages of using barrel files and how they improve our developer experience, now we will see their usage and how they affect the bundle files.

As we have already learned in the previous article about Tree shaking in Webpack, when there is no use of optimization, every module and its dependencies that exist in the code will be included in bundle files. So when we import a barrel file module, all the re-exported modules included inside it will be included in the bundle files, even modules that are not in use. This will increase the size of the bundle files and consequently harm performance.

Optimization properties

Because barrel files can increase dramatically our bundle files size, we will use barrel files with usedExports and sideEffects optimization properties to eliminate unused code. Therefore in our example, modules in barrel files whose exports are not used will not be included in the final bundle files.

First, let's look at the main files of the example:

webpack.config.js

const MiniCssExtractPlugin = require("mini-css-extract-plugin");
//...
module.exports = {
  mode: "development",
  optimization: {
    usedExports: true,
    sideEffects: true,
  },
  module: {
    rules: [
      {
        test: /\.css$/,
        exclude: /node_modules/,
        use: [MiniCssExtractPlugin.loader, "css-loader"],
      },
      //...
    ]
  },
//...
}

App.js

import GreenSection from "./components/Sections/GreenSection/GreenSection";
import RedSection from "./components/Sections/RedSection/RedSection";
import { BlueStrong } from "./components/Strongs";

function App() {
  return (
    <>
      <BlueStrong>Blue strong component (Direct Import)</BlueStrong>
      <hr />
      <GreenSection />
      <hr />
      <RedSection />
    </>
  );
}

export default App;

GreenSection.js

import { GreenText } from "../../Texts";
import { GreenButton } from "../../Buttons/GreenButton/GreenButton";
import { getTenNumber } from "../../../tools/numberFunctions/numberFunctions";

function GreenSection() {
  const tenNum = getTenNumber();
  return (
    <>
      <GreenText>Green text component (Indirect import - Barrel)</GreenText>
      <GreenText>Green ten number: {tenNum}</GreenText>
      <GreenButton>Green button component (Direct import)</GreenButton>
    </>
  );
}

export default GreenSection;

RedSection.js

import { RedText } from "../../Texts";
import { RedButton } from "../../Buttons/RedButton/RedButton";
import { getThousandNumber } from "../../../tools/numberFunctions/numberFunctions";

function RedSection() {
  const thousandNum = getThousandNumber();
  return (
    <>
      <RedText>Red text component (Indirect import - Barrel)</RedText>
      <RedText>Red thousand number: {thousandNum}</RedText>
      <RedButton>Red button component (Direct import)</RedButton>
    </>
  );
}

export default RedSection;

Before we bundle our example, let's briefly review the code above and especially the imported modules.

Let's take a look at App.js, we can see that three components are in use: BlueStrong, GreenSection and RedSection.

GreenSection.js and RedSection.js modules are performing module imports according to the appropriate color from subdirectories of Buttons and Texts, as well as importing a module numberFunctions.js.

The only module that we will import indirectly from a barrel file will be from Texts. The remaining modules will be imported directly as we have always done.

Each appropriate module of color inside the subdirectories of Buttons, Strongs and Texts has imported also a CSS file for each.

After we did a short brief about how the code is implemented, we will describe in short what we expect to see in the rendered webpage. The first line should be in the blue color, 2-4 lines should be in green color and 5-7 lines should be in red color.

We can see in the webpack.config.js file, that there is a rule about CSS files that use the loader of mini-css-extract-plugin, so each time Webpack parse the CSS files it process the loader and will inject the content of the CSS files into chunk file. In our example it will be main.css.

During the bundling process, we expect that it will produce two files (JS and CSS files).

Now run npx webpack in the terminal window.

The build process created two files as expected: main.js and main.css.

Let's take a look at the browser and check the rendered page:

The page was rendered as expected.

Now let's analyze the bundle files.

It would be easier to understand if we organized all bundle files in a table according to the following columns:

Bundle file name.
List of modules that combined to the bundle file. It's after sideEffects optimization effect.
The included functions (Actual) inside the bundle file. It's after usedExports optimization effect.
The functions that the bundle file should include (Expected) for the most optimized desired bundle file.

Javascript bundle files

Bundle file	Bundled modules	Actual functions	Expected functions
main.js	App.js, Button.js, GreenButton.js, RedButton.js, GreenSection.js, RedSection.js, BlueStrong.js, Strong.js, Texts/index.js, GreenText.js, RedText.js, Text.js, numberFunctions.js	App, Button, GreenButton, RedButton, GreenSection, RedSection, BlueStrong, Strong, GreenText, RedText, Text, getTenNumber, getThousandNumber	App, Button, GreenButton, RedButton, GreenSection, RedSection, BlueStrong, Strong, GreenText, RedText, Text, getTenNumber, getThousandNumber

Let's take a look in the JS bundle file:

main.js

//...
/* unused harmony export getHundredNumber */
function getTenNumber() {
  return 10;
}
function getHundredNumber() {
  return 100;
}
function getThousandNumber() {
  return 1000;
}
//...

In the main.js file, we can see that Webpack bundled all the used functions, including the unused getHundredNumber function, which is marked as an unused harmony export by the usedExports property. Note that the RedText component is imported from "Texts/index.js", which is a barrel file, so all re-exported modules of the barrel file should be included, such as the BlueText module. But because we use the sideEffects property and the BlueText module is not used and doesn't have side effects, it is excluded from the bundled file.

Let's analyze the CSS bundle files:

CSS bundle files

Bundle file	Actual classes	Expected classes
main.css	Text, RedText, BlueText, GreenText, Button, GreenButton, RedButton, Strong, BlueStrong	Text, RedText, GreenText, Button, GreenButton, RedButton, Strong, BlueStrong

In the main.css file, we can see an unused class selector for .BlueText because we imported a barrel file module that includes the unused BlueText module. While the BlueText module was being evaluated, the BlueText.css file was extracted by the mini-css-extract-plugin plugin and added to the main.css file. Afterwards, BlueText was eliminated from main.js due to the sideEffects: true property. We will continue to monitor this unnecessary CSS selector. Note that unnecessary CSS selectors only come from unused modules that are re-exported in used barrel files. For example, there is no .BlueButton CSS selector because GreenButton and RedButton are directly imported rather than through a barrel file.

So we have an issue that we want to solve: we don't want the unnecessary .BlueText CSS selector and we want our JS and CSS to be as small as possible.

We have two ways to solve it:

Change the imports of the GreenText and RedText to be direct imports instead of indirect imports (index.js - barrel file), so this will prevent the BlueText module and its CSS file from being loaded. This is similar to why the .BlueButton CSS selector is not present in the CSS file because GreenButton and RedButton are directly imported.
Since the BlueText.js module has an unused export and our project only has side effects in CSS files, we can manually define which modules have side effects using the config option sideEffects: ["*.css"] and then the remaining modules with unused exports like BlueText.js will be flagged as having no side effects. This will prevent evaluation of the BlueText.js module and extraction of its CSS file content through the loader.

Dynamic import (Lazy loading in React)

After we saw that using barrel files can cause unused CSS files content to be included in CSS bundle file and we disscused the optional solutions, now I want to check the using barrel files inside a module that dynamically imported.

Dynamic import of a module is usually used when we want to load the module in specific conditions (inside if statement or event handler). If these conditions are not met, the code inside this module will not be evaluated, so we don't really need to download this module while the conditions are not met. So here Webpack comes to help. Webpack will create a bundle file for each module that is dynamically imported and for its dependencies and only download and evaluate this module when the conditions are met.

For example, in React there is a package named react-router-dom that allows render specific components for a specific URL path and render different components for a different URL path. In this case, it's recommended to use in lazy loading to make the components' modules downloaded from the server only when they are used. To make it happen, Webpack will create a new bundle file for each lazy loaded module with its dependencies.

As described in Webpack website:

Dynamically load modules. Calls to import() are treated as split points, meaning the requested module and its children are split out into a separate chunk.

Dynamic import in Webpack is important for improving performance of initial loading because it allows us to only download and evaluate what is needed on each webpage. This means we can include in the bundle file only the necessary modules for the initial loading and as a result make smaller bundle file that then make our webpage load faster.

For our example, and to keep it simple, we will change only the imports of RedSection.js and GreenSection.js to be dynamic imports without conditionally use them so both of them always will be downloaded in the initial loading of the webpage. We expect that Webpack will create three JS bundle files instead one.

As we remember, RedSection.js and GreenSection.js modules have two direct common modules: Texts/index.js and numberFunctions.js that uses different functions inside them. How webpack will handle it? Are the common modules will be included only in both bundle files? Or maybe only in the main bundle file? Or maybe a fourth bundle file will be created for common modules? The answer we will see after the bundling process of the example.

Let's create an example and see the files it produces.

Clone the previous 1-optimization-sideEffects example into a new 2-lazy-loading example and make the following changes to the App.js file:

App.js

- import GreenSection from "./components/Sections/GreenSection/GreenSection";
- import RedSection from "./components/Sections/RedSection/RedSection";
  import { BlueStrong } from "./components/Strongs/BlueStrong/BlueStrong";
+ import { lazy, Suspense } from "react";

+ const GreenSection = lazy(() => import(/* webpackChunkName: 'GreenSection' */ "./components/Sections/GreenSection/GreenSection"));
+ const RedSection = lazy(() => import(/* webpackChunkName: 'RedSection' */ "./components/Sections/RedSection/RedSection"));

  function App() {
    return (
      <>
+       <Suspense fallback={<></>}>
            <BlueStrong>Blue strong component (Direct Import)</BlueStrong>
            <hr />
            <GreenSection />
            <hr />
            <RedSection />
+       </Suspense>
      </>
    );
  }

  export default App;

Now run npx webpack in the terminal window.

This produces the following files:

main.js and main.css.
GreenSection.js and GreenSection.css - New files.
RedSection.js and RedSection.css - New files.

Let's take a look at the rendered page in the browser:

We see that the Green button component (direct import), which is part of the GreenSection, has turned black instead of being green. Why did this happen?

First, let's take a look at the DevTools:

We can see that the .Button CSS selector appears twice. The GreenSection.css file loads both .Button and .GreenButton, but then .Button is loaded again but from the RedSection.css file. Loading the .Button CSS selector only once from GreenSection.css file will solve this problem. This happens because the Button.js module loaded twice instead of once, causing it to override the green color with black. The order in which CSS properties (in our case color) are applied is determined by their order of loading, where properties from class selectors loaded later will override those from earlier class selectors.

Now let's analyze our bundle files.

It would be easier to understand if we organized all bundle files in a table according to the following columns:

Bundle file name.
List of modules that combined to the bundle file. It's after sideEffects optimization effect.
The included functions (Actual) inside the bundle file. It's after usedExports optimization effect.
The functions that the bundle file should include (Expected) for the most optimized desired bundle file.

Javascript bundle files

Bundle file	Bundled modules	Actual functions	Expected functions
main.js	App.js, BlueStrong.js, Strong.js	BlueStrong, Strong	BlueStrong, Strong
GreenSection.js	Button.js, GreenButton.js, GreenSection.js, GreenText.js, RedText.js, Text.js, Texts/index.js, numberFunctions.js	Button, GreenButton, GreenSection, GreenText, RedText, Text, getTenNumber, getThousandNumber	GreenText, GreenButton, GreenSection, getTenNumber
RedSection.js	Button.js, RedButton.js, RedSection.js, GreenText.js, RedText.js, Text.js, Texts/index.js, numberFunctions.js	Button, RedButton, RedSection, GreenText, RedText, Text, getTenNumber, getThousandNumber	RedText, RedButton, RedSection, getThousandNumber
*common.js			Text, Button

Note: The common.js is not produced by the build process. It's my suggestion for a bundle file for functions that are used by more than one JS bundle file.

Explanation of JS bundle files

First, we will check in what bundle files the common modules Texts/index.js and numberFunctions.js of GreenSection.js and RedSection.js source files are included. It can be seen in the table above that they are included inside RedSection.js and GreenSection.js bundle files. We expected that the usedExports and sideEffects optimization properties would eliminate the unused code separately in each RedSection.js and GreenSection.js bundle files. Unfortunately Webpack doesn't do that. We can see in both bundle files that the content of the imported modules are the same to the first example where only BlueText.js module and getHundredNumber function are eliminated. Unfortunately, the usedExports and sideEffects optimizations performed on the entire code are the same as in the first example without dynamic imports. Therefore, the RedSection.js bundle file will include also the unused GreenText.js module and getTenNumber function and the GreenSection.js bundle file will include also the unused RedText.js module and getThousandNumber function. The Texts/index.js and numberFunctions.js modules have different solutions. For Texts/index.js, we can use the same solution I suggested in the first example. For numberFunctions.js, we can use the solution of separating the module to 3 different modules that each one will have one function and then import the function from his specific module.
In addition, Text.js and Button.js are indirectly common modules imported from Texts/index.js, GreenButton.js and RedButton.js modules. Therefore, Text.js and Button.js modules content appear in both GreenSection.js and RedSection.js bundle files that uses the same functions (Text and Button functions). This results a duplicate code, and our goal is to reduce their size. To solve this issue, we should try creating a separate bundle file for common modules which have the same used functions of both sections. Since Text.js and Button.js are modules with one function each, we can conclude that both sections are using the same functions from these modules.

Let's analyze the CSS bundle files.

CSS bundle files

Bundle file	Actual classes	Expected classes
main.css	BlueStrong, Strong	BlueStrong, Strong
GreenSection.css	Text, RedText, BlueText, GreenText, Button, GreenButton	GreenText, GreenButton
RedSection.css	Text, RedText, BlueText, GreenText, Button, RedButton	RedText, RedButton
common.css		Text, Button

Explanation of CSS bundle files:

The main.css file has class selectors for .Strong and .BlueStrong because we use the BlueStrong component in the App.js file and it works as expected.
In the CSS bundle files of GreenSection.css and RedSection.css modules, we can see that the .BlueText CSS class selector appears even when the BlueText component isn't used. We already talked about the reason why it happened in the first example and that there are two ways to solve it and we will try these options later.
The .GreenText appears in RedSection.css and .RedText appears in GreenSection.css, even though both of them aren't useful and need to be eliminated. It happened because their modules (GreenText.js and RedText.js) are imported from the barrel file of Texts/index.js. Later we will see if the solution for .BlueText will help us solve this issue as well.

Let's summarize the issues for the example of lazy loading:

Green button component (direct import) button has a black color instead green.
getTenNumber and getThousandNumber functions exist in both GreenSection.js and RedSection.js bundle files instead, getTenNumber should only be included in GreenSection.js and getThousandNumber should only be included in RedSection.js. The same applies to the unused RedText in the GreenSection.js bundle file and the unused GreenText in the RedSection.js bundle file. Why did this happen? Because the optimizations of usedExports and sideEffects occurred to the entire code and not separately to each bundle file.
Text.js and Button.js modules appear in two bundle files of GreenSection.js and RedSection.js instead of in one common bundle file for both sections.
.BlueText exists in both bundle CSS files even though it is unused. .RedText should be eliminated from GreenSection.css bundle file and .GreenText should be eliminated from RedSection.css bundle file.

Splitting bundle files can cause new issues. Some of these issues can affect performance, while others can cause unexpected visual issues that are more critical because they affect the user experience. So first, let's try to fix style issues and unnecessary duplicate code by using the optimization configuration of the splitChunks property. After that, we will address unused functions and CSS selectors to decrease the size of bundle files.

Create a separate bundle file for common modules

In the previous chapter on dynamic import, we saw that each dynamic import in Webpack produces JS and CSS bundle files. In addition, commonly used modules exist in all bundle files that use these modules. As a result, there are CSS classes that are loaded twice and also duplicate Javascript code. This behavior causes four issues, one of which is an unexpected visual issue.

To address this, we can use the splitChunks property to create a bundle file of common modules.

Let's clone the previous example 2-lazy-loading to 3-splitChunks and change the Webpack config file as follows:

webpack.config.js

//...
module.exports = {
  mode: "development",
  optimization: {
    usedExports: true,
    sideEffects: true,
+   splitChunks: {
+     cacheGroups: {
+       default: false,
+       defaultVendors: false,
+       src: {
+     test: /[\\/]src[\\/]/,
+     minSize: 0,
+     priority: 100,
+     name: (module, chunks) => {
+       const allChunksNames = chunks.map(({ name }) => name).join(".");
+       return `${allChunksNames}`;
+     },
+     chunks: "all",
+   },
+     },
+   },
  },
//...
}

Let's briefly explain what splitChunks is doing with the configuration above. It traverses each module that includes the src directory in its path and assigns a bundle file name to each traversed module through the name property. The bundle file name of the traversed module will be the name of the chunk names (webpackChunkName magic comment inside import() statement) of dynamically imported modules that include this traversed module. For example the module numberFunctions.js is included in GreenSection.js and RedSection.js source files that are dynamically imported, so the bundle file name that the module numberFunctions.js should be inside is GreenSection.RedSection.js.

I think my configuration above is better than the configuration described in the article webpack 4: Code Splitting, chunk graph and the splitChunks optimization because I control the name of the bundle files to be the name of the dynamically imported modules.

Now run npx webpack in the terminal window.

It produces the following files:

main.js and main.css.
GreenSection.js and GreenSection.css.
RedSection.js and RedSection.css.
GreenSection.RedSection.js and GreenSection.RedSection.css - New files.

In comparison to the previous example 2-lazy-loading, it generated GreenSection.RedSection.js and GreenSection.RedSection.css bundle files in addition.

Now let's take a look in the browser and check the rendered page:

We see that the Green button component (direct import) is rendered with the green color as expected.

Let's inspect the button element:

We can see that the .Button CSS selector now appears only once in the common bundle file GreenSection.RedSection.css, so with the splitChunks property, we have finally solved this visual issue.

Let's analyze the bundle files:

Javascript bundle files

Bundle file	Bundled modules	Actual functions	Expected functions
main.js	App.js, BlueStrong.js, Strong.js	BlueStrong, Strong	BlueStrong, Strong
GreenSection.js	GreenButton.js, GreenSection.js	GreenButton, GreenSection	GreenText, GreenButton, GreenSection, getTenNumber
RedSection.js	RedButton.js, RedSection.js	RedButton, RedSection	RedText, RedButton, RedSection, getThousandNumber
GreenSection.RedSection.js	Button.js, GreenText.js, RedText.js, Text.js, Texts/index.js, numberFuntions.js	Button, GreenText, RedText, Text, getTenNumber, getThousandNumber	Text, Button

Explanation of JS bundle files

If we take a look at the file GreenSection.RedSection.js, we can see that commonly used modules of the GreenSection.js and RedSection.js modules are included, such as the Button.js and Text.js modules, as expected. So we have solved this issue. Note: The Button.js and Text.js modules are indirectly imported modules through RedText.js, GreenText.js, GreenButton.js and RedButton.js modules.
The bundle file GreenSection.RedSection.js also includes the GreenText, RedText, getTenNumber, and getThousandNumber functions. These functions should not be in this common bundle file and they are part of the common bundle file because Webpack splits bundle files according to their used common module and not used common function. According to our case, the GreenSection.js and RedSection.js modules import the same modules Texts/index.js and numberFunctions.js, so these modules and their dependencies are included in the common bundle module GreenSection.RedSection.js. The desired result we wantis that GreenText and getTenNumber should be in the GreenSection.js bundle file and RedText and getThousandNumber should be in the RedSection.js bundle file.

Let's analyze the CSS bundle files.

CSS bundle files

Bundle file	Actual classes	Expected classes
main.css	BlueStrong, Strong	BlueStrong, Strong
GreenSection.css	GreenButton	GreenText, GreenButton
RedSection.css	RedButton	RedText, RedButton
GreenSection.RedSection.css	Text, RedText, BlueText, GreenText, Button	Text, Button

Explanation of CSS bundle files:

.BlueText is included in GreenSection.RedSection.css even though it is unused. This happened because we import a barrel file of Texts/index.js that first loads the re-exported modules and while evaluating these modules it extracted CSS contents by the CSS loader and then eliminates unused code. It happened for the same reason as in the first example.
.RedText and .GreenText are included in GreenSection.RedSection.css, when they should included in RedSection.css and GreenSection.css, respectively. This happened for the same reason as we mentioned about their JS files, that they are indirectly imported through a barrel file. Webpack creates a common bundle file because the common module of Text/index.js is imported in both GreenSection.js and in RedSection.js.

Let's summarize the current opened issues:

Summary of Javascript issues:

GreenText and RedText modules are included in the common bundle file GreenSection.RedSection.js instead in their specific bundle files GreenSection.js and RedSection.js, respectively. Because they are imported indirectly through a barrel file Texts/index.js that it is the common module. If we will want to render one section file instead of the two sections, then we will download unused code. For example, if we load a page that renders only GreenSection component but conditionally renders RedSection component, then the downloaded bundle will include RedText.js even though we don't need it now.
GreenSection.RedSection.js bundle file include getTenNumber and getThousandNumber functions instead GreenSection.js bundle file include only getTenNumber and RedSection.js bundle file include only getThousandNumber.

Summary of CSS issues:

.BlueText exist in common bundle CSS GreenSection.RedSection.css even it is unused.
.RedText and .GreenText shouldn't be in GreenSection.RedSection.css bundle file. They should be in RedSection.css and GreenSection.css, respectively. The behavior of .RedText and .GreenText happened because the using of barrel file.

Our conclusions for now:

Using direct import instead of indirect import (barrel files) solves most of the issues.
Using one function per module instead of multiple functions per module solves the issues of the numberFunctions module.

Manual configuration of `sideEffects` solution

One of our conclusions in the previous example was that the use of barrel files can cause issues when dynamic import is used. It seems that usedExports marks unused exports for the whole code as a one bundle file only and not for each separate bundle file. When we made direct imports with the GreenButton and RedButton components, it worked properly.

In my Tree shaking in Webpack article, we learned that we can manually configure which modules in our project have side effects and which don't.

Also from that article, we know for sure that CSS files are considered to have side effects, so we need to flag them with side effects. Barrel files in our case only have re-exported functions, so we can say that we don't use direct imports from barrel files and they also don't have side effects, so we can flag barrel files without side effects.

Webpack's team talked about the purpose of the manual sideEffects property in their conference and explained that it comes to solve the issue of big bundle files when using of barrel files.

So let's try to solve our issues from the previous example with a manual configuration of sideEffects in package.json.

Let's clone the previous example 3-splitChunks to 4-package-sideEffects and change the package config file as follows:

package.json

{
  "name": "example-module",
+ "sideEffects": ["*.css"],
}

Now run npx webpack in the terminal window.

Let's take a look in the browser and check the rendered page:

We see that the Blue strong component (Direct Import) text is black when it should be blue. This is a visual issue. Why did this strange behavior occur?

First, let's look at the dev tools:

We can see that .Strong overrides .BlueStrong because .Strong is in a higher position. Why did this change? In the previous examples, .BlueStrong overrode .Strong. This happened because of the sideEffects property.

So I started to research this issue.

I found an issue where Hypnosphi complained that there were differences between development and production when he configured sideEffects: false, so he noticed that the order of CSS was not the order of the imports but the usage order. In another issue, there is an answer from sokra (a Webpack team member) who wrote:

Technically using sideEffects you say order doesn't matter

Another answer from sokra:

If the order of some modules matter they are not side-effect-free.

So let's go back to our case.

We evaluate the BlueStrong.js module that first imports the Strong component and then BlueStrong.css. But because we flagged modules with sideEffects manually, Webpack will first evaluate import module statements flagged with side effects and then evaluate used modules flagged without side effects in the order of their use. So the import of BlueStrong.css will be evaluated first and then we use the Strong.js that will be evaluated with Strong.css inside of it.

Let's analyze bundle files:

Javascript bundle files

Bundle file	Bundled modules	Actual functions	Expected functions
main.js	App.js, BlueStrong.js, Strong.js	BlueStrong, Strong	BlueStrong, Strong
GreenSection.js	GreenButton.js, GreenSection.js, GreenText.js	GreenButton, GreenSection, GreenText	GreenText, GreenButton, GreenSection, getTenNumber
RedSection.js	RedButton.js, RedSection.js, RedText.js	RedButton, RedSection, RedText	RedText, RedButton, RedSection, getThousandNumber
GreenSection.RedSection.js	Button.js, Text.js, numberFunctions.js	Button, Text, getTenNumber, getThousandNumber	Text, Button

CSS bundle files

Bundle file	Actual classes	Expected classes
main.css	BlueStrong, Strong	BlueStrong, Strong
GreenSection.css	GreenText, GreenButton	GreenText, GreenButton
RedSection.css	RedText, RedButton	RedText, RedButton
GreenSection.RedSection.css	Text, Button	Text, Button

In the CSS table above, we can see for the first time that CSS files have the expected class selectors. So for now, we know for sure that the size of the CSS files is as small as possible.

Let's check if our previous example issues are solved:

GreenText and RedText are in their correct bundle files GreenSection.js and RedSection.js, respectively. sideEffects solved the issue of imported modules from barrel files.
.BlueText, which previously existed in the common bundle CSS file GreenSection.RedSection.css even though it was unused, is now eliminated. .RedText and .GreenText are in RedSection.css and GreenSection.css, respectively. sideEffects solved the issue caused by the barrel file.
getTenNumber and getThousandNumber still exist in the GreenSection.RedSection.js bundle file instead of getTenNumber being only inside GreenSection.js and getThousandNumber being only inside RedSection.js.

Let's summarize the current open issues:

getTenNumber and getThousandNumber still exist in the GreenSection.RedSection.js bundle file, instead of having only getTenNumber in GreenSection.js and only getThousandNumber in RedSection.js.
.Strong overrides .BlueStrong when it should be the opposite. This is a result of the sideEffects: ["*.css"] configuration that changing the order of imports based on usage of a module rather than by the order of import statements (except for CSS imports). This causes a visual issue.

I have considered several solutions for the second issue:

Convert CSS files to CSS Modules and change the sideEffects: ["*.css"] configuration to sideEffects: false.
Create a plugin that moves all CSS import statements to the end of the module if sideEffects: ["*.css"] is defined in package.json.
Change import statements from indirect imports through a barrel file to direct imports.

All of these solutions should work, but the first two solutions with configuration of sideEffects in package.json will change the import order to be determined by usage. The third solution, on the other hand, follows the order of import statements as ES Modules behavior. Since I want to follow my principle of having the bundle file resemble ES Modules behavior, the third solution is the better choice.

We still want to use barrel files because they make our code more readable and improve our developer experience. In the next chapter, we will try to develop an automatic transformation for our code that changes indirect imports through a barrel file to direct imports.

babel-plugin-transform-barrels

I know that Babel can transform code during the build process of Webpack. So I found some plugins (#1, #2, #3) that will transform the import statements from indirect import (through barrel file) to direct import, but all of them require specific configuration for each package. So I decided to develop a Babel plugin that will transform code with imports from barrel files into code with direct imports without needing configuration.

Kent C. Dodds talked about the problem of unnecessary CSS class selectors in this video and about his solution. It is based on a plugin that requires specific configuration, something that I don't want.

During the bundling process, my babel plugin transforms the line of code as follows:

From an indirect import (barrel file):

import { RedText } from "../../Texts";

To a direct import:

import { RedText } from '../../Texts/RedText/RedText';

My babel plugin prevents the inclusion of unused reexported modules from barrel files in the bundle file. This leads to a reduction in bundle size, thereby improving overall performance.

Now, let's install the plugin:

npm install --save-dev babel-plugin-transform-barrels

Now we need to add the plugin to the webpack config file which has a rule with a loader of babel-loader:

webpack.config.js

      {
        test: /\.(js|mjs|jsx|ts|tsx)$/,
        exclude: /node_modules/,
        loader: require.resolve("babel-loader"),
        options: {
          presets: [["@babel/preset-react"]],
+         plugins: [["transform-barrels", { webpackConfigFilename: __filename, ...(typeof module.exports === "function" && { args: arguments })}]],
        },
      },

Now run npx webpack in the terminal window.

Let's take a look in the browser and check the rendered page:

We see that the "Blue strong component (Direct Import)" has the blue color as expected.

Let's look at the dev tools:

So even though the CSS table in this example is the same as in the previous example, the rendered page is different because now class selectors are loaded in the order of their import statements, as expected, rather than in the order of their usage.

We can see that .BlueStrong overrides .Strong, so this issue is solved.

Let's analyze bundle files:

Javascript bundle files

Bundle file	Bundled modules	Actual functions	Expected functions
main.js	App.js, BlueStrong.js, Strong.js	BlueStrong, Strong	BlueStrong, Strong
GreenSection.js	GreenButton.js, GreenSection.js, GreenText.js	GreenButton, GreenSection, GreenText	GreenText, GreenButton, GreenSection, getTenNumber
RedSection.js	RedButton.js, RedSection.js, RedText.js	RedButton, RedSection, RedText	RedText, RedButton, RedSection, getThousandNumber
GreenSection.RedSection.js	Button.js, Text.js, numberFunctions.js	Button, Text, getTenNumber, getThousandNumber	Text, Button

CSS bundle files

Bundle file	Actual classes	Expected classes
main.css	BlueStrong, Strong	BlueStrong, Strong
GreenSection.css	GreenText, GreenButton	GreenText, GreenButton
RedSection.css	RedText, RedButton	RedText, RedButton
GreenSection.RedSection.css	Text, Button	Text, Button

As we can see in the Javascript and CSS tables above, there is no difference compared to the previous example 4-package-sideEffects.

Let's summarize the current open issues:

getTenNumber and getThousandNumber still exist in the GreenSection.RedSection.js bundle file instead of getTenNumber being only included in GreenSection.js and getThousandNumber being only included in RedSection.js.

The numberFunctions.js module has 3 function exports. If we split the module into 3 separate modules, each with one function export, it should resolve the issue.

Function per module

Before I try my optional solution, I searched for open issues on Webpack's Github repository and found the same issue we faced, but there is no solution provided by the Webpack team.

I checked a popular package with tree shaking support called Lodash. Lodash has a separate module per function. This allows the package to fully support tree shaking.

We will try this approach and see if it resolves our issue from the previous example.

Let's clone the previous example 5-babel-plugin to 6-function-per-module.

Now let's split the exports getTenNumber, getHundredNumber, and getThousandNumber from src\tools\numberFunctions\numberFunctions.js into 3 modules: getTenNumber.js, getHundredNumber.js, and getThousandNumber.js, respectively. And create a barrel file for the src\tools\numberFunctions directory. Now change the import statements of these functions in the GreenSection.js and RedSection.js modules.

Now run npx webpack in the terminal window.

Let's take a look in the browser and check the rendered page:

Everything looks great in our rendered page.

Let's analyze bundle files:

Javascript bundle files

Bundle file	Bundled modules	Actual functions	Expected functions
main.js	App.js, BlueStrong.js, Strong.js	BlueStrong, Strong	BlueStrong, Strong
GreenSection.js	GreenButton.js, GreenSection.js, GreenText.js, getTenNumber.js	GreenText, GreenButton, GreenSection, getTenNumber	GreenText, GreenButton, GreenSection, getTenNumber
RedSection.js	RedButton.js, RedSection.js, RedText.js, getThousandNumber.js	RedText, RedButton, RedSection, getThousandNumber	RedText, RedButton, RedSection, getThousandNumber
GreenSection.RedSection.js	Button.js, Text.js	Text, Button	Text, Button

CSS bundle files

Bundle file	Actual classes	Expected classes
main.css	BlueStrong, Strong	BlueStrong, Strong
GreenSection.css	GreenText, GreenButton	GreenText, GreenButton
RedSection.css	RedText, RedButton	RedText, RedButton
GreenSection.RedSection.css	Text, Button	Text, Button

Now getTenNumber and getThousandNumber no longer included in the GreenSection.RedSection.js bundle file. Instead, getTenNumber is included only in GreenSection.js and getThousandNumber is included only in RedSection.js.

We have successfully overcome all of our performance and visual issues. Now our project is optimized. We managed to minimize the size of the project by reducing the amount of CSS and Javascript code. The project only loads what it needs.

Summary

In this article, we encountered inefficient bundle files and visual issues in the browser when using barrel files with dynamic import that caused our bundle files to split into different chunks with unused Javascript code. We conducted a step-by-step examination to determine the best way to solve these issues.

We found 2 particular reasons for the issues:

Using barrel files in our code.
Using a module with more than one export.

The issues occurred because usedExports and sideEffects optimizations performed at the entirely code. So for example, in the numberFunctions.js module, usedExports first checks if its exports are used and sees that the getTenNumber function export is used by GreenSection and the getThousandNumber function export is used by RedSection and the getHundredNumber function is not used anywhere so it marks only getHundredNumber as an unused harmony export. Only after this evaluation of code, Webpack inject the code of numberFunctions.js module with the optimizations that were made into GreenSection.js and RedSection.js bundle files as we saw in the 2-lazy-loading example.

The way we solved each issue:

Using a Babel plugin babel-plugin-transform-barrels that transforms indirect imports (barrel files) into direct imports during the bundle process.
Splitting modules with more than one function into several modules with one function each.

I hope that in the future, the Webpack team will address and resolve the issues I have demonstrated in this article without any special plugin or configuration.

Additional Resources:

Your Next.js Bundle Will Thank You - It's about barrel files and sideEffects solution.
Do a barrel export - A brief overview of tools for barrel files.

Tree shaking in Webpack

Fogel — Mon, 17 Jul 2023 13:15:13 +0000

Introduction

Javascript file size can have a significant impact on browser performance. Unused code increases the size of our bundle file and as a result causes performance issues.

Delivering less JavaScript can mean less time in network transmission, less spent decompressing code and less time parsing and compiling this JavaScript - Addy Osmani

One effective way to reduce Javascript file size is through tree shaking.

Tree shaking is a term commonly used in the context of Javascript module bundlers. It refers to the process of removing unused code from the final bundle.

It is a powerful feature that can help you optimize the size of your Javascript bundle files. Despite its usefulness, many developers are still unfamiliar with how it works and how to use it effectively. After researching the topic and encountering some common issues, I decided to write a comprehensive guide to tree shaking in Webpack.

In this article, we'll explore how tree shaking works in Webpack and how you can use it to optimize your code. Through examples and visualizations, we'll explain the process of tree shaking step by step and help you optimize your code for better performance.

TL;DR

When building a production bundle in Webpack, the tree shaking process occurs automatically. The optimization properties of usedExports and sideEffects are enabled by default, leading to automatic optimization of the bundle files.

The main purpose of manually configuring sideEffects is to eliminate unused reexported modules within barrel files, resulting in a significant reduction in bundle size, improving performance and loading times.

Webpack

Webpack's main role is to bundle all module files into one or several files and minimize their size to save time and reduce server requests. Typically, we provide one entry point (the main Javascript file) to the Webpack config and then bundle files are created.

When executing regular Javascript (non-bundled), ES Modules evaluate every imported module file even if the imported specifier of the module is not used because the module can have side effects.

According to ECMA spec:

Do nothing if this module has already been evaluated. Otherwise, transitively evaluate all module dependences of this module and then evaluate this module

To resemble the behavior of ES Modules, Webpack includes every imported module's code (a dependency) in the bundle file without any elimination of code (except for optimization features).

Bundle Javascript project (development mode)

Let's create an example of regular Webpack bundle files without optimization.

In this example, we'll demonstrate how webpack bundles different files types (JS/CSS) into one file type main.js and main.css.

We'll use development mode because it does not have any optimizations configured by default.

To see the differences between different mode configurations (production/development/other) you can refer to the defaults.js file.

Let's take a look at the Webpack configuration:

webpack.config.js

//...
module.exports = {
  mode: "development",
//...

}

Before we run the webpack command, let's take a look at our code:

App.js

import { GreenText } from "./components/Texts/GreenText/GreenText";
import { RedText } from "./components/Texts/RedText/RedText";
import { getHundredNumber } from "./tools/numberFunctions/numberFunctions";
import { getUnusedModuleText } from "./tools/unusedModule/unusedModule";
import "./tools/sideEffectsModule/sideEffectsModule";

function App() {
  const hundredNumber = getHundredNumber();
  return (
    <>
      <GreenText>Number in green: {hundredNumber}</GreenText>
      <RedText>Text in red</RedText>
    </>
  );
}

export default App;

From the code above, we can see that we have GreenText and RedText components, the getHundredNumber function and the sideEffectsModule module in App.js. We also import an unused function getUnusedModuleText. These components, functions and module use different modules through direct import:

The component GreenText is from the module "./components/Texts/GreenText/GreenText.
The component RedText is from the module "./components/Texts/RedText/RedText".
The function getHundredNumber is from the module "./tools/numberFunctions/numberFunctions", which contains another two functions (getTenNumber, getThousandNumber).
the unused function getUnusedModuleText is from the module "./tools/unusedModule/unusedModule", which contains another function (getUnusedModuleButton).
A side effect import module that is imported from "./tools/sideEffectsModule/sideEffectsModule", which contains global code with side effects.

In the bundle process we expect that it will produce two files (JS and CSS files).

Let's run npx webpack in the terminal window.

The build process created two files as expected: main.js and main.css.

Let's demonstrate it in a dependency tree:

In the main.js file, we can see that all functions and global code from all imported modules are included in the file. Even functions that weren't imported as a specifier in the import statement are included in the bundle file. As we mentioned earlier, Webpack resembles the behavior of ES Modules by importing the entire code of modules including unused code (dead code).

Even the following unused functions are included:

The unused function getUnusedModuleButton from the unused module ./tools/unusedModule/unusedModule.
The unused functions getTenNumber and getThousandNumber from the used module ./tools/numberFunctions/numberFunctions.

Note: The BlueText and BlackText are not included because they haven't been imported anywhere.

When importing from a re-exported module, for example, a barrel file, Webpack will evaluate all re-exported modules as having side effects even if some of the re-exported modules aren't imported or used. The reason for this is written in the official Webpack example of side effects:

According to the EcmaScript spec, all child modules must be evaluated because they could contain side effects.

Sean from the Webpack team also explained this on Stack Overflow:

According to the ECMA Module Spec, whenever a module re-exports all exports, (regardless if used or unused) they need to be evaluated and executed in case one of those exports created a side-effect with another.

The used and unused functions are marked in the main.js bundle file by the comment "harmony export".

These unused functions (also known as dead code) increase the size of our bundle file and cause performance issues.

To improve performance, we prefer to carefully delete unused code and make our bundle file as small as possible.

In the main.css file, we can see both class selectors of .GreenText and .RedText.

The term for dead code elimination is called Tree shaking and we will discuss it in the next chapter.

Tree Shaking

During the build process, Webpack creates a dependency tree structure. In the tree, each dependency (module) is represented by a branch and each function is represented by a leaf. There are green branches (which represent modules with used functions or with side effects), light green leaves (which represent imported used functions), brown leaves (which represent unused functions from imported module, also known as "dead code") and dark brown branches (which represent imported unused modules with no side effects). When we shake the tree, the brown leaves should fall off while the green leaves remain. In our case, this means that after tree shaking only imported used functions or modules with used functions or side effects should remain.

As we saw in the last example, used and unused functions were marked the same with the comment "harmony export" that specifies the green leaves.

How can it be that unused functions were marked as green leaves? Because we were in development mode, which has no optimization enabled.

So how can we mark the unused functions as brown leaves and unused modules without side effects as dark brown branches? For this, we should use the optimization configuration.

Optimization

usedExports

The usedExports property is responsible for marking the unused functions with brown leaves.

Let's clone the previous example 1-without-optimization to 2-optimization-usedExports and change the Webpack config file as follows:

webpack.config.js

//...
module.exports = {
  mode: "development",
+ optimization: {
+   usedExports: true,
+ },
//...
}

Now run npx webpack in the terminal window.

Let's demonstrate it in a dependency tree:

Take a look at the bundle file:

main.js

//...
/* unused harmony exports getTenNumber, getThousandNumber */
function getTenNumber() {
  return 10;
}
function getHundredNumber() {
  return 100;
}
function getThousandNumber() {
  return 1000;
}
//...
/* unused harmony exports getUnusedModuleText, getUnusedModuleButton */
function getUnusedModuleText() {
  return "imported but unused module";
}
function getUnusedModuleButton() {
  return "imported but unused module";
}

In the main.js file we can see that Webpack with the usedExports: true property marked the unused functions (dead code) with the comment /* unused harmony export functionName */. This comment points to the unused function as a brown leaf in the tree.

But the entire unused function declarations are still in the file. How can we get rid of it? How can we shake the tree and cause brown leaves to fall down (eliminate dead code) to the ground? We will shake the tree later using either the configuration of minimize: true or mode: production .

In the main.css file, we can see that it's the same as in the first example 1-without-optimization.

sideEffects

First, let's explain what side effects are.

There are two types of code: pure code and code with side effects:

Pure code: It uses only variables from its scope and doesn't use global variables like the window object or data that comes from the outside sources such as HTTP requests, file system, DOM, etc. For example, a pure function always returns the same output for the same input and doesn't use global variables. In short, pure code is a code without side effects.
Code with side effects: It uses global variables or data from outside its scope. For example, a function that can return different output for the same input or a function that changes global variables like the window object or uses data from HTTP calls, file system, DOM, etc. In short, It is the opposite of pure code.

In Webpack, sideEffects configuration enables us to exclude entire module (and his dependencies) whose direct exports are not used and doesn't have side effects from the bundle file.

Point to remember to this section: In Webpack, the sideEffects configuration only affects imported modules whose direct exports are not used. Modules with used exports will always be included. An example of imported modules whose direct exports are not used are barrel files that re-export functions.

There are two configurations for sideEffects that are designed to work together if they configured:

The sideEffects property in the optimization object in webpack.config.js - Enable the use for manual configuration of modules with or without side effects and/or automatic analysis of modules for side effects.
The manual sideEffects property inside either package.json file or the module.rules array in the webpack.config.js file - Manually configure the list of modules that have or don't have side effects. In this case modules whose direct exports are not used flagged manually as having no side effects, then these modules and their dependencies will be safely excluded from the bundle file without even being evaluated.

sideEffects optimization

According to WebpackOptions.json, the optimization sideEffects property can have the following values:

true - Include or exclude modules depending on their manual configuration in the package.json or webpack.config.js file. Modules that haven't been flagged with or without side effects in the webpack.config.js file and whose exports are not used will be analyzed, if there are no side effects, they will be excluded.
"flag" - Only include or exclude modules depending on their manual configuration in the package.json or webpack.config.js file. Modules that haven't been flagged with or without side effects in the webpack.config.js file will be included as usual, just like we learned about ES modules.
false - It will not evaluate modules for side effects even if set in the package.json or webpack.config.js file. All imported modules will be included as we learned about ES modules.

Note

If the modules with side effects are flagged in the package.json file, the remaining files will be flagged as having no side effects. So if modules are configured through the package.json file, there will be no difference between the values true and "flag". The result of them will be the same because all modules are flagged with or without side effects and there is no module that isn't flagged. Then the true value will not have modules to analyze because all modules have been flagged with or without side effects, so true and "flag" will have the same behavior.
Production mode uses the optimization sideEffects value of true.

Before we dive into the manual way of configuring sideEffects, let's make an example about the optimization sideEffects property without manually defining which modules have or don't have side effects:

Clone the previous example 2-optimization-usedExports to 3-optimization-sideEffects and change the webpack config file as follows:

webpack.config.js

//...
module.exports = {
  mode: "development",
 optimization: {
   usedExports: true,
+  sideEffects: true,
 },
//...
}

Now run npx webpack in the terminal window.

Let's demonstrate it in a dependency tree:

Take a look at the bundle file:

main.js

//...
/* unused harmony exports getTenNumber, getThousandNumber */
function getTenNumber() {
  return 10;
}
function getHundredNumber() {
  return 100;
}
function getThousandNumber() {
  return 1000;
}
//...

In the main.js file, we can see that Webpack with the sideEffects: true property eliminates the unused module of unusedModule (dead code) compared to the previous example 2-optimization-usedExports which just marked unusedModule with /* unused harmony export getUnusedModuleText, getUnusedModuleButton */. When we use in mode: production, which under the hood uses minimize: true, for both the second and third examples, both bundle files will be the same because the unused unusedModule will be eliminated during the minimizing process.

In the main.css file, we can see that it's the same as in the first example 1-without-optimization.

sideEffects - Manually define

Now, if we set the optimization sideEffects property to true or "flag", we can help Webpack manually define which modules have side effects and which don't.

Sean from the Webpack team explains on Stack Overflow that we use the sideEffects configuration as a way to save on both compile time and build size because it excludes modules in advance that are flagged as having no side effects and whose direct exports are not used.

According to Webpack documentation:

sideEffects is much more effective since it allows to skip whole modules/files and the complete subtree.

usedExports relies on Terser to detect side effects in statements. It is a difficult task in JavaScript and not as effective as straightforward sideEffects flag.

Webpack's team talked about another purpose of the manual sideEffects property in their conference and explained that it comes to solve the issue of big bundle files when using of barrel files.

There are 2 ways to manually define which modules have side effects and which don't:

Package config file (package.json):

All package modules have no side effects:
```
{
  "name": "example-module",
  "sideEffects": false
}
```
Alternatively, an array of modules that have side effects (the remaining modules will be considered and flagged as having no side effects if they don't have used direct exports):
```
{
  "name": "example-module",
  "sideEffects": ["*.css", "*.scss"]
}
```

Webpack config file (webpack.config.js):

Use regular expressions to define all Javascript and Typescript files in the project as having no side effects and CSS files as having side effects:

module: {
  rules: [
    {
      test: /\.(js|mjs|jsx|ts|tsx)$/,
      sideEffects: false
    },
    {
      test: /\.s?css$/,
      sideEffects: true
    }
  ]
}

We know that CSS files are considered to have side effects, so we flag them as such. However, this is not mandatory and we can remove the rule for CSS files above. The result will be the same, it's just for protection. if someone later configures the package.json file with sideEffects: false, the rule in webpack.config.js for CSS will override the configuration in package.json

Webpack wrote a "Tip" about CSS files as described on Webpack website:

> Note that any imported file is subject to tree shaking. This means if you use something like css-loader in your project and import a CSS file, it needs to be added to the side effect list so it will not be unintentionally dropped in production mode.

Side effect import - import "filename.js"

In Side effect import also called "Empty import", It will need to be included if there are side effects inside it. This can include, for example, global code and CSS files.

import "filename.js";
import "filename.css";

In our examples, we use a module with side effects called sideEffectsModule. Note that this module has no exports but have side effects cause it affects window object. So this kind of module can easily be excluded from the bundle file if it is configured incorrectly and not included in the array of the sideEffects property in the package.json file.

So let's make a manual configuration of sideEffects in the package.json file.

Let's clone the previous example 3-optimization-sideEffects to 4-package-sideEffects and change the package config file as follows:

package.json

{
  "name": "example-module",
+ "sideEffects": ["*.css"],
}

Alternatively:

webpack.config.js

module: {
  rules: [
    {
      test: /\.(js|mjs|jsx|ts|tsx)$/,
+     sideEffects: false
    }
  ]
}

In our example we use only the package.json option, but both options have the same result.

Now run npx webpack in the terminal window.

Let's demonstrate it in a dependency tree:

In the main.js file, we can see that it is similar to the previous example (3-optimization-sideEffects) except that the content of sideEffectsModule is not included. This occurred because sideEffectsModule doesn't have any exports and was flagged as having no side effects. As a result, Webpack doesn't evaluate it for side effects and simply skips over the sideEffectsModule module.

In the main.css file, we can see that it's the same as in the first example (1-without-optimization).

So what are the differences between the third and fourth examples except the missing global code of sideEffectsModule module? It's about compile time, as we talked earlier about Sean from the Webpack team. In the fourth example, Webpack skips over modules with unused exports that have been flagged as having no side effects without attempting to evalute them for side effects.

sideEffects - Manually define fixed

Let's make the same example but this time we will correctly configure the package.json file.

package.json

{
  "name": "example-module",
- "sideEffects": ["*.css"],
+ "sideEffects": ["*.css", "sideEffectsModule.js"],
}

Now run npx webpack in the terminal window.

Let's demonstrate it in a dependency tree:

In the main.js file, we can see that now it fixed and sideEffectsModule module content is included in the bundle file.

Note - Manually configuring sideEffects issue

I found an issue where Hypnosphi complained that there were differences between development and production when he configured sideEffects: false. He noticed that the order of CSS was not the order of the imports but the usage order. In another issue there is an answer from sokra (a Webpack team member) who wrote:

Technically using sideEffects you say order doesn't matter

Another answer of sokra:

If the order of some modules matter they are not side-effect-free.

I will expand on this in the article Potential issues with barrel files in Webpack talking about issues with optimization configuration and how to solve them.

If I only import the modules that I use, why should I use the sideEffects property? It's useful for modules that only re-exports functions from other modules. For example, barrel files that are used inside modules that are dynamically imported. I will expand on this in my next article.

Summarize the sideEffects configuration in a diagram:

Production mode

The last thing that remains to check is the production bundle.

Production mode has different optimization values compared to development mode. We can see in the default.js file that minimize is set to true.

The minimize property is used as the final tree shaking step. It eliminates unused exports (brown leaves) that were marked by usedExports.

Let's clone the third example 3-optimization-sideEffects to 6 - production and change the webpack config file as follows:

webpack.config.js

  //...
  module.exports = {
+   mode: "production",
-   mode: "development",
-   optimization: {
-     usedExports: true,
-     sideEffects: true,
-   },
//...
  }

Now run npx webpack in the terminal window.

Let's demonstrate it in a dependency tree:

In the main.js file, we can see that it's significantly smaller file. It only includes what's needed and mangles the variable and function names.

In the main.css file, we can see that it has changed here because it eliminated comments in the file compared to previous examples.

After optimizing and minifying our bundle file, let's take a look at the results.

As shown in the screenshot, the size of the JS files has decreased significantly - from 1.36kb to 626 bytes, a reduction of 54%. This is a substantial decrease in size.

Tree shaking summary steps

Eliminating imported modules whose direct exports are not used and don't have side effects with sideEffects configuration.
Mark the brown leaves (comment: /* unused harmony export functionName */) with the usedExports: true property.
Shake the tree (eliminate dead code) with the minimize: true or mode: production property.

Dynamic imports

This article will not cover the topic of tree shaking dynamic imports. For an in-depth explanation of this subject, please refer to the awesome article Dynamically Import ESModules and Tree Shake them too!.

Summary

In this article, we explored the concept of tree shaking in Webpack to optimize your bundle file. We explained how tree shaking can be used to remove unused functions and modules (dead code) from the final bundle and which optimization properties involved in that through examples and visualizations. The main purpose of this article was to ease the tree shaking subject and I hope that I succeeded in that.

I recommend reading my next article on Potential issues with barrel files in Webpack.

Additional Resources:

Reduce JavaScript payloads with tree shaking

Tree Shaking in official Webpack website

Deep Dive Into Tree-Shaking

How to build tree-shakeable JavaScript libraries

JavaScript Start-up Optimization

DEV Community: Fogel

Potential issues with barrel files in Jest

Introduction

Barrel files in Jest

Issues

1. Performance Impact

Example

Solution

2. Unexpected Test Results

Example

Solution

Summary

Boost Your Webpage Load Performance with the new Webpack plugin

Introduction

Background

A regular initial webpage loading example

The solution

A new webpack plugin - html-webpack-preload-react-router

A preloading initial webpage loading example

Bonus - Navigation bar

A navigation bar example

Summary

Potential issues with barrel files in Webpack

Introduction

TL;DR

What are barrel files (index.js)?

Example

Barrel files in Webpack

Optimization properties

We have two ways to solve it:

Dynamic import (Lazy loading in React)

Create a separate bundle file for common modules

Manual configuration of sideEffects solution

babel-plugin-transform-barrels

Function per module

Summary

Tree shaking in Webpack

Introduction

TL;DR

Webpack

Bundle Javascript project (development mode)

Tree Shaking

Optimization

usedExports

sideEffects

Production mode

Tree shaking summary steps

Dynamic imports

Summary

Manual configuration of `sideEffects` solution