builder - npm Package Compare versions

Comparing version 2.0.1 to 2.1.0

HISTORY.md

 History
 =======
 
+## 2.1.0
+
+* Support new `ARCHETYPE` + `ARCHETYPE-dev` architecture for better NPM 2 + 3
+  `devDependencies` support.
+* **DEPRECATION**: Deprecate `builder install` workflow. #16
+
 ## 2.0.1
@@ -5,0 +11,0 @@

lib/config.js

@@ -25,2 +25,8 @@ "use strict";
   this.archetypes = this.cfg.archetypes || [];
+
+  // Include the `-dev` packages.
+  this.allArchetypes = this.archetypes.reduce(function (memo, name) {
+    return memo.concat([name, name + "-dev"]);
+  }, []);
+
   // Array of [name, scripts array] pairs.
@@ -162,3 +168,3 @@ this.scripts = this._loadScripts(this.archetypes);
     get: function () {
-      return _.map(this.archetypes, function (name) {
+      return _.map(this.allArchetypes, function (name) {
         return path.join(process.cwd(), "node_modules", name, "node_modules/.bin");
@@ -176,4 +182,4 @@ });
     get: function () {
-      return _.map(this.archetypes, function (name) {
-        return path.join(process.cwd(), "node_modules", name);
+      return _.map(this.allArchetypes, function (name) {
+        return path.join(process.cwd(), "node_modules", name, "node_modules");
       });
@@ -180,0 +186,0 @@ }

lib/runner.js

@@ -117,2 +117,8 @@ "use strict";
    *
+   * @deprecated https://github.com/FormidableLabs/builder/issues/16
+   *
+   * `devDependencies` should come from an `ARCHETYPE-dev` package now and
+   * not from the `ARCHETYPE/package.json`'s `devDependencies`, obviating the
+   * need for this separate installation step.
+   *
    * @param {Array}     paths       List of paths in which to `npm install`
@@ -119,0 +125,0 @@ * @param {Object}    opts        Shell options

lib/task.js

@@ -152,2 +152,8 @@ "use strict";
  *
+ * @deprecated https://github.com/FormidableLabs/builder/issues/16
+ *
+ * `devDependencies` should come from an `ARCHETYPE-dev` package now and
+ * not from the `ARCHETYPE/package.json`'s `devDependencies`, obviating the
+ * need for this separate installation step.
+ *
  * @param   {Function} callback   Callback function `(err)`
@@ -160,2 +166,4 @@ * @returns {void}
 
+  log.warn("Deprecation Warning", "Task will be removed soon. " +
+    "Please update ARCHETYPES to have separate dev packages.");
   log.info(this._action, "Install dev dependencies for:" + paths.map(function (p) {
@@ -162,0 +170,0 @@ return "\n * " + chalk.gray(p);

package.json

 {
   "name": "builder",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "An NPM-based task runner",
@@ -5,0 +5,0 @@ "repository": {

README.md

@@ -6,8 +6,33 @@ [![Travis Status][trav_img]][trav_site]
 
-Builder is a task runner.
+Builder takes your `npm` tasks and makes them composable, controllable from
+a single point, and flexible.
 
-Builder is an enhancement to `npm run TASK`.
+`npm` is fantastic for controlling dependencies, tasks (via `scripts`) and
+general project workflows. But a project-specific `package.json` simply doesn't
+scale when you're managing many (say 5-50) very similar repositories.
 
-Builder is a meta-tool for all your common build, quality, and test tasks.
+_Enter Builder._ Builder is "almost" `npm`, but provides for off-the-shelf
+"archetypes" to provide central sets of `package.json` `scripts`,
+`dependencies` and `devDependencies`. The rest of this page will dive into
+the details and machinations of the tool, but first here are a few of the
+rough goals and motivations behind the project.
 
+* **Single Point of Control**: A way to define a specific set of tasks /
+  configs / etc. for one "type" of project. For example, we have an
+  ever-expanding set of related repos for our
+  [Victory](https://github.com/FormidableLabs/?utf8=%E2%9C%93&query=victory)
+  project which all share a nearly-identical dev / prod / build workflow.
+* **Flexibility**: There are a number of meta tools for controlling JavaScript
+  workflows / development lifecycles. However, most are of the "buy the farm"
+  nature. This works great when everything is within the workflow but falls
+  apart once you want to be "just slightly" different. Builder solves this by
+  allowing fine grain task overriding by name, where the larger composed tasks
+  still stay the same and allow a specific repo's deviation from "completely off
+  the shelf" to be painless.
+* **You Can Give Up**: One of the main goals of builder is to remain very
+  close to a basic `npm` workflow. So much so, that we include a section in this
+  guide on how to abandon the use of Builder in a project and revert everything
+  from archetypes back to vanilla `npm` `package.json` `scripts`, `dependencies`
+  and `devDependencies`.
+
 ## Overview
@@ -38,2 +63,8 @@
 
+**Note**: Most archetypes have an `ARCHTEYPE` package and parallel
+`ARCHETYPE-dev` NPM package. The `ARCHETYPE` package contains _almost_
+everything needed for the archtype (prod dependencies, scripts, etc.) except
+for the `devDependencies` which the latter `ARCHETYPE-dev` package is solely
+responsible for bringing in.
+
 #### Global Install
@@ -47,2 +78,3 @@
 $ npm install --save builder-react-component
+$ npm install --save-dev builder-react-component-dev
 ```
@@ -66,3 +98,5 @@
 ```sh
-$ npm install --save builder builder-react-component
+$ npm install --save builder
+$ npm install --save builder-react-component
+$ npm install --save-dev builder-react-component-dev
 ```
@@ -81,3 +115,3 @@
 
-#### Configure, Install
+#### Configuration
 
@@ -94,11 +128,2 @@ After `builder` is available, you can edit `.builderrc` like:
 
-At this point, `builder` can build any production tasks, as only production
-`dependencies` of archetypes are installed. However, if you are in a
-**development** or CI environment, an additional manual step is needed to
-install the `devDependencies` of all the archetypes:
-
-```sh
-$ builder install
-```
-
 ... and from here you are set for `builder`-controlled meta goodness!
@@ -114,8 +139,2 @@
 
-Install archetype `devDependencies`.
-
-```sh
-$ builder install
-```
-
 Run a single `package.json` `scripts` task.
@@ -136,3 +155,3 @@
 
-The underyling concept here is that `builder` `script` commands simply _are_
+The underlying concept here is that `builder` `script` commands simply _are_
 NPM-friendly `package.json` `script` commands. Pretty much anything that you
@@ -304,2 +323,54 @@ can execute with `npm run FOO` can be executed with `builder run FOO`.
 
+### I Give Up. How Do I Abandon Builder?
+
+Builder is designed to be as close to vanilla npm as possible. So, if for
+example you were using the `builder-react-component` archetype with a project
+`package.json` like:
+
+```js
+"scripts": {
+  "postinstall": "builder run npm:postinstall",
+  "preversion": "builder run npm:preversion",
+  "version": "builder run npm:version",
+  "test": "builder run npm:test",
+  /* other deps */
+},
+"dependencies": {
+  "builder": "v2.0.0",
+  "builder-react-component": "v0.0.5",
+  /* other deps */
+},
+"devDependencies": {
+  "builder-react-component-dev": "v0.0.5",
+  /* other deps */
+}
+```
+
+and decided to _no longer_ use Builder, here is a rough set of steps to unpack
+the archetype into your project and remove all Builder dependencies:
+
+* Copy all `ARCHETYPE/package.json:dependencies` to your
+  `PROJECT/package.json:dependencies` (e.g., from `builder-react-component`).
+  You _do not_ need to copy over `ARCHETYPE/package.json:devDependencies`.
+* Copy all `ARCHETYPE/package.json:scripts` to your
+  `PROJECT/package.json:scripts` that do not begin with the `builder:` prefix.
+  You may have to manually resolve `scripts` tasks of the same name.
+* Copy all `ARCHETYPE-dev/package.json:dependencies` to your
+  `PROJECT/package.json:devDependencies`
+  (e.g., from `builder-react-component-dev`)
+* Copy all configuration files used in your `ARCHETYPE` into the root project.
+  For example, for `builder-react-component` you would need to copy the
+  `builder-react-component/config` directory to `PROJECT/config` (or a renamed
+  directory).
+* Review all of the combined `scripts` tasks and:
+    * resolve duplicate tasks names
+    * revise configuration file paths for the moved files
+    * replace instances of `builder run <TASK>` with `npm run <TASK>`
+    * for `builder concurrent <TASK1> <TASK2>` tasks, first install the
+      `concurrently` package and then rewrite to:
+      `concurrent 'npm run <TASK1>' 'npm run <TASK2>'`
+
+... and (with assuredly a few minor hiccups) that's about it! You are
+Builder-free and back to a normal `npm`-controlled project.
+
 ### Versions v1, v2, v3
@@ -306,0 +377,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

New author

Supply chain risk

A new npm collaborator published a version of the package for the first time. New collaborators are usually benign additions to a project, but do indicate a change to the security surface area of a package.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

32240

increased by17.96%

Lines of code

556

increased by3.35%

Number of lines in readme file

383

increased by22.76%

Number of medium supply chain risk alerts

1

decreased by-66.67%

No dependency changes