esbuild Bundler for Monosize

0.3.2 · active · verified Wed Apr 22

This package provides an `esbuild`-based bundler plugin for the `monosize` package size measurement tool. It enables `monosize` to use `esbuild` for creating optimized bundles, allowing developers to accurately assess the size implications of their code using a high-performance bundler. The current stable version is 0.3.2, and its release cadence is typically tied to updates in `monosize` or `esbuild` itself. Key differentiators include its seamless integration into the `monosize.config.mjs` setup, support for `esbuild`'s full configuration options via a callback, and optimized batch build modes for faster measurements compared to sequential builds. It leverages `esbuild`'s speed and efficiency to provide quick and reliable size reports.

Common errors

```
TypeError: (0 , monosize_bundler_esbuild_1.default) is not a function
```
cause Attempting to use `require()` for `monosize-bundler-esbuild` in a CommonJS context, or incorrect named import.

fix Ensure your `monosize.config.js` is named `monosize.config.mjs` and use `import esbuildBundler from 'monosize-bundler-esbuild';`.
```
Error: The bundler configuration must be a function.
```
cause Passed an `esbuild` configuration object directly to `esbuildBundler` instead of a function that returns the config.

fix Modify your configuration to `bundler: esbuildBundler(config => { /* ... */ return config; })`.
```
Error: Cannot find module 'esbuild'
```
cause The `esbuild` package is not installed in your project.

fix Install `esbuild` as a development dependency: `npm install esbuild --save-dev` or `yarn add esbuild --dev`.

Warnings

breaking This package is designed for an ESM context, typically used within `monosize.config.mjs`. Attempting to use CommonJS `require()` syntax may lead to module resolution errors or unexpected behavior.
Fix: Ensure your `monosize.config.js` is renamed to `monosize.config.mjs` and use `import` statements for all modules.
gotcha The `esbuildBundler` function expects a callback function as its argument, not a direct `esbuild` configuration object. Passing an object directly will result in an error as the bundler expects to receive a function that returns the configuration.
Fix: Wrap your `esbuild` configuration object within a function: `esbuildBundler(config => { /* modify config */ return config; })`.
gotcha While `monosize-bundler-esbuild` provides the integration, developers are responsible for ensuring `esbuild` itself is installed as a peer dependency. Missing `esbuild` will cause runtime errors.
Fix: Install `esbuild` alongside this package: `npm install esbuild --save-dev` or `yarn add esbuild --dev`.
gotcha Monosize uses 'batch build mode' by default, which is faster for most scenarios. If you encounter unexpected build issues or need precise control over individual fixture builds, you might need to switch to 'sequential mode'.
Fix: Run monosize with the `--build-mode=sequential` flag: `monosize measure --build-mode=sequential`.

Install

npm install monosize-bundler-esbuild npm
yarn add monosize-bundler-esbuild yarn
pnpm add monosize-bundler-esbuild pnpm

Imports

esbuildBundler
wrong:
```
const esbuildBundler = require('monosize-bundler-esbuild');
```
correct:
```
import esbuildBundler from 'monosize-bundler-esbuild';
```
The `monosize.config.mjs` file implies an ESM context, requiring `import` syntax. `esbuildBundler` is a default export.

config callback

wrong:

import esbuildBundler from 'monosize-bundler-esbuild';
export default {
  bundler: esbuildBundler({ /* esbuild config */ })
};

correct:

import esbuildBundler from 'monosize-bundler-esbuild';
export default {
  bundler: esbuildBundler(config => { /* customize */ return config; })
};

The `esbuildBundler` function expects a callback that receives and returns the esbuild configuration object, not the object directly.

Quickstart

Shows how to configure `monosize.config.mjs` to use `monosize-bundler-esbuild`, including custom `esbuild` configuration such as adding a file loader for SVGs and defining environment variables.

import esbuildBundler from 'monosize-bundler-esbuild';

export default {
  // Define your entry points for monosize to measure
  fixtures: {
    'my-component-bundle': 'src/my-component.ts',
    'another-lib': 'src/another-lib/index.js'
  },
  // Configure the esbuild bundler plugin
  bundler: esbuildBundler(config => {
    // Example: Add a loader for SVG files if your components import them
    config.loader = {
      ...config.loader,
      '.svg': 'file',
    };
    // Example: Define some global constants
    config.define = {
      ...config.define,
      'process.env.NODE_ENV': JSON.stringify('production'),
    };
    // Always return the (potentially modified) config
    return config;
  }),
  // Other monosize configurations...
  output: {
    directory: './monosize-results'
  }
};

view raw JSON →