An Absolute Beginner's Guide to Using npm
Using npm effectively is a cornerstone of modern web development, no matter if it's exclusively with Node.js, as a package manager or build tool for the front-end, or even as a piece of workflows in other languages and on other platforms.
Really understanding npm as a tool, understanding the core concepts, can be something that's difficult for a beginner - I spent many hours just trying to figure out small details that would seem minor or be taken for granted by others.
As such, I've written up a basic and detailed guide for understanding npm, for those who are entirely new to Node.js, npm, and the surrounding ecosystem.
An Absolute Beginner's Guide to package.json
As a general rule, any project that's using Node.js will need to have a package.json file. What is a package.json file?
At its simplest, a package.json file can be described as a manifest货单 of your project that includes the packages and applications it depends on, information about its unique source control, and specific metadata like the project's name, description, and author.
Let's break down the core parts of a typical package.json file:
Specific Metadata: name, version, description, license, and keywords
Inside a package.json, you'll almost always find metadata specific to the project - no matter if it's a web application, Node.js module, or even just a plain JavaScirpt library. This metadata helps identify the project and acts as a baseline for users and contributors to get information about the project.
Here's an example of how these fields would look in a package.json file:
{
"name": "metaverse", // The name of your project
"version": "0.92.12", // The version of your project
"description": "The Metaverse virtual reality. The final outcome of all virtual worlds, augmented reality, and the Internet.", // The description of your project
"main": "index.js"
"license": "MIT" // The license of your project
}A package.json file is always structured in the JSON format, which allows it to be easily read as metadata and parsed by machines.
If needing to format a package.json file manually to get your project up and running seems a bit daunting令人怯步的 ,there's a handy遍历的 command that will automatically generate a base package.json file for you - if you'd like to learn how to use it, take a peek一瞥 at the npm init instructions below!
Understanding and Managing Your Project's Dependencies: dependencies and devDepenendcies in your package.json
The other majorly important aspect of a package.json is that it contains a collection of any given project's dependencies. These dependencies are the modules that the project relies on to function properly.
Having dependencies in your project's package.json allows the project to install the versions of the modules it depends on. By running an install command (see the instructions for npm install below) inside of a project, you can install all of the dependencies that are listed in the project's package.json - meaning they don't have to be (and almost never should be) bundled with the project itself.
Second, it allows the separation of dependencies that are needed for production and dependencies that are needed for development. In production, you're likely not going to need a tool to watch your CSS files for changes and refresh the app when they change. But in both production and development, you'll want to have the modules that enable what you're trying to accomplish with your project - things like your web framework, API tools, and code utilities.
What would a project's package.json look like with dependencies and devDependencies? Let's expand on the previous example of a package.json to include some.
{
"name": "metaverse",
"version": "0.92.12",
"description": "The Metaverse virtual reality. The final outcome of all virtual worlds, augmented reality, and the Internet.",
"main": "index.js"
"license": "MIT",
"devDependencies": {
"mocha": "~3.1",
"native-hello-world": "^1.0.0",
"should": "~3.3",
"sinon": "~1.9"
},
"dependencies": {
"fill-keys": "^1.0.2",
"module-not-found-error": "^1.0.0",
"resolve": "~1.1.7"
}
}One key difference between the dependencies and the other common parts of a package.json is that they're both objects, with multiple key/value pairs. Every key in both dependencies and devDependencies is a name of a package, and every value is the version range that's acceptable to install (according to Semantic Versioning - to learn more about Semantic Versioning, also known as semver, check out our primer on semver).
The Essential npm Commands
When using npm, you're most likely going to be using the command line tool for the majority of your interactions. As such, here's a detailed rundown of the commands that you'll encounter and need to use most frequently.
Using npm init to Initialize a Project
The npm init command is a step-by-step tool to scaffold out your project. It will prompt you for input for a few aspects of the project in the following order:
- The project's name,
- The project's initial version,
- The project's description,
- The project's entry point (meaning the project's main file),
- The project's test command (to trigger testing with something like Standard)
- The project's git repository (where the project source can be found)
- The project's keywords (basically, tags related to the project)
- The project's license (this defaults to ISC - most open-source Node.js projects are MIT)
It's worth noting that if you're content with the suggestion that the npm init command provides next to the prompt, you can simply hit Return or Enter to accept the suggestion and move on to the next prompt.
Once you run through the npm init steps above, a package.json file will be generated and placed in the current directory. If you run it in a directory that's not exclusively for your project, don't worry! Generating a package.json doesn't really do anything, other than create a package.json file. You can either move the package.json file to a directory that's dedicated to your project, or you can create an entirely new one in such a directory.
How to use npm init:
npm init # This will trigger the initialization
Using npm init --yes to Instantly Initialize a Project
If you want to get on to building your project, and don't want to spend the (albeit brief) time answering the prompts that come from npm init, you can use the --yes flag on the npm init command to automatically populate all options with the default npm init values.
Note: You can configure what these default values are with the npm configuration - that's a more advanced topic, and outside the scope of this beginner's guide to npm.
That said, if you're interested in setting that up, you can learn how to set these defaults in the eleventh tip of our npm tricks article.
Usage:
npm init --yes # This will trigger automatically populated initialization.
Install Modules and Save Them to Your package.json as a Developer dependency
There's a flag that is nearly an exact duplicate, in terms of functionality, of the --save flag when installing a module: --save-dev. There are a few a key differences between the two - instead of saving the module being installed and added to package.json as an entry in dependencies, it will save it as an entry in the devDependencies.
The semantic difference here is that dependencies are for use in production - whatever that would entail必需 for your project. On the other hand, devDependencies are a collection of the dependencies that are used in development of your application - the modules that you use to build it, but don't need to use when it's running. This could include things like testing tools, a local server to speed up your development, and more.
Usage:
npm install <module> --save-dev # Where <module> is the name of the module you want to install
Want to keep going?
If you want to keep learning about npm and all its facets, I've got a few awesome things for you. A bit ago, we shared a few npm tricks to knock your wombat socks off. Even better, we wrote a follow-up with even more npm tricks! This beginner's guide is a great springboard to get off the ground, and both of those will help you start optimizing your work with npm! If you'd like to go even further with npm and start deploying Node.js apps and npm modules into production, you should definitely take a look at NodeSource Certified Modules - it's an awesome tool that'll compliment your newly acquired npm skills!