Notes on an intro to using npm

On npm.md

On npm

Three "types" of modules

cli modules

• "bin" in package.json
• keeping index.js and bin/module separate. You want both programmatic and cli access
• use yargs to parse options from the CLI. You can do this manually, but it's painful and error prone. yargs also helps you build a good UI.
• make sure to set the "main" field

browser modules

• running tests is tricker – smokestack mostly works
• you get access to DOM apis. Expect this file to be browserified.
• set the "browser" field in package.json
• you probably also want to set the "style" field

Node modules

• will be run in node, so no DOM apis are out
• make sure to set the "main" field
• This is the default, so things like require just work.

The "main" key

• defaults to "main": "index.js", you should set your own value if you don't have that file (e.g. "main": "index.jsx")
• "style": no default. Set this to your entry css file.
• "browser": super useful if you want one module that does different things on the server and the browser. It's a special field that browserify picks up.
• "bin" key: It's an object that defines a series of scripts other people can run. Use this to create a CLI interface for your module.

SemVer

https://docs.npmjs.com/getting-started/semantic-versioning

• bumping with npm version {}.
  • Updates package.json
  • commits the change
  • adds a git tag

deps

• normal deps: always installed with npm i
• dev deps: not installed in prod, or when you npm i <module>, but installed when you clone a module repo and run npm install
• peer deps: not installed with npm i or npm i <module>, but will throw an error if they're not installed at the same time. It's a good way of saying: "This module doesn't need or want it's own version of this dependency, but you darn well better have one of your own."
• npm i {-S,-D}: npm install --save should be your default, but if you can, use npm install --save-dev

npm link

• see if changes to a module work before publishing!
• run npm link from the module you're deving
• run npm link <modulename>

cd rentable-header
npm link
echo "console.log('hi')" >> index.jsx
npm run build-es5
cd ../experiment-server
npm link @getable/rentable-header
tail node_modules/@getable/rentable-header

Npm scripts

• there are a few built in
  • npm test
  • npm publish
  • npm start
• save the common commands in a central place. It's easier to remember, and nice to standardize. You just know every node module has a npm test.
• some of my favorites npm run tdd && npm run release

.npmignore vs .gitignore

• dmn intelligently keeps your .npmignore up-to-date
• just like .gitignore is valuable for keeping compiled files out of git, .npmignore can keep non-production code out of npm
• when your making a module, you have a bunch of code the production users don't care about. Tests, source files, etc… Including these in your published module inflates size and slows down deploys.

How to publish

• npm version {patch,minor,major} && npm publish
• add in ensuring that you have the latest from other people before publishing
• add in publish to GH
• add in run the tests first
• add in changelog updates
• add in keeping docs up-to-date
• add in keeping .npmignore up-to-date
• …that's why I like using npm run release

public vs private

• scoped are private by default --access=restricted
• non-scoped modules are public --access=public

es6

• babel doesn't transpile anything in node_modules, so when you publish an es6 module, you need to be sure to compile down to es5 (or maybe just only use es6 features that newer node versions support).
• Make sure "main" points to the compiled code
• Make sure you compile not just index.js[x] but any other files that you've made too. babel lib --out-dir dist/lib && babel index.js > dist/index.es5, then "main": "dist/index.es5"