What is package.json?

A few weeks back, when I jumped head first into building a new site using 11ty, one of the first steps was to create a package.json file and I wasn’t sure why.

So on a lazy Sunday, I thought I’d look into why I had to create it and what it’s purpose is.

TL;DR: Not as interesting as I had hoped. The package.json file is located at the root level of a javascript / Node project and contains information about the project and what other packages are required to run it.

First steps

First things first, let’s look at the package.json file, surely it’s not just an empty file.

On inspection, it contains a JSON object with many key/value pairs which appear to describe the site.

These pairs must have been generated whilst running the install of 11ty as I didn’t add them.

But what does it all mean?

So I’ll give a brief run down of the key/value pairs that we’ve got logged in here.

Name & Version

	“name”: “mrq”,
	“version”: “1.0.0”,

Reading up on the npm docs for package.json, it tells us that the name & version keys are important if you’re planning on publishing your package to somewhere like NPM as the values given should form a unique identifier for your project.

Obviously, we’re looking at a personal site here and nothing will get published back to NPM so it’s not as important here, and in fact, the docs say if you’re not publishing the code back, then the name and version keys are optional. It seems like best practice to always fill it out though.

Description

	“description”: “”,

This is fairly self explanatory. What does your app do? This is useful when added back to NPM because it allows people to find out what you’re doing. Again, in this instance, it’s a personal site so it’s not important but for clarity, I’ve added a description to my package.json.

Main

	“main”: “index.js”,

The main key should link to the main script as part of your package. In this instance, it’s index.js.

Scripts

	“scripts”: {
		…
	}

The scripts key takes another JSON object as a value. The key in the scripts value relates to an event and the value is the command that should be run when that event is called.

11ty adds a default script in as part of its build which is

	"test": "echo \"Error: no test specified\" && exit 1"

This doesn’t actually do anything except output Error: no test specified to the terminal window; but the premise is there. So to envoke this event, you would open up your terminal, cd into your directory and then type npm test in your command line. This would then run the script associated with test.

Keywords

	“keywords”: [],

Much the same as description, keywords is an array that you helps users find your package on npm.

Author

	“author”: “”,

A place to list authors or contributors to the package.

license

	“license”: “ISC”,

More aimed at those looking to publish their packages back to npm, specify a license here that suits you & your project.

DevDependencies

	“devDependencies”: {
		…
	}

This takes a JSON object and lists any tools or packages that your package may need to build; but not necessarily need documentation etc that goes with it… So basically the core code only.

My new site which is built on 11ty requires 11ty as part of the devDependencies because running npm install means it’ll grab the 11ty core code from npm and nothing else.

Dependencies

	“dependencies”: {
		…
	}

Lastly, this is another JSON object but lists third party tools that aren’t dependant for building the core site, but required for additional features. Plugins for example.

My package.json called in ”luxon”: “^1.25.0” as a dependency because we use that for readable dates. It’s not a core function and the site will still work without it.

The claret (^) before the version number tells npm that it requires at least version 1.25.0 to function.

Conclusion

So there we have it. package.json appears to be suited to those writing packages to publish back to npm but is also required for javascript/Node projects.

It would seem most of the elements aren’t required on most projects but are there for information.