Bundle Analyzer Quick Start

If you do not use a standard bundler in your production build (e.g., Webpack, Rollup, etc.), but still wish to utilize Codecov's Bundle Analysis capabilities, your options are described below.

The bundle-analyzer walks through the specified file tree(s), composes a report in the expected Codecov format, and then calls the necessary APIs to upload the report to Codecov.

Thebundle-analyzer is expected to run within a Supported CI Provider environment to pick up information about the build context (commitSha, branch, etc.) to populate the report, as well as the secret needed to call Codecov's APIs. Supported secrets to Codecov's APIs include the uploadToken (can be either repository token or org token), tokenless, or OIDC.

Below are instructions to incorporate the bundle-analyzer package into your project.

Install the @codecov/bundle-analyzer to your project.

npm install @codecov/bundle-analyzer --save-dev

yarn add @codecov/bundle-analyzer --dev

pnpm add @codecov/bundle-analyzer --save-dev

Import the bundler-analyzer library, compose the values for the options, and invoke the createAndUploadReport utility.

const { createAndUploadReport } = require("@codecov/bundle-analyzer");

const buildDirs = ["/absolute/or/relative/path/to/build"];

const coreOpts = {
  dryRun: true,
  uploadToken: "your-upload-token",
  retryCount: 3,
  apiUrl: "https://api.codecov.io",
  bundleName: "@codecov/example-bundle-analyzer-cjs",
  enableBundleAnalysis: true,
  debug: true,
};

const bundleAnalyzerOpts = {
  beforeReportUpload: async (original) => original,
  ignorePatterns: ["*.map"],
  normalizeAssetsPattern: "[name]-[hash].js",
};

createAndUploadReport(buildDirs, coreOpts, bundleAnalyzerOpts)
  .then((reportAsJson) =>
    console.log(`Report successfully generated and uploaded: ${reportAsJson}`),
  )
  .catch((error) =>
    console.error("Failed to generate or upload report:", error),
  );

Below is an example of the script being invoked by a build step.

In the package.json:

{
  ...
  "scripts": {
    "build": "<your-other-commands> && node analyze.js" // analyze.js is the name of the example script file above
  },
  ...
}

In the Actions workflow:

steps:
  - name: Build app for production
    env:
      BUNDLE_ANALYZER_UPLOAD_TOKEN: ${{ secrets.CODECOV_ORG_TOKEN }}
    run: pnpm run build

Codecov requires at least one commit to be made to properly upload bundle analysis information.

git add -A && git commit -m "Add Codecov bundler plugin" && git push

When invoking the relevant build step, the new script will create and upload the stats information to Codecov.

npm run build

yarn run build

pnpm run build