sethbattin/bundle-report

Side-development for the forkee; more betterer features

Keep your bundle size in check

 

minimal setup

npm install bundle-report --save-dev

 

usage

Add it to your scripts in package.json

"scripts": {
  "test": "bundle-report"
}

 

Or you can use npx with NPM 5.2+.

npx bundle-report

configuration

Specify configuration through any method below. Files may be yaml, json, or js modules, and package.json may contain an object.

1. Specify cli option --config [file name] to point at any config file.
2. Create a config file ".bundlereport.rc" (see the exmaple in src/default.bundlereport.rc)
3. Specify package.json key "bundleReport" with a string config file path.
4. Add a settings object in package.json under key "bundleReport".
5. Specify property "config" in the object at package.json

Basic Settings

{
  "name": "your cool library",
  "version": "1.1.2",
  "bundleReport": {
    "files": [
      {
        "path": "./dist.js",
       "maxSize": "3 kB"
      } 
    ]
  }
}

globs

bundle-report also supports glob patterns

This makes it great for using with applications that are bundled with another tool. It will match multiple files if necessary and create a new row for each file.

{
  "bundleReport": {
    "files": [
      {
        "path": "./dist/vendor-*.js",
        "maxSize": "3 kB"
      },
      {
        "path": "./dist/chunk-*.js",
        "maxSize": "3 kB"
      }
    ]
  }
}

named output

Some bundle files may contain irrelevant path info, or simply be too long, or contain hashes (which prevents comparing built-to-build). There are two ways to specify another name for the file. For more examples, see this project's package.json.

1. Each item in the files option may contain a name property. For globs with multiple entries, this name will receive a numeral suffix

{
  "bundleReport": {
    "files": [
      {"path": "webpack-with-hash*.js", "maxSize": "3KB", "name": "webpack"}
    ]
  }
}

2. You may specify a replace pattern for substring or regex replacement. The pattern may be specified at the top level config or for each entry in 'files'. The replacement will be applied to the path of the file (after glob expansion), and the result will become the name property for that file. (name is superceded by replace)

The replace options requires two properties, pattern and replacement. These properties become the first and second argument to String.prototype.replace. If pattern contains an array, then its first element and optional second element are passed as arguments to new RegExp. (This permits RegExp via package.json or yaml strings. If you use a module as configuration in progress, then you may specify a RegExp directly, as well as a function for the replacement property)

This example uses a regular expression to name each file starting with re, and removes its path and file extension.

{
  "bundleReport": {
    "files": [
      {
        "path": "./src/re*.js",
        "maxSize": "2KB",
        "replace": {
          "pattern": ["\\./src/(.*)\\.js"],
          "replacement": "$1"
        }
      }
    ]
  }
}

2) build status

Bundle report uses the storage server of its fork source, bundlesize. (Old references still exist.) buildsize hosts a server store that both 1.) uses the Github Status API to mark commits and PRs, and 2.) saves the results from the previous build, if that build is "master". bundle-report allows this storage to apply to any branch name via the baseBranch config option. The ability to check against any merge target is on the TODO list.

To use the size comparison (via bundlesize):

• Authorize bundlesize for status access, copy the token provided.
• Add this token as BUNDLESIZE_GITHUB_TOKEN as environment parameter in your CIs project settings.

Currently works for Travis CI, CircleCI, Wercker, and Drone.

 

CLI

example usage:

bundle-report -f "dist/*.js" -s 20kB

For more granular configuration, we recommend configuring it in the package.json (documented above).

TODO

• Work with other CI tools (AppVeyor, etc.)
• Automate setup (setting env_var)

 

similar projects

• bundlesize - This repo's fork source
• BuildSize - GitHub App, no manual configuration required
• travis-weigh-in - Uses Python rather than Node.js
• size-limit - Uses webpack, builds your files for you.

license

MIT © sethbattin

bundle-report's Issues

Add a script to send a failure to the status API

The script bundle-report-init sends an "in-progress" status to the current CI commit, so that it appears as a placeholder. This is useful for when the build takes a long time, so that the status is present before the build finishes.

If the build fails, we want to mark this status as failed, but currently there is no entry point for that. We should add one

failed checks send incomplete data; status link leads to an error page

When the build size is exceeded, the error handling causes incomplete data to be generated. This causes an invalid status link, which looks like a server error on the bundle-size storage app.

Revise error handling so that complete data is generated and the links work even for failed checked.

Add short names for the file names

Our bundle file names include the webpack hash. We use globs to specify which files are checked. But the output is based on the full name. This takes up too much space with unhelpful information. It also makes comparing builds difficult.

We want to allow the reported file name to be a shorter version. Some kind of filter pattern for all files or for specific entries. This shorter name should be used in the report output and data. Something like this:

"./build/assets/vendor-0b7ec4eebf367780b1a3.bundle.js" => "vendor"
"./build/assets/healthCheck.0b7ec4eebf367780b1a3.js" => "healthCheck"

Replace eslint and plugins with prettier

I have seen eslint-plugin-standard and eslint-plugin-prettier conflict with each other. We also have prettier as a dev dependency.

prettier can do all the jobs. let's purge eslint and kin.

cover config files in the npm pack test script

When running npm pack, a script runs to exercise the build to assure it works. https://github.com/sethbattin/bundle-report/blob/parallel-dev/scripts/testPack.sh

This script failed to detect the lack of the js-yaml lib that was resolved in https://github.com/sethbattin/bundle-report/releases/tag/v1.2.1

The pack script should run using all the configuration options to assure every one is functional.

test bin scripts

Add tests to excerise the CLI. Perhaps use the execa lib, as described in siddharthkp#112

replace github-build package with node-github

Currently this lib adds builds status via github-build, which does exactly one task. It can POST a status to a specific repo/ref using a token. It also doesn't support github enterprise, which is an unresolved issue, siddharthkp/github-build#5. Some other people have already written a replacement from scratch, which is feasible because the lib is so simple.

But instead of reinventing the wheel, we could use an existing system.

We should replace it with a wrapper of node-github. That will let us other API methods (e.g. GET status), as well as allow github enterprise to work.

NPM publish

The tarball experiment seems to have worked, so it's public npm time.

Add configuration via file

Feature

In addition to the CLI options and the package.json object, we should permit loading a configuration file.

• Open-ended configuration
• Tidy package.json
• Clean CLI
• Settings in version control

Requirements

Comments welcome :)

1. In the absence of any CLI arg or package.json setting, we should check for a default config file such as .bundlesize.rc.
2. Create an in-repo default config, and use that in place of hardcoding the defaults into config.
3. The CLI should accept a -c, --config [config] option and try to read it (also format inferred or agnostic).
4. Check if package.json's bundlesize key is a string, and if so try it as a file path.
5. Check the bundlesize object property in package.json for a key 'config'. If there are other config settings there, merge the file settings over the package.json settings (allows local overrides)

File format

Any of these:

• JS module
• JSON
• yaml
• other?

I vote for being format agnostic. If the file name extension isn't obvious, we should try/catch js and json via require, yaml via a yml loader, and {other} via whatever is appropriate. If we're taking a customer's file and parsing it, we can try to guess correctly based on extension and save a few caught exceptions.

Add a comment bot

Put the build results into the PR comment thread. We'd like to see the current build compared to the target branch. Something like:

Bundle	target ref	PR branch	delta	limit	❔
main.js	20kb	19kb	-1kb	25kb	✅
vendor.js	50kb	52kb	+2kb	55kb	⚠️
healthCheck.js	5kb	9kb	+4kb	8kb	❌

The existing statuses have json data containing the results for branches. We might be able to sample that to create the table. #9 might be a prerequisite for this, so that the names have something reliable to compare build-to-build.