How to Create NPM Package

Create NPM package is a rewarding process that allows developers to share their code with the world, streamline workflows, and contribute to the broader JavaScript community. Whether it’s a utility library, a framework, or a set of reusable components, NPM is the go-to repository for JavaScript packages.

Table of Contents

1. What is NPM and Why Create NPM Package?
2. Setting Up Your Development Environment
3. Planning Your NPM Package
4. Writing the Code
5. Configuring the package.json
6. Writing Documentation
7. Testing Your Package
8. Preparing Your Package for Publication
9. Publishing Your Package to NPM
10. Versioning and Updating Your Package
11. Common Issues and How to Solve Them
12. Best Practices for Creating NPM Packages
13. Conclusion

1. What is NPM and Why Create NPM Package?

What is NPM?

NPM is the world’s largest software registry. It hosts JavaScript libraries, frameworks, and utilities that developers can use in their projects. These packages are installed and managed through the NPM CLI (Command Line Interface).

Why Create NPM Package?

1. Reusability: Share common functionalities across projects.
2. Collaboration: Work with the community or your team more efficiently.
3. Contribution: Give back to the open-source community.
4. Visibility: Showcase your skills and enhance your professional portfolio

2. Setting Up Your Development Environment

Prerequisites

1. Install Node.js and NPM:
   1. Download and install Node.js from the official website. This will also install NPM.
   2. Verify installations:

node -v  
npm -v  

1. Set up a GitHub Repository (Optional):
   1. Use Git for version control and collaboration.
   2. Create a repository on GitHub.
2. Install a Code Editor:
   • Use a robust editor like Visual Studio Code.

Install Useful Tools

1. ESLint: For code linting.
2. Prettier: For consistent code formatting.
3. Jest/Mocha: For testing

3. Planning to Create NPM Package:

Before writing any code, define your package’s purpose and scope.

Key Questions to Answer:

1. What problem does it solve?
2. Who is the target audience?
3. What dependencies will it require?

Naming Your Package

1. Choose a unique and meaningful name.
2. Check availability on NPM

npm search <package-name>

4. Writing the Code

File Structure while Create NPM Package

Organize your project as follows:

my-npm-package/
├── src/
│   └── index.js
├── tests/
│   └── index.test.js
├── .eslintrc.json
├── .gitignore
├── package.json
└── README.md

Example: index.js

function capitalize(str) {
  if (typeof str !== 'string') throw new TypeError('Input must be a string');
  return str.charAt(0).toUpperCase() + str.slice(1);
}

module.exports = { capitalize };

5. Configuring the package.json (Create NPM Package)

The package.json file is the heart of your package. Create it using:

npm init

Key Fields to Include:

1. name: The package name.
2. version: Start with 1.0.0.
3. description: A short summary of the package.
4. main: The entry point file (e.g., src/index.js).
5. scripts: Add custom scripts like test or build.
6. keywords: Relevant search terms.
7. author: Your name or organization.
8. license: Use MIT or another open-source license

6. Writing Documentation

README.md

1. Title: Name of the package.
2. Description: Brief overview.
3. Installation: How to install the package.
4. Usage: Code examples.
5. Contributing: How others can contribute

7. Testing Your Package

Testing ensures that your package works as intended and provides a seamless experience for users. Writing reliable tests helps prevent bugs and makes your code maintainable and robust. Here’s how to test your NPM package effectively.

Why Testing is Important

1. Quality Assurance: Detects bugs before publishing.
2. Confidence in Updates: Ensures changes don’t break functionality.
3. User Trust: A well-tested package is more reliable.

Choosing a Testing Framework

There are several popular testing frameworks in the JavaScript ecosystem. Some common options include:

1. Jest: A comprehensive testing framework with built-in assertion and mocking capabilities.
2. Mocha: A flexible test runner often paired with assertion libraries like Chai.

Setting Up Jest

Install Jest as a development dependency:

npm install --save-dev jest

Add a test script in your package.json

"scripts": {
  "test": "jest"
}

Creating Test Files (Create NPM Package)

Organize test files separately in a tests directory or place them alongside your source files with a .test.js suffix.

Example

my-npm-package/
├── src/
│   └── index.js
├── tests/
│   └── index.test.js
├── package.json

Writing a Test Case

Let’s write a test for a capitalize function in your package.

Code in src/index.js:

function capitalize(str) {
  if (typeof str !== 'string') throw new TypeError('Input must be a string');
  return str.charAt(0).toUpperCase() + str.slice(1);
}

module.exports = { capitalize };

Test in tests/index.test.js:

const { capitalize } = require('../src/index');

describe('capitalize', () => {
  it('should capitalize the first letter of a string', () => {
    expect(capitalize('hello')).toBe('Hello');
  });

  it('should handle empty strings', () => {
    expect(capitalize('')).toBe('');
  });

  it('should throw an error for non-string inputs', () => {
    expect(() => capitalize(123)).toThrow(TypeError);
  });
});

Running Tests

Run the test suite using the command:

npm test

Test Output

If all tests pass, Jest will display a summary like this:

PASS  tests/index.test.js
✓ should capitalize the first letter of a string (5 ms)
✓ should handle empty strings (2 ms)
✓ should throw an error for non-string inputs (1 ms)

8. Preparing Your Package for Publication

Exclude unnecessary files:

node_modules/  
.env  

Check for Errors:

npm run lint  
npm test  

9. Publishing Your Package to NPM

Login to NPM

npm login  

Publish your NPM Package

npm publish

10. Versioning and Updating Your Package

Use Semantic Versioning:

• MAJOR: Breaking changes.
• MINOR: New features.
• PATCH: Bug fixes.

Update version:

npm version <major|minor|patch>
npm publish

11. Common Issues and How to Solve Them

1. Permission Errors: Use sudo or fix file permissions.
2. Name Conflicts: Choose a unique package name.
3. Unpublished Versions: Use npm unpublish cautiously.

12. Best Practices for Creating NPM Packages

1. Keep It Simple: Focus on one task.
2. Write Tests: Ensure reliability.
3. Use TypeScript: For type safety.
4. Follow Standards: Lint and format code.
5. Stay Updated: Regularly update dependencies.

13. Conclusion

Create NPM package is a great way to share your code with the world. By following these steps, you can develop, test, and publish a robust package that others will find useful. Remember, open-source is about collaboration, so welcome feedback and contributions to improve your package.

Check more content in our blogs.