Introduction

Welcome to wtf, npm?! We're very happy to see you.

note

"npm" and the npm logos are trademarks owned by npm, Inc. These trademarks are used here only to identify the product, and do not imply sponsorship or endorsement.

Who is this for?

If you're trying to use npm, arguably the most popular package manager in the Node.js ecosystem, this is for you.

• Maybe you've been handed an existing package and asked to figure it out (start with Dependencies > Installation).

• Maybe you've got a screenful of text or an npm ERR! that's just not making sense (check out Errors).

• Maybe you have an empty directory and a great idea for a package.

Whatever it is, we're here to help you be informed and effective.

info

You can tell you're using an npm-managed package if:

• There's a package-lock.json file in the root of your repo; or
• npm pkg get engines includes an entry for "npm".

Why does it exist?

npm's existing documentation is pretty good as a reference (to use Divio's categorisation). But it's lacking in some of the other categories; there are no tutorials or how-to guides to take you through particular workflows.

If you have a specific error you could also search the npm-related questions on Stack Overflow, but far too many of the (even accepted!) answers are just "delete node_modules/ and package-lock.json and try again". That doesn't explain the problem, and in many cases won't actually fix it.

These docs exist to fill some of those gaps, helping you understand how to use npm from a task-oriented perspective.

Who is it not for?

If you're using one of the ecosystem's other package managers, e.g.:

• Yarn (👀 look for a yarn.lock file in the root of your repo); or
• pNpm (👀 look for a pnpm-lock.yaml file in the root of your repo);

then this won't be much help. That's not to say that they aren't good alternatives, though, and the introduction of corepack in Node.js makes it much easier to give them a go.