How to publish packages to NPM

how-to-publish-to-npm.md

Getting Started with NPM (as a developer)

As easy as 1, 2, 3!

Updated:

• Aug, 08, 2022 update config docs for npm 8+
• Jul 27, 2021 add private scopes
• Jul 22, 2021 add dist tags
• Jun 20, 2021 update for --access=public
• Sep 07, 2020 update docs for npm version
• Jul 22, 2020 add appendix on node install

1. Set .npmrc Author Info

If you haven't already set your NPM author info, do that now:

npm config set init-author-name "Your Name"
npm config set init-author-email "[email protected]"
npm config set init-author-url "https://yourblog.com"

npm config set init-version "1.0.0"
npm config set init-license "SEE LICENSE IN LICENSE"

npm adduser

Side notes:

• There's a 🐛 rare but nasty node PATH bug that's wontfix for compatibility with systems that rely on it.
  Set npm config set scripts-prepend-node-path true to fix it.
• .npmrc comments must start with // and end with =. This is due to historical issues.
  Ex: // My comment here=.

2. npm init

Then create a package.json and publish it:

cd ./path/to/your-project/
npm init

3. npm publish

# Bump the version number in package.json (and git tag) before each publish
# (npm also has `npm version major|minor|patch|preminor|premajor|prepatch|prerelease`)
npm version patch -m "an optional description"

npm publish --access=public ./

Tip: Use your @:

npmjs.org is pretty crowded these days, but every user (and organization) has a scope.
I recommend using it.

Your username: npm whoami
Your scope: @ + <your-username>
Your next package: @<username>/<packagename>
Example: @root/async-router

Tip: Add build stepts to package.json.scripts:

npm pkg set scripts.fmt="npx -p prettier@2 -- prettier -w '**/*.{js,md}'"
npm pkg set scripts.prepublish="npm run build"

Tip: Check Dependencies:

# Note you may want to use one of these to make sure:
# 1. Your real dependencies are listed in package.json
# 2. Your development only dependencies are in the devDependencies section
# depcheck: https://www.npmjs.com/package/depcheck
# dependency-check: https://www.npmjs.com/package/dependency-check

Appendix

• Beta and Release versions
• Private Packages
• Licensing (SPDX Identifiers)
• Live Stream Walkthrough
• Installing Node.js
• Other Resources

Beta and Release versions

Typically if you publish something, it should be v1.0.0 (you won't run out of numbers, after all), but it should be at least 0.1.0.

npm config set init-version "1.0.0"

Beta Tags (won't install on @latest)

If you want a new version to not install with @latest

npm version preminor
npm publish ./ --tag beta

Reset @latest

If you published a bugfix as v1.0.7 and need to set v1.1.3 back to latest

git checkout v1.0.7
npm publish ./
   
git checkout v1.1.3
npm dist-tag add [email protected] latest

Remove a Tag

npm dist-tag rm foobar beta

Create a Commit Message Template

# Set the message template as a package.json script
npm pkg set scripts.version='npm version -m "chore(release): bump to v%s"'

# Run with the same parameters
npm run version patch

Private Packages

See The Vanilla DevOps Git Credentials & Private Packages Cheatsheet

Licensing (SPDX Identifiers)

If you don't know which license to choose, then pick MPL-2.0
(open source, but gives you legal protection against bad actors)

npm config set init-license "SEE LICENSE IN LICENSE"

Open Source:

• Trademark & Brand Safe: MPL-2.0
• Legally Open Source: Apache-2.0
• Public Domain: CCO-1.0
• MIT / ISC - you don't care (not great for CYA)

Dual License:

• (<x> OR <y>)
• (MPL-2.0 OR Apache-2.0)

Commercial:

• SEE LICENSE IN <filename>
• SEE LICENSE IN LICENSE

Live Stream: Publishing @root/uuid to npm

Install Node + npm

If you haven't already installed node + npm, or you'd like the latest version:

macOS, Linux:

curl -fsS https://webinstall.dev/node | bash

Windows 10/11:

curl.exe -fsSA "MS" https://webinstall.dev/node | powershell

Other Resources

• https://docs.npmjs.com/files/package.json (original)
• https://docs.npmjs.com/using-npm/developers.html (original)
• http://blog.izs.me/post/1675072029/10-cool-things-you-probably-didnt-realize-npm-could-do

Check out my online course

If this helped you, and if you or someone you know is just getting into development, check out my upcoming online course:

Beyond Code Bootcamp

+1