How to Create and Publish a Scoped NPM Package (@you/package) from Scratch
I had never published an NPM package, so I went through the process from start to finish and documented the steps hoping that it will help others.
First, I had to think of an idea for a new package. I wanted it to be dead simple so I could focus on the stated goal of publishing a new package from scratch. I came up with a simple idea based on my experience of copying and pasting CSS across various projects in order to create HTML elements which override the default user agent stylesheet. The classic example of this is a
<button> where the default browser styling is never something you would want to keep, so it makes sense to start off a basic, unstyled element. And so, @palta/unstyle was born: GitHub, NPM.
I knew I wanted to keep the name as simple as the package. But if you’ve ever searched through NPM, it can be challenging to find a name which is not already taken. At the same time, I found the scoped package format like
@babel/core attractive. So it was an easy decision to go with a scoped packaged where I wouldn’t have to compete for a package name in the global NPM namespace. I settled on
palta for the Org name and
unstyle for the package name, so the resulting scoped package is
Step By Step Guide
This guide assumes you already have git, node, and npm installed, and you have a GitHub account.
Creating an NPM Account and Org
- Go to https://www.npmjs.com
- Create an account which you will immediately convert into an Org where the account name you choose will become the Org name. For example, I created an account
paltawhich I then converted into an Org,
palta, to be used like this:
@palta/<package>. There may be an easier way to do it, but this is what worked for me.
- Convert your account into an Org following the instruction here: https://docs.npmjs.com/converting-your-user-account-to-an-org. You will need to provide a new account name to replace your existing one.
- You should now have an Org where you are the sole member
New GitHub Repository and Initial Commit
- Create a new GitHub repository: https://github.com/new
- Grab the URL from the newly created repository, e.g. https://github.com/paltamadura/unstyle.git
- Run this command on your machine in the location of your choice:
git clone https://github.com/paltamadura/unstyle.git
- Navigate into the project directory, e.g.
- I recommend following the Gitflow Workflow for source control management. We’ll do the bare minimum here by using a
developbranch as the main working branch rather than working directly on the
masterbranch. So create a
developbranch by running
git checkout -b develop. The
-bflag creates a new local branch if one doesn’t already exist.
- Run this command to initialize a scoped NPM project:
npm init --scope=@<org>using the Org name created above. For example, I ran
npm init --scope=@palta.
- Follow the prompts to initialize your project
- For the initial commit you can just create a
README.mdfile in the project root or add more files if you’re ready. More about
- Once you’ve created the file(s), add the single
README.mdfile like this:
git add README.md, or add all files like this:
git add --all. Before using
git statusto make sure you're not committing extraneous files like system files, or you can simply add a
.gitignorefile to prevent such files from getting tracked in the first place. More about ignoring files here. And here’s a sample
- Now run
git commit -m "Initial commit"followed by
git push --set-upstream origin develop. The develop branch doesn't exist yet in the remote repository (GitHub), so the
--set-upstreamcommand will handle creating the branch in the remote repository and linking your local branch with the remote branch.
- Finally, switch back to the
masterbranch and merge the
developbranch into the
git checkout masterfollowed by
git merge develop.
Publish your NPM Package
Note: The NPM package version will be taken from the
version field of your
package.json. So if you’re going to release multiple versions, you will need to manually update the
package.json assuming you don’t already have a build/release process in place which takes care of this for you. You should also take advantage of git tags (more about them here) when you publish a new version so you have a sort of bookmark of that version. You can start to see that this can get very repetitive and prone to errors. So investing some time in setting up an automated build/release process quickly becomes worthwhile.
- Browse to the root of your project
- When prompted, enter the account name from above. This is the replacement account name you had to provide when you converted your account to an Org.
- When prompted, enter your password
npm publish --access public
- That’s it — you should be able to create a new test project now and import the package, for example,
npm install --save @palta/unstyleor
yarn add @palta/unstyle. You can also check if it looks as expected on UNPKG, for example https://unpkg.com/@firstname.lastname@example.org/package.json.