Best Practices for npm and Yarn Libraries

German CoccaFebruary 8, 2025About 3 min

Best Practices for npm and Yarn Libraries 관련

In the world of JavaScript development, npm (Node Package Manager) has become an essential tool for managing dependencies and sharing reusable code. Whether you're building a simple website or a complex web application, npm libraries help streamline ...

How to Create an npm Library

Now that you've created, published, and used your own npm package, it's essential to follow best practices to ensure your package is reliable, maintainable, and easy to use. This section will cover key principles and techniques to make your npm library as professional as possible.

Write Meaningful Documentation

A well-documented library helps other developers understand how to use it effectively.

What to Include in Your Documentation

📌 Installation instructions
📌 Usage examples
📌 API reference (functions, parameters, return values)
📌 Versioning and update history
📌 Contributions guide (if open-source)

For example, a simple README.md file for my-awesome-library:

# my-awesome-library

A simple npm package for formatting dates.

---

## Installation

### Using npm

````sh
npm install my-awesome-library

Using Yarn

yarn add my-awesome-library

Usage

import { formatDate } from "my-awesome-library";

console.log(formatDate(new Date())); // Outputs: 2025-02-04


---

## Follow Semantic Versioning (SemVer)

Versioning helps maintain compatibility and informs users of changes. npm follows Semantic Versioning (SemVer):

MAJOR.MINOR.PATCH

| Change Type | Example | Meaning |
| --- | --- | --- |
| **Patch** | `1.0.0 → 1.0.1` | Bug fixes, no breaking changes |
| **Minor** | `1.0.0 → 1.1.0` | New features, no breaking changes |
| **Major** | `1.0.0 → 2.0.0` | Breaking changes |

::: note

To bump versions automatically, use:

```sh
npm version patch   # Small bug fix
npm version minor   # New feature added
npm version major   # Breaking changes

Then, publish the new version:

npm publish

👉 Use proper versioning to prevent breaking projects that depend on your library.

:::

Keep Dependencies Up to Date

Regularly updating dependencies improves security, performance, and compatibility.

Check for outdated dependencies:

yarn outdated

npm outdated

Update dependencies:

yarn upgrade

npm update

Write Unit Tests for Your Library

Testing ensures your package works correctly before publishing updates.

Install a Testing Framework (Jest)

npm install --save-dev jest

Create a Test File (`index.test.js`)

const { formatDate } = require("./index");

test("formats a date correctly", () => {
  expect(formatDate(new Date("2025-02-04"))).toBe("2025-02-04");
});

test("throws an error if input is not a date", () => {
  expect(() => formatDate("not a date")).toThrow("Invalid date");
});

Run Tests

npm test

👉

You can use CI/CD (for example, GitHub Actions) to run tests automatically on every push.

Using CI/CD for Automated Publishing

Automate Publishing with GitHub Actions

Create a .github/workflows/publish.yml file:

name: Publish to npm
on:
  push:
    branches:
      - main

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
          registry-url: "https://registry.npmjs.org/"
      - run: npm install
      - run: npm test
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

1️⃣ Create an npm token:

npm token create

Copy the token and add it to GitHub Secrets (NPM_TOKEN).

2️⃣ Push code to GitHub → Auto-publish on npm!

👉 Automating publishing prevents human errors and ensures quality control.

Ensure Cross-Platform Compatibility

Use ES modules (import/export) for modern compatibility.
Include CommonJS (require/module.exports) support for older environments.
Test with different Node.js versions using CI/CD.

Example package.json for dual compatibility:

"type": "module",
"main": "index.cjs",
"exports": {
  "import": "./index.mjs",
  "require": "./index.cjs"
}

👉

This ensures your package works everywhere (Node.js, React, Next.js, and so on).