Mastering npm: How to create, publish, and manage your own package

When you're working on multiple projects or building tools for your team, it helps to have a clean way to share code. Copy-pasting files between repos doesn’t scale. It gets messy fast.

npm solves that.

You can take a piece of code (maybe a utility, a config setup, or a custom component ), wrap it in a package, and publish it. Now anyone on your team (or the internet) can install it with one command.

This is how big teams stay consistent. One shared package. One source of truth. Easy to update, easy to use.

In this guide, we’ll go through the full process of creating your own npm package. From setting it up to publishing and keeping it updated. Public packages, private ones, versioning, all of it.

Let’s get into it.

Setting up your npm package

Before you can publish anything, you need to set up the basics. That means installing Node.js, running a simple command to start your package, and understanding the package.json file that gets created.

Install Node.js and npm

npm comes with Node.js, so you only need to install one thing.

Go to nodejs.org, download the LTS version, and install it. Once that’s done, open your terminal and check that it worked:

node -v
npm -v

If you see version numbers, you're good to go.

Initialize the Package

Create a new folder for your package:

mkdir my-awesome-package
cd my-awesome-package

Now run:

npm init

This will ask you a few questions: package name, version, description, entry file (usually index.js), etc. Just hit enter to accept the defaults if you're not sure. At the end, you'll have a file called package.json.

If you want to skip the questions and use the defaults right away, use:

npm init -y

What’s in package.json?

This file is the config for your package. It tells npm (and others) the name of the package, what version it is, which file to load when it’s imported, what scripts it can run, and more.

Here’s a simple example:

{  
"name": "my-awesome-package",  
"version": "1.0.0",  
"description": "Just a test package",  
"main": "index.js",  
"scripts": {    
"test": "echo \"No tests yet\" && exit 0"  
},  
"author": "Your Name",  
"license": "MIT"
}

You can edit this file manually whenever you need to update anything.

Writing and organizing the package

Once the setup is done, it’s time to actually write some code and make your package usable.

Structure your project

Keep things clean and easy to understand. Here's a simple folder structure that works for most packages:

my-awesome-package/
├── src/
│   └── index.js
├── test/│   
    └── index.test.js
├── package.json
├── README.md
├── .gitignore
├── LICENSE

• src/ is where your actual code goes
  
  
• test/ can hold unit tests (if you're using any)
  
  
• README.md is where you explain what your package does and how to use it
  
  
• .gitignore to ignore node_modules and other junk
  
  
• LICENSE if you’re sharing it publicly (MIT is a common choice)
  

Add dependencies

If your package depends on other libraries, install them :

npm install lodash

This adds the library to your dependencies in package.json.

If you only need something for development—like a test runner or bundler—use --save-dev:

npm install jest --save-dev

This adds it to devDependencies instead.

Add npm scripts

You can define custom commands in the scripts section of your package.json. Here's an example:

"scripts": {  
"test": "jest",  
"build": "babel src -d dist"
}

Now you can run npm run test or npm run build right from the terminal.

Write a README

This is important. A good README.md helps others (and future you) understand what your package does and how to use it.

At the very least, include:

• What the package does
  
  
• How to install it
  
  
• Basic usage examples
  
  
• Any available options or config
  
  

You don’t need to go overboard, just make it useful.

Publishing to npm

Once your package is ready, it’s time to publish it so others can use it too. This is easier than it sounds.

Create an npm account

First, sign up at npmjs.com. Once you’ve created your account, log in from the terminal:

npm login

It’ll ask for your username, password, and email. After that, you’re good to go.

Check if the package name is available

Package names on npm have to be unique (if public). To check if your name is taken:

npm search my-awesome-package

If it’s already published by someone else, you’ll need to pick a different name or scope it under your username or org (e.g., @yourname/my-package).

Publish the Package

Now the fun part. From the root of your package directory, just run:

npm publish

npm will package everything up and push it to the registry.

Quick tip: By default, npm includes all files in your folder when publishing. If there are things you don’t want to publish (like test/ or .env), add them to a .npmignore file—just like .gitignore.

Versioning Your Package

npm uses semantic versioning (semver). Every time you publish a new version, you need to bump the version number.

Use one of these:

npm version patch   # small fix
npm version minor   # new feature, backward compatible
npm version major   # breaking change

This command updates the version in package.json and creates a git tag (if you’re using git).

After bumping the version, just run:

npm publish

And your update will be live.

Making private npm packages

Not everything needs to be public. Sometimes you just want to share code within your team or company. That’s where private packages come in.

Public vs private

By default, every package you publish to npm is public. Anyone can search for it, install it, and see the code.

Private packages are different—they stay hidden unless someone has permission to access them. This is great for internal tools, company-specific utilities, or anything you don’t want out in the wild.

Publish a private package

To make a package private, first set "private": true in your package.json if you want to keep it local only and never publish it. But if you do want to publish it to npm and still keep it private, use this:

npm publish --access=restricted

This makes it a private package on the registry. Only people with access (you or your team) can install it.

You’ll also need a paid npm account or be part of an npm organization with a private plan.

Use npm Organizations

If you're working in a team, it’s worth creating an npm Organization. It lets you:

• Group packages under a shared scope (like @yourteam/package-name)
  
  
• Manage who can read, write, and publish packages
  
  
• Keep things organized across teams and projects
  
  

Example of publishing under a scoped name:

npm init --scope=@yourteam
npm publish --access=restricted

Now your package is @yourteam/my-package and private to the team.

Maintaining and updating npm package

Publishing your package is just the start. Keeping it up-to-date, secure, and usable over time is what really makes it solid.

Run security checks

npm has a built-in tool to help you find and fix known vulnerabilities in your dependencies.

Just run:

npm audit

To automatically fix what it can:

npm audit fix

This is worth running regularly, especially before publishing new versions.

Deprecate old versions

Sometimes you release a version that breaks something, or you want people to stop using an outdated release. You can mark it as deprecated :

npm deprecate my-awesome-package@1.0.0 "This version has issues. Please upgrade to 1.1.0"

npm will show that message to anyone trying to install the old version.

Stay active on GitHub

If your package is public or open source, GitHub is where users will go to file issues, suggest changes, or ask questions. A few quick tips:

• Keep your README up to date
  
  
• Respond to issues if you can
  
  
• Accept pull requests when they make sense
  
  
• Tag releases so people can track changes
  
  

Even if it’s just an internal tool, having it on GitHub (or GitLab, Bitbucket, etc.) helps with version control 

Conclusion 

Creating and managing your own npm package is a great way to share code, improve consistency, and speed up development across projects. Whether it's for your team or the open-source community, a well-built package can save hours and reduce tech debt over time.

At Aubergine, we help engineering teams build scalable systems through clean architecture, reusable components, and smart workflows. If you're looking to standardize your development process or build tools that grow with your team, let’s talk.