React Example Package

A minimal React TypeScript package template for creating reusable React components that can be used both locally and published to NPM.

Features:

• Written in TypeScript
• Builds to both modern ES modules and CommonJS formats
• Provides TypeScript type definitions
• ESLint for code linting
• Prettier for code formatting
• Vitest for testing
• Tsup for building
• React component optimization with tree-shaking
• Tailwind CSS integration

Installation

npm install @madooei/react-example-package

Peer Dependencies: This package requires React, React DOM, and Tailwind CSS as peer dependencies:

npm install react react-dom tailwindcss

Usage

You can import components in two ways for optimal bundle optimization:

Named Imports (Barrel Export)

import React from "react";
import { Button, Card } from "@madooei/react-example-package";

function App() {
  return (
    <div>
      <Card title="Welcome">
        <p>This is a card component from the example package.</p>
        <Button onClick={() => alert("Hello!")}>Click me!</Button>
      </Card>
    </div>
  );
}

Individual Imports (Optimal Tree-Shaking)

For the smallest possible bundle size, import components individually:

import React from "react";
import { Button } from "@madooei/react-example-package/button";
import { Card } from "@madooei/react-example-package/card";

function App() {
  return (
    <div>
      <Card title="Welcome">
        <p>This is a card component from the example package.</p>
        <Button onClick={() => alert("Hello!")}>Click me!</Button>
      </Card>
    </div>
  );
}

Components

Button

A customizable button component with variants, sizes, and states.

Props:

• children (ReactNode) - Button content
• variant? ("primary" | "secondary" | "danger") - Button style variant (default: "primary")
• size? ("small" | "medium" | "large") - Button size (default: "medium")
• disabled? (boolean) - Whether button is disabled (default: false)
• onClick? (function) - Click handler

Card

A container component with optional title and custom styling.

Props:

• children (ReactNode) - Card content
• title? (string) - Optional title displayed at top of card
• className? (string) - Additional CSS classes to apply

Styling

This package requires Tailwind CSS for styling. Components use Tailwind utility classes and will not display correctly without Tailwind CSS properly configured in your project.

Configure your tailwind.config.js to include the component library:

/** @type {import('tailwindcss').Config} */
export default {
  content: [
    "./index.html",
    "./src/**/*.{js,ts,jsx,tsx}",
    // Add this line to scan the component library:
    "./node_modules/@madooei/react-example-package/dist/**/*.{js,cjs}",
  ],
  theme: {
    extend: {},
  },
  plugins: [],
};

Cloning the Repository

To make your workflow more organized, it's a good idea to clone this repository into a directory named react-package-workspace. This helps differentiate the workspace from the react-example-package located in the packages directory.

git clone https://github.com/madooei/react-example-package react-package-workspace

cd react-package-workspace

Repository Structure

• packages — Contains the primary package(s) for this repository (e.g., react-example-package). Each package is self-contained and can be copied out and used independently.
• examples — Contains examples of how to use the packages. Each example is a minimal, standalone project.
• playgrounds — Contains demos of the dependencies of the primary package(s). Each playground is a minimal, standalone project.
• docs — Contains various documentation for users and developers.
• .github — Contains GitHub-specific files, such as workflows and issue templates.

How to Use This Repo

• To work on a package, go to packages/<package-name> and follow its README.
• To try an example, go to examples/<example-name> and follow its README.
• To run the playground, go to playground/<package-name> and follow its README.
• For documentation, see the docs folder.

Using a VSCode Multi-root Workspace

With Visual Studio Code, you can enhance your development experience by using a multi-root workspace to access packages, examples, and playgrounds simultaneously. This approach is more efficient than opening the root directory, or each package or example separately.

To set up a multi-root workspace:

1. Open Visual Studio Code.
2. Navigate to File > Open Workspace from File....
3. Select the react-example-package.code-workspace file located at the root of the repository. This action will open all specified folders in one workspace.

The react-example-package.code-workspace file can be customized to include different folders or settings. Here's a typical configuration:

{
  "folders": [
    {
      "path": "packages/react-example-package"
    },
    {
      "path": "examples/with-tailwind3"
    },
    {
      "path": "playgrounds/vite"
    }
  ],
  "settings": {
    // Add any workspace-specific settings here, for example:
    "git.openRepositoryInParentFolders": "always"
  }
}

Developing the Package

Change to the package directory and install dependencies:

cd packages/react-example-package
npm install

• Read the Project Roadmap for project goals, status, evolution, and development guidelines.
• Read the Development Guide for detailed information on the package architecture, build configuration, and implementation patterns.
• Follow the Contributing Guide for contribution guidelines, coding standards, and best practices.

Package Management

When you are ready to publish your package:

npm run release

This single command will:

• Validate your code with the full validation pipeline
• Analyze commits to determine version bump
• Update package.json version and changelog
• Build the package
• Create and push git tag
• Create GitHub release
• Publish to NPM

[!TIP] For detailed information about package publishing, versioning, and local development workflows, see the NPM Package Management Guide.