Node.js package.json Exploring package.json
Example
A package.json file, usually present in the project root, contains metadata about your app or module as well as the list of dependencies to install from npm when running npm install.
To initialize a package.json type npm init in your command prompt.
To create a package.json with default values use:
npm init --yes
# or
npm init -y
To install a package and save it to package.json use:
npm install {package name} --save
You can also use the shorthand notation:
npm i -S {package name}
NPM aliases -S to --save and -D to --save-dev to save in your production or development dependencies respectively.
The package will appear in your dependencies; if you use
--save-dev instead of --save, the package will appear in your devDependencies.
Important properties of package.json:
{
"name": "module-name",
"version": "10.3.1",
"description": "An example module to illustrate the usage of a package.json",
"author": "Your Name <[email protected]>",
"contributors": [{
"name": "Foo Bar",
"email": "[email protected]"
}],
"bin": {
"module-name": "./bin/module-name"
},
"scripts": {
"test": "vows --spec --isolate",
"start": "node index.js",
"predeploy": "echo About to deploy",
"postdeploy": "echo Deployed",
"prepublish": "coffee --bare --compile --output lib/foo src/foo/*.coffee"
},
"main": "lib/foo.js",
"repository": {
"type": "git",
"url": "https://github.com/username/repo"
},
"bugs": {
"url": "https://github.com/username/issues"
},
"keywords": [
"example"
],
"dependencies": {
"express": "4.2.x"
},
"devDependencies": {
"assume": "<1.0.0 || >=2.3.1 <2.4.5 || >=2.5.2 <3.0.0"
},
"peerDependencies": {
"moment": ">2.0.0"
},
"preferGlobal": true,
"private": true,
"publishConfig": {
"registry": "https://your-private-hosted-npm.registry.domain.com"
},
"subdomain": "foobar",
"analyze": true,
"license": "MIT",
"files": [
"lib/foo.js"
]
}
Information about some important properties:
name
The unique name of your package and should be down in lowercase. This property is required and your package will not install without it.
- The name must be less than or equal to 214 characters.
- The name can't start with a dot or an underscore.
- New packages must not have uppercase letters in the name.
version
The version of the package is specified by Semantic Versioning (semver). Which assumes that a version number is written as MAJOR.MINOR.PATCH and you increment the:
- MAJOR version when you make incompatible API changes
- MINOR version when you add functionality in a backwards-compatible manner
- PATCH version when you make backwards-compatible bug fixes
description
The description of the project. Try to keep it short and concise.
author
The author of this package.
bin
An object which is used to expose binary scripts from your package. The object assumes that the key is the name of the binary script and the value a relative path to the script.
This property is used by packages that contain a CLI (command line interface).
script
A object which exposes additional npm commands. The object assumes that the key is the npm command and the value is the script path. These scripts can get executed when you run npm run {command name} or npm run-script {command name}.
Packages that contain a command line interface and are installed locally can be called without a relative path. So instead of calling ./node-modules/.bin/mocha you can directly call mocha.
main
The main entry point to your package. When calling require('{module name}') in node, this will be actual file that is required.
It's highly advised that requiring the main file does not generate any side affects. For instance, requiring the main file should not start up a HTTP server or connect to a database. Instead, you should create something like exports.init = function () {...} in your main script.
keywords
An array of keywords which describe your package. These will help people find your package.
devDependencies
These are the dependencies that are only intended for development and testing of your module. The dependencies will be installed automatically unless the NODE_ENV=production environment variable has been set. If this is the case you can still these packages using npm install --dev
peerDependencies
If you are using this module, then peerDependencies lists the modules you must install alongside this one. For example, moment-timezone must be installed alongside moment because it is a plugin for moment, even if it doesn't directly require("moment").
preferGlobal
A property that indicates that this page prefers to be installed globally using npm install -g {module-name}. This property is used by packages that contain a CLI (command line interface).
In all other situations you should NOT use this property.
publishConfig
The publishConfig is an object with configuration values that will be used for publishing modules. The configuration values that are set override your default npm configuration.
The most common use of the publishConfig is to publish your package to a private npm registry so you still have the benefits of npm but for private packages. This is done by simply setting URL of your private npm as value for the registry key.
files
This is an array of all the files to include in the published package. Either a file path or folder path can be used. All the contents of a folder path will be included. This reduces the total size of your package by only including the correct files to be distributed. This field works in conjunction with a .npmignore rules file.
