# monosize

> monosize 📦 Monorepo + bundlesize M

Latest version **0.10.0** (published 2026-07-22) · MIT license · 0 weekly downloads

## Install

```sh
npm install monosize
pnpm add monosize
yarn add monosize
bun add monosize
```

Provides the command `monosize`.

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.10.0 |
| Published | 2026-07-22 |
| First published | 2022-03-24 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Dependencies | 8 |
| Unpacked size | 112 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 48 |
| Maintainers | layershifter, uifabricteam, microsoft-oss-releases |

## Links

- npm: https://www.npmjs.com/package/monosize
- Repository: https://github.com/microsoft/monosize
- Homepage: https://github.com/microsoft/monosize#readme
- Issues: https://github.com/microsoft/monosize/issues
- npm.io page: https://npm.io/package/monosize

## Dependencies (8)

- [acorn](https://npm.io/package/acorn.md) ^8.17.0
- [tslib](https://npm.io/package/tslib.md) ^2.4.1
- [yargs](https://npm.io/package/yargs.md) ^18.0.0
- [ci-info](https://npm.io/package/ci-info.md) ^4.2.0
- [empathic](https://npm.io/package/empathic.md) ^2.0.0
- [cli-table3](https://npm.io/package/cli-table3.md) ^0.6.5
- [tinyglobby](https://npm.io/package/tinyglobby.md) ^0.2.13
- [pretty-bytes](https://npm.io/package/pretty-bytes.md) ^7.1.0

## Recent versions

- 0.10.0 (latest) — 2026-07-22
- 0.9.0 — 2026-05-07
- 0.8.3 — 2026-04-27
- 0.8.2 — 2026-04-16
- 0.8.1 — 2026-04-16
- 0.8.0 — 2026-01-27
- 0.7.1 — 2025-12-08
- 0.7.0 — 2025-07-10
- 0.6.3 — 2024-08-06
- 0.6.2 — 2024-05-20
- 0.6.1 — 2024-05-17
- 0.6.0 — 2024-05-16
- 0.5.1 — 2024-05-10
- 0.5.0 — 2024-03-22
- 0.4.0 — 2024-03-16
- … 14 more at https://npm.io/package/monosize/versions

## README

<div align="center">
  <img width="600" alt="A sample report produced by monosize" src="https://raw.githubusercontent.com/microsoft/monosize/main/.github/images/gh-report.png">
  <h1>monosize 📦</h1>
  <b>Mono</b>repo + bundle<b>size</b>
  <br/>
  <span>Monosize is a CLI tool to measure bundle size locally and on CI</span>
  <br />
  <br />
</div>

- 📚 Designed to be used in CI/CD pipelines
- 🎱 Designed to represent real-world scenarios
- 🧰 Supports single packages & monorepos
- 🍿 Supports various bundlers ([Webpack](https://github.com/microsoft/monosize/tree/main/packages/monosize-bundler-webpack), [Rspack](https://github.com/microsoft/monosize/tree/main/packages/monosize-bundler-rspack), [Vite](https://github.com/microsoft/monosize/tree/main/packages/monosize-bundler-vite), implement your own? 🐱)
- ☁️ Supports various storage adapters

<hr />

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

- [Install](#install)
- [Usage](#usage)
  - [Fixtures](#fixtures)
- [Configuration](#configuration)
  - [Config API](#config-api)
  - [Measuring CSS, JSON, and other assets](#measuring-css-json-and-other-assets)
  - [Bundler adapters](#bundler-adapters)
  - [Storage adapters](#storage-adapters)
  - [Threshold](#threshold)
- [Commands](#commands)
  - [`measure`](#measure)
    - [Options](#options)
    - [Examples](#examples)
  - [`compare-reports`](#compare-reports)
    - [Options](#options-1)
  - [`upload-report`](#upload-report)
    - [Options](#options-2)
- [Contributing](#contributing)
- [Trademarks](#trademarks)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## Install

```sh
# yarn
yarn add --dev monosize

# npm
npm install --save-dev monosize
```

## Usage

> Note: `monosize` requires building packages first before doing any kind of measurements. Make sure to accommodate this in your pipeline

### Fixtures

Fixtures declare exports that should be measured by the `monosize` tool. Fixtures are created inside each package.

For example:

```js
import { Component } from '@library/component';

export { Component };
// 👆 "export" is required to be able to measure the size of the component

export default {
  name: 'Component',
  // 👆 defines a name for a fixture that will be used in output
};
```

## Configuration

You need to create a `monosize.config.mjs` in the root of your project directory (next to `package.json`) to configure storage and bundler adapters.

```
my-proj/
├─ src/
├─ monosize.config.mjs
├─ node_modules/
├─ bundle-size/
│  ├─ Fixture.fixture.js
├─ package.json
```

A global configuration can also be used for monorepo scenarios:

```
my-proj-a/
├─ src/
├─ node_modules/
├─ bundle-size/
│  ├─ Fixture.fixture.js
├─ package.json
my-proj-b/
├─ src/
├─ node_modules/
├─ bundle-size/
│  ├─ Fixture.fixture.js
├─ package.json
monosize.config.mjs
```

### Config API

```js
// monosize.config.mjs
import storageAdapter from 'monosize-storage-*';
import webpackBundler from 'monosize-bundler-webpack';

/** @type {import('monosize').MonoSizeConfig} */
const config = {
  repository: 'https://github.com/__ORG__/__REPOSITORY__',
  storage: storageAdapter(),
  bundler: webpackBundler(config => {
    // customize config here
    return config;
  }),

  // Optional `compare-reports`/`upload-reports` commands config overrides
  reportResolvers: {
    packageRoot: async reportFile => {
      // provide custom logic on how to resolve package root
      return '...';
    },
    packageName: async packageRoot => {
      // provide custom logic on how to resolve packageName used within reports
      return '...';
    },
  },

  threshold: '10kB', // default is "10%"

  // Optional: which asset types to measure. Default: ['js'] — opt in to
  // 'css' / 'json' by listing them explicitly. Files in the bundler output
  // dir whose extension is not in the allowlist are ignored. Each entry
  // must be one of the known AssetType values.
  assetTypes: ['js', 'css', 'json'],
};

export default config;
```

### Measuring CSS, JSON, and other assets

Each fixture's bundler output is treated as a directory; the CLI walks it
non-recursively, classifies files by extension against `assetTypes`, and
reports a per-type breakdown alongside top-level totals. Threshold gates on
totals only.

To measure CSS or other non-JS assets, configure your bundler (via the
adapter's config-enhancer callback) to extract them. monosize itself does
not bundle a CSS plugin — install whatever your bundler needs (e.g.
`mini-css-extract-plugin` for webpack) in your own project and wire it
through the enhancer. Rspack / vite handle CSS extraction natively.

### Bundler adapters

To build fixtures and produce artifacts you need to use a bundler adapter. Following adapters are available:

- [`monosize-bundler-webpack`](https://github.com/microsoft/monosize/tree/main/packages/monosize-bundler-webpack)
- [`monosize-bundler-rspack`](https://github.com/microsoft/monosize/tree/main/packages/monosize-bundler-rspack)
- [`monosize-bundler-vite`](https://github.com/microsoft/monosize/tree/main/packages/monosize-bundler-vite)

### Storage adapters

To store reference results and run comparisons you need to use a storage adapter. Following adapters are available:

- [`monosize-storage-git`](https://github.com/microsoft/monosize/tree/main/packages/monosize-storage-git)
- [`monosize-storage-upstash`](https://github.com/microsoft/monosize/tree/main/packages/monosize-storage-upstash)

### Threshold

The threshold is used to determine if the bundle size is acceptable. It can be set in the configuration file and can be a percentage (e.g., `10%`) or an absolute size (e.g., `10kB`). The default value is `10%`.

If the bundle size exceeds the threshold, the `compare-reports` command will fail with exit code `1`.

## Commands

### `measure`

```sh
monosize measure [--debug] [--artifacts-location] [--fixtures] [--build-mode] [--quiet]
```

Builds fixtures and produces artifacts. For each fixture:

- `[fixture].fixture.js` - a modified fixture without a default export, used by a bundler
- `[fixture].output/` - a directory containing the bundler's output for this fixture (at minimum `index.js`, plus extracted CSS / JSON sidecars when configured). The CLI walks this directory, classifies files by extension against `assetTypes`, and produces a per-type breakdown plus totals.
- `[fixture].debug.js` - a partially minified file alongside (not inside) `[fixture].output/`, useful for debugging (optional, if `--debug` is passed)

Produces a report file (`dist/bundle-size/monosize.json`) that is used by other steps.

#### Options

- `artifacts-location` - defines relative path from the package root where the artifact files will be stored (`monosize.json` & bundler output). If specified, `--report-files-glob` in `monosize compare-reports` & `monosize upload-report` should be set accordingly.
- `fixtures` - optional argument to pass a fixture filename or globbing pattern. If not specified, all fixture files matching a `*.fixture.js` pattern will be measured.
- `build-mode` - controls how fixtures are built. `batch` builds all fixtures in a single bundler run with multiple entry points (3-15x faster). `sequential` builds one at a time. Default: `batch`.

#### Examples

`monosize measure --fixtures ba*` - matches any fixtures with filenames starting with `ba`
`monosize measure --fixtures Fixture.fixture.js` - matches a fixture with the exact filename
`monosize measure --build-mode=sequential` - builds fixtures one at a time (slower but useful for debugging)

### `compare-reports`

Compares local (requires call of `monosize measure` first) and remote results, provides output to CLI or to a Markdown file.

```sh
monosize compare-reports --branch=main --output=["cli"|"markdown"] [--deltaFormat=["delta"|"percent"]] [--report-files-glob] [--quiet]
```

> [!TIP]
> In order to resolve package name used within report, we look for `package.json` or `project.json` by default to identify project root and use `#name` property from obtained configuration.
> If you have custom solution that needs changes please use monosize configuration API (`MonoSizeConfig.reportResolvers`).

#### Options

- `branch` - the branch to compare the results with, usually `main`
- `output` - defines the output formatter, either `cli` or `markdown`
- `deltaFormat` - defines the format of the delta column, either `delta` or `percent`
- `report-files-glob` - defines a glob pattern to search for report files, defaults to `packages/**/dist/bundle-size/monosize.json`

### `upload-report`

> [!CAUTION]
> Should be called only during CI builds.

> [!TIP]
> Requires a configured storage adapter.

> [!TIP]
> In order to resolve package name used within report, we look for `package.json` or `project.json` by default to identify project root and use `#name` property from obtained configuration.
> If you have custom solution that needs changes please use monosize configuration API (`MonoSizeConfig.reportResolvers`).

```sh
monosize upload-report --branch=main --commit-sha=HASH [--report-files-glob] [--quiet]
```

Aggregates local results to a single report and uploads data using the configured storage adapter.

#### Options

- `branch` - the branch to compare the results with, usually `main`
- `commit-sha` - the commit SHA to associate the report with
- `report-files-glob` - defines a glob pattern to search for report files, defaults to `packages/**/dist/bundle-size/monosize.json`

## Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide
a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.

## Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft
trademarks or logos is subject to and must follow
[Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
Any use of third-party trademarks or logos are subject to those third-party's policies.

---
_Source: https://npm.io/package/monosize · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._