Skip to content

Instantly share code, notes, and snippets.

@coolaj86
Last active February 20, 2024 11:43
Star You must be signed in to star a gist
Save coolaj86/1318304 to your computer and use it in GitHub Desktop.
How to publish packages to NPM

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 "you@example.com"
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 foobar@1.1.3 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

root-uuid npm thumbnail

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

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

@danawoodman
Copy link

If you're tagging versions, try npm version major|minor|patch which intelligently increments the version number and creates a git tag and package.json version bump.

Copy link

ghost commented Mar 19, 2016

👍

@autopulous
Copy link

Is it possible to publish directly from a GitHub repository (as opposed to publishing from a local machine)? or better said, I'm not able to figure out how to do this... https://docs.npmjs.com/all#repository seems to indicate that the repository can be referenced/extracted from GitHub...

http://stackoverflow.com/questions/35026096/is-it-possible-to-publish-to-npm-directly-from-a-github-repository

👍👍👍👍👍👍👍👍👍👍👍👍👍👍👍👍👍👍👍👍👍👍👍👍👍👍👍👍👍👍

P.S. The first two links in the More Info section are broken

@Obooman
Copy link

Obooman commented Mar 29, 2016

Cool work!Thanks.

@abdghani
Copy link

Is it compulsory to provide a test in publishing a npm package ?

@andreafalzetti
Copy link

Very handy. Thanks 👍

@avaleriani
Copy link

👍

@AmmarHasan
Copy link

+1

@paradigmist
Copy link

👍

@zhangbg
Copy link

zhangbg commented Nov 30, 2016

mark.

@mortezakarimi
Copy link

mortezakarimi commented Aug 9, 2017

+1 👍

@alexandlazaris
Copy link

I'm having issues publishing my npm package. I added name and email using npm set init.author.name + same for email. After I do npm adduser and login successfully. After this I enter npm publish and get this error:

you do not have permission to publish "auto-reload". Are you logged in as the correct user? : auto-reload

Does this mean I must login as my package-name? (auto-reload) This makes no sense to me 🤔

@nuno-nlfsoftware
Copy link

👍

@jonathanarbely
Copy link

jonathanarbely commented Jan 21, 2018

CMD should be started as admin.
Edit: User Accounts should be created on npmjs.com. Then do npm login. Then publish with npm publish ./.

@xizon
Copy link

xizon commented Feb 2, 2018

nice!!

@ryanburnette
Copy link

Can you update this to include horse-npm?

@chattes
Copy link

chattes commented Feb 23, 2018

I published a package to npm but I dont see the linked github repo?
Any ideas?
image

@Aoa77
Copy link

Aoa77 commented Feb 28, 2018

+100

@AugustoAleGon
Copy link

AugustoAleGon commented Mar 27, 2018

I got the same problem!! @chattes

@talentedandrew
Copy link

Published my first npm package react-modern-datepicker

@PetrSnobelt
Copy link

to add linked github repo add repo section to package.json

@hustcc
Copy link

hustcc commented Nov 6, 2018

npm-robbery A command tool to register npm package name conveniently.

@nakulkundra
Copy link

@silviu-burcea Like this one?
https://npmjs.org/doc/developers.html

404

@markolofsen
Copy link

It's really easy if are you using special tool for publications.
It's works in your browser, without any special dependencies.

Try this library for that https://github.com/markolofsen/how_to_upload_package_to_npm

@karan3112
Copy link

Very helpful

@hayatbiralem
Copy link

Thank you, it was fast :)

@kapitannwel
Copy link

very very helpful, worked first time doing it! [+1]

@031nna
Copy link

031nna commented Sep 7, 2020

+1

@amirshnll
Copy link

thanks

@UltiRequiem
Copy link

+1

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment