@fimbul-works/bundle-size 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FimbulWorks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# @fimbul-works/bundle-size
+
+[![npm version](https://badge.fury.io/js/%40fimbul-works%2Fbundle-size.svg)](https://www.npmjs.com/package/@fimbul-works/bundle-size)
+[![TypeScript](https://badges.frapsoft.com/typescript/code/typescript.svg?v=101)](https://github.com/microsoft/TypeScript)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/%40fimbul-works%2Fbundle-size)](https://bundlephobia.com/package/@fimbul-works/bundle-size)
+
+A minimalistic library for calculating and reporting bundle sizes.
+
+## Features
+
+- **Minification**: Powered by Terser.
+- **Compression**: Gzip and Brotli support.
+- **Grouped Reports**: Organize files into logical groups.
+- **In-Memory Measurement**: Reports sizes without needing to write archives to disk unless requested.
+
+## Installation
+
+```bash
+pnpm add -D @fimbul-works/bundle-size
+
+# Use directly with npx
+npx @fimbul-works/bundle-size
+```
+
+## Usage
+
+```typescript
+import { calculateBundleSizes } from '@fimbul-works/bundle-size';
+
+calculateBundleSizes({
+  groups: [
+    {
+      name: 'Main Bundles',
+      include: 'dist/*.js',
+    },
+    {
+      name: 'Plugins',
+      include: 'plugins/*.js',
+    }
+  ],
+  minify: {
+    toplevel: true,
+    compress: { passes: 2, ecma: 2020 },
+    mangle: { module: true },
+    module: true,
+  },
+  compression: ['gzip', 'brotli'],
+  save: ['minify'],
+  cleanup: ['gzip', 'brotli']
+});
+```
+
+## Configuration
+
+Create a configuration file (`bundle-size.config.(ts|js|mjs|cjs|json)`) in the project root for easy setup:
+
+```json
+{
+  "groups": [
+    {
+      "name": "Main Bundles",
+      "include": "dist/*.js",
+    },
+    {
+      "name": "Plugins",
+      "include": "dist/plugins/*.js",
+    }
+  ],
+  "minify": true
+}
+```
+
+### `BundleGroup`
+- `name`: string - Display name for the group.
+- `include`: string | string[] - Glob patterns to include.
+- `exclude`: string | string[] - Glob patterns to exclude.
+- `minify`: boolean | TerserOptions - Whether to minify. If `true`, uses top-level `minify` options or defaults.
+
+### `BundleSizeOptions`
+- `groups`: BundleGroup[] - Array of groups to process.
+- `compression`: ('gzip' | 'brotli')[] - Compression formats to report.
+- `minify`: boolean | TerserOptions - Default minification settings for groups.
+- `save`: boolean | ('minify' | 'gzip' | 'brotli')[] - Which files to keep on disk.
+- `cleanup`: boolean | ('minify' | 'gzip' | 'brotli')[] - Which files to remove after reporting.
+
+## License
+
+MIT License - See [LICENSE](LICENSE) file for details.
+
+---
+
+Built with 📦 by [FimbulWorks](https://github.com/fimbul-works)

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+import { access, readFile } from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import pc from "picocolors";
+import { calculateBundleSizes } from "./index.js";
+/**
+ * Loads a configuration file from a specific path
+ */
+async function loadConfigFile(fullPath) {
+    if (fullPath.endsWith(".json")) {
+        const content = await readFile(fullPath, "utf-8");
+        return JSON.parse(content);
+    }
+    const module = await import(pathToFileURL(fullPath).href);
+    return module.default || module;
+}
+/**
+ * Searches for a configuration file in the current directory
+ */
+async function findConfig() {
+    const names = [
+        "bundle-size.config.ts",
+        "bundle-size.config.js",
+        "bundle-size.config.mjs",
+        "bundle-size.config.cjs",
+        "bundle-size.config.json",
+    ];
+    for (const name of names) {
+        const fullPath = path.join(process.cwd(), name);
+        try {
+            await access(fullPath);
+            return await loadConfigFile(fullPath);
+        }
+        catch { }
+    }
+    return null;
+}
+async function run() {
+    const args = process.argv.slice(2);
+    const customConfigPath = args[0];
+    let config;
+    if (customConfigPath) {
+        const fullPath = path.resolve(process.cwd(), customConfigPath);
+        try {
+            await access(fullPath);
+            config = await loadConfigFile(fullPath);
+        }
+        catch (error) {
+            console.error(pc.red(`Error: Could not load configuration from "${customConfigPath}"`));
+            if (error instanceof Error) {
+                console.error(pc.dim(error.message));
+            }
+            process.exit(1);
+        }
+    }
+    else {
+        config = await findConfig();
+    }
+    if (!config) {
+        console.error(pc.red("Error: No configuration found. Create a bundle-size.config.ts/js/json or provide a path as an argument."));
+        process.exit(1);
+    }
+    try {
+        await calculateBundleSizes(config);
+    }
+    catch (error) {
+        console.error(pc.red("Error calculating bundle sizes:"));
+        console.error(error);
+        process.exit(1);
+    }
+}
+run();

package/dist/index.d.ts

@@ -0,0 +1,97 @@
+import { type MinifyOptions } from "terser";
+/**
+ * Output type
+ */
+export type OutputType = "minify" | "gzip" | "brotli";
+/**
+ * Bundle group
+ */
+export interface BundleGroup {
+    /**
+     * Group name
+     */
+    name: string;
+    /**
+     * Glob patterns to include
+     */
+    include: string | string[];
+    /**
+     * Glob patterns to exclude
+     */
+    exclude?: string | string[];
+    /**
+     * Whether to minify
+     */
+    minify?: boolean | MinifyOptions;
+}
+/**
+ * Bundle size options
+ */
+export interface BundleSizeOptions {
+    /**
+     * Groups of files to process
+     */
+    groups: BundleGroup[];
+    /**
+     * Compression formats to report
+     */
+    compression?: ("gzip" | "brotli")[];
+    /**
+     * Which files to keep on disk
+     */
+    save?: boolean | OutputType[];
+    /**
+     * Which files to remove after reporting
+     */
+    cleanup?: boolean | OutputType[];
+    /**
+     * Default minification settings for groups
+     */
+    minify?: boolean | MinifyOptions;
+}
+/**
+ * File size result
+ */
+interface FileSizeResult {
+    /**
+     * File path
+     */
+    file: string;
+    /**
+     * Original size
+     */
+    size: number;
+    /**
+     * Minified size
+     */
+    minified?: number;
+    /**
+     * Gzipped size
+     */
+    gzip?: number;
+    /**
+     * Brotli size
+     */
+    brotli?: number;
+}
+/**
+ * Group result
+ */
+interface GroupResult {
+    /**
+     * Group name
+     */
+    name: string;
+    /**
+     * File size results
+     */
+    files: FileSizeResult[];
+}
+/**
+ * Calculates bundle sizes.
+ *
+ * @param options Bundle size options
+ * @returns Promise that resolves to the group results
+ */
+export declare function calculateBundleSizes(options: BundleSizeOptions): Promise<GroupResult[]>;
+export {};

package/dist/index.js

@@ -0,0 +1,158 @@
+import { readFile, stat, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { brotliCompressSync, gzipSync } from "node:zlib";
+import bytes from "bytes";
+import glob from "fast-glob";
+import pc from "picocolors";
+import { minify } from "terser";
+/**
+ * Calculates bundle sizes.
+ *
+ * @param options Bundle size options
+ * @returns Promise that resolves to the group results
+ */
+export async function calculateBundleSizes(options) {
+    const { groups, compression = ["gzip", "brotli"] } = options;
+    const results = [];
+    const defaultTerserOptions = {
+        toplevel: true,
+        compress: { passes: 2, ecma: 2020 },
+        mangle: { module: true },
+        module: true,
+    };
+    const isOutputRequested = (option, type) => {
+        if (typeof option === "boolean")
+            return option;
+        if (Array.isArray(option))
+            return option.includes(type);
+        return false;
+    };
+    const shouldSave = (type) => isOutputRequested(options.save, type);
+    const shouldCleanup = (type) => isOutputRequested(options.cleanup, type);
+    const safeUnlink = async (path) => {
+        try {
+            await unlink(path);
+        }
+        catch {
+            // Ignore errors if file doesn't exist
+        }
+    };
+    const getMinifyOptions = (minify, undefinedValue) => {
+        if (typeof minify === "undefined") {
+            return undefinedValue === true ? defaultTerserOptions : undefinedValue;
+        }
+        if (typeof minify === "object") {
+            return minify;
+        }
+        return defaultTerserOptions;
+    };
+    // Default minification options
+    const defaultMinifyOptions = getMinifyOptions(options.minify, true);
+    // Process each group
+    for (const group of groups) {
+        const groupResult = { name: group.name, files: [] };
+        const files = await glob(group.include, {
+            ignore: group.exclude ? (Array.isArray(group.exclude) ? group.exclude : [group.exclude]) : [],
+        });
+        for (const file of files) {
+            // Ignore already minified files
+            if (file.includes(".min.js")) {
+                continue;
+            }
+            const minFile = file.replace(/\.js$/, ".min.js");
+            // Read the contents and size
+            const content = await readFile(file);
+            const originalSize = (await stat(file)).size;
+            const fileResult = { file, size: originalSize };
+            let currentContent = content;
+            // Minifiy if requested
+            const terserOptions = getMinifyOptions(group.minify, defaultMinifyOptions);
+            if (terserOptions) {
+                const minified = await minify(content.toString(), terserOptions);
+                if (minified.code) {
+                    currentContent = Buffer.from(minified.code);
+                    fileResult.minified = currentContent.length;
+                    if (shouldSave("minify")) {
+                        await writeFile(minFile, currentContent);
+                    }
+                }
+            }
+            const baseFileForCompressed = terserOptions ? minFile : file;
+            // Compression
+            if (compression.includes("gzip")) {
+                const gzipped = gzipSync(currentContent);
+                fileResult.gzip = gzipped.length;
+                if (shouldSave("gzip")) {
+                    await writeFile(`${baseFileForCompressed}.gz`, gzipped);
+                }
+            }
+            if (compression.includes("brotli")) {
+                const brotlied = brotliCompressSync(currentContent);
+                fileResult.brotli = brotlied.length;
+                if (shouldSave("brotli")) {
+                    await writeFile(`${baseFileForCompressed}.br`, brotlied);
+                }
+            }
+            groupResult.files.push(fileResult);
+        }
+        results.push(groupResult);
+    }
+    // Print results
+    printResults(results);
+    // Cleanup
+    for (const group of results) {
+        for (const file of group.files) {
+            const minFile = file.file.replace(/\.js$/, ".min.js");
+            const baseFileForCompressed = file.minified !== undefined ? minFile : file.file;
+            if (shouldCleanup("minify") && file.minified !== undefined) {
+                await safeUnlink(minFile);
+            }
+            if (shouldCleanup("gzip") && file.gzip !== undefined) {
+                await safeUnlink(`${baseFileForCompressed}.gz`);
+            }
+            if (shouldCleanup("brotli") && file.brotli !== undefined) {
+                await safeUnlink(`${baseFileForCompressed}.br`);
+            }
+        }
+    }
+    return results;
+}
+/**
+ * Print the bundle size results to the console.
+ * @param results
+ */
+function printResults(results) {
+    const divider = pc.bold(pc.cyan("===================================================================================="));
+    console.log(`\n${divider}`);
+    console.log(pc.bold(pc.cyan(" Bundle sizes (bytes):")));
+    console.log(`${divider}\n`);
+    for (const group of results) {
+        console.log(pc.bold(pc.yellow(` ${group.name}:`)));
+        // Sort files by size descending
+        const sortedFiles = [...group.files].sort((a, b) => b.size - a.size);
+        for (const file of sortedFiles) {
+            const fileName = path.basename(file.file);
+            let line = `  ${pc.white(fileName.padEnd(30))} ${pc.green(formatSize(file.size).padStart(10))}`;
+            if (file.minified !== undefined) {
+                line += ` ${pc.dim("min:")} ${pc.blue(formatSize(file.minified).padStart(8))}`;
+            }
+            if (file.gzip !== undefined) {
+                line += ` ${pc.dim("gz:")} ${pc.magenta(formatSize(file.gzip).padStart(8))}`;
+            }
+            if (file.brotli !== undefined) {
+                line += ` ${pc.dim("br:")} ${pc.cyan(formatSize(file.brotli).padStart(8))}`;
+            }
+            console.log(line);
+        }
+        console.log("");
+    }
+    console.log(`${divider}\n`);
+}
+/**
+ * Format file size.
+ * @param size
+ * @returns
+ */
+function formatSize(size) {
+    return bytes(size, { decimalPlaces: 2 }) || "0 B";
+}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@fimbul-works/bundle-size",
+  "description": "A micro-library for calculating bundle sizes with minification and compression support",
+  "version": "1.0.0",
+  "type": "module",
+  "private": false,
+  "license": "MIT",
+  "author": "FimbulWorks <contact@fimbul.works>",
+  "homepage": "https://github.com/fimbul-works/bundle-size#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fimbul-works/bundle-size.git"
+  },
+  "bugs": {
+    "url": "https://github.com/fimbul-works/bundle-size/issues"
+  },
+  "keywords": [
+    "bundle",
+    "bundle-size",
+    "bundlesize",
+    "minify",
+    "gzip",
+    "brotli",
+    "compression",
+    "size",
+    "build",
+    "cli",
+    "reporter",
+    "metrics",
+    "esbuild",
+    "rollup",
+    "vite",
+    "performance",
+    "javascript",
+    "typescript"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "bundle-size": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc --build --clean && tsc",
+    "format": "npx @biomejs/biome format --write src",
+    "prepublishOnly": "npm run build"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "dependencies": {
+    "bytes": "^3.1.2",
+    "fast-glob": "^3.3.3",
+    "picocolors": "^1.1.1",
+    "terser": "^5.48.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.16",
+    "@types/bytes": "^3.1.5",
+    "@types/node": "^25.9.1",
+    "typescript": "^6.0.3"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ]
+}