node package manager
Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

paragon-scripts

Why not just use npm scripts?

The basic idea is that our build system is getting more and more options as time goes on, like environments, cold/hot builds, watch mode for tests, uglification toggling for production, etc. With npm scripts we have to create a separate script for every possible combination of options and memorize the exact order those options have to be provided (ie. npm run watch:cold:locahost vs npm run watch:localhost:cold which was tripping people up yesterday).

Then when scripts change we have to edit them all. For example, to change how watching works currently we'd have to edit 6 scripts in each of the 6 clients, for a total of 36 scripts that have to be edited to make one change.

And then each copy of each script has to be tested individually, because it's so easy to make a typo when doing that type of work. NPM scripts aren't syntax checked, so we won't be able to depend on any sort of automated tools to detect mistakes.

Why move dependencies out of the client's package.json?

Another advantage of paragon-scripts is that its package can contain all the build system dependencies, which means that each client can depend only on the libraries it actually uses.

This has several effects:

  1. It makes the package.json of each client much easier to read and maintain, since it's not cluttered by all the build system packages.
  2. Because of ^^^^, It lets us start doing things like scanning for unused/outdated dependencies.
  3. It makes installing/updating packages for a client much faster. Optimizing this action is a priority since it must occur whenever you switch branches that contain conflicting package versions.
  4. It makes updating the build system a lot easier. We can just update the dependencies of paragon-scripts and everything will be automatically updated thanks to semantic versioning.
  5. It saves installation time and disk space by only having one copy of build system files (which are quite large, and take a long time to install)

Why are the scripts so much longer than before?

In order to achieve the above goal of keeping a client's dependencies down to the packages it directly uses, we have to do a lot more configuration at every step of the build process. Webpack and most other utilities we use assume that all the packages needed to compile a client are located directly in its own package.json

As long as this was the case, we were able to use default settings for much of the build system. This enabled the scripts to be much simpler, which is why the previous npm scripts are much shorter than those found in paragon-scripts.

For example, to correctly configure the testing framework to load and transpile files correctly, we have to generate a custom configuration file for each specific client as part of the build process. This would have been impossible to do with npm scripts.

Why not commit package-lock.json?

npm 5 is severely messed up. Furthermore, package-lock.json is fundamentally broken in that it does not accomplish its stated purpose of providing package version security. This was a deliberate change by the npm developers that they don't plan on reverting.

Because of this, there is absolutely nothing to be gained by committing package-lock.json files. They clutter up pull requests with meaningless thousand line changes, cause merge conflicts on any pull request that updates packages, and frequently break builds.

Why not just roll back to npm 4?

npm 4 is much slower than yarn or npm 5, and most importantly it doesn't provide the ability to lock packages, which is a vital feature for reliable deterministic builds and deployments.

Why yarn?

Yarn is an alternative node package manager that was written by Facebook and Google when they became frustrated with the state of npm. It's much faster than npm 4, slightly faster than npm 5, and can validate installed packages with checksums. But most importantly, it has a well designed package locking system that actually works and doesn't break everything it touches.

Note that switching the build scripts to yarn doesn't force everyone on the team to make the switch. Yarn doesn't break any existing workflows, so you're completely able to continue using either npm 4 or 5. Just don't ask David for help when all your packages break. ;)

Why not call it paragon-build-scripts?

The command will be manually typed every time anyone builds, runs, or does anything with a client. It's important that it be short, easy to type, and memorable.

Binary name ideas:

  • CAP - Chihuahuas Ain't Pugs
  • ryan/dexter
  • paragon

Example usages:

cap watch --cold
ryan watch --cold
dexter watch --cold
paragon watch --cold