arjun-react-ui-demo

A beginner-friendly React component library project built for learning how npm packages work, how reusable React libraries are created, and how publishing and installing packages works.

Project Purpose

This repository is not a normal React app. It is a library package that can be published to npm and installed into other React projects.

• package.json is configured as a library package, not an application.
• src/ contains reusable components and shared theme logic.
• vite.config.ts builds the package in both ESM and CommonJS formats.
• dist/ is generated after build and contains the ready-to-publish package.

Folder Structure

• src/components/ - reusable UI components like Button, Card, and Input.
• src/themes/ - theme definitions and provider logic for light/dark mode.
• src/hooks/ - helper hooks like useTheme.
• src/styles/ - simple CSS styles for the components.
• src/types/ - shared TypeScript types and interfaces.
• src/index.ts - centralized exports so consumers can import from the package root.

Build Steps

Run:

npm install
npm run build

This creates the dist/ folder. The dist/ folder is the compiled package output that npm will publish.

Why build?

• src/ uses TypeScript and React JSX.
• The build step turns that source code into JavaScript that other projects can consume.
• The package exports both ESM and CommonJS formats for compatibility.
• Type declarations are generated so TypeScript users get proper autocompletion.

NPM Package Configuration

Key package.json fields

• name - package name published to npm.
• version - current package version following semantic versioning.
• main - CommonJS entry used by Node and some bundlers.
• module - ESM entry used by modern bundlers.
• types - TypeScript declaration file entry.
• exports - controls what files are visible to package consumers.
• files - limits what files are included when publishing.
• peerDependencies - tells consumers which versions of React the library expects.

Version Management

This project uses semantic versioning (semver): MAJOR.MINOR.PATCH

• 0.1.0 - initial release.
• 0.1.1 - patch release, bug fixes or small improvements.
• 0.2.0 - minor release, new features without breaking changes.
• 1.0.0 - major release, breaking changes may be introduced.

Npm will not allow republishing the same version once it has been published, so every release must use a new version.

Publish Guide

1. Log in to npm:

npm login

2. Build the package:

npm run build

3. Publish the package:

npm publish --access public

4. Update the package version for a new release:

npm version patch
npm version minor
npm version major

Example Consumer Usage

In another React project, install the package:

npm install arjun-react-ui-demo

Then import the components:

import React from 'react';
import { Button, Card, Input, ThemeProvider } from 'arjun-react-ui-demo';

function App() {
  return (
    <ThemeProvider>
      <Card title="Welcome">
        <p>This is a reusable card from the library.</p>
        <Input placeholder="Type here" />
        <Button variant="primary">Click me</Button>
      </Card>
    </ThemeProvider>
  );
}

export default App;

Public vs Private Packages

• Public package: available to everyone on npm.
• Private package: only available to your account or organization.
• Scoped package: starts with @scope/name and can be public or private.

This project is set up as a public package example using a simple public name.

Example Consumer Project Files

A small example consumer app is included in example/App.tsx to show how imports look from a package.

Happy learning! This repository is intentionally simple so you can understand the full package workflow.