How to Create and Publish a Scoped NPM Package (@you/package) from Scratch

Photo by David A. Good (CC BY-NC-ND 2.0)

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.

@palta/unstyle

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.

Normal button vs. unstyled button

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 @palta/unstyle.

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

1. Go to https://www.npmjs.com
2. 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 palta which 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.
3. 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.
4. You should now have an Org where you are the sole member

New GitHub Repository and Initial Commit

1. Create a new GitHub repository: https://github.com/new
2. Grab the URL from the newly created repository, e.g. https://github.com/paltamadura/unstyle.git
3. Run this command on your machine in the location of your choice: git clone https://github.com/paltamadura/unstyle.git
4. Navigate into the project directory, e.g. cd unstyle
5. I recommend following the Gitflow Workflow for source control management. We’ll do the bare minimum here by using a develop branch as the main working branch rather than working directly on the master branch. So create a develop branch by running git checkout -b develop. The -b flag creates a new local branch if one doesn’t already exist.
6. 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.
7. Follow the prompts to initialize your project
8. For the initial commit you can just create a README.md file in the project root or add more files if you’re ready. More about README.md here: https://www.makeareadme.com/.
9. Once you’ve created the file(s), add the single README.md file like this: git add README.md, or add all files like this: git add --all. Before using --all , run git status to make sure you're not committing extraneous files like system files, or you can simply add a .gitignore file to prevent such files from getting tracked in the first place. More about ignoring files here. And here’s a sample .gitignore file I created for JavaScript projects: https://github.com/paltamadura/.files/blob/master/JavaScript.gitignore.
10. 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-upstream command will handle creating the branch in the remote repository and linking your local branch with the remote branch.
11. Finally, switch back to the master branch and merge the develop branch into the master branch: git checkout master followed 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 version in 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.

1. Browse to the root of your project
2. Run npm adduser
3. 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.
4. When prompted, enter your password
5. Run npm publish --access public
6. That’s it — you should be able to create a new test project now and import the package, for example, npm install --save @palta/unstyle or yarn add @palta/unstyle. You can also check if it looks as expected on UNPKG, for example https://unpkg.com/@palta/unstyle@1.0.1/package.json.