lerna-script

Lerna is a nice tool to manage JavaScript projects with multiple packages, but sometimes you need more than it provides. lerna-script might be just the thing you need. It allows you to add custom tasks/scripts to automate multiple package management routine tasks. Some use cases:

• normalize package.jsons of all modules (ex. fix repo url, docs url) on pre-push/pre-commit;
• generate WebStorm project for all modules in repo;
• sync dependencies across all modules - ex. to have same version of mocha;
• have composite tasks (install, run npm scripts) to ease maintenance for large teams/OSS projects.
• regenerate readme's for root readme and all modules that are using ex. markdown-magic;
• whatever else you need.

Install

npm install --save-dev lerna-script

Usage

• Basic usage example
• Incremental builds
• Tasks
• Git hooks
• External presets

Basic usage example

Add lerna-script launcher to package.json scripts:

{
  "scripts": {
    "ls": "lerna-script"
  }
}

To start using, add lerna.js to root of your mono-repo and add initial task:

const {loadPackages, iter, exec} = require('lerna-script'),
  {join} = require('path')

module.exports.syncNvmRc = log => {
  log.info('syncNvmRc', 'syncing .nvmrc to all modules from root')

  return iter.parallel(loadPackages())(lernaPackage => {
    exec.command(lernaPackage)(`cp ${join(process.cwd(), '.nvmrc')} .`)
  })
}

And then you can run it:

npm run ls syncNvmRc

What happened here:

• you created lerna.js where each export is a task referenced by export name you can execute via lerna-script [export];
• you used functions from lerna-script which are just thin wrappers around lerna api;
• you created task to sync root .nvmrc to all modules so that all of them have same node version defined.

You could also fallback to lerna api and write same task as:

const Repository = require('lerna/lib/Repository'),
  PackageUtilities = require('lerna/lib/PackageUtilities'),
  {join} = require('path'),
  {execSync} = require('child_process')

module.exports.syncNvmRc = () => {
  const rootNvmRcPath = join(process.cwd(), '.nvmrc')

  return PackageUtilities.getPackages(new Repository()).forEach(lernaPackage => {
    execSync(`cp ${rootNvmRcPath}`, {cwd: lernaPackage.location})
  })
}

To see available function please check-out lerna-script, for pre-cooked tasks check-out tasks.

Incremental builds

Lerna provides a way to run commands (bootstrap, npm scripts, exec) either for all modules or a sub-tree based on git diff from a ref (master, tag, commit), but does not provide a way to run actions incrementally. One use case would be to run tests for all modules, once one of the modules fail, fix it an continue, so you don't have to rerun tests for modules that already passed. Or do a change and run tests for a subtree that might be impacted by a change given module dependency graph.

For this lerna-script provides means to both mark modules as built and filter-out already built modules:

const {loadPackages, iter, exec, changes, filters} = require('lerna-script')

module.exports.test = log => {
  return iter.forEach(changedPackages, {log, build: 'test'})(lernaPackage => {
    return exec.script(lernaPackage)('test')
  })
}

where property build on forEach marks processed package as built with label test. For different tasks you can have separate labels so they do not clash.

Tasks

lerna-script has some pre-assembled tasks/task-sets for solving some problem. Examples:

• idea - to generate WebStorm project for all modules in repo;
• npmfix - to fix repo, docs links for all modules matching their git path;
• modules - to align module versions across repo;
• depcheck - to run depcheck for all modules in repo;
• dependencies - group of tasks to manage/sync/update dependency versions for all modules.

Git hooks

Sometimes there are things you want to make sure are done/enforced on your modules like:

• linting all modules in repo;
• making sure some meta is normalized automatically across all modules;
• ...

Recommendation is to combine lerna-script with husky for running automatic actions on pre-push/pre-commit hooks. Then you don't have to think about it and it just happens automatically.

Say you want to make sure that repository url is valid for all modules and you don't leave it out when adding new module (via amazing copy/paste pattern).

For that you could add a lerna-script task to normalize repository and hook-it up to pre-push git hook.

First install husky:

npm install --save-dev husky

then add script to package.json

{
  "scripts": {
    "prepush": "lerna-script update-repo-urls"
  }
}

and add export to lerna.js:

const npmfix = require('lerna-script-tasks-npmfix')

module.exports['update-repo-urls'] = npmfix()

External presets

You can also use presets or otherwise tasks exprted by external modules. lerna-script by default reads tasks from lerna.js, but you can actually write tasks in any other file(module) and define it in your lerna.json like:

{
  "lerna-script-tasks": "./tasks.js"
}

So if you want to use presets from say module lerna-script-preset-wix-npm, you can just set it in lerna.json like:

{
  "lerna-script-tasks": "lerna-script-preset-wix-npm"
}