Non-ESModule dependencies

One of the most common causes of bundle size bloat are modules that can’t be tree-shaken, such as CommonJS modules. It can be a good idea to take note of the larger dependencies found through bundle analysis, and research if the package provides an ESM variant. A quick way to check for this is to see if a "module" entry is present inside the dependency’s package.json file in node_modules.

Once you’ve identified modules that aren’t available in the ESM format, it’s a good idea to check if an update is available that provides it. It’s worth checking the NPM page or GitHub, in case the dependency has undergone a change in NPM package name. For example, react-query recently became @tanstack/react-query, with the new package name including an ESM release. If no new update is available, checking GitHub issues might provide timeframes or discussions around this.

For these cases where no ESM update is available though, there are a few options. In most cases, it’s a matter of deciding whether the potential bundle size savings are worth the development cost of switching to a new dependency or contributing ESM support yourself. There are some projects, such as esm-bundle that provide re-compiles of packages in ESM format, however these can be troublesome to setup for modules that are frequently used as dependencies.

CommonJS Module type in TSConfig

If you’re using TypeScript alongside a bundler, an easy mistake to make that will disable many optimisations, is to have the "module" property of the TSConfig file set to CommonJS. This doesn’t set the actual output of the bundler, but instead changes what intermediary format the bundler receives the compiled TypeScript in. In most cases this should be easy to change to an ESM format, such as "es2020". If you’re using Jest, it might still need the CommonJS output, in which case you can setup a second tsconfig.spec.json file that extends the first but sets module back to CommonJS. This allows the bundler to receive ESM, while Jest can be set to use the altered TSConfig to retain CommonJS.

Marking code as side effect free

In some bundlers, such as Webpack, you can give hints to the side effect detection process. If you’re sure your code doesn’t contain side effects, you can set the "sideEffects" property in your package.json file to false. This tells the bundler that the library doesn’t contain side effects, allowing much more in-depth tree-shaking to take place. This effect can be much more pronounced when using libraries such as React, as various React patterns such as higher order components can falsely trigger side effect detection.

If you do have side effects, but know exactly where they are, you can instead pass a list of patterns to the "sideEffects" property. Specific syntax is outlined in the Webpack documentation. This allows marking a package as mostly side-effect free, while still retaining side effects in situations such as CSS imports.

rules: [
  {
    test: /\/index.ts$/,
    sideEffects: false,
  },
];

Type modifier on imports and exports

If you’re using TypeScript, you’ll often find that you’re importing a file purely to grab types from it. In some situations, this can actually cause that file to not be tree-shaken, despite types having no impact on the output code. If Webpack imports a file and deems it has side effects, even if the only import was a type, it will disable the “used exports” optimisation, and keep the file around anyway.

One way to resolve this is to use the type modifier on type imports and exports in your application. These are covered on the TypeScript documentation and are basically modifiers that can be placed after the import and export keywords to state that all named import/exports that follow are types and can be erased by the compiler. As these entire statements are erased, the bundler never sees the import or export, and therefore will not check the file for side effects. In newer TypeScript versions (4.5+), you can also mark individual imports as types rather than the whole statement.

Example,

// TS 3.8+ syntax
import type { A, B, C } from './letters';
// TS 4.5+ syntax
import { type D, E } from './moreLetters';
// TS 3.8+ syntax
export type { F, G } from './letters';
// TS 4.5+ syntax
export { type H, I } from './moreLetters';

Barrels

Barrel files are a common pattern amongst JavaScript apps, but they can be an easy way to accidentally pull files into your bundle that you didn’t expect. Barrel files are files that re-export the exports from other files. Usually using a wildcard export, such as the following,

export * from './someFile';
export * from './someOtherFile';

While this can be convenient to keep imports tidy, if one of the files getting re-exported contains a side effect, it will be bundled. This will even happen if the import you’re using wasn’t even in the file that got re-exported.

One way to resolve this is to name all barrel files something easily identifiable, such as index.js or index.ts. Then a Webpack rule such as the one earlier in the article can be used to disable side effect detection for these. Another method to reduce this for TypeScript users would be to use named exports rather than wildcard exports, as then type modifiers can be applied to the exports. This would look like the following,

export type { A, B, C } from './someFile';
export { type D, E, F } from './someOtherFile';

This also provides a small improvement to correctness, given accidental duplicate exports can happen using wildcard exports in barrels. Explicitly exporting named exports also allows better encapsulation, by only exporting what you want exposed to other packages rather than exports used between internal files.

Lazy loading

Lazy loading has the potential to be the most impactful optimisation on this page, however I left it last for a reason. While lazy loading is a great tool, it will be held back by a codebase full of the other problems mentioned throughout this article. To get the most out of lazy-loading, your codebase needs to be easily analyzable by your bundler, and as tree-shakeable as possible.

Lazy loading can also cause more problems than solutions if not well thought out. Loading code to parse a file that the user is waiting on right as the process starts will likely lead to a worse user experience than loading it up-front. It’s important to think through where lazy loading will happen, to ensure that the app is split in a way that won’t impede on user experience but will also adequately split the bundles. If you previously had lazy loading setup before doing the above steps, it can also be important to ensure that those places still make sense to lazy load. It’s common for engineers to lazy load many small sections of a codebase to make Webpack split a bundle, only to find that it causes a large number of extremely small bundles to be created once the above problems are solved.

You can lazily-load JavaScript code using the dynamic import statement, import('./Module').then(module => {});. This can be best used at the router level for frontend applications. As this statement is a promise, you can either await it and use the response as any normal imported module or use the callback in .then() to access the imported module.

const LazyViewer = React.lazy(() => import('./Viewer'));

const App = () => (
  <Suspense fallback={<Spinner />}>
    <LazyViewer />
  </Suspense>
);