GitBook: [master] 17 pages and 8 assets modified

Author: jondavidjohn

.gitbook/assets/2018-11-20-at-5.10-pm.png

@@ -0,0 +1,2 @@
+# packtracker.io documentation
+

.gitbook/assets/2019-03-04-at-10.27-am.png

@@ -0,0 +1,19 @@
+# Table of contents
+
+* [packtracker.io documentation](README.md)
+* [Creating your first project](creating-your-first-project.md)
+* [Uploading your webpack stats](uploading-your-webpack-stats/README.md)
+  * [GitHub Action](uploading-your-webpack-stats/github-actions.md)
+  * [CircleCI Orb](uploading-your-webpack-stats/circleci-orb.md)
+  * [Webpack Plugin](uploading-your-webpack-stats/webpack-plugin.md)
+  * [Command Line Interface](uploading-your-webpack-stats/with-our-cli.md)
+  * [Common App Platforms](uploading-your-webpack-stats/common-app-platforms/README.md)
+    * [Laravel Mix](uploading-your-webpack-stats/common-app-platforms/laravel-mix.md)
+    * [Webpacker \(with Rails\)](uploading-your-webpack-stats/common-app-platforms/webpacker-with-rails.md)
+    * [Create React App](uploading-your-webpack-stats/common-app-platforms/create-react-app.md)
+* [GitHub Pull Request Checks](github-pull-request-checks/README.md)
+  * [Performance Budgets](github-pull-request-checks/performance-budgets.md)
+  * [Forked Repositories](github-pull-request-checks/forked-repositories.md)
+* [Managing your team](managing-your-team.md)
+* [FAQ](faq.md)
+

.gitbook/assets/github-check.png

@@ -0,0 +1,10 @@
+# Creating your first project
+
+### Create an Organizaiton
+
+In order to get started tracking your webpack build stats, you need to create an organization to house your team and projects.  Anyone invited to your organization will be able to see and interact with any projects created by your organization.
+
+### Create your project
+
+Once you have an organization set up, you are ready to create your first project.  Projects provide you a space to visualize your webpack asset history allowing you to keep track of the assets you are delivering to your users.  Once you have created your project you will have access to the `project_token` on your project settings page. This token is what identifies your project when uploading to packtracker.
+

.gitbook/assets/github-checks.png

@@ -0,0 +1,40 @@
+# FAQ
+
+## Do you have access to my source code?
+
+No, [the way we gather your webpack stats is entirely open source and open for inspection](https://github.com/packtracker/webpack-plugin).  We filter out your source code specifically.
+
+We also do not request source code access through our GitHub App integration.
+
+## Can I upload my stats from my local development environment?
+
+Yes, **this is possible** though we don't recommend it.
+
+Any run of your webpack build process in which our plugin has `upload` set to  `true` will send your stats to our service.
+
+We recommend setting your process up to upload your stats in an automated way when you push your code.  Generally this is done either:
+
+* In a CI environment
+* In your deployment process
+
+This ensures that your not creating a lot of noise in your asset metrics, and allows everyone on your team to take advantage of the tool without additional training and manual intervention.
+
+## Why can't the plugin determine my branch name?
+
+Our webpack plugin uses the local git checkout to query against to determine the branch name.  Commonly in CI environments this query comes back as `HEAD` which doesn't quite give us the information we want.
+
+When this is the case the plugin will thrown an error informing you of this **\(as of version `1.2.0`\)**. In this case you need to provide the branch name as either [a plugin configuration or environment variable](https://github.com/packtracker/webpack-plugin#options).  In most CI environments there is an environment variable available to you to pass along to the plugin.  For example, in CodeShip this environment variable is called `CI_BRANCH`, and you would pass it along to us like so:
+
+```javascript
+const PacktrackerPlugin = require('@packtracker/webpack-plugin')
+​
+module.exports = {
+  plugins: [
+    new PacktrackerPlugin({
+      project_token: '<your packtracker project token>',
+      branch: process.env.CI_BRANCH,
+    })
+  ]
+}
+```
+

.gitbook/assets/github-status (1).png

@@ -0,0 +1,41 @@
+---
+description: >-
+  Use our GitHub Checks integration to see the real time effects of your asset
+  changes on a per pull request basis and establish performance budgets for your
+  asset profile.
+---
+
+# GitHub Pull Request Checks
+
+## A note on using automation
+
+In order for this integration to run smoothly, we assume you are using a CI/CD service to perform your webpack build and [report your build stats](https://docs.packtracker.io/uploading-your-webpack-stats).
+
+If you are not utilizing a CI environment to run your webpack builds and report your stats, we suggest starting there first.  Integrating your project with a provider that runs your build every time you push, provides a consistent basis to perform these checks.
+
+Make sure you're uploading your stats for every push, not only pull requests.  We need stats for both the last commit of the branch you're merging into, as well as the head of the pull request branch in order to provide you with details of the difference between the two.
+
+## Setting up GitHub Checks
+
+![](../.gitbook/assets/github-status%20%281%29.png)
+
+### Connecting to GitHub
+
+First visit the **"GitHub Checks"** tab from your project overview page. 
+
+From there you should see an option to connect your user account with your GitHub user account.  Once you complete this process, you will then see the option to select which repository you want us to report Checks to.
+
+Initially you will not see any repositories because you have not installed our GitHub App yet.  When you open the repository drop down you should see a link suggesting that you install our GitHub App.  While installing our GitHub App, be sure to provide us with access to the repository you ware wanting to attach to your packtracker project.
+
+Once you have installed the app and selected it from the dropdown, save your project settings.  This should get webhooks flowing.
+
+### When does it report?
+
+We will report asset changes on all your pull requests, taking a previously calculated base commit and comparing it with the latest commit on your pull request.
+
+Once you open and/or push to a pull request, you should see our in progress checks show up.  Once we have calculated your stats for both the base and latest commit on your branch, they will show up as completed.
+
+![](../.gitbook/assets/github-checks.png)
+
+
+

.gitbook/assets/github-status.png

@@ -0,0 +1,36 @@
+# Forked Repositories
+
+### My checks are stuck "in progress"!
+
+Many CI providers \(like TravisCI\) run pull request build jobs on the merged result of the base and head commit.  This is **great** because you get to test the _result_ of the pull request, not only it's current state.
+
+The problem this creates for us, is that because we try \(by default\) to glean the head commit SHA by running something like `git rev-parse --short HEAD`, we end up getting the merge commit SHA instead of most recent commit SHA of the pull request.
+
+In order to report your data to the SHA we expect, most CI providers have environment variables that provide the data we need.  We can adjust our configuration to look to those variables for the data we want.
+
+For example, TravisCI provides not only `TRAVIS_BRANCH` but also `TRAVIS_PULL_REQUEST_BRANCH`
+
+The difference is subtle, but important \(from the TravisCI documentation\)
+
+> `TRAVIS_BRANCH`:
+>
+> * for push builds, or **builds not triggered by a pull request**, this is the name of the branch.
+> * **for builds triggered by a pull request** this is the name of the branch targeted by the pull request.
+
+> `TRAVIS_PULL_REQUEST_BRANCH`:
+>
+> * **if the current job is a pull request**, the name of the branch from which the PR originated.
+> * if the current job is a push build, this variable is empty \(`""`\).
+
+This distinction also extends to the way Travis exposes their commit SHA, so to correctly report your packtracker information to your forked pull requests, configure your plugin similarly as follows
+
+```javascript
+new PacktrackerPlugin({
+  branch: process.env.TRAVIS_PULL_REQUEST_BRANCH || process.env.TRAVIS_BRANCH,
+  commit: process.env.TRAVIS_PULL_REQUEST_SHA || process.env.TRAVIS_COMMIT,
+}),
+
+```
+
+And in this way, we can apply your build stats against the head commit of your pull request resulting in the correct reporting for forked pull requests.
+

.gitbook/assets/screen-shot-2018-11-20-at-5.12.39-pm.png

@@ -0,0 +1,16 @@
+# Performance Budgets
+
+As part of our Github Checks integration, you can set up performance budgets for both your **total asset output size** and on a **per asset basis**.
+
+This means you can have both an upper limit for your total asset footprint, and also make sure your individual assets are beneath the threshold you configure.  When either of these limits are exceeded, we will fail the offending pull request with detailed information.
+
+### Setting up your performance budgets
+
+Performance budgets can be configured within the Project settings.
+
+A budget of 0 will disable the budget checks.
+
+![Navigate to your project settings](../.gitbook/assets/2018-11-20-at-5.10-pm.png)
+
+![](../.gitbook/assets/2019-03-04-at-10.27-am.png)
+

.gitbook/assets/screen-shot-2019-05-01-at-11.54.58-am.png

@@ -0,0 +1,31 @@
+---
+description: Permissions and Roles
+---
+
+# Managing your team
+
+Inviting members to your organization
+
+Once you have created your organization, you can access your team management feature through the **People** tab on your organization overview page.  On this page you will be able to see existing members, see outstanding invitations, and send out new invitations.
+
+When inviting a team member \(and managing existing members\), we have 3 levels of access for you to choose from.
+
+* Owner
+* Admin
+* Contributor
+
+| Capability | Owner | Admin | Contributor |
+| :--- | :--- | :--- | :--- |
+| View Private Projects | ✅ | ✅ | ✅ |
+| Create Projects | ✅ | ✅ | 🚫 |
+| Modify Project Settings | ✅ | ✅ | 🚫 |
+| Delete Projects | ✅ | ✅ | 🚫 |
+| Invite new members | ✅ | ✅ | 🚫 |
+| Modify Organization Settings | ✅ | 🚫 | 🚫 |
+| Modify Organization Subscription | ✅ | 🚫 | 🚫 |
+| Delete the Organization | ✅ | 🚫 | 🚫 |
+| Modify Member Roles | ✅ | 🚫 | 🚫 |
+| Revoke membership from the Organization | ✅ | 🚫 | 🚫 |
+
+
+

README.md

@@ -0,0 +1,18 @@
+# Uploading your webpack stats
+
+There are a few requirements that enable you to take advantage of the core packtracker experience:
+
+* Usage of [webpack](https://webpack.js.org/) 2, 3, or 4
+* Node 6.14.4+
+* Usage of `git` for source control
+
+{% page-ref page="github-actions.md" %}
+
+{% page-ref page="circleci-orb.md" %}
+
+{% page-ref page="webpack-plugin.md" %}
+
+{% page-ref page="with-our-cli.md" %}
+
+{% page-ref page="common-app-platforms/" %}
+

SUMMARY.md

@@ -0,0 +1,82 @@
+---
+description: >-
+  CircleCI Orbs are reusable bits of configuration, we've combined this with a
+  standard Docker image to provide a turn key solution for CircleCI users.  No
+  need to modify your project at all.
+---
+
+# CircleCI Orb
+
+{% hint style="warning" %}
+In order to use the CircleCI Orb, you must first opt-in your organization to allow third party orbs within your Organization Security settings.  
+  
+You can do this by going to **Settings** > **Organization** > **Security**
+{% endhint %}
+
+Next, you will add our orb to your configuration by declaring it in your CircleCI configuration.
+
+```yaml
+version: 2.1
+
+orbs:
+  packtracker: packtracker/[email protected]
+```
+
+{% hint style="info" %}
+ If you started using CircleCI prior to 2.1, you must enable pipelines within your project configuration to be able to use the `orbs` configuration.
+{% endhint %}
+
+### Authentication
+
+In order for us to know what project you are reporting stats for, you must send along your packtracker project token.  To do this with the CircleCI Orb, you must create a new project environment variable in your CircleCI settings called `PT_PROJECT_TOKEN`.  You can find your packtracker project token in your project's settings.
+
+### Configuration
+
+{% hint style="info" %}
+If you are not yet using [CircleCI Workflows](https://circleci.com/docs/2.0/workflows/), you will need to do so.  If this is the case, you likely have a single `build` job in your CircleCI configuration.  In order to add the packtracker `job` to your CI run, you will need to set up a [multi-job workflow as seen in this example configuration](https://circleci.com/docs/2.0/workflows/#workflows-configuration-examples).
+{% endhint %}
+
+Now that you've declared our orb for use and added your project token, you have access to our `report` **job**.  You can put this job anywhere inside your existing CircleCI workflows.
+
+```yaml
+workflows:
+  version: 2
+  your_existing_workflow:
+    jobs:
+      - build
+      - packtracker/report
+```
+
+Or, create a new workflow to run packtracker reporting.
+
+```yaml
+workflows:
+  version: 2
+  your_existing_workflow:
+    jobs:
+      - build
+  packtracker:
+    jobs:
+      - packtracker/report
+```
+
+By default, this base configuration should _just work_ most of the time.  If you have a non-standard setup, you can tweak the job with the following 2 optional parameters.
+
+| Parameter | Description |
+| :--- | :--- |
+| `project_root`  | The relative path to the directory containing the `package.json` of your project.  By default, this is the root of your repository.  This can be especially useful for projects that do not live at the root of the repository, like lerna mono-repositories for example. |
+| `webpack_config` | The relative path to your webpack configuration.  By default, it looks in the root directory for `webpack.config.js`. |
+
+For example, a Ruby on Rails project might look something like this.
+
+```yaml
+workflows:
+  packtracker:
+    jobs:
+      - packtracker/report:
+          webpack_config: "./config/webpack/production.js"
+
+```
+
+
+

creating-your-first-project.md

@@ -0,0 +1,8 @@
+---
+description: >-
+  We also offer additional instruction for tools that use webpack, but might do
+  so in their own proprietary way.
+---
+
+# Common App Platforms
+

faq.md

@@ -0,0 +1,70 @@
+---
+description: >-
+  Create React App is a powerful, opinionated tool for bootstrapping a modern
+  React web application.
+---
+
+# Create React App
+
+## For CircleCI or GitHub Actions Users
+
+If you're using CircleCI or GitHub Actions, the packaged stat reporter for these integrations automatically handles the process of uploading the build stats of your Create React App application.
+
+{% page-ref page="../circleci-orb.md" %}
+
+{% page-ref page="../github-actions.md" %}
+
+## Not using CircleCI or GitHub Actions?
+
+{% hint style="danger" %}
+This documentation works **only for projects using Create React App 2.x**
+
+Unfortunately they have removed the `--stats` flag in 3.x
+{% endhint %}
+
+While the [Create React App](https://facebook.github.io/create-react-app/) project maintains great usability by hiding much of the ceremony of webpack behind it's own set of scripts, without ejecting you would otherwise not be able to use our service to track your bundle sizes.
+
+To allow you to maintain your usage of the CRA scripts, we have provided a CLI tool along side our plugin that allows you to upload your stats to us as long as you have a static json stats file available.
+
+You will still need to install our plugin in your project
+
+```text
+npm install @packtracker/webpack-plugin
+```
+
+The provided command, `packtracker-upload`, will upload your stats to our service from a static json file. Luckily, Create React App exposes this json via the `--stats` flag.
+
+The only caveat to using the command \(instead of the plugin\) is that you **must** use environment variables to configure your stat reporting \(most importantly `PT_PROJECT_TOKEN`\).
+
+{% hint style="info" %}
+See [our plugin documentation](https://github.com/packtracker/webpack-plugin#options) for a full list of configuration options available via environment variable.
+{% endhint %}
+
+### Get your project token
+
+After [creating your organization and project on packtracker.io](https://docs.packtracker.io/creating-your-first-project), grab your project token and assign it to `PT_PROJECT_TOKEN` as an environment variable.
+
+```text
+export PT_PROJECT_TOKEN=your-project-token-here
+```
+
+### **Creating the npm script to report your stats**
+
+Now that your environment has your environment variable available.  In your `package.json` you can add a npm script like the following
+
+```text
+{
+  "scripts": {
+    "packtracker": "react-scripts build --stats && packtracker-upload --stats=build/bundle-stats.json"
+  }
+}
+```
+
+Then running `npm run packtracker` should upload your stats to our service
+
+Once you've tested that you are all set up, be sure to set this script to run in your CI environment or on deployment of your application so we can track each and every commit.
+
+
+
+
+