Hanging out at JavaScript conferences means I know what npm is, the story behind the wombat developer’s union, and get jokes about unpublished modules… At the same time, my tasks at work have not been heavily into modern JS‑land yet. 6 months ago, I was confused about everything related to packages and managers. Recently things like these 👇 have become clear enough:

  • packages can be local dependencies in a project
  • or they can be globally installed on my machine
  • npm is both a client and a registry
  • yarn is an alternative npm client
  • package.json lists the project dependencies
  • and package-lock.json is generated automatically

Commence Confusion… 📦💻🙃

I recently picked up a repo with an experiment that hadn’t been touched in a while. npm install worked as I thought, but also left me with a diff on package-lock.json. This is where I get confused about what code goes where and why. Should I check that in? Was something ideally supposed to be set up differently? Would this somehow interfere with versions of stuff on my machine? I wasn’t sure! But here’s what I learnt after reading and asking questions:

  • package-lock.json is intended to be committed.
  • Yeah, that is actually the whole point of the file.

The npm docs on package‑lock.json say that: “One key detail about package-lock.json is that it cannot be published”. I think that is what tripped me up before. I read “published” and thought they meant “putting this file in your project’s GitHub repository”. Reading about npm‑shrinkwrap.json now helped me understand that it’s about publishing to the registry.

Cheatsheet for words in npm context

  • Local means locally to the project.

  • Global means globally on my machine.

  • Publish means publishing a package to the npm registry.

  • Most npm packages are modules, but…

  • …the definitions of packages and modules are different

  • node_modules is where Node.js looks for modules.

  • There are two types of packages!

  • dependencies are for running the app in prod.

  • devDependencies are for developing or testing.

CLI commands

  • npm install will install dependencies in a local node_modules.
  • npm install -g will set up modules globally on my machine.
  • npm start will mostly find a way to start a server.
  • npm run is an alias for run-script and will look for scripts to run.
  • npm update will both update outdated and install missing packages.

Different but related will help stuff click

There were a couple of different things recently, that helped make more sense of this:

npx is a tool intended to help round out the experience of using packages from the npm registry — the same way npm makes it super easy to install and manage dependencies hosted on the registry, npx makes it easy to use CLI tools and other executables hosted on the registry.

Less confused now! In fact, it all makes perfect sense once you understand it.