FormidableLabs/builder

Name: builder

Owner: Formidable

Description: An npm-based task runner

Created: 2015-10-19 22:00:13.0

Updated: 2018-01-13 13:02:38.0

Pushed: 2017-10-09 01:40:36.0

Homepage: http://formidable.com/open-source/builder/

Size: 290

Language: JavaScript

GitHub Committers

UserMost Recent Commit# Commits

Other Committers

UserEmailMost Recent Commit# Commits

README

Travis Status Appveyor Status Coverage Status

Builder

Builder takes your npm tasks and makes them composable, controllable from a single point, and flexible.

npm is fantastic for controlling 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.

Enter Builder. Builder is “almost” npm, but provides for off-the-shelf “archetypes” to provide central sets of package.json scripts tasks, and dependencies and devDependencies for those tasks. 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.

Contents:

Overview

At a high level builder is a tool for consuming package.json scripts commands, providing sensible / flexible defaults, and supporting various scenarios (“archetypes”) for your common use cases across multiple projects.

Builder is not opinionated, although archetypes are and typically dictate file structure, standard configurations, and dev workflows. Builder supports this in an agnostic way, providing essentially the following:

… and that's about it!

Usage

To start using builder, install and save builder and any archetypes you intend to use. We'll use the builder-react-component archetype as an example.

Note: Most archetypes have an ARCHETYPE package and parallel ARCHETYPE-dev npm package. The ARCHETYPE package contains almost everything needed for the archetype (prod dependencies, scripts, etc.) except for the devDependencies which the latter ARCHETYPE-dev package is solely responsible for bringing in.

Global Install

For ease of use, one option is to globally install builder and locally install archetypes:

m install -g builder
m install --save builder-react-component
m install --save-dev builder-react-component-dev

Like a global install of any Node.js meta / task runner tool (e.g., eslint, mocha, gulp, grunt) doing a global install is painful because:

… so instead, we strongly recommend a local install described in the next section!

To help you keep up with project-specific builder requirements, a globally-installed builder will detect if a locally-installed version of builder is available and switch to that instead:

LOBAL/PATH/TO/builder
lder:local-detect] Switched to local builder at: ./node_modules/builder/bin/builder-core.js

now using local builder! ...
Local Install

To avoid tying yourself to a single, global version of builder, the option that we endorse is locally installing both builder and archetypes:

m install --save builder
m install --save builder-react-component
m install --save-dev builder-react-component-dev

However, to call builder from the command line you will either need to either augment PATH or call the long form of the command:

PATH Augmentation

Our recommended approach is to augment your PATH variable with a shell configuration as follows:

Mac / Linux

fer version, but if you _have_ global installs, those come first.
rt PATH="${PATH}:./node_modules/.bin"

R) Less safe, but guarantees local node modules come first.
rt PATH="./node_modules/.bin:${PATH}"

eck results with:
 $PATH

To make these changes permanent, add the export command to your .bashrc or analogous shell configuration file.

Windows

fer version, but if you _have_ global installs, those come first.
PATH=%PATH%;node_modules\.bin

R) Less safe, but guarantees local node modules come first.
PATH=node_modules\.bin;%PATH%

eck results with:
 %PATH%

To make these changes permanent, please see this multi-OS article on changing the PATH variable: https://www.java.com/en/download/help/path.xml (the article is targeted for a Java executable, but it's analogous to our situation). You'll want to paste in ;node_modules\.bin at the end or node_modules\.bin; at the beginning of the PATH field in the gui. If there is no existing PATH then add a user entry with node_modules\.bin as a value. (It is unlikely to be empty because an npm installation on Windows sets the user PATH analogously.)

Full Path Invocation

Or you can run the complete path to the builder script with:

Mac / Linux

_modules/.bin/builder <action> <task>

Windows

_modules\.bin\builder <action> <task>
Configuration

After builder is available, you can edit .builderrc like:


etypes:
builder-react-component

to bind archetypes.

… and from here you are set for builder-controlled meta goodness!

Builder Actions

Display general or command-specific help (which shows available specific flags).

ilder [-h|--help|help]
ilder help <action>
ilder help <archetype>

Run builder help <action> for all available options. Version information is available with:

ilder [-v|--version]

Let's dive a little deeper into the main builder actions:

builder run

Run a single task from script. Analogous to npm run <task>

ilder run <task>

Flags:

builder concurrent

Run multiple tasks from script concurrently. Roughly analogous to npm run <task1> & npm run <task2> & npm run <task3>, but kills all processes on first non-zero exit (which makes it suitable for test tasks), unless --no-bail is provided.

ilder concurrent <task1> <task2> <task3>

Flags:

Note that tries will retry individual tasks that are part of the concurrent group, not the group itself. So, if builder concurrent --tries=3 foo bar baz is run and bar fails twice, then only bar would be retried. foo and baz would only execute once if successful.

builder envs

Run a single task from script concurrently for each item in an array of different environment variables. Roughly analogous to:

O=VAL1 npm run <task> & FOO=VAL2 npm run <task> & FOO=VAL3 npm run <task>

… but kills all processes on first non-zero exit (which makes it suitable for test tasks), unless --no-bail is provided. Usage:

ilder envs <task> <json-array>
ilder envs <task> --envs-path=<path-to-json-file>

Examples:

Mac / Linux

ilder envs <task> '[{ "FOO": "VAL1" }, { "FOO": "VAL2" }, { "FOO": "VAL3" }]'
ilder envs <task> '[{ "FOO": "VAL1", "BAR": "VAL2" }, { "FOO": "VAL3" }]'

Mac / Linux / Windows

ilder envs <task> "[{ \"FOO\": \"VAL1\" }, { \"FOO\": \"VAL2\" }, { \"FOO\": \"VAL3\" }]"
ilder envs <task> "[{ \"FOO\": \"VAL1\", \"BAR\": \"VAL2\" }, { \"FOO\": \"VAL3\" }]"

Flags:

Note: The environments JSON array will overwrite existing values in the environment. This includes environment variables provided to / from builder from things such as npm config and the --env/--env-path flags.

So, for example, if you invoke builder with:

ilder envs <task> '[{"FOO": "ENVS"}]' --env='{"FOO": "FLAG"}'

The environment variable FOO will have a value of "ENVS" with the single environment object array item given to builder envs overriding the --env flag value.

Custom Flags

Just like npm run <task> [-- <args>...], flags after a -- token in a builder task or from the command line are passed on to the underlying tasks. This is slightly more complicated for builder in that composed tasks pass on the flags all the way down. So, for tasks like:

ipts": {
own": "echo down",
ay": "builder run down -- --way",
he": "builder run way -- --the",
ll": "builder run the -- --all"

We can run some basics (alone and with a user-added flag):

ilder run down


ilder run down -- --my-custom-flag
 --my-custom-flag

If we run the composed commands, the -- flags are accumulated:

ilder run all
 --way --the --all

ilder run all -- --my-custom-flag
 --way --the --all --my-custom-flag

The rough heuristic here is if we have custom arguments:

  1. If a builder <action> command, pass through using builder-specific environment variables. (Builder uses _BUILDER_ARGS_CUSTOM_FLAGS).
  2. If a non-builder command, then append without -- token.
Expanding the Archetype Path

Builder tasks often refer to configuration files in the archetype itself like:

tinstall": "webpack --bail --config node_modules/<archetype>/config/webpack/webpack.config.js",

In npm v2 this wasn't a problem because dependencies were usually nested. In npm v3, this all changes with aggressive flattening of dependencies. With flattened dependencies, the chance that the archetype and its dependencies no longer have a predictable contained structure increases.

Thus, commands like the above succeed if the installation ends up like:

_modules/
 module>/
node_modules/
  <archetype>/
    node_modules/
      webpack/

If npm flattens the tree like:

_modules/
 module>/
rchetype>/
bpack/

Then builder can still find webpack due to its PATH and NODE_PATH mutations. But an issue arises with something like a postinstall step after this flattening in that the current working directory of the process will be PATH/TO/node_modules/<a module>/, which in this flattened scenario would not find the file:

_modules/<archetype>/config/webpack/webpack.config.js

because relative to node_modules/<a module>/ it is now at:

archetype>/config/webpack/webpack.config.js

To address this problem builder has an --expand-archetype flag that will replace an occurrence of the specific node_modules/<archetype> in one of the archetype commands with the full path to the archetype, to guarantee referenced files are correctly available.

The basic heuristic of things to replace is:

Some notes:

Tasks

The underlying concept here is that builder script commands simply are npm-friendly package.json script commands. Pretty much anything that you can execute with npm run <task> can be executed with builder run <task>.

Builder can run 1+ tasks based out of package.json scripts. For a basic scenario like:


cripts": {
"foo": "echo FOO",
"bar": "echo BAR"

Builder can run these tasks individually:

ilder run foo
ilder run bar

Sequentially via || or && shell helpers:

ilder run foo && builder run bar

Concurrently via the Builder built-in concurrent command:

ilder concurrent foo bar

With concurrent, all tasks continue running until they all complete or any task exits with a non-zero exit code, in which case all still alive tasks are killed and the Builder process exits with the error code.

npm Config

builder supports package.json config properties the same way that npm does, with slight enhancements in consideration of multiple package.json's in play.

npm Config Overview

As a refresher, npm utilizes the config field of package.json to make “per-package” environment variables to scripts tasks. For example, if you have:


onfig": {
"my_name": "Bob"

cripts": {
"get-name": "echo Hello, ${npm_package_config_my_name}."

and ran:

m run get-name
o, Bob.

More documentation about how npm does per-package configuration is at:

Builder Configs

In builder, for a single package.json this works essentially the same in the above example.

ilder run get-name
o, Bob.

However, builder has the added complexity of adding in config variables from archetypes and the environment. So the basic resolution order for a config environment variable is:

  1. Look to npm_package_config_<VAR_NAME>=<VAR_VAL> on command line.
  2. If not set, then use <root>/package.json:config:<VAR_NAME> value.
  3. If not set, then use <archetype>/package.json:config:<VAR_NAME> value.

So, let's dive in to a slightly more complex example:

archetype>/package.json

onfig": {
"my_name": "ARCH BOB"

cripts": {
"get-name": "echo Hello, ${npm_package_config_my_name}."



root>/package.json

onfig": {
"my_name": "ROOT JANE"

When we run the builder command, the <root> value overrides:

ilder run get-name
o, ROOT JANE.

We can inject a command line flag to override even this value:

m_package_config_my_name="CLI JOE" builder run get-name
o, CLI JOE.

Note that the ability to override via the process environment is unique to builder and not available in real npm.

Config Notes
Tip - Use String Values

Although config properties can be something like:

fig": {
nabled": true

We strongly recommend that you always set strings like:

fig": {
nabled": "true"

And deal just with string values in your tasks, and files. The reasoning here is that when overriding values from the command line, the values will always be strings, which has a potential for messy, hard-to-diagnose bugs if the overridden value is not also a string.

npmrc Configuration

npm has additional functionality for config values that are not presently supported, such as issuing commands like npm config set <pkg-name>:my_name Bill that store values in ~/.npmrc and then override the package.json values at execution time. We may extend support for this as well, but not at the present.

Command Line Environment Variables

npm does not support overriding config environment variables from the actual environment. So doing something in our original example like:

m_package_config_my_name=George npm run get-name
o, Bob.

In fact, npm will refuse to even add environment variables starting with npm_package_config to the npm run environment. E.g.


onfig": {},
cripts": {
"get-npm-val": "echo NPM VAR: ${npm_package_config_var}",
"get-env-val": "echo ENV VAR: ${env_var}"

The npm config variable doesn't make it through:

m_package_config_var=SET npm run get-npm-val
VAR:

While a normal environment variable will:

v_var=SET npm run get-env-val
VAR: SET

By contrast, builder does pass through environment variables already existing on the command line, and moreover those overrides takes precedence over the root and archetype package.json values. Those same examples with builder show that the environment variables do make it through:

m_package_config_var=SET builder run get-npm-val
VAR: SET

v_var=SET builder run get-env-val
VAR: SET

Things are a little more complex when using with builder envs, but the rough rule is that the environment JSON array wins when specified, otherwise the existing environment is used:

m_package_config_var=CLI builder envs get-npm-val --queue=1 \
{}, {"npm_package_config_var":"This Overrides"}]'
VAR: CLI
VAR: This Overrides
Archetypes

Archetypes deal with common scenarios for your projects. Like:

Archetypes typically provide:

In most cases, you won't need to override anything. But, if you do, pick the most granular scripts command in the archetype you need to override and define just that in your project's package.json script section. Copy any configuration files that you need to tweak and re-define the command.

Task Resolution

The easiest bet is to just have one archetype per project. But, multiple are supported. In terms of scripts tasks, we end up with the following example:

/package.json
/node_modules/ARCHETYPE_ONE/package.json
/node_modules/ARCHETYPE_TWO/package.json

Say we have a .builderrc like:


etypes:
ARCHETYPE_ONE
ARCHETYPE_TWO

The resolution order for a script task (say, foo) present in all three package.json's would be the following:

Special Archetype Tasks

Archetypes use conventional scripts task names, except for the following special cases:

These tasks are specifically actionable during the npm lifecycle, and consequently, the archetype mostly ignores those for installation by default, offering them up for actual use in your project.

We strongly recommend entirely avoiding npm lifecycle task names in your archetype package.json files. So, instead of having:

archetype>/package.json
ad
t": "builder concurrent --buffer test-frontend test-backend"

We recommend something like:

archetype>/package.json
ood / OK
:test": "builder run test-all",
t-all": "builder concurrent --buffer test-frontend test-backend"

lso OK
:test": "builder concurrent --buffer test-frontend test-backend"

and then in your <root>/package.json using the real lifecycle task name.

t": "builder run npm:test"
Creating an Archetype

Moving common tasks into an archetype is fairly straightforward and requires just a few tweaks to the paths defined in configuration and scripts in order to work correctly.

Initializing a Project

An archetype is simply a standard npm module with a valid package.json. To set up a new archetype from scratch, make a directory for your new archetype, initialize npm and link it for ease of development.

 path/to/new/archetype
m init
m link

From your consuming project, you can now link to the archetype directly for ease of development after including it in your dependencies and creating a .builderrc as outlined above in configuration.

 path/to/consuming/project
m link new-archetype-name
Managing the dev Archetype

Because builder archetypes are included as simple npm modules, two separate npm modules are required for archetypes: one for normal dependencies and one for dev dependencies. Whereas in a non-builder-archetype project you'd specify dev dependencies in devDependencies, with builder all dev dependencies must be regular dependencies on a separate dev npm module.

builder is designed so that when defining which archetypes to use in a consuming project's .builderrc, builder will look for two modules, one named appropriately in dependencies (ex: my-archetype) and one in devDependencies but with -dev appended to the name (ex: my-archetype-dev).

To help with managing these while building a builder archetype, install builder-support to create and manage a dev/ directory within your archetype project with it's own package.json which can be published as a separate npm module. builder-support will not only create a dev/package.json with an appropriate package name, but will also keep all the other information from your archetype's primary package.json up to date as well as keep README.md and .gitignore in parity for hosting the project as a separate npm module.

Get started by installing and running builder-support gen-dev:

m install builder-support --save-dev
node_modules/.bin/builder-support gen-dev

TIP: Create a task called "builder:gen-dev": "builder-support gen-dev" in your archetype to avoid having to type out the full path each time you update your project's details.

For ease of development, npm link the dev dependency separately:

 dev
m link

Then from your consuming project, you can link to the dev package.

 path/to/consuming/project
m link new-archetype-name-dev

Read the builder-support docs to learn more about how dev archetypes are easily managed with builder-support gen-dev.

Node Require Resolution and Module Pattern

As a background primer, whenever a file has a require("lib-name") in it, Node performs the following check for /path/to/ultimate/file.js:

h/to/ultimate/node_modules/lib-name
h/to/node_modules/lib-name
h/node_modules/lib-name
e_modules/lib-name

After this, Node then checks for NODE_PATH for additional paths to search. This presents a potentially awkward pattern when combined with npm deduplication / flattening for say a file like: <root>/node_modules/<archetype>/config/my-config.js that requires lib-name@right-version as follows:

Node modules layout:

t>/
de_modules/
lib-name@wrong-version
<archetype>/
  config/my-config.js         // require("lib-name");
<archetype-dev>/
  node_modules/
    lib-name@right-version

This unfortunately means that the search path for require("lib-name") is:

om file path priority resolution
t>/node_modules/<archetype>/config/node_modules
t>/node_modules/<archetype>/node_modules
t>/node_modules/node_modules
t>/node_modules                                   // Matches `lib-name@wrong-version`!!!

w, from `NODE_PATH`
t>/node_modules/<archetype>/node_modules
t>/node_modules/<archetype-dev>/node_modules      // Too late for `right-version`.
The Module Pattern

To remedy this situation, we encourage a very simple pattern to have Node.js require's start from the dev archetype when appropriate by adding a one-line file to the dev archetype: <archetype-dev>/require.js

ontents of <archetype-dev>/require.js
le.exports = require;

By exporting the require from the dev archetype, the resolution starts in the dev archetype and thus ensures the dev archetype “wins” for the archetype tasks. Thus in any archetype files that do a require, simply switch to:

mod = require("<archetype-dev>/require")("lib-name");             // Module
modPath = require("<archetype-dev>/require").resolve("lib-name"); // Module path

And the dependency from the dev archetype is guaranteed to “win” no matter what happens with actual module layout from npm installation.

Note that because a file from within the normal <archetype> will naturally search <archetype>/node_modules before hitting <root>/node_modules you do not need to use this require pattern for normal archetype dependencies in archetype Node.js files.

Node.js files in the normal production archetype do not need a <archetype>/require.js file akin to the dev archetype because <archetype>/node_modules is already at the top of the require search path. However, some projects may wish to have an archetype control and provide application dependencies and dev dependencies, which we discuss in the next section

ES.next Imports and The Module Pattern

The module pattern works great for any require()-based CommonJS code. Unfortunately, when using babel and ES.next imports like:

rt _ from "lodash";

The module pattern is not available because the actual require("lodash") statement spit out during transpilation is not directly accessible to the developer.

Fortunately (and unsurprisingly) we have a babel plugin to enable the module pattern in ES.next code: babel-plugin-replace-require. The plugin can easily be configured with tokens to insert dev archetypes in requires produced by babel transpilation. For example, say we wanted to get lodash from above from our dev archetype, we would configure a .babelrc like:


lugins": [
["replace-require", {
  "DEV_ARCHETYPE": "require('<archetype-dev>/require')"
}]

Then prepend our custom token to the source ES.next code:

rt _ from "DEV_ARCHETYPE/lodash";

When transpiled, the output would become:

 strict";

_lodash = require('<archetype-dev>/require')("lodash");

_lodash2 = _interopRequireDefault(_lodash);

tion _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }

giving us the correct module pattern.

Webpack and Module Pattern

An analogous situation occurs for frontend JS code in the production archetype, but with a different solution. The underlying issue is that Webpack cannot ingest:

rc/foo.js
mod = require("<archetype-dev>/require")("lib-name");

like Node.js can, so we need a little help in the form of a loader.

Note: Previous incarnations of this documentation suggested mutating Webpack code (resolve.root) and loader (resolveLoader.root) configurations. We no longer suggest this as the loader pattern in this section is much more precise and doesn't lead to potential prod-vs-dev ambiguities in module use.

Turning to the above example, we can use the webpack-alternate-require-loader to rewrite CommonJS forms of the module pattern into fully-resolved paths on disk that work for webpack.

Let's start with our webpack configuration:

ebpack.config.js
le.exports = {
dule: {
loaders: [
  {
    test: /\.js$/,
    loader: "webpack-alternate-require-loader",
    query: JSON.stringify({
      "<archetype-dev>/require": require.resolve("<archetype-dev>/require")
    })
  }
]

With this configuration, Webpack will parse our above code sample and actually perform the resolution of lib-name using the require provided in <archetype-dev>/require producing ultimate code like:

ib/foo.js
mod = require("/RESOLVED/PATH/TO/lib-name");

This essentially converts a runtime lookup of the require starting from the dev archetype to a build time lookup performed by webpack.

Conveniently, this plugin also works with code produced by babel-plugin-replace-require when configured as specified in the previous section.

Shared Node / Frontend Code: The best part of this plugin is that if you have shared code between Node.js and the frontend, you can have the exact same code work in both places – unparsed for Node.js and processed via Webpack for the frontend.

Application vs. Archetype Dependencies

Out of the box builder does not manage application dependencies, instead managing dependencies only for builder workflows and tasks, e.g. things starting with the builder command.

Most notably, this means that if your application code includes a dependency like lodash:

root>/src/index.js
_ = require("lodash");

le.exports = _.camelCase("Hi There");

and the root project is consumed by anything besides a builder command, then it must have a dependency like:

root>/package.json
endencies": {
odash": "^4.2.1"

However, if you want to use builder to also manage application dependencies, then you can follow the module pattern and provide an <archetype>/require.js file consisting of:

ontents of <archetype>/require.js
le.exports = require;

The root project could then require code like:

modFromProd = require("<archetype>/require")("lib-name");               // Module
pathFromProd = require("<archetype>/require").resolve("lib-name");      // Module path
modFromDev = require("<archetype-dev>/require")("lib-name");            // Module
pathFromDev = require("<archetype-dev>/require").resolve("lib-name");   // Module path

Using the above pattern, <archetype> or <archetype-dev> dependencies would override <root>/node_modules dependencies reliably and irrespective of npm flattening.

So, turning back to our original example, we could utilize archetype dependencies by refactoring to something like:

root>/src/index.js
_ = require("<archetype>/require")("lodash");

le.exports = _.camelCase("Hi There");

and dev code like:

root>/test/index.js
_ = require("<archetype-dev>/require")("lodash");

le.exports = _.camelCase("Hi There");

after which you would not need a lodash dependency in root/package.json.

Moving dependencies and scripts to a New Archetype

Once everything is configured and npm link'd, it should be easy to move scripts to your archetype and quickly test them out from a consuming project.

Moving dependencies and devDependencies from an Existing package.json

Note that you should only copy dependencies from <root>/package.json to <archetype>/package.json that are needed within the archetype itself for:

You can then remove any dependencies only used by the scripts tasks that you have moved to the archetype. However, take care to not remove real application dependencies unless you are using a module pattern to provide application dependencies.

Moving scripts and Config Files

All scripts defined in archetypes will be run from the root of the project consuming the archetype. This means you have to change all paths in your scripts to reference their new location within the archetype.

An example script and config you may be moving to an archetype would look like:

t-server-unit": "mocha --opts test/server/mocha.opts test/server/spec"

When moving this script to an archetype, we'd also move the config from test/server/mocha.opts within the original project to within the archetype such as config/mocha/server/mocha.opts.

For this example script, we'd need to update the path to mocha.opts as so:

t-server-unit": "mocha --opts node_modules/new-archetype-name/config/mocha/server/mocha.opts test/server/spec"

Any paths that reference files expected in the consuming app (in this example test/server/spec) do not need to change.

Updating Path and Module References in Config Files

Any JavaScript files run from within an archetype (such as config files) require a few changes related to paths now that the files are being run from within an npm module. This includes all require() calls referencing npm modules and all paths to files that aren't relative.

For example, karma.conf.js:

le.exports = function (config) {
quire("./karma.conf.dev")(config);

nfig.set({
preprocessors: {
  "test/client/main.js": ["webpack"]
},
files: [
  "sinon/pkg/sinon",
  "test/client/main.js"
],
;

All non-relative paths to files and npm modules need to be full paths, even ones not in the archetype directory. For files expected to be in the consuming project, this can be achieved by prepending process.cwd() to all paths. For npm modules, full paths can be achieved by using require.resolve().

An updated config might look like:

path = require("path");
ROOT = process.cwd();
MAIN_PATH = path.join(ROOT, "test/client/main.js");

le.exports = function (config) {
quire("./karma.conf.dev")(config);

nfig.set({
preprocessors: {
  [MAIN_PATH]: ["webpack"]
},
files: [
  require.resolve("sinon/pkg/sinon"),                             // Normal archetype
  require("<archetype-dev>/require").resolve("sinon/pkg/sinon"),  // Dev archetype
  MAIN_PATH
],
;
Example builder Archetype Project Structure 

CONTRIBUTING.md
HISTORY.md
LICENSE.txt
README.md
config
??? eslint
??? karma
??? mocha
?   ??? func
?   ?   ??? mocha.dev.opts
?   ?   ??? mocha.opts
?   ??? server
?       ??? mocha.opts
??? webpack
    ??? webpack.config.coverage.js
    ??? webpack.config.dev.js
    ??? webpack.config.hot.js
    ??? webpack.config.js
    ??? webpack.config.test.js
dev
??? package.json
??? require.js
package.json
Tips, Tricks, & Notes
PATH, NODE_PATH Resolution

Builder uses some magic to enhance PATH and NODE_PATH to look in the installed modules of builder archetypes and in the root of your project (per normal). We mutate both of these environment variables to resolve in the following order:

PATH:

  1. <cwd>/node_modules/<archetype>/.bin
  2. <cwd>/node_modules/<archetype-dev>/.bin
  3. <cwd>/node_modules/.bin
  4. Existing PATH

require + NODE_PATH: For file.js with a require

  1. /PATH/TO/file.js (all sub directories + node_modules going down the tree)
  2. <cwd>/node_modules/<archetype>/node_modules
  3. <cwd>/node_modules/<archetype-dev>/node_modules
  4. <cwd>/node_modules
  5. Existing NODE_PATH

The order of resolution doesn't often come up, but can sometimes be a factor in diagnosing archetype issues and script / file paths, especially when using npm v3.

Environment Variables

Builder clones the entire environment object before mutating it for further execution of tasks. On Mac/Linux, this has no real change of behavior of how the execution environment works. However, on Windows, there are some subtle issues with the fact that Windows has a case-insensitive environment variable model wherein you can set PATH in a node process, but internally this is transformed to set Path. Builder specifically handles PATH correctly across platforms for it's own specific mutation.

However, if your tasks rely on the Windows coercion of case-insensitivity of environment variables, you may run into some idiosyncratic problems with tasks.

Alternative to npm link

In some cases, npm link can interfere with the order of resolution. If you run into resolution problems, you can develop locally with the following in your consuming project's package.json as an alternative to npm link:


ependencies": {
"YOUR_ARCHETYPE_NAME": "file:../YOUR_ARCHETYPE_REPO"

evDependencies": {
"YOUR_ARCHETYPE_NAME_dev": "file:../YOUR_ARCHETYPE_REPO/dev"
Project Root

The enhancements to NODE_PATH that builder performs can throw tools / libraries for a loop. Generally speaking, we recommend using require.resolve("LIBRARY_OR_REQUIRE_PATH") to get the appropriate installed file path to a dependency.

This comes up in situations including:

The other thing that comes up in our Archetype configuration file is the general requirement that builder is running from the project root, not relative to an archetype. However, some libraries / tools will interpret "./" as relative to the configuration file which may be in an archetype.

So, for these instances and instances where you typically use __dirname, an archetype may need to use process.cwd() and be constrained to only ever running from the project root. Some scenarios where the process.cwd() path base is necessary include:

Avoid npm Lifecycle Commands

We recommend not using any of the special npm scripts commands listed in https://docs.npmjs.com/misc/scripts such as:

in your archetype scripts. This is due to the fact that the archetype package.json files are themselves consumed by npm for publishing (which can lead to tasks executing for the archetype instead of the project using the archetype) and potentially lead to awkward recursive composed task scenarios.

Instead, we recommend adding an npm:<task> prefix to your tasks to identify them as usable in root projects for real npm lifecycle tasks.

We plan on issuing warnings for archetypes that do implement lifecycle tasks in: https://github.com/FormidableLabs/builder/issues/81

Other Process Execution

The execution of tasks generally must originate from Builder, because of all of the environment enhancements it adds. So, for things that themselves exec or spawn processes, like concurrently, this can be a problem. Typically, you will need to have the actual command line processes invoked by Builder.

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:

ipts": {
ostinstall": "builder run npm:postinstall",
reversion": "builder run npm:preversion",
ersion": "builder run npm:version",
est": "builder run npm:test",
 other deps */

endencies": {
uilder": "v2.0.0",
uilder-react-component": "v0.0.5",
 other deps */

Dependencies": {
uilder-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:

… and (with assuredly a few minor hiccups) that's about it! You are Builder-free and back to a normal npm-controlled project.

This work is supported by the National Institutes of Health's National Center for Advancing Translational Sciences, Grant Number U24TR002306. This work is solely the responsibility of the creators and does not necessarily represent the official views of the National Institutes of Health.