Surviving Unfamiliar JavaScript Projects: package.json

June 17, 2018

This isn’t your code or project: you git clone and step into the directory…

Where do you start? What’s important? How are things organized?


A project’s package.json will tell you a lot. All sections are informative, but some are better starting points than others.

Is that too obvious? You can play along with the package.json from real projects. The more unfamiliar the project, the better:

Any surprises in there? My answers/spoilers below.

section: main

"main": "index.js"

A good place to start … if you’re going to jump in and read some code, this is the entry point of this project; this is what a require would read.

section: bin

"bin": {
  "nyc": "./bin/nyc.js"

Does this project provide “executables”? If so, that’s another kind of entry point into the code. It comes from a different perspective: doing something useful and specific.

Sometimes it’s obvious what’s in there, sometimes not. It’s usually worth a look.

section: scripts

this snippet was trimmed down to simplify

"scripts": {
  "test": "npm run clean && npm run build && ...",
  "clean": "rimraf ./.nyc_output ./node_modules/.cache ...",
  "build": "node ./build-tests"

Other languages have Makefiles, Rakefiles, or something else. The scripts section ends up being a dumping ground for useful “commands” and “recipes”.

Look for the unexpected.

section: *dependencies

People don’t write code anymore, people glue code together until it’s useful.

Yes, dependencies and devDependencies (and others) contain “everything”, but it doesn’t tell you where and why.

Also, it’s probably not up to date:

The good news is that you don’t have to do this alone, there are tools to help.

Surprises from real package.json

When I read a package.json, I look for the unexpected. Here are some things that caught my eye:






Discuss on Twitter