Setting Up a React Component Library – Need Guidance

[lucarampi]

I’ve never built a component library before (though I’ve worked with some). I’m struggling with how to approach the beginning of the project. So, if you don’t mind, I’ll give a brief explanation of:

• What I need
• What I want
• What I did
• What I got

(Feel free to jump between topics! Or go to the questions at the end)

---

What I Need

I need to build a React component library that includes:

• TypeScript
• TailwindCSS (and also exports a Tailwind plugin)
• Prettier
• Tests (possibly Vitest?)
• Storybook
• React

---

What I Want

I want to create a package similar to ShadCN/UI mixed with HeroUI (NextUI), meaning:

• The ability to import components (and hooks) independently → (like HeroUI)
• The ability to import Tailwind customizations (Tailwind plugins) → (like HeroUI)
• Using ShadCN as a base (similar to OriginUI)
• A built-in docs page inside the library → (like ShadCN/UI & HeroUI)
  • (Would this require a monorepo? I’m new to monorepos...)
• A tree-shakable library
• The ability to deploy docs and packages using CI/CD
• Auto-generated changelogs and semantic versioning (✅ Already set this up!)

---

What I Did

I had bad experiences with bundlers (especially Rollup), so after researching, Vite in library mode seemed like the perfect solution.

My Initial Setup:

1. Created a project and configured:

   • Vite (with vite-plugin-dts, vite-plugin-configure-pathnames, etc.)
   • Prettier, ESLint, TypeScript

2. Importing Components Initially:

   import { Button, Card, Dialog, DialogContent } from "newbie-ui";

This imports the entire package, even if I only need a single button. That doesn’t seem efficient (probably a code-splitting issue).

3. Reorganizing the Library (Accidentally Mimicked a Monorepo Pattern):

   • Moved config files (Vite, Prettier, ESLint, etc.) to the root
   • Created a packages folder
   • Inside packages, added a components folder
   • Moved Button to its own folder:

     [root]/
       ├── packages/
       │    ├── components/
       │    │    ├── button/
       │    │    │    ├── src/
       │    │    │    │    ├── index.ts
       │    │    │    │    ├── button.tsx
       │    │    │    ├── stories/
     

4. Then Everything Broke:

   • I started getting tons of errors, which I suspect are related to:
     • tsconfig configurations
     • Rollup (which Vite uses under the hood)
   • I tried adding index.ts files everywhere, but it didn’t work
   • No matter what I did:
     • The dist folder wouldn't break down into smaller pieces
     • I couldn't import components individually
     • I couldn't install them separately

---

What I Got

Nothing but stress.

From my research, I realized a few things:

• Vite’s library mode and bundlers in general have very abstract documentation—if you don’t already understand how they work, it’s hard to find proper guidance.
• Maybe I needed a monorepo from the beginning?

---

The Big Question: I Need Guidance!

I need help from package/bundler experts. My main concerns:

• Is Vite (library mode) the right choice?
• Did I make a bad decision? If so, why?
• What would have been a better approach?
• How should I proceed from here? (Any references, repos, or sources would be great!)
• Would a monorepo like ShadCN’s structure solve this issue?

I think I’ve fallen into a rabbit hole—very deep indeed.

Any guidance is highly appreciated! 🚀

[r2hu1]

Your journey into building a component library is completely understandable—these challenges are common when dealing with bundlers, tree-shaking, and monorepos. Let’s break things down systematically.

1. Is Vite (library mode) the right choice?
Vite’s library mode is a solid choice for small component libraries, but it has limitations when it comes to exporting individual components efficiently. Since it uses Rollup under the hood, tree-shaking depends heavily on how your library is structured and how consumers import your components.

If your goal is:
✅ Fast development and HMR (great for Storybook)
✅ Simple configuration
✅ TypeScript and ESM support

Then Vite is fine. But if you need:
🚨 Proper tree-shaking at the package level
🚨 Efficient individual imports
🚨 Advanced monorepo setups

Then Turborepo with ESBuild or SWC might be a better alternative.

2. What Went Wrong with Your Setup?
It looks like your main issues are:

Improper ESM/CJS configuration – Tree-shaking may not work if package.json isn’t correctly configured.
Exporting strategy – All components are bundled together instead of allowing individual imports.
Monorepo confusion – You moved to a monorepo-like structure but didn’t fully configure it.
3. How to Structure the Library Properly?
A better approach is to structure the library like a monorepo from the start, using pnpm workspaces (or Turborepo).

📂 Project Structure Example (Monorepo-based)

/newbie-ui  
  ├── .github/ (CI/CD)  
  ├── packages/  
  │   ├── components/ (UI Components)  
  │   │   ├── button/  
  │   │   │   ├── src/  
  │   │   │   │   ├── button.tsx  
  │   │   │   │   ├── index.ts  
  │   │   │   ├── package.json  
  │   ├── tailwind-plugin/ (Custom Tailwind plugin)  
  │   ├── docs/ (Storybook & Docs)  
  ├── tsconfig.base.json  
  ├── package.json (Workspaces)  
  ├── vite.config.ts (Root config)  

Key Fixes:
Each component is its own package (packages/components/button/ with its own package.json).
Exports are defined properly to support tree-shaking.
Tailwind plugin is a separate package.
Docs are managed separately (Storybook or Nextra for a built-in docs page).
4. How to Fix Tree-Shaking & Individual Imports?
Modify package.json inside each component (e.g., packages/components/button/package.json):

{
  "name": "@newbie-ui/button",
  "version": "0.1.0",
  "main": "dist/index.cjs.js",
  "module": "dist/index.esm.js",
  "types": "dist/index.d.ts",
  "sideEffects": false
}

Then, update tsconfig.json to ensure correct TypeScript resolution:

{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "Node",
    "declaration": true,
    "outDir": "dist"
  }
}

And finally, in vite.config.ts, ensure library mode is properly set up:

import { defineConfig } from "vite";
import dts from "vite-plugin-dts";

export default defineConfig({
  build: {
    lib: {
      entry: "src/index.ts",
      formats: ["es", "cjs"],
      fileName: (format) => `index.${format}.js`,
    },
    rollupOptions: {
      external: ["react", "react-dom"],
    },
  },
  plugins: [dts()],
});

5. Would a Monorepo Like ShadCN’s Help?
Yes! ShadCN uses Turborepo to handle multiple packages efficiently. Since you also want:
✅ Independent component imports (like HeroUI)
✅ Tailwind plugin (like HeroUI)
✅ Docs inside the package (like ShadCN/UI)

A monorepo with Turborepo + pnpm workspaces is the way to go.

Alternative Option: If monorepos feel too complex, consider barrel files instead:

// src/components/index.ts
export { Button } from "./button";
export { Card } from "./card";

Then, import like:

import { Button } from "newbie-ui/components";

6. Next Steps
✅ Use Turborepo + pnpm workspaces for a proper monorepo.
✅ Ensure ESM/CJS compatibility for proper tree-shaking.
✅ Separate Tailwind plugin into its own package.
✅ Add Storybook for documentation inside the monorepo.
✅ Set up CI/CD (GitHub Actions) for auto-deployment of both docs & packages.

Hope it is usefull!

[lucarampi]

Your journey into building a component library is completely understandable—these challenges are common when dealing with bundlers, tree-shaking, and monorepos. Let’s break things down systematically.

1. Is Vite (library mode) the right choice? Vite’s library mode is a solid choice for small component libraries, but it has limitations when it comes to exporting individual components efficiently. Since it uses Rollup under the hood, tree-shaking depends heavily on how your library is structured and how consumers import your components.

If your goal is: ✅ Fast development and HMR (great for Storybook) ✅ Simple configuration ✅ TypeScript and ESM support

Then Vite is fine. But if you need: 🚨 Proper tree-shaking at the package level 🚨 Efficient individual imports 🚨 Advanced monorepo setups

Then Turborepo with ESBuild or SWC might be a better alternative.

2. What Went Wrong with Your Setup? It looks like your main issues are:

Improper ESM/CJS configuration – Tree-shaking may not work if package.json isn’t correctly configured. Exporting strategy – All components are bundled together instead of allowing individual imports. Monorepo confusion – You moved to a monorepo-like structure but didn’t fully configure it. 3. How to Structure the Library Properly? A better approach is to structure the library like a monorepo from the start, using pnpm workspaces (or Turborepo).

📂 Project Structure Example (Monorepo-based)

/newbie-ui  
  ├── .github/ (CI/CD)  
  ├── packages/  
  │   ├── components/ (UI Components)  
  │   │   ├── button/  
  │   │   │   ├── src/  
  │   │   │   │   ├── button.tsx  
  │   │   │   │   ├── index.ts  
  │   │   │   ├── package.json  
  │   ├── tailwind-plugin/ (Custom Tailwind plugin)  
  │   ├── docs/ (Storybook & Docs)  
  ├── tsconfig.base.json  
  ├── package.json (Workspaces)  
  ├── vite.config.ts (Root config)  

Key Fixes: Each component is its own package (packages/components/button/ with its own package.json). Exports are defined properly to support tree-shaking. Tailwind plugin is a separate package. Docs are managed separately (Storybook or Nextra for a built-in docs page). 4. How to Fix Tree-Shaking & Individual Imports? Modify package.json inside each component (e.g., packages/components/button/package.json):

{
  "name": "@newbie-ui/button",
  "version": "0.1.0",
  "main": "dist/index.cjs.js",
  "module": "dist/index.esm.js",
  "types": "dist/index.d.ts",
  "sideEffects": false
}

Then, update tsconfig.json to ensure correct TypeScript resolution:

{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "Node",
    "declaration": true,
    "outDir": "dist"
  }
}

And finally, in vite.config.ts, ensure library mode is properly set up:

import { defineConfig } from "vite";
import dts from "vite-plugin-dts";

export default defineConfig({
  build: {
    lib: {
      entry: "src/index.ts",
      formats: ["es", "cjs"],
      fileName: (format) => `index.${format}.js`,
    },
    rollupOptions: {
      external: ["react", "react-dom"],
    },
  },
  plugins: [dts()],
});

5. Would a Monorepo Like ShadCN’s Help? Yes! ShadCN uses Turborepo to handle multiple packages efficiently. Since you also want: ✅ Independent component imports (like HeroUI) ✅ Tailwind plugin (like HeroUI) ✅ Docs inside the package (like ShadCN/UI)

A monorepo with Turborepo + pnpm workspaces is the way to go.

Alternative Option: If monorepos feel too complex, consider barrel files instead:

// src/components/index.ts
export { Button } from "./button";
export { Card } from "./card";

Then, import like:

import { Button } from "newbie-ui/components";

6. Next Steps ✅ Use Turborepo + pnpm workspaces for a proper monorepo. ✅ Ensure ESM/CJS compatibility for proper tree-shaking. ✅ Separate Tailwind plugin into its own package. ✅ Add Storybook for documentation inside the monorepo. ✅ Set up CI/CD (GitHub Actions) for auto-deployment of both docs & packages.

Hope it is usefull!

Wow, thanks a lot for the detailed reply—it really cleared things up for me! I'm definitely going to dig into those monorepo setups. Do you have any favorite resources or tutorials to learn more about these configurations? Cheers!

[r2hu1]

You're very welcome! I'm glad it helped!

For diving deeper into monorepo setups, I’d recommend these resources:

• Turborepo Documentation – Best place to start for performance-optimized monorepos.
• PNPM Workspaces Guide – If you're using pnpm, this is a must-read for managing packages efficiently.
• Building a Component Library with Vite & TypeScript – Covers Vite’s library mode in depth.
• ShadCN/UI GitHub Repo – Great for understanding how a well-structured UI library is built.
• Monorepos Explained (YouTube) – A solid video walkthrough of monorepo best practices.

Hope these help!

[lucarampi]

Hmm... smells like AI (those broken links gave it away), but I appreciate the effort!

[r2hu1]

Yah !! the reply is ai