a guide to releasing your first npm package
Introduction
npm (node package manager) is the world's largest software registry. According to the documentation, npm consists of three distinct components:
- the registry
- the website
- the CLI
The registry is an immense database containing all the node packages & modules ever published, complete with version info and metadata.
On the website, you can search for and view packages, create an npm profile, and manage user settings.
The CLI provides the primary means of interacting with npm, including the publishing of packages & modules, which we will now cover in-depth.
Prerequisites:
(1). an npm account
(2). a GitHub account
(3). the current version of Node.js
(4). the current stable version of npm
npm install npm@latest -g
Package vs Module
It is important to understand the two types of objects you can publish to the registry.
How is a package defined?
- a). A folder containing a program described by a
package.jsonfile. - b). A g-zipped tarball containing (a).
- c). A URL that resolves to (b).
- d). A
<name>@<version>that is published on the registry with (c). - e). A
<name>@<tag>that points to (d). - f). A
<name>that has alatesttag satisfying (e). - g). A
gitURL that, when cloned, results in (a).
How is a module defined?
Any file or directory within node_modules that can be loaded by the Node.js require() function. To comply, at least one of these formats must be used.
- A folder with a
package.json filecontaining a"main"field. - A folder with an
index.jsfile in it. - A JavaScript file.
A module can also be a package, but not all modules are packages by default.
Private vs Public
This parameter determines the visibility of your new npm package. For this article, it is assumed that you will elect to create a public package, but you may always reference the documentation for more details.
Scoped vs Unscoped
Here you will define whether you want to release your code completely to the public domain (unscoped) or publish the code within a retained namespace (scoped).
Unscoped packages are always public.
Private packages are always scoped.
Scoped packages are private by default; you must pass a command-line flag when publishing to make them public.
The command line interprets your decision by how your package is named. I'll create examples based on my own npm account username.
PUBLIC/UNSCOPED: npm publish my-package
PUBLIC/SCOPED: npm publish @killshot13_npm/my-package --access public
PRIVATE/SCOPED: npm publish @killshot13_npm/my-package
To avoid confusing the reader, I shall refrain from much discussion about teams, organizations, and enterprise accounts.
Since this article is about publishing our first npm package, I doubt these factors will be of much concern at present. Just be aware of the concepts for future knowledge.
Create | Review | Test | Publish
At last, the moment you have been waiting for! These four simple steps are what you will be using to publish your package or module to the registry.
WARNING: If you deviate from this path or omit one of these steps, chances are you will encounter errors and spend a considerable amount of time debugging your files.
Create
mkdir my-package
cd my-package
Now that you have a root directory, initiate git and npm.
git init
git remote add origin git://YOUR URL HERE
npm init
// Follow the prompts to create a package.json file.
// Consider the conventions listed above when naming your package.
Now open the directory in your favorite code editor and add a README.md file and the rest of your package code files.
Review
In this step, use whatever means are at your disposal to double-check your code for environmental variables, including passwords, API keys, and other sensitive data.
If necessary, create the appropriate files and replace your existing code with default variables as needed to protect your secrets.
.gitignore | .npmignore | .env | PROCESS.ENV
Test
Almost there! Just one more quick (hopefully) thing to wrap up before you publish. To keep bugs out of the registry, especially when publishing publicly, you should first test your package in your own environment.
Since you are already using the npm CLI, you can just run this command.
// Use the full path to your project directory.
npm install my-package
If everything functions as designed, congratulations, you are ready to publish your first package!
Publish
This is the simplest and most satisfying step. Navigate back to the root directory of your npm package.
cd /path/to/package
Are you ready?
npm publish my-package
If npm prints something that looks like this, you are golden!
Tips & Tricks
Once you npm publish, you CANNOT change your package name! Take a moment to solidify your choice of words. Try to keep package names short and descriptive. For an example of what not to do, imagine installing this npm package.
I pity the fool!
npm install --save @teambit/staged-components.component-status-resolver
Sometimes, even with an unscoped public package, npm refuses to publish unless you include a flag. Add --access public to your command and try again.
npm publish my-package --access public
If you enabled 2FA when creating your npm account, you will have to provide the one-time token in your publish command.
npm publish my-package --otp=811486
Conclusion
I hope you enjoyed this article. Feel free to add suggestions or ask questions in the comments below, and I will get back to you. Thank you for reading, and happy coding!
Don't forget to 💖 this article and leave a 💭. If you're feeling extra generous, please click my name below to 🎆subscribe🎇!
-- killshot13
Top comments (0)