While there are various ways to manage your own Javascript library locally or
from a git repository, it is more convenient to deploy to npm and consume
from there and certainly if you want to share your code publicly, you will at
some point want to publish to npm. Here, we’ll guide you through the basic
process.
npm Sign Up
In order to publish packages on npm, you need to have an account. If you don’t already have one, go ahead and sign up. A free account will allow you to publish public packages. But, if you want to publish private packages, you will need to sign up for a paid plan.
Getting Started
Create a new folder for your package. You’ll probably want to initialise it as
a git repository but we won’t cover that here. To initialise the folder for
use with npm, you should run npm init. npm will prompt for various parameters
before creating your package.json file. You can change your answers later
by editing package.json.
Package Name
One of the parameters you’ll be asked for is your package name. This name needs
to be unique in the npm repository, so you won’t be able to use a name that’s
already been used by someone else. A bit like .com domain names, you will find
that most of the good top level bare names are already gone. However, npm packages
can have scoped names of the form @scope/package-name. Since the scope is usually
your unique username or organization name, you shouldn’t have too much trouble
with a scoped name. Unless you’re planning an open source library that you expect
to be very widely used by the community, I would suggest sticking to scoped names
for now. Note that private packages will always have scoped names.
Top Level Files
README
You should create an informative README.md for your package that will explain to potential users how to install the package and call it’s API.
License
You may want to include a license file that documents the license and ownership of your package. If your package.json has referenced a standard license, you may not need a separate file.
Your Code
Now that you’ve created a package.json file, let’s go ahead and create some
code. We’ll come back to package.json later. We’re going to create a CommonJS
or cjs module. If you don’t know what that is, don’t worry about it for now.
cjs modules are the traditional and default module format for nodejs.
Let’s create a folder called src and a file called index.js in that folder.
For now, our library consists of a simple hello-world function.
function helloWorld() {
return 'Hello World!';
}
module.exports = helloWorld;
Edit package.json and set the main property to point to this file:-
{
...
"main": "src/index.js",
...
}
Testing the Package
We could try publishing the package, install it in another project, import it into an application and try it out. But, that would be a pretty slow dev/test cycle. Instead, it is preferable to test locally first. We’ll cover two different options here.
Use npm link
In the root folder of the library, run the command npm link. This will make the
package available globally. Now in a different directory tree, create a folder for
a test project. Let’s call it test_hello. Go to that folder and execute the following
commands:
npm init -y
npm link @scope/package-name
where scope and package-name are the values you used when creating your library. You
can check the name property in the package.json file of the library.
Create a file called test.js with the following content:
const helloWorld = require('@scope/package-name');
console.log(helloWorld());
If you’ve followed the above steps, you should see Hello World! being output
to the command line.
Use npm pack
npm pack will create a tarball, which is effectively the same as the tarball
that would be created in the npm repository if we published. As such, using it
for testing perhaps gets us a little bit closer to the publish scenario.
From the root folder of your package, execute:
npm pack
This will produce a file with a .tgz extension. The filename will reflect
your scoped package name with a version number.
Create and initialize a test folder with the commands:
npm init -y
npm install /<path-to-lib-folder>/<scope-package-name-0.1.0.tgz>
The additional steps are the same as described above for npm link.
Once again, running your test script should result in the expected output.
Publish the Package
In order to publish a package to npm, you must be logged in. Execute the command:
npm login
You will be prompted for username and password. You can login to the account you created earlier.
Now execute
npm publish
Depending on how you have set up your multi-factor authentication, you will
have to enter appropriate details. You should get a successful response
and your package will be available from npm. You can test it in the same
way as you tested with npm pack, replacing the initialisation commands
with:
npm init -y
npm install @<scope>/<package-name>
Updating the Package
If you update your package, you will want to publish again. When doing
so, you must update the version property in package.json. Any attempt
to publish with a version that has previously been used will result in an
error.
You probably won’t want version numbers to increment too quickly when you
are developing new features in your package. While npm link and npm pack
help in this regard, they may not cover all aspects of your dev/test cycle.
One way you can deal with this is to use alternative version names e.g.
alpha versions. To publish an alpha version:
npm version --no-git-tag-version 0.1.1-alpha1
npm publish -tag alpha
Then, to install the latest alpha version in your test project:
npm i @<scope>/<package-name>@alpha
Wrapping Up
This guide should get you started with creating npm packages. We have
only covered cjs packages in this article. In a future article,
we’ll cover how to publish esm packages and how you might approach
universal packages, that can be used by either type of application.