Marcus Node Bits - Package.json is a mighty tool

· February 5, 2014

I’m writing down some of the things I’ve picked up when I started to learn about NodeExpress and Mongo. Here are all the post in the series:

This post is about the package.json file that is more than first meets the eye. All node.js projects with any self-respect has a package.json. All npm-modules must have one. It’s a manifest file that holds various meta-data around the project. The file is, as the extension is revealing, just a JSON-file and hence easy to create in any text editor.

Some of the basic things that the file contains are:

  • name - the name of the project (or package in the case your building a nom-package).
  • version - well the version of the project
  • description - since js-project must be named something that won’t reveal it’s content we need a description to tell people what the project is about. Btw deckchair.js is my favourite so far. Longing for noun.js, but it’s still out for grabs as it seems…
  • author - your name and contact information

Node.js itself only understands name and version btw. The rest is meta-data that npm (node package manager) is using.

Other attributes I often end up using are:

  • dependencies - this list the other packages (and their version) that your project is using.
  • scripts - here you can create small build commands that npm can execute for you. The next part of this series is about that.

This is a typical package.json for my projects (please note the update below after some excellent comments):

When I create a new project, I often create the package.json first of all. I fill out the things I know, and that’s often the better part of the file, actually.

sublime package.json - create the file and open it with Sublime.

copy in some template data, like this one for example

fill out the name, description, version (0.0.1) nodes of the package.json

create the scripts node and add scripts for starting the app.js file and test, with my mocha switches.

create the dependencies node and add the things that I will be using for this project. Typically

  • express - my web framework of choice
  • monk - if I’m going to have a db
  • mocha - my testing framework
  • should - nice assertions
  • and maybe something else

Save the package.json and go to the terminal and go npm install. This will read the package.json and download and install all the dependencies into your node_modules-folder.

If I’m adding new dependencies I typically do that by adding them to package.json and rerun “npm install”. You can do

npm install [package name] –save

which will update the package.json for you, but I don’t do that.

So the package.json is a manifest describing your project, a package manager specification that helps you update the dependencies and build script where you can define your own commands, in one.

Here’s an excellent interactive guide to the package.json. If you like it static… you wouldn’t do JavaScript, now would you. Any case here’s an static page describing the package.json file in an great way.

One final thing (as they said)… did you see that “startLocal”-node under the scripts-node in my package.json file above? It turns out that npm only understands a couple of scripts by default (test, start etc.) but if you want something else you can add them under the scripts node too, making your package.json even more powerful. You have to start these scripts like this:

npm run-script startLocal

UPDATED: From mr Ullmark I got some great tips on how to improve my knowledge. They are in the comments below, but I’ll mention them here too:

  • npm init - is a interactive tool, that helps you build your package.json file. So you don’t need a template to tweak but can let the tool work for you. Really nice!
  • There’s a package.json node called devDependencies, for all the things you need in development. These are testing-, assertion- and mocking-frameworks for example. It’s a good thing not to mix it up with the production dependencies for clarity and since a much smaller foot print on your production environment. Read more here.
  • Finally, my way to set up the test-command in the package.json required all the people that wanted to use the npm test command to have mocha installed globally (npm install mocha -g). Not everyone wants that. Build servers for example… So I’ve updated it to a better version that uses the mocha I have in my project local node_modules folder

Twitter, Facebook