Building complex Node.js projects with the run-z utility

There are several dozen related packages in the Yarn Workspaces .

We need to collect a few of them. Frequently, quickly, and in the right order.

Existing tools either collect everything at once and for a long time, or assemble them in an arbitrary order, which is incorrect and not always possible.

Solution - run-z

Installation

npm install run-z --save-dev  #  NPM
yarn add run-z --dev          #  Yarn

Now package.jsonyou can add tasks to

{
  "scripts": {
    "all": "run-z build lint,test",
    "build": "run-z --then tsc -p .",
    "clean": "run-z --then shx rm -rf ./dist",
    "lint": "run-z --then eslint .",
    "test": "run-z --then jest",
    "z": "run-z"
  }
}

And run them

npm run all               #   ,  NPM
yarn all                  #   ,  Yarn

yarn clean build          #   ,  Yarn
npm run clean -- build    #   ,  NPM

npm run z -- clean build  #     `z`

, z. run-z, npm yarn. , :

yarn z --help
npm run z -- --help

, Yarn , NPM.

Yarn .

scripts package.json. run-z, .

run-z, :

run-z prerequisite1 prerequisite2 --then node ./my-script.js --arg

prereqiusite1, , — prerequisite2, — node ./my-script.js --arg.

:

• --then. , — , .
• NPM — scripts package.json, run-z. run-z npm run yarn run.
• , . .
• , package.json. . , .

. :

run-z test/--ci/--runInBand     #  `--ci`  `--runInBand`
                                #     NPM,
                                #   `test`.
run-z test //--ci --runInBand// #   .

, , run-z. , , /.

/. .

( ) /.

— /, , :

run-z test/attribute=value       #  `attribute`   `value`
                                 #   `test`
run-z build test attribute=value #  `attribute`   `value`
                                 #       .
run-z test/=if-present           #  `if-present=on`.

, :

• if-present , package.json, .
  
  , , .
• skip, .

run-z , . . , , . .

, . +, , .

, , . package.json:

{
  "scripts": {
    "test": "run-z +z jest",
    "z": "run-z +test/--runInBand"
  }
}

test, jest --runInBand.

, .

.

,

run-z clean build lint,test

lint test , build . build , clean.

. --then --and:

run-z copy-assets --and tsc -p .  #    
                                  # TypeScript .

. — . --max-jobs ( -j):

run-z build,lint,test -j2          #    .
run-z build,lint,test -max-jobs 1  #   .
run-z build,lint,test -j0          #  .

:

run-z ../package1 build test . build test

build test ../package1, — .

., .., ./ ../ — URL . , , .

— — . . :

run-z ./packages//  build #  `build`   
                          #    `./packages`.
run-z ./packages/// build #  `build`   `./packages`
                          #        .

// . /// . package.json .

. :

run-z ./3rd-party// ./packages// build #  `build`   
                                       #   `./3rd-party`
                                       #  `./packages`.

. , — . .

--batch-parallel, --bap:

run-z --batch-parallel ./packages// lint #  `lint`   
                                         #   `./packages
                                         # .

"" . .

. (-), . .

package.json:

{
  "scripts": {
    "each": "run-z ./3rd-party// ./packages//"
  }
}

3rd-party/ packages/:

yarn each /build each /test  #  `build`,   `test`   .  

( Yarn Workspaces) .

, package.json:

{
  "scripts": {
    "all/*": "run-z ./packages//",
    "z": "run-z"
  }
}

"all/*" — . , :

yarn z build --all       #  `build`   .

--all, run-z , , .

"_/_". "_/*", "_". , , :

{
  "scripts": {
    "all/*": "run-z ./packages//",
    "all/test": "run-z ./packages// +test/--runInBand",
    "z": "run-z"
  }
}

yarn z build --all  #  `build` .
yarn z test --all   #  `test`    `--runInBand`.

:

yarn build --with-deps        #  `build`  
                              #    .
yarn build --only-deps        #  `build`   .
yarn build --with-dependants  #  `build`  ,
                              #      .
yarn build --only-dependants  #  `build`    .

npm-run-all

npm-run-all — . .

, TypeScript, Rollup, ESLint Jest:

{
  "scripts": {
    "all": "run-p --aggregate-output build:all \"test {@}\" --",
    "build": "rollup --config ./rollup.config.js",
    "build:all": "run-p --aggregate-output rebuild lint",
    "ci:all": "run-p --aggregate-output build:all ci:test",
    "ci:test": "jest --ci --runInBand",
    "clean": "shx rm -rf d.ts dist target",
    "lint": "eslint .",
    "rebuild": "run-s clean build",
    "test": "jest",
  }
}

run-p . run-s — .

:

{
  "scripts": {
    "all": "run-z build,lint,test",
    "build": "run-z +z rollup --config ./rollup.config.js",
    "ci:all": "run-z all +test/--ci/--runInBand",
    "clean": "run-z +z --then shx rm -rf d.ts dist target",
    "lint": "run-z +z --then eslint .",
    "test": "run-z +z --then jest",
    "z": "run-z +build,+doc,+lint,+test"
  }
}

1. "ci:test" CI . "test".
2. "build:all" . .
3. "rebuild" , : yarn clean build.
4. "z". , . yarn build lint test . , .
5. run-z. , , , yarn clean build.
6. , run-z , . run-p run-s . V8 .

— . , , thread_workers. . , . shx rm. , , , .