How to Publish a React NPM Package: A Step-by-Step Guide for Reusable Component Development

Building reusable React components and publishing them as an NPM package is an effective way to accelerate frontend development, standardize interface elements, and share code across multiple projects.

Whether you are creating a React component library, design system, or reusable UI package, this guide walks through the complete process of creating, building, testing, and publishing a React NPM package.

Step 1: Create the React Package Structure

Create the following project structure:

my-react-package/
├── src/
│   ├── components/
│   │   └── MyComponent.js
│   ├── index.js
│   └── styles.css
├── package.json
├── README.md
└── .gitignore

This structure keeps components, styles, exports, documentation, and package configuration organized for long-term maintainability.

Step 2: Configure `package.json`

Create a package.json file with the following configuration:

{
  "name": "my-react-package",
  "version": "1.0.0",
  "description": "A description of your React package",
  "main": "dist/index.js",
  "scripts": {
    "build": "babel src -d dist",
    "prepublishOnly": "npm run build"
  },
  "keywords": [
    "react",
    "component",
    "npm"
  ],
  "peerDependencies": {
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  }
}

Important Fields

name defines the package name published to NPM.
version defines the current release version.
main defines the package entry point used by consumers.
peerDependencies helps prevent duplicate React installations.
prepublishOnly automatically builds the package before publishing.

Step 3: Create the React Component

Create the reusable component:

import React from 'react';

const MyComponent = (props) => {
  const { label } = props;

  return (
    <div>
      <button>{label}</button>
    </div>
  );
};

export default MyComponent;

Export the component through src/index.js:

export { default as MyComponent } from './components/MyComponent';

This export allows users to import the component directly from the package.

Step 4: Add a `.gitignore` File

node_modules/
dist/
.env

This prevents dependencies, generated build files, and environment variables from being committed to version control.

Step 5: Install and Configure Babel

Install the required Babel development dependencies:

npm install --save-dev @babel/cli @babel/preset-env @babel/preset-react

Create a .babelrc file:

{
  "presets": [
    "@babel/preset-react",
    "@babel/preset-env"
  ]
}

Babel transpiles modern JavaScript and JSX into code that can be consumed across different build environments.

Step 6: Build the Package

Run the build command:

npm run build

Before publishing, verify that:

All components compile successfully.
Exports resolve correctly.
No dependency conflicts exist.
The package entry point is correct.
The README documentation is complete.

Step 7: Publish the Package to NPM

npm login
npm publish

When the package name is already taken, choose a unique name or publish it under an organization scope.

Best Practices Before Publishing

Use semantic versioning.
Add clear documentation in README.md.
Include installation and usage instructions.
Test the package locally before publishing.
Add TypeScript definitions when applicable.
Confirm only required files are included in the published package.
Add a license field and license file when appropriate.

Using the Published React Package

Install the package:

npm install my-react-package

Import and use the component:

import { MyComponent } from 'my-react-package';

const App = () => {
  return (
    <div>
      <MyComponent label="Submit" />
    </div>
  );
};

export default App;

Common Challenges When Publishing React Packages

React version conflicts
Missing peer dependencies
Incorrect export paths
Babel configuration issues
Package naming conflicts
Unexpected build-output errors
Missing files in the published package

Testing the package locally with tools such as npm link can help identify issues before publication.

Conclusion

Publishing a React NPM package allows teams to create reusable UI components, accelerate frontend development, and share code consistently across applications.

By following a structured package setup, configuring Babel correctly, managing peer dependencies carefully, testing locally, and following NPM publishing best practices, you can create maintainable React component libraries that scale with your projects.

Anuj

Our Blogs

How to Publish a React NPM Package: A Step-by-Step Guide for Reusable Component Development