NPM Guide
This guide is designed to help beginners understand and use NPM effectively. It covers everything from basic setup to advanced tasks like publishing packages and managing versions.
Introduction to package managers
-
npm (Node Package Manager) is the default package manager for Node.js. It helps developers to install, manage, and share packages (modules) of JavaScript code. If you’re building a project in Node.js or working with front-end frameworks like Next.js, you’ll likely use NPM to handle your dependencies.
-
yarn is a package manager that doubles down as project manager. Whether you work on simple projects or industry monorepos, whether you’re an open source developer or an enterprise user, Yarn has your back.
-
pnpm is a fast, disk space-efficient package manager for JavaScript. It is an alternative to NPM and Yarn, offering unique features like a non-flat node_modules structure and symlinked dependencies, making it faster and more reliable in handling large projects.
-
[bun ](https://bun .sh) is a fast npm-compatible JavaScript package manager. Develop, test, run, and bundle JavaScript & TypeScript projects—all with bun . bun is an all-in-one JavaScript runtime & toolkit designed for speed, complete with a bundler, test runner, and Node.js-compatible package manager.
Installing Node.js and NPM
To get started with NPM, you need to install Node.js, which comes with NPM by default.
- Windows/macOS: Download and install from the official Node.js website.
- Linux: Follow the instructions in this video or install via your package manager.
After installation, you can check the versions of Node.js and NPM installed on your system:
node -vnpm -v
Initializing a New Project
To start a new project using NPM, you need to create a package.json
file, which holds metadata about your project and its dependencies.
npm init
Follow the prompts to set up your package.json
. You can also use the -y
flag to skip the prompts and use default values:
npm init -y
Installing Packages
NPM makes it easy to install packages that you need for your project.
- Installing a package locally (for your project):
npm install <package_name>
This will add the package to your node_modules
directory and list it as a dependency in your package.json
.
- Installing a package globally (available system-wide):
npm install -g <package_name>
Global installations are useful for command-line tools that you want to access from anywhere on your system.
Managing Dependencies
Adding and Removing Packages
- Add a package as a dependency:
npm install <package_name>
- Add a package as a development dependency:
npm install <package_name> --save-dev
- Remove a package:
npm uninstall <package_name>
Updating Packages
To update all packages to their latest versions based on the semver
ranges specified in package.json
, run:
npm update
If you want to update a specific package:
npm install <package_name>@latest
Publishing a New Package
If you have created a package that you want to share with others, you can publish it to the NPM registry.
Preparing Your Package
Ensure your package.json
is correctly set up with necessary details like name
, version
, description
, and main
. Also, make sure you have a .gitignore
file to avoid publishing unnecessary files.
Logging into NPM
First, log in to your NPM account:
npm login
Publishing Your Package
Once logged in, you can publish your package with:
npm publish# If you want to have a @scope/* then use:npm publish --access public
Your package will be available on npmjs.com and can be installed by others using:
npm install <your_package_name>
Releasing New Versions
When you make changes to your package, you’ll need to release new versions. Follow the semantic versioning principles (MAJOR.MINOR.PATCH
) to version your package appropriately.
- Update the patch version (e.g., 1.0.0 -> 1.0.1):
npm version patch
- Update the minor version (e.g., 1.0.0 -> 1.1.0):
npm version minor
- Update the major version (e.g., 1.0.0 -> 2.0.0):
npm version major
After updating the version, publish the new version:
npm publish
Using changeset
Tool for Version Management
Changesets is a tool that helps with versioning and publishing packages in a mono-repo or multi-package repository setup.
Installing changeset
Install the changeset tool globally or as a dev dependency:
npm install @changesets/cli --save-dev
Setting Up Changesets
Initialize changesets in your project:
npx changeset init
Creating a Changeset
Whenever you make changes that need to be released, create a changeset:
npx changeset
Follow the prompts to describe the changes and bump versions.
Releasing Changes
Once you’re ready to release the changes:
-
1. Update versions: Run the following command to bump versions and update changelogs.
Terminal window npx changeset version -
2. Publish packages: Finally, publish the updated packages:
Terminal window npx changeset publish
Additional Resources
- NPM Documentation
- Semantic Versioning
- Creating and Publishing Unscoped Packages
- Using Changesets with NPM
This guide should give beginners a comprehensive introduction to NPM while also providing enough detail for more advanced users to manage and publish their packages effectively. You can continue to expand this guide with additional sections as needed.