The best way to manage locally installed npm packages is to create a
package.json
file.
A package.json
file:
A package.json
must have:
"name"
"version"
x.x.x
For example:
{
"name": "my-awesome-package",
"version": "1.0.0"
}
package.json
There are two basic ways to create a package.json file.
To create a package.json
with values that you supply, run:
> npm init
This will initiate a command line questionnaire that will conclude with the
creation of a package.json
in the directory in which you initiated the command.
package.json
To get a default package.json
, run npm init
with the --yes
or -y
flag:
> npm init --yes
This method will generate a default package.json
using information extracted from the current directory.
> npm init --yes
Wrote to /home/ag_dubs/my_package/package.json:
{
"name": "my_package",
"description": "",
"version": "1.0.0",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"repository": {
"type": "git",
"url": "https://github.com/ashleygwilliams/my_package.git"
},
"keywords": [],
"author": "",
"license": "ISC",
"bugs": {
"url": "https://github.com/ashleygwilliams/my_package/issues"
},
"homepage": "https://github.com/ashleygwilliams/my_package"
}
name
: the current directory nameversion
: always 1.0.0
description
: info from the readme, or an empty string ""
main
: always index.js
scripts
: by default creates an empty test
scriptkeywords
: emptyauthor
: emptylicense
: ISC
bugs
: info from the current directory, if presenthomepage
: info from the current directory, if presentYou can also set several config options for the init command. Some useful ones:
> npm set init.author.email "[email protected]"
> npm set init.author.name "ag_dubs"
> npm set init.license "MIT"
If there is no description field in the package.json
, npm uses the first line of the README.md
or README instead. The description helps people find your package when searching npm, so it's definitely useful to make a custom description in the package.json
to make your package easier to find.
package.json
questionnaireIf you expect to create many package.json files, you might wish to customize the questions asked during the init process, so that the files always contain key information that you expect. You can customize the fields as well as the questions that are asked.
To do this, you create a custom .npm-init.js
in your home directory
~/.npm-init.js
.
A simple .npm-init.js
might look something like this:
module.exports = {
customField: 'Custom Field',
otherCustomField: 'This field is really cool'
}
Running npm init
with this file in your home directory would output a package.json
that included these lines:
{
customField: 'Custom Field',
otherCustomField: 'This field is really cool'
}
You can also customize the questions by using the prompt
function.
module.exports = prompt("what's your favorite flavor of ice cream, buddy?", "I LIKE THEM ALL");
To learn more about how to create advanced customizations, check out the docs for init-package-json
To specify the packages your project depends on, you need to
list the packages you'd like to use in your package.json
file. There are
2 types of packages you can list:
"dependencies"
: These packages are required by your application in production."devDependencies"
: These packages are only needed for development and testing.package.json
You can manually edit your package.json
. You'll need to create an attribute
in the package object called dependencies
that points to an object. This object will hold attributes that name the packages you'd like to use. It will point to a semver expression that specifies the versions of that project that are compatible with your project.
If you have dependencies you only need to use during local development,
follow the same instructions as above but use the attribute called devDependencies
.
For example, the project below uses any version of the package my_dep
that matches major version 1 in production and requires any version of the package my_test_framework
that matches major version 3, but only for development:
{
"name": "my_package",
"version": "1.0.0",
"dependencies": {
"my_dep": "^1.0.0"
},
"devDependencies" : {
"my_test_framework": "^3.1.0"
}
}
--save-prod
and --save-dev
install flagsThe easier (and more awesome) way to add dependencies to your package.json
is to do
so from the command line, flagging the npm install
command with either --save-prod
(assumed by default) or
--save-dev
, depending on how you'd like to use that dependency.
To add an entry to your package.json
's dependencies
:
npm install <package_name> [--save-prod]
To add an entry to your package.json
's devDependencies
:
npm install <package_name> --save-dev
npm uses Semantic Versioning, or, as we often refer to it, SemVer, to manage versions and ranges of versions of packages.
If you have a package.json
file in your directory and you run npm install
, npm will look at the dependencies that are listed in that file and download the latest versions, using semantic versioning.
To understand more about the power of package.json, see the video "Installing npm packages locally" which you can find in Chapter 4.
To learn more about semantic versioning, see Getting Started "Semver" page.
Last modified June 11, 2018 Found a typo? Send a pull request!