This is our first semver major release since the release of
npm@3 just over a year ago. Back then,
@3 turned out to be a bit of a ground-shaking release, with a brand-new installer with significant structural changes to how npm set up your tree. This is the end of an era, in a way.
npm@4 also marks the release when we move both
npm@3 into maintenance: We will no longer be updating those release branches with anything except critical bugfixes and security patches.
While its predecessor had some pretty serious impact,
npm@4 is expected to have a much smaller effect on your day-to-day use of npm. Over the past year, we've collected a handful of breaking changes that we wanted to get in which are only breaking under a strict semver interpretation (which we follow). Some of these are simple usability improvements, while others fix crashes and serious issues that required a major release to include.
We hope this release sees you well, and you can look forward to an accelerated release pace now that the CLI team is done focusing on sustaining work -- our Windows fixing and big bugs pushes -- and we can start focusing again on usability, features, and performance. Keep an eye out for
npm@5 in Q1 2017, too: We're planning a major overhaul of
shrinkwrap as well as various speed and usability fixes for that release. It's gonna be a fun ride. I promise.
BRIEF OVERVIEW OF BREAKING CHANGES
The following breaking changes are included in this release:
npm searchrewritten to stream results, and no longer supports sorting.
npm scriptsno longer prepend the path of the node executable used to run npm before running scripts. A
--scripts-prepend-node-pathoption has been added to configure this behavior.
npathas been removed.
prepublishhas been deprecated, replaced by
prepublishOnlyscript has been temporarily added, which will only run on
npm outdatedexits with exit code
1if it finds any outdated packages.
npm taghas been removed after a deprecation cycle. Use
- Partial shrinkwraps are no longer supported.
npm-shrinkwrap.jsonis considered a complete installation manifest except for
- npm's default git branch is no longer
master. We'll be using
latestfrom now on.
SEARCH REWRITE (BREAKING)
Let's face it --
npm search simply doesn't work anymore. Apart from the fact that it grew slower over the years, it's reached a point where we can no longer fit the entire registry metadata in memory, and anyone who tries to use the command now sees a really awful memory overflow crash from node.
It's still going to be some time before the CLI, registry, and web team are able to overhaul
npm search altogether, but until then, we've rewritten the previous
npm search implementation to stream results on the fly, from both the search endpoint and a local cache. In absolute terms, you won't see a performance increase and this patch does come at the cost of sorting capabilities, but what it does do is start outputting results as it finds them. This should make the experience much better, overall, and we believe this is an acceptable band-aid until we have that search endpoint in place.
Incidentally, if you want a really nice search experience, we recommend checking out npms.io, which includes a handy-dandy
npms-cli for command-line usage -- it's an npm search site that returns high-quality results quickly and is operated by members of the npm community.
2b8057b#13746 Stream search process end-to-end. (@zkat and @aredridel)
87d504e#13746 Updated search-related tests. (@zkat)
SCRIPT NODE PATH (BREAKING)
Thanks to some great with by @addaleax, we've addressed a fairly tricky issue involving the node process used by
Previously, npm would prefix the path of the node executable to the script's
PATH. This had the benefit of making sure that the node process would be the same for both npm and
scripts unless you had something like
node-bin in your
node_modules. And it turns out lots of people relied on this behavior being this way!
It turns out that this had some unintended consequences: it broke systems like
nyc, but also completely broke/defeated things like
virtualenv by often causing things that relied on them to fall back to the global system versions of ruby and python.
In the face of two perfectly valid, and used alternatives, we decided that the second case was much more surprising for users, and that we should err on the side of doing what those users expect. Anna put some hard work in and managed to put together a patch that changes npm's behavior such that we no longer prepend the node executable's path by default, and adds a new option,
--scripts-prepend-node-path, to allow users who rely on this behavior to have it add the node path for them.
This patch also makes it so this feature is discoverable by people who might run into the first case above, by warning if the node executable is either missing or shadowed by another one in
PATH. This warning can also be disabled with the
--scripts-prepend-node-path option as needed.
378ae08#13409 Add a
--scripts-prepend-node-pathoption to configure whether npm prepends the current node executable's path to
70b352c#13409 Change the default behaviour of npm to never prepending the current node executable’s directory to
PATHbut printing a warning in the cases in which it previously did. (@addaleax)
Let's be real here -- almost no one knows this feature ever existed, and it's a vestigial feature of the days when the ideal for npm was to distribute full packages that could be directly developed on, even from the registry.
It turns out the npm community decided to go a different way: primarily publishing packages in a production-ready format, with no tests, build tools, etc. And so, we say goodbye to
prepublish DEPRECATED (BREAKING)
If there's anything that really seemed to confuse users, it's that the
prepublish script ran when invoking
npm install without any arguments.
Turns out many, many people really expected that it would only run on
npm publish, even if it actually did what most people expected: prepare the package for publishing on the registry.
And so, we've added a
prepare command that runs in the exact same cases where
prepublish ran, and we've begun a deprecation cycle for
prepublish itself only when run by
npm install, which will now include a warning any time you use it that way.
We've also added a
prepublishOnly script which will execute only when
npm publish is invoked. Eventually,
prepublish will stop executing on
npm install, and
prepublishOnly will be removed, leaving
prepublish as two distinct lifecycles.
prepublishOnlylifecyle events. (@othiym23)
52fdefd#14290 Warn when running
npm pack. (@othiym23)
npm install. (@zkat)
npm help package.jsondocumentation. (@zkat)
NO MORE PARTIAL SHRINKWRAPS (BREAKING)
That's right. No more partial shrinkwraps. That means that if you have an
npm-shrinkwrap.json in your project, npm will no longer install anything that isn't explicitly listed there, unless it's a
devDependency. This will open doors to some nice optimizations and make use of
npm shrinkwrap just generally smoother by removing some awful corner cases. We will also skip
devDependency installation from
package.json if you added
devDependencies to your shrinkwrap by using
npm shrinkwrap --dev.
readShrinkwrapto read top level shrinkwrap. There's no reason for npm to be doing its own bespoke heirloom-grade artisanal thing here. (@iarna)
3f61189#14327 Treat shrinkwrap as canonical. That is, don't try to fill in for partial shrinkwraps. Partial shrinkwraps should produce partial installs. If your shrinkwrap contains NO
devDependenciesthen we'll still try to install them from your
package.jsoninstead of assuming you NEVER want
npm tag REMOVED (BREAKING)
94255da#14328 Remove deprecated tag command. Folks must use the
dist-tagcommand from now on. (@iarna)
NON-ZERO EXIT CODE ON OUTDATED DEPENDENCIES (BREAKING)
exit 1if any outdated dependencies are found by
npm outdated. (@watilde)
c81838a#14013 Log non-zero exit codes at
verboselevel -- this isn't something command line tools tend to do. It's generally the shell's job to display, if at all. (@zkat)
SEND EXTRA HEADERS TO REGISTRY
For the purposes of supporting shiny new registry features, we've started sending
Npm-In-CI headers in outgoing requests.
** Allow npm to add headers to outgoing requests.
Npm-In-CIheader that reports whether we're running in CI.
Npm-Scopeheader along with requests to registry.
Npm-Scopeis set to the
@scopeof the current top level project. This will allow registries to implement user/scope-aware features and services. (@iarna)
506de80#14129 Add test to ensure
Npm-In-CIheader is being sent when CI is set in env. (@iarna)
bc84012#14117 Fixes a bug where installing a shrinkwrapped package would fail if the platform failed to install an optional dependency included in the shrinkwrap. (@watilde)
a40b32d#13519 If a package has malformed metadata,
node.requiredByis sometimes missing. Stop crashing when that happens. (@creationix)
643dae2#14244 Remove some ancient aliases that we'd rather not have around. (@zkat)
bdeac3e#14230 Detect unsupported Node.js versions and warn about it. Also error on really old versions where we know we can't work. (@iarna)
9ca18ad#13746 Updated docs for
npm searchoptions. (@zkat)
npm@3changelog into the archived changelogs directory. (@zkat)
c12bbf8#14290 Document prepublish-on-install deprecation. (@othiym23)
c246a75#14129 Document headers added by npm to outgoing registry requests. (@iarna)