What everybody should know about npm

JSConf Budapest, 2016-05-12

Who is this guy?

Laurie Voss

CTO, npm Inc.

@seldo

Not @izs.

Stuff everybody should know about npm

1. Basic architecture
2. Building a project
3. Sharing a project
4. Managing dependencies
5. Managing lifecycle
6. Essential third-party tools

npm architecture

3 places to get stuff

Where's GitHub?

 npm Enterprise

Obvious

plug for

paid product

npm commands

npm install npm -g

If you get an EACCESS error, you can sudo, or you can fix your permissions with this:

https://docs.npmjs.com/getting-started/fixing-npm-permissions

Not ready for npm@3? Then:

npm install npm@lts -g

npm init

npm init --yes

Avoid naming problems with scopes

npm init --scope=myusername

npm install @myusername/mypackage

require('@myusername/mypackage')

~/.npm-init.js

and

PromZard

npm init

can be re-run

Save to package.json

npm install --save-dev
npm install -D

npm install --save 
npm install -S 

Why devDependencies?

npm install --production

Skip your devDependencies in production!

Bundled dependencies

npm install --save --save-bundle

Offline installs

npm install --cache-min 999999

Run scripts

npm start
npm stop
npm restart
npm test

{
  "name": "@seldo/some-package",
  "version": "1.0.0",
  ...
  "scripts": {
    "test": "mocha ./test/*.js",
    "start": "node ./index.js"
  }
}

Run scripts get devDependencies

in path

Don't force users to install global tools

Don't get conflicts over global tool versions

Publishing

npm publish

npm publish --access=restricted

npm publish --access=public

SemVer

Semantic Versioning

1.5.6

Breaking

Feature

Fix

Major

Minor

Patch

Versioning

npm version major
npm version minor
npm version patch

npm version major -m "bump to version %s"

SemVer is a promise

not a guarantee

Shrinkwrap

npm shrinkwrap

(well, kinda)

npm install clingwrap -g

Multiple users

old way: npm owner

npm Organizations

npm team
npm access

npm team

npm team create <scope>:<team>
e.g. npm team create myorg:myteam

npm team destroy <scope>:<team>

npm team add <scope>:<team> <user>

npm team rm <scope>:<team> <user>

npm team ls <scope>:<team>

npm access

npm access grant read-only|read-write <scope>:<team> [package]

npm access revoke <scope>:<team> [package]

npm access ls-packages [user|scope|scope:team]

npm access ls-collaborators [package [user]]

Multiple packages

npm link

Work with multiple packages simultaneously

2 steps to use link

In your package "alice":

npm link

In "bob", which requires "alice":

npm link alice

Multiple current versions

dist-tags

npm publish --tag

npm dist-tag

npm publish --tag

Publish with a tag:

npm install <package>@<tag>

Install a package at a tag:

npm install npm@next

Try out the next version of npm!

npm dist-tag add <package>@<version> <tag>

Apply a tag after publishing:

npm dist-tag rm <package> <tag>

Remove a tag:

npm dist-tag ls <package>

List tags on a package:

Prefer a tag when installing

npm install --tag <tag>

npm unpublish

Danger, Will Robinson!

npm unpublish

npm unpublish <package>@<version>

Unpublishing is restricted after 24 hours

npm deprecate

The kinder, gentler alternative to unpublish

Keep projects up to date

npm outdated
npm update

Package     Current  Wanted  Latest  Location
domutils      1.3.0   1.3.0   1.5.1  @npm/testnpm
handlebars    1.3.0   1.3.0   4.0.5  @npm/testnpm
hbsfy         1.3.2   1.3.2   2.7.0  @npm/testnpm

More run scripts

npm run start

npm run <anything>

Run script environment

npm_package_name
npm_package_version
npm_package_dependencies_request
npm_package_dependencies_express
npm_config_node_version
npm_config_registry

e.g.

console.log(process.env.npm_package_name)

Package configuration variables

{
  "name": "@seldo/mypackage",
  "config": {
    "port": "80"
  }
}

> console.log(npm_package_config_port)
> 80

npm config set @seldo/mypackage:port 8080
> console.log(npm_package_config_port)
> 8080

Lifecycle hooks

publish:   prepublish, publish, postpublish
install:      preinstall, install, postinstall
uninstall: preuninstall, uninstall, postuninstall
version:   preversion, version, postversion
test:          pretest, test, posttest
stop:         prestop, stop, poststop
start:         prestart, start, poststart
restart:     prerestart, restart, postrestart

.npmrc(s)

per-project: /path/to/my/project/.npmrc
per-user:    ~/.npmrc
global:      $PREFIX/etc/npmrc
built-in:    /path/to/npm/npmrc

.npmrc auth

//registry.npmjs.org/:_authToken=00000000-0000-0000-0000-000000000000

Looks like:

For CI, try:

//registry.npmjs.org/:_authToken={$NPM_TOKEN}

https://remysharp.com/2015/10/26/using-travis-with-private-npm-deps

More details:

Fun config options

For limited values of "fun"

sign-git-tag: automatically sign every version

save: automatically install everything with --save
 

init-author-{name,email}: default values for npm init
 

cache-min: how old a local package can be before checking the registry
 

ignore-scripts: disable install scripts, for the paranoid

Stuff everybody should know about !npm

Babel

Transpile all the things!

Webpack

and

Browserify

Greenkeeper

greenkeeper.io

"npm outdated" as a service!

Node Security Project

npm install nsp -g

nsp check

npm reduces friction

Recap

architecture

npm update

npm init

auto saving

.npm-init.js

devDependencies

bundledDependencies

offline installs

run scripts

publishing

SemVer

npm version

shrinkwrap

npm team

npm access

npm link

dist-tags

unpublish

deprecate

outdated

lifecycle events

.npmrc files

...and more!

Thank you!

laurie@npmjs.com

@seldo

You should follow me on Twitter for no reason:

Good questions get swag!