14 DAY TRIAL // Node.js and its developer community depend on npm to automate the installation of Node modules based on a list of minimum dependencies. At the same time, npm won't work if developers don't add package.json files to their projects.
In this small article, we plan to detail how package.json files work, and why they're so important to the Node ecosystem, and recently even beyond it.
For starters, we should mention that only two fields are actually needed for a package.json file to be valid and work. These are the name and version fields. The first must be unique in order to be published on the npm repository, while the recommendation for the second is to be in accordance with the SemVer versioning system.
Of course, if you download any Node module and open its package.json file, you'll find a dozen of other fields, and most of them are as follows:
description - well, it's the description. Since it's a JSON file, try and keep it as short as possible, otherwise it will be hard to read. The description is also pulled and displayed in the npm search results, so keeping it simple will also help it display properly on Node terminals.
author - the name of the package's creator. The format is usually “Name Surname.”
contributors - the names of other developers that have contributed to the code enough (in your own opinion) to be mentioned.
keywords - terms used to describe your project, which will also be used by the npm system when searching the database. We don't recommend keyword spamming, as the npm repository has good moderators.
homepage - if your npm module has its own website, this is the place to put it.
bugs - when reporting bugs, users can utilize this data to let you know about them. The field can be a URL pointing to an issues or bug tracker, or an email address.
repository - the URL for the source code's repository. Most of the times, this is a GitHub page, but other VCSs can also be used.
license - most of the times, you'll find an open source license here. Recently, npm has moved on to using PDX license IDs, so licenses can be specified like “CC-BY-2.0” instead of writing the whole text, like “Creative Commons Attribution 2.0 License.”
Now for the technical part
publish - a true/false field, this one will help developers keep an npm private and inaccessible to other modules until you reach a stable tag or fix important bugs.
dependencies - a list of npm modules accompanied by their version numbers. This is where Node will look and download dependencies for your project when running the “npm install” command.
devDependencies - other packages that will be installed alongside the default dependencies when running the “npm install –dev” command. These are packages used for development operations and aren't used in the production stages. Usually, this is the place where testing frameworks and debug tools are loaded.
main - the location of your project's main file. This is the file loaded when using require('{module_name}') inside your JavaScript code.
bin - the location of files that power a package's CLI tool.
preferGlobal - a true/false field that tells npm to install the script globally via “npm install -g” even if the user forgets to add the “-g” parameter.
scripts - a list of files which can be used to run different files when various commands like npm start, npm stop, npm restart, or npm test are run. Scripts can also be mentioned here to be executed before and after the package's publishing on npm, installation on the client's side, and even when bumping the version number. This is probably the hardest section to set up.
It is important to learn how to properly write and read package.json files, since they are crucial when developing Node.js applications that dynamically import and update their code via npm. A poorly formatted packge.json file can break projects and prevent them from working, even if there's nothing wrong with the JavaScript code itself.
Outside of the sections listed above, package.json files can contain custom fields as well, as long as they don't have the same names. This versatility has allowed the jQuery Foundation to migrate their plugins repository to npm and use package.json files with a similar structure to allow developers to list, search, and install jQuery plugins via the npm command.