Engineer's Guide: Building a React Component Library From Scratch

Need custom internal tools, minus the usual dev marathon? Try DronaHQ Free —Go from zero to deployed app in an afternoon!

TL;DR: Engineer's Quick Start

This guide walks engineers through building a React component library from scratch. Key steps include:

1. Introduction: Why Build a Component Library?

As an engineer, you understand the value of DRY (Don't Repeat Yourself) principles and maintainable code. A React component library embodies these by providing a centralized, versioned collection of reusable UI elements. For internal tools, this means:

This guide focuses on the technical execution of building such a library. For a higher-level overview on planning and strategy, refer to resources aimed at engineering management.

2. Core Project Setup & Essential Tooling

Setting up your project correctly is crucial. We'll use TypeScript for type safety, Rollup for efficient bundling, Jest for testing, and Storybook for component development and documentation.

Start by initializing a new npm package and installing essential development dependencies:

mkdir my-react-ui-library && cd my-react-ui-library
npm init -y
# Core React and build tools
npm install --save-dev react react-dom typescript rollup @rollup/plugin-node-resolve @rollup/plugin-commonjs @rollup/plugin-typescript @babel/preset-react @babel/preset-typescript tslib
# Testing tools
npm install --save-dev jest @testing-library/react @testing-library/jest-dom jest-environment-jsdom babel-jest
# Storybook
npm install --save-dev storybook @storybook/react-webpack5 @storybook/addon-essentials @storybook/addon-interactions @storybook/testing-library webpack
# Optional: for CSS handling in Rollup
npm install --save-dev rollup-plugin-postcss postcss

Configure tsconfig.json for TypeScript compilation:

{
  "compilerOptions": {
    "target": "ES6",            // Target modern JavaScript
    "module": "ESNext",         // Use ES modules for tree shaking
    "lib": ["dom", "dom.iterable", "esnext"],
    "jsx": "react-jsx",         // Use new JSX transform
    "declaration": true,        // Generate .d.ts files
    "declarationDir": "dist/types", // Output directory for .d.ts files
    "outDir": "dist",           // Output directory for JS files (if not using Rollup for this)
    "rootDir": "src",           // Source directory
    "strict": true,             // Enable all strict type-checking options
    "esModuleInterop": true,    // Enables emit interoperability between CommonJS and ES Modules
    "skipLibCheck": true,       // Skip type checking of all declaration files (*.d.ts)
    "forceConsistentCasingInFileNames": true,
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true              // Let Rollup handle emits, TS only for type checking & declarations
                                // Set to false if you want tsc to emit JS files alongside Rollup
  },
  "include": ["src/**/*"],      // Files to include for compilation
  "exclude": ["node_modules", "dist", "**/*.stories.tsx", "**/*.test.tsx"]
}

Note: The "noEmit": true setting is common if Rollup is solely responsible for transpiling and bundling JS, while tsc is used for generating declaration files. Adjust if your setup differs.

Configure Babel (babel.config.js) for Jest and Storybook (Rollup can use its own TypeScript plugin):

module.exports = {
  presets: [
    '@babel/preset-env', // For transpiling ES6+ down to ES5 if needed for older environments
    '@babel/preset-react',
    '@babel/preset-typescript',
  ],
};

Configure Rollup (rollup.config.js) for bundling your library:

import resolve from '@rollup/plugin-node-resolve';
import commonjs from '@rollup/plugin-commonjs';
import typescript from '@rollup/plugin-typescript';
import postcss from 'rollup-plugin-postcss'; // If handling CSS
// import { terser } from 'rollup-plugin-terser'; // For minification

const packageJson = require('./package.json');

export default {
  input: 'src/index.ts', // Your library's entry point
  output: [
    {
      file: packageJson.main,
      format: 'cjs', // CommonJS for Node compatibility
      sourcemap: true,
    },
    {
      file: packageJson.module,
      format: 'esm', // ES Module for tree shaking
      sourcemap: true,
    },
  ],
  plugins: [
    resolve(),
    commonjs(),
    typescript({ tsconfig: './tsconfig.json', exclude: ["**/*.test.tsx", "**/*.stories.tsx"] }),
    postcss({ // Example for handling CSS files
      extract: 'styles.css', // Extracts CSS to a single file
      minimize: true,
    }),
    // terser(), // Uncomment for production builds to minify
  ],
  external: ['react', 'react-dom'], // Externalize peer dependencies
};

Ensure your package.json has main, module, and types fields pointing to the Rollup outputs and declaration files respectively (see Publishing section).

3. Structuring Your Library for Maintainability

A clear folder structure is vital for a growing component library:

my-react-ui-library/
├── dist/                     // Bundled output
├── src/
│   ├── index.ts              // Main export file for all public components/hooks
│   ├── components/           // Directory for individual UI components
│   │   └── Button/
│   │       ├── Button.tsx    // Component logic and JSX
│   │       ├── Button.module.css // Component-specific styles (CSS Modules example)
│   │       ├── Button.stories.tsx // Storybook stories
│   │       └── Button.test.tsx    // Jest/RTL tests
│   │   └── AnotherComponent/
│   ├── hooks/                // Reusable custom React hooks
│   │   └── useSomeLogic.ts
│   ├── styles/               // Global styles, design tokens, base styles
│   │   ├── _variables.css    // CSS Variables for design tokens
│   │   └── global.css
│   └── utils/                // Shared utility functions
│       └── helpers.ts
├── .storybook/               // Storybook configuration
├── jest.config.js            // Jest configuration
├── rollup.config.js          // Rollup configuration
├── tsconfig.json             // TypeScript configuration
├── babel.config.js           // Babel configuration
└── package.json

Your main entry point src/index.ts should export everything you want to make public from your library:

// src/index.ts
export * from './components/Button/Button';
// export * from './components/AnotherComponent/AnotherComponent';
// export * from './hooks/useSomeLogic';
// export * from './styles/global.css'; // If you want to allow global CSS import

4. Crafting Your First Component (Button Example)

Let's create a foundational Button component.

src/components/Button/Button.tsx:

import React, { ButtonHTMLAttributes } from 'react';
import styles from './Button.module.css'; // Using CSS Modules

export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: 'primary' | 'secondary' | 'destructive';
  size?: 'small' | 'medium' | 'large';
  children: React.ReactNode; // Use children for the label or content
}

export const Button: React.FC<ButtonProps> = ({
  children,
  variant = 'primary',
  size = 'medium',
  className = '',
  ...props
}) => {
  const modeClass = styles[variant] || styles.primary;
  const sizeClass = styles[size] || styles.medium;

  return (
    <button
      type="button" // Default to type="button" for accessibility unless overridden
      className={`${styles.buttonBase} ${modeClass} ${sizeClass} ${className}`}
      {...props}
    >
      {children}
    </button>
  );
};

src/components/Button/Button.module.css (Example using CSS Modules):

/* src/components/Button/Button.module.css */
.buttonBase {
  border: none;
  padding: 10px 20px;
  cursor: pointer;
  font-family: inherit;
  border-radius: 4px;
  transition: background-color 0.2s ease-in-out, box-shadow 0.2s ease-in-out;
  display: inline-flex;
  align-items: center;
  justify-content: center;
  text-decoration: none; /* For anchor-like buttons */
  font-weight: 700; /* Bolder for Montserrat */
}

.buttonBase:focus-visible {
  outline: 2px solid var(--focus-ring-color, blue); /* Define --focus-ring-color in global styles */
  outline-offset: 2px;
}

/* Variants */
.primary {
  background-color: var(--button-primary-bg, #007bff);
  color: var(--button-primary-text, white);
}
.primary:hover {
  background-color: var(--button-primary-hover-bg, #0056b3);
}

.secondary {
  background-color: var(--button-secondary-bg, #6c757d);
  color: var(--button-secondary-text, white);
}
.secondary:hover {
  background-color: var(--button-secondary-hover-bg, #545b62);
}

.destructive {
  background-color: var(--button-destructive-bg, #dc3545);
  color: var(--button-destructive-text, white);
}
.destructive:hover {
  background-color: var(--button-destructive-hover-bg, #c82333);
}

/* Sizes */
.small {
  padding: 6px 12px;
  font-size: 0.875rem;
}
.medium {
  padding: 10px 20px;
  font-size: 1rem;
}
.large {
  padding: 12px 24px;
  font-size: 1.125rem;
}

Ensure you define CSS variables like --button-primary-bg in your global styles (e.g., src/styles/_variables.css) for theming capabilities.

5. Comprehensive Testing & Storybook Integration

Testing with Jest & React Testing Library:

jest.config.js:

module.exports = {
  testEnvironment: 'jsdom',
  setupFilesAfterEnv: ['<rootDir>/jest.setup.js'], // if you have a setup file
  moduleNameMapper: {
    '\\.(css|less|scss|sass)$': 'identity-obj-proxy', // Mocks CSS Modules
  },
  transform: {
    '^.+\\.(ts|tsx|js|jsx)$': 'babel-jest',
  },
};

Create jest.setup.js (optional, for global test setup like importing @testing-library/jest-dom):

// jest.setup.js
import '@testing-library/jest-dom';

src/components/Button/Button.test.tsx:

import React from 'react';
import { render, screen, fireEvent } from '@testing-library/react';
import { Button } from './Button';

describe('Button Component', () => {
  test('renders with children', () => {
    render(<Button>Click Me</Button>);
    expect(screen.getByRole('button', { name: /Click Me/i })).toBeInTheDocument();
  });

  test('applies variant and size classes correctly', () => {
    render(<Button variant="secondary" size="large">Submit</Button>);
    const button = screen.getByRole('button', { name: /Submit/i });
    // Note: Testing CSS module class names can be tricky. 
    // It's often better to test visual appearance via visual regression tests.
    // However, you can check if base classes are applied if needed.
    expect(button).toHaveClass('buttonBase'); // from Button.module.css, actual name might be mangled
    // For specific variant/size classes, snapshot testing or visual testing is more robust.
  });

  test('calls onClick handler when clicked', () => {
    const handleClick = jest.fn();
    render(<Button onClick={handleClick}>Test Click</Button>);
    fireEvent.click(screen.getByText('Test Click'));
    expect(handleClick).toHaveBeenCalledTimes(1);
  });

  test('is disabled when disabled prop is true', () => {
    render(<Button disabled>Disabled Button</Button>);
    expect(screen.getByRole('button', { name: /Disabled Button/i })).toBeDisabled();
  });
});

Storybook for Development and Documentation:

Initialize Storybook in your project:

npx storybook@latest init

Follow the prompts. It should detect your React setup.

src/components/Button/Button.stories.tsx:

import React from 'react';
import type { Meta, StoryObj } from '@storybook/react';
import { Button, ButtonProps } from './Button'; // Import ButtonProps

const meta: Meta<ButtonProps> = { // Use ButtonProps for Meta type
  title: 'Components/Button',    // How it will appear in Storybook navigation
  component: Button,
  tags: ['autodocs'],            // Enables auto-generated documentation
  argTypes: {                   // Define controls for props
    variant: {
      control: { type: 'select' },
      options: ['primary', 'secondary', 'destructive'],
      description: 'The visual style of the button',
    },
    size: {
      control: { type: 'select' },
      options: ['small', 'medium', 'large'],
      description: 'The size of the button',
    },
    children: {
      control: 'text',
      description: 'Button label or content',
    },
    disabled: {
      control: 'boolean',
      description: 'Disables the button',
    },
    onClick: {
      action: 'clicked', // Logs clicks in the Storybook actions tab
      description: 'Optional click handler',
    },
  },
  parameters: {
    layout: 'centered', // Centers the component in the Canvas tab
  },
};

export default meta;

// Define a "template" story that maps args to the component
type Story = StoryObj<ButtonProps>; // Use ButtonProps for Story type

export const Primary: Story = {
  args: {
    variant: 'primary',
    size: 'medium',
    children: 'Primary Button',
  },
};

export const Secondary: Story = {
  args: {
    variant: 'secondary',
    size: 'medium',
    children: 'Secondary Button',
  },
};

export const Destructive: Story = {
  args: {
    variant: 'destructive',
    size: 'medium',
    children: 'Delete',
  },
};

export const LargePrimary: Story = {
  args: {
    variant: 'primary',
    size: 'large',
    children: 'Large Primary',
  },
};

export const SmallSecondary: Story = {
  args: {
    variant: 'secondary',
    size: 'small',
    children: 'Small Secondary',
  },
};

export const Disabled: Story = {
  args: {
    variant: 'primary',
    children: 'Disabled Button',
    disabled: true,
  },
};

Run Storybook with npm run storybook.

6. Publishing & Versioning Your Library

Once your components are ready, you'll publish your library to a package registry (like npm or a private registry).

Update package.json with necessary fields:

{
  "name": "my-react-ui-library",
  "version": "0.1.0",
  "private": false, // Set to false to publish
  "description": "A fantastic React UI component library.",
  "author": "Your Name <youremail@example.com>",
  "license": "MIT", // Or your chosen license
  "repository": {
    "type": "git",
    "url": "https://github.com/yourusername/my-react-ui-library.git" // Replace
  },
  "main": "dist/index.cjs.js", // CommonJS entry point from Rollup
  "module": "dist/index.esm.js", // ES Module entry point from Rollup
  "types": "dist/types/index.d.ts", // TypeScript definitions entry point
  "files": [ // Files to include in the published package
    "dist"
  ],
  "scripts": {
    "build": "rollup -c", // Your build command
    "test": "jest",
    "storybook": "storybook dev -p 6006",
    "build-storybook": "storybook build",
    "lint": "eslint src --ext .ts,.tsx",
    "clean": "rm -rf dist" // Script to clean the dist folder
  },
  "peerDependencies": { // Specify peer dependencies
    "react": "^17.0.0 || ^18.0.0",
    "react-dom": "^17.0.0 || ^18.0.0"
  },
  "devDependencies": {
    // ... your dev dependencies ...
  },
  "dependencies": {
    // "tslib": "^2.x.x" // tslib is often a runtime dependency when using --importHelpers in tsconfig or by some TS features
  }
}

Publishing Steps:

  1. Ensure your code is committed and pushed to your Git repository.
  2. Build your library: npm run build (this should run Rollup and tsc for declarations).
  3. Log in to npm (or your private registry): npm login.
  4. Update the version (semantic versioning is recommended): npm version patch (for bug fixes: 0.1.0 -> 0.1.1)
    npm version minor (for new features, non-breaking: 0.1.0 -> 0.2.0)
    npm version major (for breaking changes: 0.1.0 -> 1.0.0)
  5. Publish: npm publish (add --access public if publishing a scoped package to npm for the first time).
  6. Push tags to Git: git push --tags.

Consider using tools like semantic-release to automate the versioning and publishing process based on commit messages.

7. Advanced Considerations for Robust Libraries

As your library grows, consider these advanced topics:

8. Conclusion & Best Practices

Building a high-quality React component library is an iterative process that requires careful planning, robust tooling, and a commitment to best practices. As an engineer, your focus should be on:

A well-crafted component library will significantly improve the efficiency, consistency, and quality of your organization's internal tools, making it a valuable asset for the engineering team.

Dinesh Kumar, VP Engineering, Yubi Group

"We didnt build our library for internal tools; we rather used DronaHQ low code platform!"

"Building and maintaining our own React component library was a huge time sink. We switched to DronaHQ, a visual dev tool, and it's made building internal tools 10x simpler and faster for our entire engineering team. Now we focus on solving business problems, not UI plumbing."

Dinesh Kumar

VP Engineering, Yubi Group

Simplify Your Internal Tooling →