README
jobsite
Tools for working with workspaces as defined by Yarn, Lerna, Bolt, etc.
npm i jobsite
Usage
Usage: jobsite [options] [command]
Options:
-c, --concurrency [number] The number of tasks to run at any given time. If true, then as many threads as possible are used.
-p, --packages [glob] Filters or finds workspaces that have a package.json and name that match the specified glob. If true, then it operates on all packages that have a name.
-w, --workspaces <glob> Filters or finds workspaces that have a path that match the specified glob.
-h, --help output usage information
Commands:
get Returns the available workspaces.
run <cmd> [args...] Runs <cmd> in each workspace and passes in <options>.
npm <cmd> [args...] Runs the specified npm commands, if they exist.
get
Returns the available workspaces.
$ jobsite get
$ jobsite get -w "packages/*"
run <cmd> [args...]
Runs
<cmd>
in each workspace and passes in<options>
.
$ jobsite run ls
$ jobsite run -- ls -la
$ jobsite run -p "package*" -- ls -la
$ jobsite run -w "packages/*" -- ls -la
It's recommended you use --
so that you can pass arguments to the command you
want to run.
npm <cmd> [args...]
Runs the NPM script specified by
<cmd>
in all workspaces that have the specified script defined in their package.json.
$ jobsite npm test
$ jobsite npm -p "package*" test
$ jobsite npm -w "packages/*" test
API
You can also use jobsite
as a module.
A workspace can be defined as:
type Workspace = {
path: string;
package: null | { [s: string]: string };
};
For the following examples, let's assume that we have the following workspaces:
const workspaces = [
{ path: "packages/a", package: { name: "a", scripts: { test: "jest" } } },
{ path: "packages/b", package: { name: "b", scripts: { test: "jest" } } }
];
And that we have a workspace definition in our package.json
that looks like:
{
"workspaces": ["packages/*"]
}
Our directory structure looks like:
- packages
- a/package.json
- b/package.json
async getWorkspacesPatterns()
Returns an array of the defined workspaces or null if none are specified. It supports Bolt, Lerna and Yarn workspace definitions.
const { getWorkspacesPatterns } = require("jobsite");
// ["packages/*"]
getWorkspacesPatterns().then(console.log);
Not only does it support Bolt, Lerna and Yarn definitions, it supports anything
that [cosmiconfig
])(https://github.com/davidtheclark/cosmiconfig) supports,
too. This means that you can define a .workspacesrc
file next to several repos
if you wanted to, and manage them with jobsite!
async getWorkspaces(glob: string | string[])
Expands the workspace glob into an array of
Workspace
objects.
If you don't specify glob
, it will use getWorkspacePatterns()
to try and
find workspaces.
const { getWorkspaces } = require("jobsite");
// Would return all packages.
getWorkspaces().then(console.log);
getWorkspacesPatterns("packages/*").then(console.log);
Filters
Filters are functions that return functions, than can be passed into
Array.prototype.filter
.
filterByPackageName(glob: string)
Returns a function that filters the workspaces by matching the glob to the package name.
const { filterByPackageName, getWorkspaces } = require("jobsite");
// Only returns package "b".
getWorkspaces()
.then(filterByPackageName("b"))
.then(console.log);
filterByPackageScript(script: string)
Returns a function that filters the workspaces that only have the specified script defined in their package.json, if one exists.
const { filterByPackageScript, getWorkspaces } = require("jobsite");
// Returns both packages.
getWorkspaces()
.then(filterByPackageScript("test"))
.then(console.log);
filterByPath(glob: string)
Returns a function that filters the workspaces by matching their path to the package name.
const { filterByPath, getWorkspaces } = require("jobsite");
// Only returns package "b".
getWorkspaces()
.then(filterByPath("*/b"))
.then(console.log);