For-each-project NPM

for-each-project

Processes a set of project directories defined in a package.json file

About

for-each-project is one of several utility packages in the buildverse tool suite. It is a command-line utility that is intended to be invoked as part of an npm package script to process a set of project directories defined in the enclosing package.json file.

To see how some projects are using for-each-project, peruse the package.json files the following projects. Note that these projects will generally contain several package.json files spread across different folders within the project.

Like the concept of this project? Let other developers know with a tweet.

Installing

for-each-project requires

node version 4.8.4+

and, at your option, any of these package managers:

npm version 5.3.0+
pnpm version 1.16.0+
yarn version 1.1.0+

This package is automatically installed alongside all other packages in the buildverse tool suite with the single install command

npm install --save-dev buildverse

though it can be installed and used separately on its own by

npm install --save-dev for-each-project

if you wish to use it standalone.

Note the use of --save-dev since buildverse tool suite packages are typically used during development as opposed to being deployed in production, runtime environment.

Using

The following demonstration is for a Linux terminal session. Use on Windows systems is the same, albeit modulo Windows command-line idiosyncrasies such as the use of backslashes ('\') versus foreslashes ('/') for path separators, etc.

Commands

# Create a directory as a top-level development project,
# change into that directory and initialize a
# package.json file.
$ mkdir foobar-project
$ cd foobar-project
$ npm init -y

# Choose only one of the following install commands:
$ npm install --save-dev buildverse
# or
$ npm install --save-dev for-each-project

# Create a subdirectory as a subproject/package, change
# into that directory and initialize a package.json
# file.
$ mkdir foo
$ cd foo
$ npm init -y
$ cd ..

# For the purpose of this example, repeat for a second
# subproject/package.
$ mkdir bar
$ cd bar
$ npm init -y
$ cd ..

Result

At this point the foobar-project directory layout is:

foobar-project/
  bar/
    package.json
  foo/
    package.json
  node_modules/
    ...
  package.json
  package-lock.json

Configure package.json to use for-each-project

Now edit foobar-project/package.json making these changes:

add a private property with the value true,
change the test script to for-each-project apply-cmdline, and
add a buildverse section containing an array of subproject names (["foo", "bar"]) under the key, subprojects.

The result should look something like this (irrelevant fields omitted):

foobar-project/package.json:

{
  "private": true,
  "name": "foobar-project",
  "version": "1.0.0",
  "scripts": {
    "test": "for-each-project apply-cmdline"
  },
  "devDependencies": {
    "for-each-project": "^0.2.20"
  },
  "buildverse": {
    "subprojects": [
      "foo",
      "bar"
    ]
  }
}

Commands

From the command line now run the npm test script (while still in the foobar-project directory).

$ npm test

Output

> foobar-project@0.1.0 test /home/.../tmp/foobar-project
> for-each-project apply-cmdline

(cd foo && /usr/lib/node_modules/npm/bin/npm-cli.js test)

> foo@0.1.0 test /home/.../tmp/foobar-project/foo
> echo "Error: no test specified" && exit 1

Error: no test specified
npm ERR! Test failed.  See above for more details.
npm ERR! Test failed.  See above for more details.

Notice what happened. The effect of for-each-project apply-cmdline was to cause the shell to change into the foo subdirectory and execute the test script contained in the package.json file from that directory. At that point the npm test command abruptly ended with Test failed errors. This is because foo's test script shell command exited with code 1 which indicates failure:

echo \"Error: no test specified\" && exit 1`

Let's change that outcome to achieve a successful run. Edit the test script in both foo/package.json and bar/package.json to now read:

foo/package.json:

  "scripts": {
    "test": "echo testing-foo-subproject"
  }

bar/package.json:

  "scripts": {
    "test": "echo testing-bar-subproject"
  }

Commands

The effect now of running npm test from (the parent) directory foobar-project is that both subproject (child) directories foo and bar are visted and their respective test scripts are executed (since both their associated shell commands exited with code 0 which indicates success).

$ npm test

Output

> foobar-project@0.1.0 test /home/.../tmp/foobar-project
> for-each-project apply-cmdline

(cd foo && /usr/lib/node_modules/npm/bin/npm-cli.js test)

> foo@0.1.0 test /home/.../tmp/foobar-project/foo
> echo testing-foo-subproject

testing-foo-subproject
(cd bar && /usr/lib/node_modules/npm/bin/npm-cli.js test)

> bar@0.1.0 test /home/.../tmp/foobar-project/bar
> echo testing-bar-subproject

testing-bar-subproject

Summary

Summing up, when used in an npm package script for-each-project apply-cmdline does the following things:

Consults the package.json file in the current working directory for a special configuration object under the key buildverse. This object contains an array, subprojects, of directory pathnames representing (sub)projects. The pathnames are relative to the location of the containing package.json file.
Each directory entry in this array is then processed by:

Changing the current working directory to the given directory
Recursively executing the package manager program (npm, pnpm or yarn) with the same command line arguments that it was originally executed with.

If for-each-project is invoked with the --reverse switch, the directory set is processed in reverse order.

This is the bare bones of information you need to start using for-each-project in your own npm package scripts. See the Command-line Usage Docs section for detailed information about the for-each-project command.

Command-line Usage Docs

for-each-project command

Support

If you run into any problems or have constructive criticism, suggestions for improvement or just plain encouragement to offer please open or comment on an issue on GitHub.

Note that issues are managed under the buildverse-sdk umbrella project.

You can also show your support for this project by following BuildverseJS, @buildverse on Twitter or simply by letting other developers know with a tweet.

License

Currently this project is licensed GPLv3.

The author is working however towards gaining community-funding so as to make this a successful and sustainable, quality open-source project with an MIT license.