run-shared-scripts

Define and run shared scripts of a monorepo using Yarn workspaces, Bolt, Lerna or pnpm

Install

$ npm install --save-dev run-shared-scripts

Usage

Using npm-scripts is a convenient way to run our CI/CD tasks, and we may have some similar "scripts" in a monorepo workspaces. Take the following monorepo for example.

.
├── lerna.json
├── package.json
└── packages
    ├── project-a
    │   ├── index.js
    │   ├── node_modules
    │   └── package.json
    ├── project-b
    │   ├── index.js
    │   ├── node_module
    │   └── package.json
    ...

The "scripts" defined in ./packages/project-a/package.json and ./packages/project-b/package.json is similar.

  "scripts": {
    "clean:build": "rimraf dist lib es",
    "clean:coverage": "rimraf ./test/coverage",
    "clean": "run-p clean:build clean:coverage",
    "build:esm": "tsc --module esnext --target es2015 --outDir ./es",
    "build:cjs": "tsc --module commonjs --target es5 --outDir ./lib",
    "build:umd": "rollup -c",
    "build:style": "../../scripts/build-style.js",
    "build": "run-p build:style build:cjs build:esm build:umd",
    "prebuild": "run-s lint clean",
    "test": "jest",
    "coveralls": "cat ./test/coverage/lcov.info | coveralls",
    "pretest": "run-p clean:coverage",
    "prepare": "yarn build"
  }

Basic Usage

Then we can use run-shared-scripts to define and run these similar "scripts".

1. Add rss config in the monorepo root's ./package.json file.

  "rss": {
    "clean:build": "rimraf dist lib es",
    "clean:coverage": "rimraf ./test/coverage",
    "clean": "run-p clean:build clean:coverage",
    "build:esm": "tsc --module esnext --target es2015 --outDir ./es",
    "build:cjs": "tsc --module commonjs --target es5 --outDir ./lib",
    "build:umd": "rollup -c",
    "build:style": {
      "file": "./scripts/build-style.js" // path relative to monorepo's root directory
    },
    "build": "run-p build:style build:cjs build:esm build:umd",
    "prebuild": "run-s lint clean",
    "test": "jest",
    "coveralls": "cat ./test/coverage/lcov.info | coveralls",
    "pretest": "run-p clean:coverage",
    "prepare": "yarn build"
  }

Note that the "build:style" command define the task to run an executable file. The executable file path must be an absolute path or a path relative the monorepo's root directory.

1. Replace with rss command in ./packages/project-a/package.json and ./packages/project-b/package.json.

  "scripts": {
    "clean:build": "rss",
    "clean:coverage": "rss",
    "clean": "rss",
    "build:esm": "rss",
    "build:cjs": "rss",
    "build:umd": "rss",
    "build:style": "rss",
    "build": "rss",
    "prebuild": "rss",
    "test": "rss",
    "coveralls": "rss",
    "pretest": "rss",
    "prepare": "rss"
  }

Run specified task

The rss command run the same named(the key of "scripts") task by default. We can pass a task name to specify the task to run.

  "scripts": {
    "clean": "rss clean:build" // run "clean:build" task defined in the "rss" config
  }

Run with arguments

Arguments before -- separator are rss command args.

  "scripts": {
    "test": "rss --dry-run" // dry-run model
  }

Arguments after -- separator will pass to task.

  "scripts": {
    "test": "rss -- --watch" // => "jest --watch"
  }

Argument placeholders

We can use placeholders to define the "rss" scripts.

• {1}, {2}, ... -- An argument. {1} is the 1st argument. {2} is the 2nd.
• {@} -- All arguments.
• {*} -- All arguments as combined.
• {n=defaultValue} -- An argument with default value. n is the n-th argument.

  "rss": {
    "s1": "server --port {1}",
    "s2": "server -a {1} --port {2}",
    "s3": "server {@}",
    "s4": "server {*}",
    "s5": "server --port {1=8080}",
    "s6": "server --port1 {1=8080} --port2 {1}",
    "s7": "server -a {1=0.0.0.0} --port {2=8080}"
  }

Then pass your args in the "scripts".

  "scripts": {
    "s1": "rss -- 8080",         // => "server --port 8080"
    "s2": "rss -- 0.0.0.0 8080", // => "server -a 0.0.0.0 --port 8080"
    "s3": "rss -- -a 0.0.0.0 --port 8080", // => "server -a 0.0.0.0 --port 8080"
    "s4": "rss -- -a 0.0.0.0 --port 8080", // => "server '-a 0.0.0.0 --port 8080'"
    "s5-1": "rss s5",         // => "server --port 8080"
    "s5-2": "rss s5 -- 9090", // => "server --port 9090"
    "s6-1": "rss s6",         // => "server --port1 8080 --port2 8080"
    "s6-1": "rss s6 -- 9090", // => "server --port1 9090 --port2 9090"
    "s7-1": "rss s7",                    // => "server -a 0.0.0.0 --port 8080"
    "s7-2": "rss s7 -- '' 9090",         // => "server -a 0.0.0.0 --port 9090"
    "s7-3": "rss s7 -- 127.0.0.1 9090",  // => "server -a 127.0.0.1 --port 9090"
  }

Contributing

Please let us know how can we help. Do check out issues for bug reports or suggestions first.

To become a contributor, please follow our contributing guide.

License

The scripts and documentation in this project are released under the MIT License