⚡ vite-plugin-bundlesize

Vite plugin for inspecting bundlesizes and enforcing limits on the amount of JS shipped to the client. Works with Vite, Astro, SvelteKit, and any other Vite-based build tool.

Inspired by webpack-bundle-analyzer and Bundlephobia.

!screenshot

Setup

$3

- Vite >= 6.0

$3

Install from npm:

``
npm install --dev vite-plugin-bundlesize
`

$3

And add to your Vite config plugins. Also be sure to enable sourcemaps as this is needed to calculate the sizes more accurately (setting it to hidden is recommended):

`diff
import { defineConfig } from "vite";
+ import bundlesize from "vite-plugin-bundlesize";

export default defineConfig({
plugins: [
+ bundlesize(),
],
+ build: {
+ sourcemap: "hidden",
+ },
});
`

Now whenever you run npx vite build, a bundlemeta.json file will be created. It’s recommended to add this to .gitignore as most people don’t need to track this. This is created only so you can inspect your bundle without having to do a fresh build each time.

$3

Make sure you’ve built your project first (vite build). Then, inspect your bundle composition by running the following command from the project root:

`
npx bundlesize
`

This will reuse the existing data saved to bundlemeta.json from the last build. If your code has changed at all, you’ll need to rerun vite build to regenerate that.

$3

Add a limits option to enforce limits on chunks:

`diff
import { defineConfig } from "vite";
import bundlesize from "vite-plugin-bundlesize";

export default defineConfig({
plugins: [
- bundlesize(),
+ bundlesize({
+ limits: [
+ { name: "assets/index-*.js", limit: "100 kB", mode: "uncompressed" },
+ { name: "*/", limit: "150 kB", mode: "uncompressed" },
+ ],
+ }),
],
});
`

limits is an array of the following;

| Name | Type | Default | Description |
| :------ | :-----------------------------------: | :--------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| name | string | | A glob matched by picomatch. |
| limit | string | "150 kB" | Any human-readable size. We recommend 150 kB which is the default, but you may raise or lower that number as needed. |
| mode | "gzip" \| "brotli" \|"uncompressed" | "uncompressed" | Whether or not to take compression into account for size limits. _Note: this plugin will NOT compress anything for you! This is only for reporting purposes._ |

The order of the array matters. Only the first name a file matches with will apply, so order your matches from more-specific to less-specific.

> [!NOTE]
>
> Note on gzip and brotli compression: the stats that show how each chunk breaks down into what modules
> only rely on "uncompressed" sizes for %s. gzip and brotli rely on repetition, therefore each module
> does not contribute to the compressed size in 1:1 proportion with its unpacked size.

#### Ignoring chunks

To ignore a chunk, set limit: Infinity:

`diff
import { defineConfig } from "vite";
import bundlesize from "vite-plugin-bundlesize";

export default defineConfig({
plugins: [
bundlesize({
limits: [
{ name: "assets/index-*.js", limit: "100 kB" },
+ { name: "assets/ignored-*.js", limit: Infinity },
{ name: "*/", limit: "150 kB" },
],
}),
`

While it's possible to increase the limit globally with { name: "*/", limit: Infinity }. It is not recommended and you should prefer being explicit as to which files you are excluding.

#### Exiting build

By default, this plugin will cause vite build to error and exit when a chunk exceeds a certain limit (as opposed to build.chunkSizeWarningLimit which will only warn). In order to allow every build to pass and only show warnings, add allowFail: true:

`diff
import { defineConfig } from "vite";
import bundlesize from "vite-plugin-bundlesize";

export default defineConfig({
plugins: [
bundlesize({
+ allowFail: true,
}),
],
});
`

If allowFail: true is set, you’ll have to run npx bundlesize after every build to throw an error (including in CI).

All options

| Name | Type | Default | Description |
| :--------------- | :------------------: | :-----------------: | :---------------------------------------------------------------------------------------------------------------------------------- |
| outputFile | string | "bundlemeta.json" | Change the location/name of bundlemeta.json |
| limits | Limit[] | | See enforcing size limits |
| allowFail | boolean | false | Allow vite build to succeed even if limits are exceeded (docs) |
| stats | "summary" \| "all" | "summary" | Show a summary of failed chunks, or view all stats. |
| entryPointOnly | boolean | false | When true, the tool will only check entry points and not all chunks. This is useful if you're only focused on render blocking code. |

Troubleshooting

$3

If you get the following error add "type": "module" to your top-level package.json (docs). For most users using Vite this won’t have any impact (and is recommended to do anyway).

`
Error [ERR_REQUIRE_ESM]: require() of ES Module /…/vite-plugin-bundlesize/dist/plugin/index.js from /…/vite-plugin-bundlesize/example/vite-react/vite.config.ts not supported.
Instead change the require of index.js in /…/vite-plugin-bundlesize/example/vite-react/vite.config.ts to a dynamic import() which is available in all CommonJS modules.
``