How to Publish Your First npm Package: A Step-by-Step Guide

How to Publish Your First npm Package: A Step-by-Step Guide

Introduction

Publishing an npm package allows you to share your JavaScript or TypeScript project with the world. Whether it’s a utility library, a framework, or a tool, making your code available via npm opens up countless possibilities for collaboration and usage. In this guide, we’ll walk you through the process of publishing your first npm package, including automating the process with GitHub Actions.

Step 1: Setting Up the Package

Every npm package starts with a package.json file. This file contains metadata about your project, such as its name, version, and dependencies.

Verifying or Creating package.json

To check if package.json exists, run:

ls package.json

If it doesn’t exist, create it with:

npm init

Follow the prompts to fill out details like the package name, version, description, and entry point.

Key Fields in package.json

• name: The unique identifier for your package.
• version: The version number, following semantic versioning.
• main: The entry point file for your package.
• scripts: Commands to build, test, and publish.

Example: Minimal package.json

{  
"name": "my-awesome-package",  
"version": "1.0.0",  
"description": "A simple npm package example",  
"main": "index.js",  
"scripts": {  
"build": "tsc"  
},  
"keywords": \["example", "npm", "typescript"\],  
"author": "Your Name",  
"license": "MIT"  
}

Step 2: Preparing the Repository

Before publishing, ensure your repository is in a clean state:

git status

If there are uncommitted changes, stage and commit them:

git add .  
git commit -m "Prepare for publishing"

Check that all dependencies are installed and up-to-date:

npm install

Step 3: Authenticating with npm

Log in to npm to authenticate your account:

npm login

If you’re using GitHub’s Package Registry, use:

npm login --registry=<https://npm.pkg.github.com/>

Step 4: Building the Project

If your project uses TypeScript or needs transpilation, add a build script to your package.json:

"scripts": {  
"build": "tsc"  
}

Run the build command:

npm run build

Step 5: Publishing the Package

To publish your package, run:

npm publish

For scoped packages (e.g., @yourusername/package-name), use:

npm publish --access public

If you encounter errors, check:

• Your package.json for missing fields.
• The registry URL (https://registry.npmjs.org/ or https://npm.pkg.github.com/).

Automating Publishing with GitHub Actions

Setting Up a Workflow File

Create a directory for workflows:

mkdir -p .github/workflows

Add a publish.yml file with the following content:

name: Publish Package

on:  
push:  
branches:  
\- main  
\- 'release/\*'

jobs:  
publish:  
runs-on: ubuntu-latest

steps:  
\- name: Checkout repository  
uses: actions/checkout@v2

\- name: Set up Node.js  
uses: actions/setup-node@v2  
with:  
node-version: '16'  
registry-url: '<https://npm.pkg.github.com/>'

\- name: Install dependencies  
run: npm install

\- name: Build package  
run: npm run build

\- name: Publish package  
run: npm publish  
env:  
NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Explanation of the Workflow

• Triggers: Runs on pushes to main or release/* branches.
• Steps:

1. Checkout the repository.
2. Set up Node.js and configure the registry.
3. Install dependencies.
4. Build the package.
5. Publish the package using GITHUB_TOKEN .

Common Questions

Do I Need a Release Branch?

No, a release branch is optional. You can configure the workflow to trigger on any branch.

What About secrets.GITHUB_TOKEN?

GitHub automatically provides a GITHUB_TOKEN for workflows. No additional setup is needed.

Conclusion

Publishing your first npm package is a rewarding process that enables you to share your work with the developer community. By following this guide, you can confidently prepare, publish, and even automate the process using GitHub Actions. Happy coding!