lerna / lerna

:dragon: Lerna is a fast, modern build system for managing and publishing multiple JavaScript/TypeScript packages from the same repository.

Important note: this project recently changed stewardship to Nrwl!

Your favorite tool is alive and well: https://blog.nrwl.io/lerna-5-1-new-website-new-guides-new-lerna-example-repo-distributed-caching-support-and-speed-64d66410bec7

Lerna is a fast, modern build system for managing and publishing multiple JavaScript/TypeScript packages from the same repository.

---

A few links to help you get started:

• lerna.js.org: Documentation, Guides, Interactive Tutorials
• Getting Started
• Features
• Official Nx and Lerna YouTube Channel
• Blog Posts About Lerna and Nx

Engage with the Core Team and the Community

• Follow Lerna on Twitter
• Community Discord, #forum channel

Want to help?

If you want to file a bug or submit a PR, read up on our guidelines for contributing

Core Team

Victor Savkin	James Henry	Austin Fahsl
vsavkin	JamesHenry	fahslaj

Benjamin Cabanes	Juri Strumpflohner
bcabanes	juristr

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Jeff Cross 💼	Daniel Stockman 💻 📖 🚇 🚧	Jamie Kyle 💻 📖 🚇 🚧	Henry Zhu 💻 📖 🚧	Bo Borgerson 💻 🚧
Sebastian 💻	Joscha Feth 💻 🐛	Norbert Csaba Herczeg 💻	Douglas Wade 💻

This project follows the all-contributors specification. Contributions of any kind welcome!

lerna's Issues

Why does `lerna bootstrap` not `npm link`?

Hi!

Can anyone explain why lerna bootstrap doesn't do npm link? Instead, I only see a pattern like this in, for example, /Users/justin/path/to/monorepo/packages/pkg2/node_modules/pkg1

module.exports = require("/Users/justin/path/to/monorepo/packages/pkg1");

By npm linking or by some other means, I'm trying to write a monorepo where each package has the following structure:

pkg1:
index.js
a/
b/

I would like inter-dependent repos to be "installed" / linked in such a way as to be able to require/import files like so:

require('pkg1');
require('pkg1/a');
require('pkg1/b');

i.e. lerna bootstrap's solution won't allow this, since only pkg1's main index.js file is exported:

module.exports = require("/Users/justin/path/to/monorepo/packages/pkg1");

Any ideas? Thanks!

Should changed packages include cross-depencies?

Right now when publishing a new version we:

1. Find all the changed packages by checking their diffs. ref
2. Cross check these "changed packages" for cross-deps and update them in package.json. ref
3. However, we don't update cross-dependencies outside of the original changed packages. (ref1, ref2)

I feel like this will cause issues with major versions. Because we're relying on npm's ^x.x.x version matching for minor and patch versions outside of the changed packages.

[Feature] Check npm login and registry before publishing

If you aren't logged in to npm, lerna should stop and ask you to login. It would be good if it logged you back out afterwards.

--dryrun

lerna publish --dryrun would be nice to have, which could show you what would happen when you put publish!

Or maybe lerna dryrun just to be safer.

Linking of Internal Packages Not Working in TravisCI

First referenced here #50 but @thejameskyle recommended this be a separate issue.

I have several packages that are linked/published by lerna https://github.com/dtothefp/build-boiler. I run lerna bootstrap on travis and it seems to complete successfully, but when I run my build task via gulp the internal packages that are "linked" by lerna cannot be found.

https://travis-ci.org/dtothefp/build-boiler/builds/116948869

But upon running the build task in my module which depends upon some of my linked `packages` it seems the the `npm link` has failed

Error: Cannot find module '/home/travis/build/dtothefp/build-boiler/packages/boiler-utils'

New logging interrupts progress bar display

Since #63 landed, I've noticed some degradation in the progress output (but no regression in the ultimate result) of NPM_DIST_TAG=monorepo lerna publish:

...
Publishing tagged packages...
Setting latest npm tags...
Removing temporary npm dist-tag
Adding monorepo npm dist-tag
@zillow/module-a                                   ╢███████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░╟Removing temporary npm dist-tag
Adding monorepo npm dist-tag
@zillow/module-b                                   ╢██████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░╟Removing temporary npm dist-tag
Adding monorepo npm dist-tag
@zillow/module-c                                   ╢█████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░╟Removing temporary npm dist-tag
Adding monorepo npm dist-tag
@zillow/module-d                                   ╢████████████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░╟Removing temporary npm dist-tag
Adding monorepo npm dist-tag
@zillow/module-e                                   ╢███████████████████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░╟Removing temporary npm dist-tag
Adding monorepo npm dist-tag
@zillow/module-f                                   ╢██████████████████████████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░╟Removing temporary npm dist-tag
Adding monorepo npm dist-tag
@zillow/module-g                                   ╢█████████████████████████████████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░╟Removing temporary npm dist-tag
Adding monorepo npm dist-tag
@zillow/module-h                                   ╢████████████████████████████████████████████████████████░░░░░░░░░░░░░░░░░░░░░╟Removing temporary npm dist-tag
Adding monorepo npm dist-tag
@zillow/module-i                                   ╢███████████████████████████████████████████████████████████████░░░░░░░░░░░░░░╟Removing temporary npm dist-tag
Adding monorepo npm dist-tag
@zillow/module-j                                   ╢██████████████████████████████████████████████████████████████████████░░░░░░░╟Removing temporary npm dist-tag
Adding monorepo npm dist-tag
...

The Removing temporary npm dist-tag message actually looks wrapped to the next line on my terminal, but apparently copying the output reveals there is no actual newline.

It used to update a single progress bar, like you'd expect. Now it doesn't. Not the end of the world, just something that might benefit from a "hidden" level of logging (stored for potential debug.log) instead of output to the console.

`git rev-list --tags --max-count=1` fails

It wants me to put master after rev-list in order to function.

Using lerna as a library

Hi, I'm trying to build a couple of tools on top of lerna, but I don't want to duplicate logic inside of lerna. Especially since it seems to be in flux right now and I don't want to keep updating things.

It would be cool if you could require("lerna") and call methods like getPackagesDirectory() or getPackages().

I can open a PR for this

Should major releases update all packages?

I updated my packages from 9.0.x to 10.0.0 today and noticed only some of my packages were updated (the ones changed since the last publish, which didn't use lerna yet). I feel like that makes sense for patch and minor releases, but for majors it probably makes sense to publish all packages and update all dependencies – otherwise I can imagine that it is going to give some headaches.

What do you think?

Private NPM Modules

A little while back I tested lerna with private npm modules and prima facie it didn't seem to work.

Do you know if anyone has used it with private modules and whether or not this currently works? If not, I might look at creating a pull request to support them.

Git push only current branch

We're currently pushing every branch on lerna publish which breaks the publishing process if you have branches that are rejected.

Publishing tagged packages...
Setting latest npm tags...
Removing temporary npm dist-tag
Adding latest npm dist-tag
npm WARN dist-tag add latest is already set to version 1.0.0
To ssh://[email protected]
   aafeff6..f74cc37  master -> master
 ! [rejected]        form -> form (non-fast-forward)

Testing

Testing is like... really hard and stuff.

We should test though, because it's really hard to make changes on this repo with confidence.

Remove NPM_DIST_TAG in favor of --canary and --tag name

I'm pretty new versioning packages using npm and feels pretty conformable with the canary strategy over custom tags.

The question is, does it make sense to keep NPM_DIST_TAG over --canary or --tag name?

Thanks!

[Feature] lerna owners

It's rather tedious to have to add npm owners to every project. It would be nice to have commands that could do the following operations in every package.

$ lerna owners add username
$ lerna owners rm username

Which would do the following actions.

$ npm add owner username package
$ npm rm owner username package

It'd be even nicer if it tracked the owners so that when you added a new package it would add them all.

Would work well with #42

[Feature] Allow custom publish subdirectory

EDIT: I overlooked package/[name]/scripts/prepublish.js, so that's awesome. It would however be a bit difficult to customize the directory in which npm publish is run just with a prepublish script. I'll adjust this issue to recommend adding a way to customize that publish directory, since it's hard-coded in publishTaggedInDir.

---

It would be awesome to be able to customize the publish behavior (like the publish directory) - for my use case, I build the packages like packages/abc/src into a directory called packages/abc/dist, then copy the package.json into dist and publish from there (to have a flat module structure). I've gotten it working for now by overriding the exports of npmUtils, but in the future it would be awesome to be able to customize this step:

#!/usr/bin/env node

// Wrapper script that patches lerna with our custom publish path

import child from 'child_process';
import logger from 'lerna/lib/utils/logger';
import path from 'path';

const newPublishTaggedInDir = logger.logifyAsync('npmUtils.publishTaggedInDir', (tag, dir, callback) => {
  const cmd = `cd ${dir}/dist && cp ../package.json . && npm publish --tag ${tag}`;
  child.exec(cmd, (err, stdout, stderr) => {
    callback(stderr || err, stdout);
  });
});

// Manually require npmUtils to load it into the cache
require('lerna/lib/utils/npmUtils');

// Patch the exports
const modulePath = path.resolve(__dirname, '../node_modules/lerna/lib/utils/npmUtils.js');
require('module')._cache[modulePath].exports.publishTaggedInDir = newPublishTaggedInDir;

// Run the original binary
require('lerna/bin/lerna');

Cross-dependency version not updated during publish

Hi there. Just getting started with lerna. Very cool.

I've experienced unexpected behavior. Not sure yet if I did something wrong or if this was a bug.

I have a project with two packages. The react-server package depends on react-server-gulp-module-tagger.

I've just published v0.0.6 which introduces this dependency.

What I thought would happen: The lerna publish updates the version in react-server's devDependencies to point to the newly published version.

What actually happened: The devDependency version was not modified. This causes lerna bootstrap to fail in travis ci and breaks our build. Strangely lerna bootstrap still works fine locally.

I'm confused. Have I set up the cross-dependency incorrectly? Has something gone wrong during publish?

Thanks!

Bo

[Feature] Option instead of lastTag/lastRelease for updated packages

Right now we figure out what packages to publish based on a git diff of the lastTag.

However in the case of a backport (you might publish v5.x.x after a v.6.x.x) and now the lastTag is actually v5.x.x, so maybe you should be able to pass in a tag, otherwise default to the latest (we should log out the last tag if we aren't already or prompt it).

Windows paths are broken

While generating index.js files Lerna doesn't escape the backslashes. This produces files like this:

module.exports = require("D:\src\babel\babel\packages\babel-messages");

lerna bootstrap for a single (new package)

We probably don't want to lerna bootstrap each each we create a new package so it should just npm install and link up that new package?

Should lerna bootstrap install deps individually

Right now we're just executing npm install in each package directory. However, because of the "linked" dependencies, we have an order of operations issue, either we end up installing over the linked dependencies or we try installing dependencies that do not exist.

A possible solution to this might be manually writing out what we want to install:

{
  "dependencies": {
    "a": "1.0.0",
    "b": "2.0.0"
  }
}

$ npm install [email protected] [email protected]

This might fix #59. Also I wonder if this will make npm any faster because we're explicitly asking it for things, probably not, but maybe.

lerna run stderr

lerna run test is great for running tests against collections of packages, but it's hard to determine from the error message (in my case, Run script failed Errored while running npm script 'test' in packages.) which package failed and how. Could it output the package that failed, or its stderr?

[Bug] README.md is not published to npm

When I try lerna publish - npm registry doesn't display readme, however when I use npm publish - it does.

[Feature] lerna --dryrun

Hi,

Really liking lerna so far. However I've encountered some unexpected behavior that wound up getting pushed to our public repo and published to npm.

I'd like to be able to run lerna publish to the point of creating the version commit and tag and stop it there so I can inspect what it did before proceeding.

My first thought for an interface for this is:

$ lerna prepublish
... make sure everything's as expected...
$ lerna publish

Where in this case lerna publish would see that the head revision is a version tag and skip the prepublish steps.

It might also be nice to have a lerna revert that's basically just git reset --hard HEAD^ after verifying that the HEAD revision is a version commit.

I'd be happy to do the work for this and submit a PR if you're open to the idea. How does it sound? Ideas for a better interface?

Thanks!

Bo

Nested directory support

I currently access packages like this import { foo } from 'foo/bar';. It seems the current bootstrap only creates node_modules/foo/index.js with module.exports = require('/full/path/packages/foo');. Thus when accessing foo/bar, it Error: Cannot find module.

What would be the best path forward for supporting this? The only thing I can think of is to find all *.js paths and then create that path with matching exports.

Strategy for new versions

I'm a little confused by the workflow lerna carves out for new major point versions of a library. In my example, Turf is, in 3.0.0, going to be a monorepo project instead of ~45 little repos. So right now I have a monorepo, with lots of newly-merged-in packages with 3.0.0 versions in their package.jsons, and a branch with a 3.0.0 in the VERSION file.

What has worked sometimes and what I expected to be the workflow was that I'd run lerna and all of the 3.0.0 packages (which are not released) would link to each other, and that'd be it. But reading the code & diagnosing an issue today, I'm seeing that lerna runs npm install before it links dependencies, so it doesn't appear to be possible to reference unreleased versions in my repo. Is this the intentional design, and if so, how should lerna-based projects build major point releases?

lerna changelog

Could print out a simple changelog of commits since the last tag/release?

Can be on by default after lerna publish but can be run seperately.

Example: git log git describe --tags --abbrev=0..HEAD --pretty=format:' * %s (%an)' | grep -v 'Merge pull request'

Changed Folder Structure

Hi, I was trying lerna for a test project and it was all going fine until I decided to rename my modules in packages.

After I changed the name even if I delete node and npm and then reinstall lerna I get the follow:

There was a problem publishing.
Error: Command failed: git rev-list --tags --max-count=1
usage: git rev-list [OPTION] <commit-id>... [ -- paths... ]

I was able to bootstrap and publish without any issues prior to folder renaming.

I have a .git folder. I've tried starting again with a fresh folder and project, restarting my computer...no luck, it's dead in the water.

Is their some state being managed somewhere globally? I couldn't find anything that suggested their was, but it feels like something is amiss.

npmInstallInDir and linkDepedendenciesForPackage happen in wrong order

It looks like 4ecfff5 reversed the order of npmInstallInDir and linkDependenciesForPackage occur, so lerna bootstrap fails if the local packages have not previously been published to npm.

I'm happy to submit a PR to fix, but given how small that commit is, it seems like this was done intentionally.

Validate versions before publishing

I've screwed up multiple publishes now because of being in a bad state.

I want a couple of things:

• Version prompts should show the current version locally
• Lerna should make sure that the current version exists on npm before publishing a new version. Only skipping when the current version is 0.0.0 (we need to improve the first publish process more anyways)
• Lerna should confirm the versions that you've input before continuing.

This leaves a lot less room to mess things up.

Don't use semver ranges

Currently, if a library relies on a Babel package and they try to lockdown the dependency version they will invariably get updates since Babel packages uses "^" all over. That means that if we do a release with a regression we would break people's packages and CI's even though they tried to lock down the version.

A core feature of monorepos is explicit dependency management. Since we update everything atomically we have the opportunity to lockdown dependencies. That may mean more minor version releases but that also means more safety.

What does it mean to "link together" packages?

Bootstrap

$ lerna bootstrap

1. Link together all packages that depend on each other.
2. npm install all other dependencies of each package.

What does the first point actually mean? Does it use npm link?

pre-release is not a dist-tag on <lib>

When publishing with lerna, the packages do publish, but NPM takes a dump on me by saying:

prerelease is not a dist-tag on [library]

I'm sure there's just some setting I need to do on my repo to fix this, however your docs should probably mention something on it.

---

Otherwise, great lib! It's saving my life on this project.

Version tags not automatically pushed

Hi,

After each lerna publish I've found that I need to git push origin <tag>.

It looks like this should happen automatically. That's what the --follow-tags option is for, right?

I'm using the master branch of lerna (since v1.1.0 doesn't actually work for me).

I'm on git version 2.6.2.

Thanks,

Bo

Independent mode

Talked to @kittens about this the other day.

I have a project where I want all the packages to be in the same repo, to be tested together and for versions to be bumped for inter-dependencies. However we don't want all the versions to be locked together.

I'm suggesting adding an --independent flag (name can be whatever) that will not force the same version on all packages and will instead prompt for versioning in each package that has been changed.

no carrot breaks on unpublished modules

For example in /packages/a/package.json, if I have "dependencies": { "b": "1.0.0" } if b is not published it will throw an error:

npm ERR! 404 Registry returned 404 for GET on https://registry.npmjs.org/b

OTOH if I use "dependencies": { "b": "^1.0.0" } then it will work

This is all assuming that b is in the packages directory and has a version of 1.0.0

Something else I noticed was that after I successfully bootstrap with a carrot, I can then remove the carrot and subsequent calls to bootstrap will work

lerna publish --tag

We should be able to publish tagged releases like prerelease or next easily.

$ lerna publish --tag prerelease
$ lerna publish --tag next

Windows Support

Based on how paths are handled alone, there's likely a lot of issues with windows.

lerna init

Rather than running the init script every single time, I think it'd be good to split that out into a lerna init command that did the same thing.

When you run any other command in a directory that hasn't been initialized using lerna init then it would just error.

This prevents weirdness when accidentally running lerna in a subdirectory which currently will just setup a new lerna repo.

Add verbose logging

We should log everything and then when an error occurs we should dump all of logs so we can diagnose issues like #37

added packages to packages/ folder but `bootstrap` does not link them

hello!

i added two existing projects to my root/packages folder. i cleared the node_modules, and attempted to lerna bootstrap. it does not link the packages. A uses B. I tried updating A's package.json to specify the exact version of B that is in root/packages, but to no avail.

tips?

thx

Error running `lerna updated`

Hi, I'm trying to run lerna on an existing monorepo. I've run lerna bootstrap without issues, but I'm seeing this error when running lerna updated:

Checking packages...
fatal: No annotated tags can describe 'af2c265fda2e7a93c4f6881b747e6f398d4e7c8d'.
However, there were unannotated tags: try --tags.
child_process.js:484
    throw err;
    ^

Error: Command failed: git describe af2c265fda2e7a93c4f6881b747e6f398d4e7c8d
fatal: No annotated tags can describe 'af2c265fda2e7a93c4f6881b747e6f398d4e7c8d'.
However, there were unannotated tags: try --tags.

    at checkExecSyncError (child_process.js:441:13)
    at Object.execSync (child_process.js:481:13)
    at execSync (/usr/local/lib/node_modules/lerna/lib/commands/updated.js:63:16)
    at Object.exports.checkUpdatedPackages (/usr/local/lib/node_modules/lerna/lib/commands/updated.js:30:23)
    at Object.exports.execute (/usr/local/lib/node_modules/lerna/lib/commands/updated.js:9:33)
    at Object.<anonymous> (/usr/local/lib/node_modules/lerna/bin/lerna.js:41:9)
    at Module._compile (module.js:435:26)
    at Object.Module._extensions..js (module.js:442:10)
    at Module.load (module.js:356:32)
    at Function.Module._load (module.js:311:12)

Any idea what could be wrong?

lerna publish --only

Not every change in a package needs to be published. For example if I just update a test I don't want to publish that. It might be cool if you could have a files array/glob of what you publish:

$ lerna publish --only package.json,README.md,src/**

Would work well with #42

lerna diff

Whenever I run lerna updated and find something I didn't expect in there I immediately want to see the diff. It would be great if lerna could easily show me that.

$ lerna diff
$ lerna diff package-name

Rewrite README

• lerna-temp tag
• support for @org/packages
• #44
• #36
• #45
• removed stable tag
• exposed api #75
• dev/canary release #65

Support scope packages

First thanks for this amazing package. I would like to use it within my project, but I'm using npm scoped packages which is not supported by lerna, yet. Before I start writing the PR, I would like to know if you would accept a PR for that.

lerna.json

Adding configuration and state to repos through CLI flags and separate files is going to get crazy. We should have one place for all of this in a repo.

{
  "version": "1.0.0",
  "independent": false,
  "owners": [
    "kittens",
    "thejameskyle",
    "hzoo"
  ],
  // ...
}

Prepublish

I'm exploring converting a project to Lerna, it was based on Babel's old script system.

One thing I added was some tasks before publish depending on the package. Like we have a webpack that builds a production build before publishing in some packages.

Not sure if that exists here already? Some way to have certain packages run things before they publish?

Should Lerna support Mercurial?

One of the concerns about monorepos is that git doesn't scale well for massive repositories, and while there is lots of work being done to improve this. Today mercurial has much better support for it, companies like Facebook and Google both use mercurial for large scale projects (@kittens you probably have insight on this).

Do we want to consider dual-supporting both git and mercurial? I haven't used mercurial before, but based on some initial reading I don't think it'd be hard to abstract out our git operations that could support both.

[Feature] Better exiting on publish

Right now if stuff starts erroring out or you cancel before everything is finished lerna doesn't completely roll back. It would be nice if it could handle this more gracefully.

[Feature] Adding cross-dependencies

It's kinda awkward right now to cd into a package directory and install a dependency, cd back up and run lerna bootstrap again.

Is there a way we can abstract this?

Something along the lines of:

$ lerna add [package] dependency
$ lerna add [package] dependency --dev
$ lerna add [package] dependency --peer

Update: We should match Yarn's API for adding.