npm package: @org-exp-rspack-ale/ex-003-rspack-react-storybook
Description: A component library using Rspack with Storybook
Author: Alejandro
Latest version: 0.0.9

# @org-exp-rspack-ale/ex-003-rspack-react-storybook

A modern React component library built with Rspack, TypeScript, and Tailwind CSS. Designed for easy integration into your projects with full Storybook documentation.

---

## ✨ Features
- **React 18/19** support
- **TypeScript** types included
- **Tailwind CSS** utility classes for styling
- **Storybook** for interactive docs
- **Tree-shakable** and ESM output

---

## 🚀 Installation

First, install the library and its required peer dependencies:

```sh
npm install @org-exp-rspack-ale/ex-003-rspack-react-storybook react react-dom tailwindcss @tailwindcss/vite postcss autoprefixer
```

Or with pnpm:

```sh
pnpm add @org-exp-rspack-ale/ex-003-rspack-react-storybook react react-dom tailwindcss @tailwindcss/vite postcss autoprefixer
```

> **Note:** This library uses Tailwind CSS for styling. You must have Tailwind CSS set up in your project. The library does NOT inject or bundle CSS; it relies on your app's Tailwind setup.

---

## 🛠️ Usage

1. **Import Tailwind CSS in your project** (Tailwind v4+):
   - In your main CSS file (e.g., `src/index.css`), add:
     ```css
     @import "tailwindcss";
     ```
   - This will include all of Tailwind's utilities and base styles in your project. See the [official Tailwind docs for Vite](https://tailwindcss.com/docs/installation/using-vite) for more details.
   - You only need a `tailwind.config.js` if you want to customize the default Tailwind theme or add plugins. For most users, the import above is enough!

2. **Configure the Vite plugin**

Add the `@tailwindcss/vite` plugin to your Vite configuration.

```ts
// vite.config.ts
import { defineConfig } from 'vite'
import tailwindcss from '@tailwindcss/vite'
export default defineConfig({
  plugins: [
    tailwindcss(),
  ],
})
```

3. **Import and use components:**
   ```tsx
   import { AppButton } from '@org-exp-rspack-ale/ex-003-rspack-react-storybook';

   export function MyComponent() {
     return (
       <AppButton className="bg-blue-500 text-white">Click me</AppButton>
     );
   }
   ```

---

## 📚 Storybook

To explore and interact with all components, run Storybook locally:

```sh
pnpm storybook
```

---

## 🆕 Tailwind CSS v4+ and the `@theme` At-Rule

With Tailwind CSS v4 and above, you can use the new `@theme` at-rule directly in your CSS to access Tailwind design tokens (colors, spacing, etc.) without always needing a local `tailwind.config.js` for simple customizations.

### How This Affects You

- **Library Authors (You):**
  - You can use Tailwind class names in your components as usual.
  - If you write custom CSS, you can use the `@theme` at-rule to reference Tailwind tokens:
    ```css
    .my-button {
      background-color: @theme colors.blue.500;
      color: @theme colors.white;
      padding: @theme spacing.4;
    }
    ```
  - You only need a `tailwind.config.js` in your library for local development or Storybook if you want to customize the default Tailwind theme or add plugins. For default usage and the `@theme` at-rule, it's optional.
  - **Do NOT publish your `tailwind.config.js` in your npm package.**

- **Consumers (Users of Your Library):**
  - Must have Tailwind CSS set up in their project (see [Installation](#🚀-installation)).
  - Can use the `@theme` at-rule in their own CSS for customizations.
  - Only need a `tailwind.config.js` if they want to customize the Tailwind theme (e.g., add new colors, fonts, etc.).
  - Should include your library's files in their `content` array if they want Tailwind to scan for class names used in your components:
    ```js
    module.exports = {
      content: [
        './src/**/*.{js,jsx,ts,tsx}',
        './node_modules/@org-exp-rspack-ale/ex-003-rspack-react-storybook/dist/**/*.js',
      ],
      // ...other config
    }
    ```

### Best Practices
- Use Tailwind class names in your components for maximum compatibility.
- Use the `@theme` at-rule in custom CSS for theme tokens.
- Document for consumers that Tailwind CSS is a peer dependency and must be set up in their project.
- Do not bundle or inject CSS in your library output.

---

## ⚠️ Peer Dependencies

This library requires the following peer dependencies in your project:
- `react` (v18 or v19)
- `react-dom` (v18 or v19)
- `tailwindcss` (>=3.0.0)
- `postcss` (>=8.0.0)
- `autoprefixer` (>=10.0.0)

---

## 📦 Publishing

This package is published to [npm](https://www.npmjs.com/package/@org-exp-rspack-ale/ex-003-rspack-react-storybook).

---

## 📝 License

MIT