Docs WIP

docs/README.md

@@ -1,60 +1,54 @@
-# Overview:
-Run `bundlesize` in CI after you have finished building your production assets. Bundlesize will keep track of these files and alert you when they go over max size, or increase/decrease by a certain percentage (against say master). Bundlesize will post back to your Github pull request.
+# bundlesize
+[![npm][npm]][npm-url]
+[![bundlesize][bundlesize]][bundlesize-url]
+[![node][node]][node-url]
 
-# Getting Started
 
-- With NPM: `npm install @bundlesize/bundlesize --save-dev`
+## Overview:
+bundlesize is a file size checker. Its main purpose is to ensure bundled browser assets don't jump in file size.
 
-- With Yarn: `yarn add @bundlesize/bundlesize --dev`
+Sharp increases in bundlesize can signal something is wrong, for example:
+- added a package that bloated the slug
+- wrong import
+- forgot to minify
 
-- Usage Run: `bundlesize`
+Run `bundlesize` in CI after you have finished building your production assets.
+Bundlesize will keep track of these files and alert you when they go over max size, etc.
+Bundlesize will update status on your GitHub pull request, blocking builds that fail checks.
 
 
-# Configuring Bundlesize
-Bundlesize can read configuration from `.json`, `.js`, or your package.json file. To use `.json` or `.js`, supply the name on the command line `bundlesize --config .bundlesize.config.js`.
+## Installation
+- NPM: `npm install @bundlesize/bundlesize --save-dev`
+- Yarn: `yarn add @bundlesize/bundlesize --dev`
 
-Otherwise, omit this to have it look in the package.json under the bundlesize key, e.g. package.json.
 
-```json
-{
-	"name": "my package name",
-	"bundlesize" : "...actualBundleSizeConfig"
-}
-```
+## Basic Usage
+```bash
+$yarn run bundlesize --max-size 100kb ./webpack-build/*.js
 
+[WARNING] Some CI configuration options were not found (repoOwner, repoName, commitSha):
+    bundlesize will be unable to report build status, or save comparison data
+    Learn more at: http://bundlesize.io/#/getting-started/the-best-parts
 
-# Configuration Options
-## Node API
-
-```js
-const defaultConfig = {
-   files: [],
-   bundlesizeServiceHost: 'https://service.bundlesize.io', // Can be a custom service, or set to NUll
-   ci: {
-       githubAccessToken: ciEnv.githubAccessToken,
-       repoOwner: ciEnv.repoOwner,
-       repoName: ciEnv.repoName,
-       repoCurrentBranch: ciEnv.repoCurrentBranch,
-       repoBranchBase: ciEnv.repoBranchBase || 'master', // Branch PR is being merged into
-       commitSha: ciEnv.commitSha,
-       trackBranches: ['master', 'develop'],
-   },
-   defaultCompression: 'gzip',
-}
-```
+Result breakdown at: https://ja2r7.app.goo.gl/aDzEQjBVMXxrCgaa7
+
+PASS ./webpack-build/app.js: 30.71KB < 100KB (gzip)
+FAIL ./webpack-build/vendor.js: 198.6KB > 100KB (gzip)
 
-## Command Line Params
-
-```js
-program
-   .usage('[options] <filePathGlobs ...>')
-   .option(
-       '--config [configFilePath]',
-       'file to read configuration from, if used all options are blown away',
-   )
-   .option('--max-size [maxSize]', 'maximum size threshold (e.g. 3kb)')
-   .option(
-       '--compression [compression]',
-       'specify which compression algorithm to use',
-   )
+bundlesize FAIL
+maxSize check failed
 ```
+Above bundlesize is just running the files through a maxSize check, this is the most basic usage of bundlesize.
+
+Bundlesize can do alot more than this, [check out the-best-parts of bundlesize](getting-started/the-best-parts.md).
+
+
+
+[npm]: https://img.shields.io/npm/v/@bundlesize/bundlesize.svg
+[npm-url]: https://npmjs.com/package/@bundlesize/bundlesize
+
+[node]: https://img.shields.io/node/v/@bundlesize/bundlesize.svg
+[node-url]: https://nodejs.org
+
+[bundlesize]: https://img.shields.io/badge/bundlesize-checked-green.svg
+[bundlesize-url]: http://bundlesize.io

docs/_coverpage.md

@@ -9,6 +9,6 @@
 * Block builds when files get too big
 
 [GitHub](https://github.com/bundlesize/bundlesize)
-[Get Started](#getting-started)
+[Get Started](#bundlesize)
 
 ![color](linear-gradient(to left bottom, #b3c8ff 0%,#fffcb3 100%))

docs/_sidebar.md

@@ -1,23 +1,14 @@
 * Getting started
-
-  * [Quick start](getting-started/quickstart.md)
+  * [Getting Started](README.md)
   * [The Best Parts](getting-started/the-best-parts.md)
 
 * Usage
-  * [CLI](getting-started/cli.md)
-  * [Node API <sup style="color:red">(new)<sup>](getting-started/node.md)
+  * [CLI](apis/cli.md)
+  * [NodeJS API <sup style="color:red">(new)<sup>](apis/nodejs.md)
 
 * Configuration
-
-  * [Watching Files](configuration/files.md)
-  * [Pull Request/Build Status](configuration/build-status.md)
-  * [Build Comparisions/Histogram](configuration/build-comparisons.md)
-
-* Guides
-  * [Setting up with CircleCI + Webpack](guide/circle-webpack.md)
-
-* Advanced Configuration
+  * [Configuration](configuration/configuration.md)
   * [Custom Server <sup style="color:red">(new)<sup>](configuration/custom-server.md)
 
-
-* [GitHub](https://github.com/bundlesize/bundlesize)
+* Guides
+  * [Setting up with CircleCI + Webpack](guides/circleci-webpack.md)

docs/apis/cli.md

@@ -0,0 +1,26 @@
+## Command Line Params
+
+```bash
+$yarn add @bundlesize/bundlesize --dev
+$yarn bundlesize --help
+
+  Usage: bundlesize [options] <filePathGlobs ...>
+
+  Options:
+
+    --config [configFilePath]    file to read configuration from, if used all options are blown away
+    --max-size [maxSize]         maximum size threshold (e.g. 3kb)
+    --compression [compression]  specify which compression algorithm to use
+    -h, --help                   output usage information
+
+  Examples:
+
+   Read configuration from package.json
+     $ bundlesize
+
+   Read configuration from file
+     $ bundlesize --config internals/bundlesize.config.js
+
+   Use command line
+     $ bundlesize --max-size 100KB ./src/*.js /lib/*.js
+```

docs/apis/nodejs.md

@@ -0,0 +1,60 @@
+# NodeJS Api
+The API can be used as below, for detail information on the different params, [see configuration](configuration/configuration.md)
+
+```js
+import bundlesize from '@bundlesize/bundlesize'
+
+const results = await bundlesize({
+   files: [{
+       path: './myfolder/*.js',
+       maxSize: '100kb',
+       compression: 'none',
+   }],
+   bundlesizeServiceHost: 'https://service.bundlesize.io', // Can be a custom service, or set to NUll
+   ci: {
+       githubAccessToken: ciEnv.githubAccessToken,
+       repoOwner: ciEnv.repoOwner,
+       repoName: ciEnv.repoName,
+       repoCurrentBranch: ciEnv.repoCurrentBranch,
+       repoBranchBase: ciEnv.repoBranchBase || 'master', // Branch PR is being merged into
+       commitSha: ciEnv.commitSha,
+       trackBranches: ['master', 'develop'],
+   },
+   defaultCompression: 'gzip',
+})
+
+
+console.log(results)
+// Outputs:
+{ status: 'fail',
+    fullResults:
+    [
+        {
+            filePath: './myfolder/test-file-1.jpg',
+            message: '30.71KB < 100KB (gzip)',
+            status: 'pass',
+            size: 31448,
+            baseBranchSize: 0,
+            maxSize: 102400
+        },
+        {
+            filePath: './myfolder/test-file-2.jpg',
+            message: '198.6KB > 100KB (gzip)',
+            status: 'fail',
+            size: 203368,
+            baseBranchSize: 0,
+            maxSize: 102400
+        }
+    ],
+    summary: 'maxSize check failed',
+    url: 'https://ja2r7.app.goo.gl/FJR3Rx1EdC1QjAii1'
+}
+
+
+// Status strings can also be accessed from the api
+// import { STATUSES } from '@bundlesize/bundlesize'
+console.log(result.status === STATUES.FAIL)
+
+```
+
+An example usage of Node API can be seen in the bundlesizeCLI: https://github.com/bundlesize/bundlesize/blob/master/src/bin/index.js#L43

docs/configuration/configuration.md

@@ -0,0 +1,87 @@
+# Configuring Bundlesize
+The [bundlesize CLI](apis/cli.md) can read configuration from `.json`, `.js`, or your package.json file.
+To use `.json` or `.js`, supply the name on the command line `bundlesize --config .bundlesize.config.js`.
+
+Otherwise, omit this to have it look for the `bundlesize` key in the `package.json`, e.g.
+
+```json
+{
+	"name": "my package name",
+	"version": "0.0.1",
+	"bundlesize" : {
+	    "files": [
+	        {
+	            "path": "myfolder/*.js",
+	            "maxSize": "100kB"
+	        }
+        ]
+	}
+}
+```
+
+Alternatively supply the config directly to the [Node JS API](apis/nodejs.md)
+
+# Bundlesize Configuration
+## Complete Configuration
+The only required config is the `files` array, with at least one `path`.
+`myconfig.js`
+```js
+const bundlesizeConfig = {
+   files: [{
+       path: './myfolder/*.js',
+       maxSize: '100kb',
+       compression: 'none',
+   }],
+   bundlesizeServiceHost: 'https://service.bundlesize.io', // Can be a custom service, or set to NUll
+   ci: {
+       githubAccessToken: ciEnv.githubAccessToken,
+       repoOwner: ciEnv.repoOwner,
+       repoName: ciEnv.repoName,
+       repoCurrentBranch: ciEnv.repoCurrentBranch,
+       repoBranchBase: ciEnv.repoBranchBase || 'master', // Branch PR is being merged into
+       commitSha: ciEnv.commitSha,
+       trackBranches: ['master', 'develop'],
+   },
+   defaultCompression: 'gzip',
+}
+
+module.exports = bundlesizeConfig
+
+```
+
+## The `files` Array
+Each `file` in the array is as follows
+```js
+{
+   path: './myfolder/*.js', // Required
+   maxSize: '100kb',
+   compression: 'none',
+}
+
+```
+`path` is a glob for a single file, or a set of files.
+`maxSize` is optional, but defaults to Infinity, this should be set to a string of the maxSize, e.g. '100KB'
+`compression` is optional, and defaults to `gzip`. This string must be one of `gzip`, `brotli` or `none`
+
+
+## The `ci` object
+This object, enables lots of the really cool features of bundlesize.
+// TODO: EXPAND ON THIS
+```js
+{
+    githubAccessToken: ciEnv.githubAccessToken,
+    repoOwner: ciEnv.repoOwner,
+    repoName: ciEnv.repoName,
+    repoCurrentBranch: ciEnv.repoCurrentBranch,
+    repoBranchBase: ciEnv.repoBranchBase || 'master', // Branch PR is being merged into
+    commitSha: ciEnv.commitSha,
+    trackBranches: ['master', 'develop'],
+}
+```
+
+
+## bundlesizeServiceHost
+This can be modified if you wish to use a [custom server](configuration/custom-server.md).
+
+
+

docs/configuration/custom-server.md

@@ -0,0 +1,16 @@
+# Using a Custom server with bundlesize
+Fork:
+https://github.com/bundlesize/service
+And spin up your own instance somewhere
+
+Then update your configuration to include your server location:
+```js
+module.exports = {
+   files: [...],
+   bundlesizeServiceHost: 'https://bundlesize.example.com',
+}
+```
+
+
+
+