### BundleMon GitHub Actions Integration

Source: https://context7.com/lironer/bundlemon/llms.txt

Minimal GitHub Actions workflow example to build project artifacts and then run BundleMon. Assumes BundleMon GitHub App is installed or appropriate environment variables are set.

```yaml
# .github/workflows/build.yml — minimal GitHub Actions example
name: Build
on:
  push:
    branches: [main]
  pull_request:
    types: [synchronize, opened, reopened]

jobs:
  build:
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - run: yarn && yarn build
      - uses: lironer/bundlemon-action@v1
        # BundleMon GitHub App auto-provides project ID and auth in GitHub Actions.
        # For other CIs, set BUNDLEMON_PROJECT_ID and BUNDLEMON_PROJECT_APIKEY.
```

--------------------------------

### Install Dependencies with Yarn

Source: https://github.com/lironer/bundlemon/blob/main/CONTRIBUTING.md

Installs all project dependencies using Yarn. Ensure Node.js and Yarn are installed.

```bash
yarn install
```

--------------------------------

### GitHub Actions Workflow for BundleMon

Source: https://github.com/lironer/bundlemon/blob/main/README.md

Example GitHub Actions workflow to build a project and run BundleMon. Ensure Node.js is set up and dependencies are installed before running the BundleMon action.

```yaml
name: Build

on:
  push:
    branches: [main]
  pull_request:
    types: [synchronize, opened, reopened]

jobs:
  build:
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '22'

      - name: Install dependencies
        run: yarn

      - name: Build
        run: yarn build

      - name: BundleMon
        uses: lironer/bundlemon-action@v1
```

--------------------------------

### BundleMon Output Example

Source: https://github.com/lironer/bundlemon/blob/main/README.md

Example of BundleMon output showing the status (PASS/FAIL) and size of monitored files, including those with hashed filenames.

```text
[PASS] bundle.(hash).js: 19.67KB
[FAIL] home.(hash).chunk.js: 70.09KB > 50KB
[PASS] login.(hash).chunk.js: 3.37KB < 50KB
```

--------------------------------

### Starting Self-Hosted BundleMon and CLI Configuration

Source: https://context7.com/lironer/bundlemon/llms.txt

Commands to start the self-hosted BundleMon platform using Docker Compose and configure the BundleMon CLI to point to your custom instance.

```bash
# Start the platform
docker compose up -d

# Point the CLI at your self-hosted instance
export BUNDLEMON_SERVICE_URL=https://bundlemon.my-company.com/api
npx bundlemon
```

--------------------------------

### Install BundleMon

Source: https://context7.com/lironer/bundlemon/llms.txt

Install BundleMon as a development dependency using npm or yarn.

```bash
npm install bundlemon --save-dev
```

```bash
yarn add bundlemon --dev
```

--------------------------------

### Start Mock Services for Testing

Source: https://github.com/lironer/bundlemon/blob/main/CONTRIBUTING.md

Initiates mock services required for running tests within the BundleMon service. Execute from the `apps/service/` directory.

```bash
yarn start:mock-services
```

--------------------------------

### Install BundleMon

Source: https://github.com/lironer/bundlemon/blob/main/README.md

Install BundleMon as a development dependency using yarn.

```bash
yarn add bundlemon --dev
```

--------------------------------

### Install BundleMon

Source: https://github.com/lironer/bundlemon/blob/main/README.md

Install BundleMon as a development dependency using npm. This command should be run in your project's root directory.

```bash
npm install bundlemon --save-dev

```

--------------------------------

### Example Stored Record (JSON)

Source: https://github.com/lironer/bundlemon/blob/main/docs/privacy.md

This JSON object represents an example of a record stored in the free hosted service. It includes details about the project, commit, and files analyzed.

```json
{
  "_id": "6897284dd96dcac9c6449c84",
  "branch": "dependabot/npm_and_yarn/npm_and_yarn-45ede89f0a",
  "commitSha": "472e405f5261fc02f3af8ba491b5fc121dbff98d",
  "baseBranch": "main",
  "prNumber": "245",
  "projectId": "60a928cfc1ab380009f5cc0b",
  "creationDate": "2025-08-09T10:51:57.069Z",
  "files": [
    {
      "compression": "none",
      "pattern": "index.html",
      "matches": [
        {
          "path": "index.html",
          "size": 869
        }
      ]
    },
    {
      "compression": "none",
      "friendlyName": "JS files",
      "pattern": "assets/**/*-<hash>.js",
      "matches": [
        {
          "path": "assets/Alert-(hash).js",
          "size": 5913
        },
        {
          "path": "assets/AlertTitle-(hash).js",
          "size": 659
        }
      ]
    },
    {
      "compression": "none",
      "pattern": "assets/Main-*-<hash>.js",
      "matches": [
        {
          "path": "assets/Main-index-(hash).js",
          "size": 473258
        }
      ]
    }
  ],
  "groups": [
    {
      "compression": "none",
      "friendlyName": "JS files",
      "pattern": "**/*.js",
      "size": 1252544
    }
  ],
  "outputs": {
    "github": {
      "owner": "LironEr",
      "repo": "bundlemon",
      "outputs": {
        "commitStatus": 38346868576,
        "prComment": 3170605595
      }
    }
  }
}
```

--------------------------------

### BundleMon Configuration in package.json

Source: https://context7.com/lironer/bundlemon/llms.txt

Example configuration for BundleMon within the package.json file. Specifies base directory, compression, and file-specific size limits.

```json
{
  "bundlemon": {
    "baseDir": "./build",
    "defaultCompression": "gzip",
    "verbose": false,
    "includeCommitMessage": false,
    "reportOutput": [],
    "files": [
      {
        "path": "index.html",
        "maxSize": "2kb",
        "maxPercentIncrease": 5
      },
      {
        "path": "static/js/main.<hash>.js",
        "maxSize": "150kb"
      },
      {
        "path": "static/js/*.<hash>.chunk.js",
        "maxSize": "50kb",
        "maxPercentIncrease": 10
      },
      {
        "path": "assets/**/*.{png,svg}"
      }
    ],
    "groups": [
      {
        "path": "static/js/**/*.js",
        "friendlyName": "All JS",
        "maxSize": "500kb"
      }
    ]
  }
}
```

--------------------------------

### Serve BundleMon Service Locally

Source: https://github.com/lironer/bundlemon/blob/main/CONTRIBUTING.md

Starts the BundleMon service locally. The service will reload automatically when code in `apps/service/` changes. Requires Docker and Docker Compose.

```bash
yarn serve
```

--------------------------------

### Example JSON Report Structure

Source: https://context7.com/lironer/bundlemon/llms.txt

This is an example of the structure of the JSON report generated by BundleMon.

```json
{
  "status": "Pass",
  "files": [
    {
      "path": "static/js/main.(hash).js",
      "pattern": "static/js/main.<hash>.js",
      "size": 148302,
      "compression": "gzip",
      "maxSize": 153600,
      "status": "Pass",
      "diff": { "bytes": -1200, "percent": -0.8, "change": "Update" }
    }
  ],
  "groups": [],
  "stats": {
    "currBranchSize": 148302,
    "baseBranchSize": 149502,
    "diff": { "bytes": -1200, "percent": -0.8 }
  },
  "metadata": {
    "subProject": null,
    "linkToReport": "https://app.bundlemon.dev/projects/abc123/reports?...",
    "record": { "id": "rec_xyz", "branch": "feat/my-feature", "commitSha": "a1b2c3d4" },
    "baseRecord": { "id": "rec_abc", "branch": "main" }
  }
}
```

--------------------------------

### GitHub Actions for Monorepo Packages

Source: https://context7.com/lironer/bundlemon/llms.txt

Example GitHub Actions workflow steps to run BundleMon separately for each package in a monorepo using their respective configuration files.

```yaml
# GitHub Actions — run BundleMon for each package separately
- name: BundleMon web-app
  run: npx bundlemon --config packages/web-app/bundlemon.config.json
- name: BundleMon admin-app
  run: npx bundlemon --config packages/admin-app/bundlemon.config.json
```

--------------------------------

### BundleMon Configuration with Path Labels

Source: https://context7.com/lironer/bundlemon/llms.txt

Configure path labels to normalize hashed filenames for consistent tracking across builds. This example shows how BundleMon interprets hashed and chunk ID segments.

```json
// bundlemon.config.json
{
  "baseDir": "./build",
  "pathLabels": {
    "hash": "[a-zA-Z0-9]+",
    "chunkId": "[\\w-]+"
  },
  "files": [
    { "path": "static/js/main.<hash>.js",                "maxSize": "200kb" },
    { "path": "static/js/*.<hash>.chunk.<chunkId>.js",   "maxSize": "50kb" },
    { "path": "static/css/*.<hash>.css",                 "maxSize": "20kb" }
  ]
}
```

```text
# Build output might contain:
#   static/js/main.a1b2c3.js
#   static/js/home.d4e5f6.chunk.sidebar-7.js
#
# BundleMon normalises these to:
#   [PASS] static/js/main.(hash).js: 145.3KB < 200KB
#   [PASS] static/js/home.(hash).chunk.(chunkId).js: 38.1KB < 50KB
```

--------------------------------

### Build Packages with Yarn

Source: https://github.com/lironer/bundlemon/blob/main/CONTRIBUTING.md

Builds all packages within the BundleMon project. This command is typically run after installing dependencies or making code changes.

```bash
yarn build-packages
```

--------------------------------

### Generate Secret Session Key

Source: https://github.com/lironer/bundlemon/blob/main/apps/service/README.md

Use this command to generate a secret session key for the service. Ensure you have yarn installed.

```sh
yarn install

# prints the secret key
node apps/service/scripts/generateSecretKey.js
```

--------------------------------

### Get Commit Record with Base Record

Source: https://context7.com/lironer/bundlemon/llms.txt

Fetches a specific commit record along with its corresponding base record for comparison. The base record defaults to the previous commit on the same branch.

```bash
curl -s "https://api.bundlemon.dev/v1/projects/60a928cfc1ab380009f5cc0b/commit-records/rec_newrecordid/base?compareTo=previousCommit"

# compareTo: "previousCommit" (default) | "latestBranch"
# Response: { "record": CommitRecord, "baseRecord": CommitRecord | null }
```

--------------------------------

### Self-Hosted Deployment

Source: https://context7.com/lironer/bundlemon/llms.txt

Instructions for running the full BundleMon platform on your own infrastructure using Docker.

```APIDOC
## Self-Hosted Deployment

Run the full BundleMon platform (service + website) on your own infrastructure using Docker.

### Docker Compose Configuration

```yaml
# docker-compose.yml
services:
  bundlemon:
    image: ghcr.io/lironer/bundlemon-platform:v1
    ports:
      - '8080:8080'
    environment:
      MONGO_URL: mongodb://mongo:27017
      MONGO_DB_NAME: bundlemon
      PORT: 8080
      ROOT_DOMAIN: bundlemon.my-company.com
      HTTP_SCHEMA: https
      SECRET_SESSION_KEY: "your-generated-secret-key"  # node scripts/generateSecretKey.js
      SHOULD_SERVE_WEBSITE: "true"
      # GitHub App integration (optional)
      GITHUB_APP_ID: "123456"
      GITHUB_APP_PRIVATE_KEY: "-----BEGIN RSA PRIVATE KEY-----\n..."
      GITHUB_APP_CLIENT_ID: "Iv1.abcdef123456"
      GITHUB_APP_CLIENT_SECRET: "your-client-secret"
    depends_on:
      - mongo

  mongo:
    image: mongo:7.0
    ports:
      - '27017:27017'
```

### Starting the Platform

```bash
# Start the platform
docker compose up -d
```

### CLI Configuration for Self-Hosted Instance

Point the BundleMon CLI at your self-hosted instance by setting the `BUNDLEMON_SERVICE_URL` environment variable.

```bash
export BUNDLEMON_SERVICE_URL=https://bundlemon.my-company.com/api
npx bundlemon
```
```

--------------------------------

### Run BundleMon from Command Line

Source: https://context7.com/lironer/bundlemon/llms.txt

Execute BundleMon from the command line. It reads configuration from package.json or a config file. Options to specify config path, override compression, or set sub-project for monorepos are available.

```bash
npx bundlemon
```

```bash
npx bundlemon --config my-bundlemon.json
```

```bash
npx bundlemon --defaultCompression brotli
```

```bash
npx bundlemon --subProject my-app
```

--------------------------------

### Get Record with Base

Source: https://context7.com/lironer/bundlemon/llms.txt

Returns a specific commit record paired with its base record (defaults to the previous commit on the same branch).

```APIDOC
## GET /api/v1/projects/:projectId/commit-records/:commitRecordId/base — Get Record with Base

Returns a specific commit record paired with its base record (defaults to the previous commit on the same branch).

```bash
curl -s "https://api.bundlemon.dev/v1/projects/60a928cfc1ab380009f5cc0b/commit-records/rec_newrecordid/base?compareTo=previousCommit"

# compareTo: "previousCommit" (default) | "latestBranch"
# Response: { "record": CommitRecord, "baseRecord": CommitRecord | null }
```
```

--------------------------------

### Create Project

Source: https://context7.com/lironer/bundlemon/llms.txt

Creates a new BundleMon project. Returns the project ID and API key to use in CI environment variables.

```APIDOC
## POST /api/v1/projects — Create Project

Creates a new BundleMon project. Returns the project ID and API key to use in CI environment variables.

```bash
curl -s -X POST https://api.bundlemon.dev/v1/projects \
  -H "Content-Type: application/json" \
  -d '{}'

# Response
# {
#   "projectId": "60a928cfc1ab380009f5cc0b",
#   "apiKey": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
# }
```
```

--------------------------------

### Generate Local Data for Service

Source: https://github.com/lironer/bundlemon/blob/main/CONTRIBUTING.md

Generates sample data for local testing of the BundleMon service. Run this command when the local service is active.

```bash
yarn gen-local-data
```

--------------------------------

### Create BundleMon Project

Source: https://context7.com/lironer/bundlemon/llms.txt

Use this endpoint to create a new BundleMon project. It returns a unique `projectId` and an `apiKey` required for subsequent API interactions.

```bash
curl -s -X POST https://api.bundlemon.dev/v1/projects \
  -H "Content-Type: application/json" \
  -d '{}'

# Response
# {
#   "projectId": "60a928cfc1ab380009f5cc0b",
#   "apiKey": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
# }
```

--------------------------------

### BundleMon CLI Usage

Source: https://github.com/lironer/bundlemon/blob/main/README.md

Run BundleMon using the CLI, specifying a custom configuration file path.

```bash
bundlemon --config my-custom-config-path.json
```

--------------------------------

### Run BundleMon Platform with Docker

Source: https://github.com/lironer/bundlemon/blob/main/docs/self-hosted/README.md

Use this command to run the BundleMon platform container. Ensure MongoDB is accessible at the specified URL.

```sh
docker run --rm -p 8080:8080 -e MONGO_URL="mongodb://localhost:27017" ghcr.io/lironer/bundlemon-platform:v1
```

--------------------------------

### Run BundleMon Service Tests

Source: https://github.com/lironer/bundlemon/blob/main/CONTRIBUTING.md

Executes the test suite for the BundleMon service. Ensure mock services are running before executing.

```bash
yarn test
```

--------------------------------

### BundleMon package.json Configuration

Source: https://github.com/lironer/bundlemon/blob/main/README.md

Configure BundleMon by adding a 'bundlemon' property to your package.json. Specify base directory and files to monitor, including size limits and percentage increases.

```json
"bundlemon": {
  "baseDir": "./build",
  "files": [
    {
      "path": "index.html",
      "maxSize": "2kb",
      "maxPercentIncrease": 5
    },
    {
      "path": "bundle.<hash>.js",
      "maxSize": "10kb"
    },
    {
      "path": "assets/**/*.{png,svg}"
    }
  ]
}
```

--------------------------------

### BundleMon CLI Flags and Exit Codes

Source: https://context7.com/lironer/bundlemon/llms.txt

Demonstrates using CLI flags to override configuration values and checking the exit code for build status. An exit code of 0 indicates success, while 1 indicates failure.

```bash
npx bundlemon -c ./configs/bundlemon-prod.json --subProject dashboard --defaultCompression brotli
```

```bash
echo $?
```

--------------------------------

### Customizing and Adding Multiple Path Labels

Source: https://github.com/lironer/bundlemon/blob/main/docs/customPathLabels.md

Shows how to customize the existing 'hash' label and add a new 'chunkId' label for advanced path matching in the configuration.

```json
{
  "baseDir": "./build",
  "pathLabels": {
    "hash": "[a-z]+",
    "chunkId": "[\\w-]+"
  },
  "files": [
    {
      "path": "*.<hash>.chunk.<chunkId>.js"
    },
    {
      "path": "*.<hash>.js"
    }
  ]
}
```

--------------------------------

### Self-Hosted BundleMon Deployment with Docker Compose

Source: https://context7.com/lironer/bundlemon/llms.txt

Configure and run the full BundleMon platform on your own infrastructure using Docker. Ensure you generate a secret key for `SECRET_SESSION_KEY` and optionally configure GitHub App integration.

```yaml
# docker-compose.yml
services:
  bundlemon:
    image: ghcr.io/lironer/bundlemon-platform:v1
    ports:
      - '8080:8080'
    environment:
      MONGO_URL: mongodb://mongo:27017
      MONGO_DB_NAME: bundlemon
      PORT: 8080
      ROOT_DOMAIN: bundlemon.my-company.com
      HTTP_SCHEMA: https
      SECRET_SESSION_KEY: "your-generated-secret-key"  # node scripts/generateSecretKey.js
      SHOULD_SERVE_WEBSITE: "true"
      # GitHub App integration (optional)
      GITHUB_APP_ID: "123456"
      GITHUB_APP_PRIVATE_KEY: "-----BEGIN RSA PRIVATE KEY-----\n..."
      GITHUB_APP_CLIENT_ID: "Iv1.abcdef123456"
      GITHUB_APP_CLIENT_SECRET: "your-client-secret"
    depends_on:
      - mongo

  mongo:
    image: mongo:7.0
    ports:
      - '27017:27017'
```

--------------------------------

### BundleMon Configuration for Report Output Plugins

Source: https://context7.com/lironer/bundlemon/llms.txt

Configure an array of output plugins to specify where and how BundleMon reports results. Supports built-in plugins like 'github' and 'json', or custom scripts.

```json
{
  "reportOutput": [
    "github",
    ["json", { "fileName": "bundlemon-results.json" }],
    ["custom", { "path": "./scripts/my-output.js" }]
  ]
}
```

--------------------------------

### FileConfig Options for BundleMon

Source: https://context7.com/lironer/bundlemon/llms.txt

Define rules for tracking file sizes, enforcing limits, and overriding compression. Use 'path' for glob matching and 'friendlyName' for reporting.

```typescript
import type { FileConfig } from 'bundlemon'; // from lib/main/types

// Minimal — just track size, no limits
const trackOnly: FileConfig = { path: 'dist/vendor.<hash>.js' };

// Enforce absolute max size (bytes-compatible string: "b", "kb", "mb")
const withMaxSize: FileConfig = {
  path: 'dist/main.<hash>.js',
  maxSize: '150kb',
};

// Enforce max percent increase from base branch
const withPercentLimit: FileConfig = {
  path: 'dist/runtime.<hash>.js',
  maxSize: '5kb',
  maxPercentIncrease: 10,   // Fail if size grew > 10% vs base branch
};

// Per-file compression override (ignores defaultCompression)
const rawHtml: FileConfig = {
  path: 'index.html',
  compression: 'none',
  maxSize: '8kb',
};

// Friendly name displayed in reports / GitHub comments
const named: FileConfig = {
  path: 'static/js/**/*.chunk.js',
  friendlyName: 'Route chunks',
  maxSize: '60kb',
};
```

--------------------------------

### BundleMon Configuration with Default Compression

Source: https://context7.com/lironer/bundlemon/llms.txt

Set the default compression mode for measuring file sizes globally. Individual files can override this setting using the 'compression' field.

```json
{
  "baseDir": "./dist",
  "defaultCompression": "brotli",
  "files": [
    { "path": "*.js",   "maxSize": "100kb" },
    { "path": "*.css",  "maxSize": "20kb",  "compression": "gzip" },
    { "path": "*.html", "maxSize": "5kb",   "compression": "none" }
  ]
}
```

```bash
# Override at runtime without editing the config file
npx bundlemon --defaultCompression none
```

--------------------------------

### Run BundleMon Programmatically

Source: https://context7.com/lironer/bundlemon/llms.txt

Use the default export to integrate BundleMon into your build process. Handle the returned report object to determine success or failure.

```typescript
import bundlemon from 'bundlemon';

async function checkBundleSize() {
  let report;
  try {
    report = await bundlemon({
      baseDir: './dist',
      defaultCompression: 'gzip',
      files: [
        { path: 'index.html',          maxSize: '2kb' },
        { path: 'main.<hash>.js',      maxSize: '200kb', maxPercentIncrease: 5 },
        { path: '**/*.chunk.<hash>.js', maxSize: '60kb' },
      ],
      groups: [
        { path: '**/*.js', friendlyName: 'Total JS', maxSize: '500kb' },
      ],
      reportOutput: [['json', { fileName: 'bundlemon-results.json' }]],
      verbose: true,
    });
  } catch (err) {
    console.error('BundleMon error:', err.message);
    process.exit(1);
  }

  // report.status: "Pass" | "Fail"
  // report.stats:  { currBranchSize, baseBranchSize, diff: { bytes, percent } }
  // report.files:  FileDetailsDiff[]  — per-file results including diff vs base
  // report.groups: FileDetailsDiff[]  — group results
  // report.metadata.linkToReport — URL to the online history report

  if (report.status === 'Fail') {
    const failing = report.files.filter((f) => f.status === 'Fail');
    for (const f of failing) {
      console.error(`FAIL ${f.path}: ${f.size} bytes, limit ${f.maxSize}`);
    }
    process.exit(1);
  }

  console.log('All bundle size checks passed!');
  console.log(`Total: ${report.stats.currBranchSize} bytes`);
  if (report.metadata.linkToReport) {
    console.log(`Report: ${report.metadata.linkToReport}`);
  }
}

checkBundleSize();

```

--------------------------------

### Adding Custom Labels to Path Matching

Source: https://github.com/lironer/bundlemon/blob/main/docs/customPathLabels.md

Demonstrates how to add a 'chunkId' label to the path labels configuration, allowing for more specific file matching.

```json
{
  "baseDir": "./build",
  "pathLabels": {
    "chunkId": "[\\w-]+"
  },
  "files": [
    {
      "path": "*.<hash>.chunk.<chunkId>.js"
    },
    {
      "path": "*.<hash>.js"
    }
  ]
}
```

--------------------------------

### Configure BundleMon Report Output to GitHub

Source: https://github.com/lironer/bundlemon/blob/main/README.md

Configure BundleMon to report outputs to GitHub. Supports basic boolean flags or more granular control with specific string values like 'on-failure'.

```json
"reportOutput": ["github"]
```

```json
"reportOutput": [
    [
      "github",
      {
        "checkRun": false,
        "commitStatus": true,
        "prComment": true
      }
    ]
  ]
```

```json
"reportOutput": [
    [
      "github",
      {
        "checkRun": false, 
        "commitStatus": true, 
        "prComment": "on-failure"
      }
    ]
  ]
```

--------------------------------

### Configure GitHub Output

Source: https://github.com/lironer/bundlemon/blob/main/docs/output.md

Use the 'github' output plugin to create check runs, post commit statuses, and comments on your PRs. Default options are enabled unless overridden.

```json
"reportOutput": ["github"]
```

```json
"reportOutput": [
  [
    "github",
    {
      "checkRun": false,
      "commitStatus": true,
      "prComment": true
    }
  ]
]
```

--------------------------------

### Configure Custom Output

Source: https://github.com/lironer/bundlemon/blob/main/docs/output.md

Use the 'custom' output plugin to process results with your own JavaScript implementation. A 'path' to your JS file is required.

```json
"reportOutput": [
  [
    "custom",
    {
      "path": "custom-output.js"
    }
  ]
]
```

--------------------------------

### Configure JSON Output Plugin

Source: https://context7.com/lironer/bundlemon/llms.txt

Specify the 'json' output plugin and the output file name in your BundleMon configuration.

```json
{
  "reportOutput": [
    ["json", { "fileName": "dist/bundlemon-report.json" }]
  ]
}
```

--------------------------------

### BundleMon Path Labels Configuration

Source: https://github.com/lironer/bundlemon/blob/main/README.md

Configure BundleMon to handle hashed filenames by using '<hash>' as a placeholder. This allows BundleMon to track files whose names change with each build.

```json
"bundlemon": {
  "baseDir": "./build",
  "files": [
    {
      "path": "*.<hash>.chunk.js"
    },
    {
      "path": "*.<hash>.js"
    }
  ]
}
```

--------------------------------

### Save Bundle Size Snapshot for a Commit

Source: https://context7.com/lironer/bundlemon/llms.txt

This endpoint saves the bundle size snapshot for a specific commit. It requires project details, commit information, and file data. Authentication is handled via the `authType` query parameter.

```bash
curl -s -X POST \
  "https://api.bundlemon.dev/v1/projects/60a928cfc1ab380009f5cc0b/commit-records?authType=PROJECT_API_KEY&token=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ 
    "branch": "feat/reduce-bundle",
    "commitSha": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
    "baseBranch": "main",
    "prNumber": "42",
    "files": [
      {
        "path": "main.(hash).js",
        "pattern": "main.<hash>.js",
        "size": 153600,
        "compression": "gzip"
      }
    ],
    "groups": []
  }'

# Response
# {
#   "record": {
#     "id": "rec_newrecordid",
#     "projectId": "60a928cfc1ab380009f5cc0b",
#     "branch": "feat/reduce-bundle",
#     "commitSha": "a1b2c3d4...",
#     "creationDate": "2024-05-01T12:00:00.000Z",
#     "files": [...],
#     "groups": []
#   },
#   "baseRecord": {
#     "id": "rec_baserecordid",
#     "branch": "main",
#     ...
#   },
#   "linkToReport": "https://app.bundlemon.dev/projects/60a928cfc1ab380009f5cc0b/reports?commitRecordId=rec_newrecordid"
# }
```

--------------------------------

### Programmatic API — `bundlemon(config)`

Source: https://context7.com/lironer/bundlemon/llms.txt

The default export of the `bundlemon` package accepts a `Config` object and returns a `Promise<Report>`. It allows for programmatic control over bundle size checks.

```APIDOC
## Programmatic API — `bundlemon(config)`

### Description
The default export of the `bundlemon` package accepts a `Config` object and returns a `Promise<Report>`. It exits with status 1 if the report status is `"Fail"` when used via the CLI; in programmatic usage the caller decides what to do with the returned report.

### Usage
```typescript
import bundlemon from 'bundlemon';

async function checkBundleSize() {
  let report;
  try {
    report = await bundlemon({
      baseDir: './dist',
      defaultCompression: 'gzip',
      files: [
        { path: 'index.html',          maxSize: '2kb' },
        { path: 'main.<hash>.js',      maxSize: '200kb', maxPercentIncrease: 5 },
        { path: '**/*.chunk.<hash>.js', maxSize: '60kb' },
      ],
      groups: [
        { path: '**/*.js', friendlyName: 'Total JS', maxSize: '500kb' },
      ],
      reportOutput: [['json', { fileName: 'bundlemon-results.json' }]],
      verbose: true,
    });
  } catch (err) {
    console.error('BundleMon error:', err.message);
    process.exit(1);
  }

  // report.status: "Pass" | "Fail"
  // report.stats:  { currBranchSize, baseBranchSize, diff: { bytes, percent } }
  // report.files:  FileDetailsDiff[]  — per-file results including diff vs base
  // report.groups: FileDetailsDiff[]  — group results
  // report.metadata.linkToReport — URL to the online history report

  if (report.status === 'Fail') {
    const failing = report.files.filter((f) => f.status === 'Fail');
    for (const f of failing) {
      console.error(`FAIL ${f.path}: ${f.size} bytes, limit ${f.maxSize}`);
    }
    process.exit(1);
  }

  console.log('All bundle size checks passed!');
  console.log(`Total: ${report.stats.currBranchSize} bytes`);
  if (report.metadata.linkToReport) {
    console.log(`Report: ${report.metadata.linkToReport}`);
  }
}

checkBundleSize();
```

### Parameters
- `config` (Config): An object containing the configuration for BundleMon.
  - `baseDir` (string): The base directory for the files.
  - `defaultCompression` (string): The default compression type ('gzip', 'brotli', 'none').
  - `files` (Array<FileConfig>): An array of file configurations.
    - `path` (string): The path or glob pattern for the file.
    - `maxSize` (string): The maximum allowed size for the file (e.g., '2kb', '100b').
    - `maxPercentIncrease` (number, optional): The maximum allowed percentage increase in size.
  - `groups` (Array<GroupConfig>, optional): An array of group configurations.
    - `path` (string): The path or glob pattern for files in the group.
    - `friendlyName` (string): A friendly name for the group.
    - `maxSize` (string): The maximum allowed size for the group.
  - `reportOutput` (Array<ReportOutputConfig>): An array specifying the report output format and file name.
    - `format` (string): The output format ('json', 'html', 'markdown').
    - `fileName` (string): The name of the output file.
  - `verbose` (boolean, optional): Enables verbose logging.

### Returns
- `Promise<Report>`: A promise that resolves to a `Report` object.
  - `status` (string): The overall status of the report ('Pass' or 'Fail').
  - `stats` (object): Statistics about the bundle size comparison.
    - `currBranchSize` (number): The current branch size in bytes.
    - `baseBranchSize` (number): The base branch size in bytes.
    - `diff` (object): The difference in bytes and percentage.
      - `bytes` (number): The difference in bytes.
      - `percent` (number): The percentage difference.
  - `files` (Array<FileDetailsDiff>): Details for each file, including comparison results.
  - `groups` (Array<FileDetailsDiff>): Details for each group, including comparison results.
  - `metadata` (object): Metadata about the report.
    - `linkToReport` (string): URL to the online history report.
```

--------------------------------

### Max Percent Increase Configuration

Source: https://github.com/lironer/bundlemon/blob/main/docs/types.md

Set the maximum percentage increase allowed for matched files compared to the base branch. Values are represented as numbers.

```json
0.5
```

```json
4
```

```json
200
```

--------------------------------

### Test Packages with Yarn

Source: https://github.com/lironer/bundlemon/blob/main/CONTRIBUTING.md

Runs tests for the BundleMon packages. This is a crucial step to ensure code integrity.

```bash
yarn test-packages
```

--------------------------------

### BundleMon GitHub Output Plugin Options

Source: https://context7.com/lironer/bundlemon/llms.txt

Configure the GitHub output plugin for posting check runs, commit statuses, or PR comments. Each option can be set to 'true', 'false', 'always', 'on-failure', 'pr-only', or 'off'.

```json
// Full options — each field accepts: true | false | "always" | "on-failure" | "pr-only" | "off"
{
  "reportOutput": [
    [
      "github",
      {
        "checkRun": false,
        "commitStatus": true,
        "prComment": "on-failure"
      }
    ]
  ]
}
```

--------------------------------

### Max Size Configuration

Source: https://github.com/lironer/bundlemon/blob/main/docs/types.md

Define the maximum allowed size for matched files. Supports various units like bytes, kilobytes, and megabytes.

```json
"2000b"
```

```json
"20kb"
```

```json
"1mb"
```

--------------------------------

### Configure Custom Output Plugin

Source: https://context7.com/lironer/bundlemon/llms.txt

Use the 'custom' output plugin to provide a JavaScript function for handling report data. Specify the path to your custom script.

```json
{
  "reportOutput": [
    ["custom", { "path": "./scripts/bundlemon-custom-output.js" }]
  ]
}
```

--------------------------------

### List Commit Records for a Project

Source: https://context7.com/lironer/bundlemon/llms.txt

Retrieve a list of commit records for a given project. Supports filtering by branch and retrieving only the latest record.

```bash
curl -s "https://api.bundlemon.dev/v1/projects/60a928cfc1ab380009f5cc0b/commit-records?branch=main&latest=true"

# Response — array of CommitRecord objects sorted by creation date descending
# [
#   {
#     "id": "rec_latestmain",
#     "projectId": "60a928cfc1ab380009f5cc0b",
#     "branch": "main",
#     "commitSha": "deadbeef...",
#     "creationDate": "2024-05-01T10:00:00.000Z",
#     "files": [ ... ],
#     "groups": []
#   }
# ]
```

--------------------------------

### bundlemon-utils Text Utilities

Source: https://context7.com/lironer/bundlemon/llms.txt

Helper functions for formatting diff sizes and percent changes as human-readable strings, and producing a one-line report conclusion. Used by the console output plugin and the markdown report generator.

```APIDOC
## `bundlemon-utils` — Text Utilities

Helper functions for formatting diff sizes and percent changes as human-readable strings, and producing a one-line report conclusion. Used by the console output plugin and the markdown report generator.

```typescript
import { 
  getDiffSizeText,
  getDiffPercentText,
  getLimitsCellText,
  getReportConclusionText,
  Status,
  Compression,
  DiffChange,
} from 'bundlemon-utils';

console.log(getDiffSizeText(5120));    // "+5KB"
console.log(getDiffSizeText(-2048));   // "-2KB"
console.log(getDiffSizeText(0));       // "0B"

console.log(getDiffPercentText(1.45)); // "+1.45%"
console.log(getDiffPercentText(-3));   // "-3%"
console.log(getDiffPercentText(Infinity)); // "-"

// getLimitsCellText — formats limits for table display
const file = { 
  path: 'main.js', pattern: 'main.js', size: 153600,
  compression: Compression.Gzip, maxSize: 163840, maxPercentIncrease: 5,
  status: Status.Pass, diff: { bytes: 5120, percent: 1.45, change: DiffChange.Update },
};
console.log(getLimitsCellText(file)); // "160KB / +5%"

// getReportConclusionText — summary line used in CI output / GitHub comment
import { generateDiffReport } from 'bundlemon-utils';
const report = {
  ...generateDiffReport({ files: [file], groups: [] }),
  metadata: {},
};
console.log(getReportConclusionText(report));
// "+5KB +1.45% total files change"  (Pass)

// On failure:
const failingFile = { ...file, status: Status.Fail, failReasons: ['MaxSize'], maxSize: 102400 };
const failReport = { ...generateDiffReport({ files: [failingFile], groups: [] }, undefined), metadata: {} };
console.log(getReportConclusionText(failReport));
// 'Max size exceeded in file "main.js": 150KB > 100KB'
```
```

--------------------------------

### Custom Output Implementation

Source: https://github.com/lironer/bundlemon/blob/main/docs/output.md

Implement a custom output function in a JavaScript file. This function receives the report as a parameter and can be asynchronous.

```javascript
// Function that accepts generated report as parameter
const output = (report) => {
  console.log(report);
};

module.exports = output;
```

```javascript
module.exports = async (report) => {
  console.log(report);

  await writeToStorage(report);
};
```

--------------------------------

### Default Path Labels Configuration

Source: https://github.com/lironer/bundlemon/blob/main/docs/customPathLabels.md

This is the default configuration for path labels, which only includes the 'hash' label.

```json
{
  "pathLabels": {
    "hash": "[a-zA-Z0-9]+"
  }
}
```

--------------------------------

### File Path Patterns

Source: https://github.com/lironer/bundlemon/blob/main/docs/types.md

Specify relative paths to files using glob patterns. Supports single files, multiple files, and hashed filenames.

```json
"js/*.js"
```

```json
"**/*.css"
```

```json
"**/*.{js,css}"
```

```json
"**/*.<hash>.js"
```

--------------------------------

### BundleMon CI Environment Variables

Source: https://context7.com/lironer/bundlemon/llms.txt

Environment variables required for BundleMon to function correctly in CI environments, including remote history and GitHub output.

```bash
# --- Required for remote history (non-GitHub-Actions CIs) ---
export BUNDLEMON_PROJECT_ID="60a928cfc1ab380009f5cc0b"
export BUNDLEMON_PROJECT_APIKEY="your-secret-api-key"

# --- Required CI context (auto-set on GitHub Actions / Travis / Codefresh) ---
export CI=true
export CI_REPO_OWNER="LironEr"
export CI_REPO_NAME="bundlemon"
export CI_BRANCH="feat/my-feature"
export CI_COMMIT_SHA="a1b2c3d4e5f6..."
export CI_TARGET_BRANCH="main"     # only on pull requests
export CI_PR_NUMBER="42"           # only on pull requests
export CI_COMMIT_MESSAGE="feat: reduce vendor bundle"  # optional, needs includeCommitMessage: true

# --- GitHub output (required when NOT running in GitHub Actions) ---
export BUNDLEMON_GITHUB_TOKEN="ghp_..."

# --- Override service URL for self-hosted deployments ---
export BUNDLEMON_SERVICE_URL="https://bundlemon.my-company.com/api"

# --- Opt-out of remote service (local-only analysis) ---
export BUNDLEMON_REMOTE=false

# --- Override sub-project at runtime ---
export BUNDLEMON_SUB_PROJECT="web-dashboard"
```

--------------------------------

### Configure JSON Output

Source: https://github.com/lironer/bundlemon/blob/main/docs/output.md

Save raw results in a JSON file using the 'json' output plugin. You can specify a custom file name for the output.

```json
"reportOutput": ["json"]
```

```json
"reportOutput": [
  [
    "json",
    {
      "fileName": "fantastic-file-name.json"
    }
  ]
]
```

--------------------------------

### Monorepo Sub-project Configuration (web-app)

Source: https://context7.com/lironer/bundlemon/llms.txt

Configure BundleMon for a sub-project within a monorepo by specifying a unique 'subProject' name in its configuration file.

```json
// packages/web-app/bundlemon.config.json
{
  "baseDir": "./dist",
  "subProject": "web-app",
  "files": [
    { "path": "index.html", "maxSize": "2kb" },
    { "path": "main.<hash>.js", "maxSize": "200kb" }
  ],
  "reportOutput": ["github"]
}
```

--------------------------------

### Format Bundle Size and Percentage Differences

Source: https://context7.com/lironer/bundlemon/llms.txt

Use these functions to format numerical size and percentage differences into human-readable strings for display. Handles positive, negative, zero, and infinite values.

```typescript
import {
  getDiffSizeText,
  getDiffPercentText,
  getLimitsCellText,
  getReportConclusionText,
  Status,
  Compression,
  DiffChange,
} from 'bundlemon-utils';

console.log(getDiffSizeText(5120));    // "+5KB"
console.log(getDiffSizeText(-2048));   // "-2KB"
console.log(getDiffSizeText(0));       // "0B"

console.log(getDiffPercentText(1.45)); // "+1.45%"
console.log(getDiffPercentText(-3));   // "-3%"
console.log(getDiffPercentText(Infinity)); // "-"

// getLimitsCellText — formats limits for table display
const file = {
  path: 'main.js', pattern: 'main.js', size: 153600,
  compression: Compression.Gzip, maxSize: 163840, maxPercentIncrease: 5,
  status: Status.Pass, diff: { bytes: 5120, percent: 1.45, change: DiffChange.Update },
};
console.log(getLimitsCellText(file)); // "160KB / +5%"

// getReportConclusionText — summary line used in CI output / GitHub comment
import { generateDiffReport } from 'bundlemon-utils';
const report = {
  ...generateDiffReport({ files: [file], groups: [] }),
  metadata: {},
};
console.log(getReportConclusionText(report));
// "+5KB +1.45% total files change"  (Pass)

// On failure:
const failingFile = { ...file, status: Status.Fail, failReasons: ['MaxSize'], maxSize: 102400 };
const failReport = { ...generateDiffReport({ files: [failingFile], groups: [] }, undefined), metadata: {} };
console.log(getReportConclusionText(failReport));
// 'Max size exceeded in file "main.js": 150KB > 100KB'
```

--------------------------------

### BundleMon TypeScript Configuration Interface

Source: https://context7.com/lironer/bundlemon/llms.txt

The full TypeScript interface for the BundleMon configuration object, used when calling the programmatic API. Includes options for base directory, file/group specific limits, compression, output plugins, and monorepo settings.

```typescript
import bundlemon from 'bundlemon';
import type { Config } from 'bundlemon';

const config: Config = {
  // Directory containing build artifacts. Defaults to process.cwd().
  baseDir: './dist',

  // Per-file limits. Glob patterns supported.
  files: [
    {
      path: 'index.html',
      maxSize: '2kb',
      maxPercentIncrease: 5,
      compression: 'none',       // override default compression for this file
      friendlyName: 'HTML entry', // shown in reports
    },
    { path: 'static/js/main.<hash>.js', maxSize: '200kb' },
    { path: 'static/css/*.<hash>.css', maxSize: '30kb' },
  ],

  // Aggregated size across all matching files; same FileConfig shape.
  groups: [
    { path: 'static/js/**/*.js', friendlyName: 'Total JS', maxSize: '600kb' },
  ],

  // Compression applied before measuring. "gzip" | "brotli" | "none"
  defaultCompression: 'gzip',

  // Output plugins: "github" | "json" | "custom" or [name, options] tuple.
  reportOutput: ['github', ['json', { fileName: 'size-report.json' }]],

  // Monorepo: scope this run to a named sub-project.
  subProject: 'web-app',

  // Save commit message alongside the size record.
  includeCommitMessage: true,

  // Regex map for path label substitution (default: hash → [a-zA-Z0-9]+).
  pathLabels: {
    hash: '[a-zA-Z0-9]+',
    chunkId: '[\w-]+',
  },

  verbose: true,
};

// Programmatic usage — returns a Report object
const report = await bundlemon(config);
console.log(report.status);        // "Pass" | "Fail"
console.log(report.stats);         // { currBranchSize, baseBranchSize, diff: { bytes, percent } }
console.log(report.files);         // FileDetailsDiff[]
console.log(report.groups);        // FileDetailsDiff[]
console.log(report.metadata);      // { subProject, linkToReport, record, baseRecord }

```

--------------------------------

### Monorepo Sub-project Configuration (admin-app)

Source: https://context7.com/lironer/bundlemon/llms.txt

Configure BundleMon for another sub-project within a monorepo, using a different 'subProject' name.

```json
// packages/admin-app/bundlemon.config.json
{
  "baseDir": "./dist",
  "subProject": "admin-app",
  "files": [
    { "path": "index.html", "maxSize": "3kb" },
    { "path": "main.<hash>.js", "maxSize": "350kb" }
  ],
  "reportOutput": ["github"]
}
```