metafile-codecov-bundle

Convert bun or esbuild metafile output to Codecov bundle analysis format.

Both bun and esbuild produce an identical metafile JSON format describing the build. This package transforms that into Codecov's v3 bundle analysis payload and can upload it directly using GitHub Actions OIDC.

Installation

bun add -d metafile-codecov-bundle
# or
npm install -D metafile-codecov-bundle

CLI usage

Generate a metafile during your build, then convert it:

# bun
bun build --outdir=dist --metafile=metafile.json ./src/index.ts
metafile-codecov -f metafile.json -n my-app --bundler-name bun --bundler-version 1.2.0

# esbuild
esbuild src/index.ts --bundle --outdir=dist --metafile=metafile.json
metafile-codecov -f metafile.json -n my-app --bundler-name esbuild --bundler-version 0.24.0

The Codecov JSON is written to stdout. To write to a file instead:

metafile-codecov -f metafile.json -n my-app -o codecov-bundle-stats.json

Options

| Flag | Short | Description | | ----------------------- | ----- | ---------------------------------------------------- | | --metafile <path> | -f | Path to metafile JSON (required) | | --bundle-name <name> | -n | Bundle name for Codecov (required) | | --output-dir <dir> | | Build output directory for gzip size calculation | | --bundler-name <name> | | Bundler name (default: bun) | | --bundler-version <v> | | Bundler version | | --output <path> | -o | Write output to file instead of stdout | | --upload | | Upload bundle stats to Codecov (GitHub Actions OIDC) | | --help | -h | Show help | | --version | -v | Show version |

When --output-dir is provided, gzip sizes are computed by reading the actual output files from disk. Without it, gzipSize will be null.

Programmatic API

import { readFileSync, writeFileSync } from "node:fs";
import { transformMetafile } from "metafile-codecov-bundle";

const metafile = JSON.parse(readFileSync("metafile.json", "utf-8"));
const payload = transformMetafile(metafile, {
	bundleName: "my-app",
	outputDir: "dist",
	bundler: { name: "bun", version: "1.2.0" },
});

writeFileSync("codecov-bundle-stats.json", JSON.stringify(payload));

transformMetafile(metafile, options)

Transforms a bun/esbuild metafile into a Codecov OutputPayload.

The metafile parameter accepts the Metafile type exported by this package. It is also compatible with esbuild's Metafile type from the esbuild package.

| Option | Type | Description | | ------------ | ----------------------------------- | ------------------------------------------------------------ | | bundleName | string | Name for this bundle in Codecov (required) | | outputDir | string | Directory containing build output files for gzip calculation | | bundler | { name: string; version: string } | Bundler metadata | | builtAt | number | Unix timestamp in ms (defaults to Date.now()) | | duration | number | Build duration in ms |

Upload to Codecov

Built-in upload (OIDC)

The --upload flag uploads bundle stats directly to Codecov using GitHub Actions OIDC authentication. No token required — the workflow must have id-token: write permission.

permissions:
  id-token: write

steps:
  - name: Build
    run: bun build --outdir=dist --metafile=metafile.json ./src/index.ts

  - name: Upload bundle stats
    run: bunx metafile-codecov-bundle -f metafile.json -n my-app --upload

Programmatic upload

import { fetchOidcToken, getServiceParams, uploadBundleStats } from "metafile-codecov-bundle";

const result = await uploadBundleStats({
	payload: JSON.stringify(codecovPayload),
	oidcToken: await fetchOidcToken(),
	serviceParams: getServiceParams(),
});

How it works

The metafile contains inputs (source modules) and outputs (bundled files). These map to Codecov's payload as follows:

| Metafile | Codecov | Mapping | | --------- | --------- | ----------------------------------------------------- | | outputs | assets | File name, byte size, gzip size, hash-normalized name | | outputs | chunks | Entry detection, dynamic imports, file associations | | inputs | modules | Module path, byte size, chunk membership |

Source map files (.map) are excluded. Asset filenames containing 8+ hex character hashes are normalized (e.g., main-2c458a0c.js becomes main-*.js) for stable cross-build comparison.

License

MIT