Installation

You can use any package manager:

• bun: bunx @happlyui/cli@latest add button

• npm: npx @happlyui/cli@latest add button

• pnpm: pnpx @happlyui/cli@latest add button

Manual Installation

If you prefer to set things up manually:

1. Install dependencies

bun add clsx tailwind-merge class-variance-authority tailwindcss-animate

2. Configure Tailwind CSS

We provide ready-to-use configuration files for both Tailwind v3 and v4 in the tailwind-manual-installation directory of the repository.

Tailwind v3

1. Copy tailwind-manual-installation/v3/happly-tailwind.preset.js to your project root.
2. Add it to your tailwind.config.js:

   module.exports = {
     presets: [require('./happly-tailwind.preset.js')],
     // ... rest of your config
   };
   

3. Copy the CSS variables from tailwind-manual-installation/v3/globals.css into your global CSS file.

Tailwind v4

1. Copy tailwind-manual-installation/v4/happly-theme.css to your project (e.g., src/happly-theme.css).
2. Import it in your main CSS file:

   @import './happly-theme.css';
   

Conflict Resolution & Overrides

When using happly-tailwind.preset.js (Tailwind v3), Happly's configuration is provided as a preset. This means:

• Your configuration overrides the preset: Any keys defined in your tailwind.config.js will take precedence over Happly's defaults.

• Use theme.extend: To add custom colors or fonts without removing Happly's tokens, always use theme.extend.

  // ✅ Good: Extends Happly defaults
  module.exports = {
    theme: {
      extend: {
        colors: { brand: '#ff0000' },
      },
    },
  };
  
  // ❌ Bad: Overrides Happly defaults (removes semantic tokens)
  module.exports = {
    theme: {
      colors: { brand: '#ff0000' },
    },
  };
  

Tailwind v4 Conflict Resolution

For Tailwind v4:

• Import Order Matters: Ensure @import "./happly-theme.css"; comes before your own @theme block or variable definitions.

• Overriding Variables: You can override any Happly variable by redefining it in your :root or @theme block after the import.

  @import './happly-theme.css';
  
  @theme {
    /* Overrides Happly's --color-primary */
    --color-primary: red;
  }
  

3. Add the utility function

Create src/lib/happly-ui/happly-ui-utils.ts:

import { type ClassValue, clsx } from 'clsx';
import { twMerge } from 'tailwind-merge';

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

4. Configure path aliases

In your tsconfig.json, add path aliases:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

5. Copy components

Browse the components section and copy the source code directly into your project.

Configuration

HapplyUI stores its configuration in happly-ui-components.json:

{
  "$schema": "https://cdn.jsdelivr.net/gh/Mindful-Connect/happly-ui-npm@production/schemas/happly-ui-components.json",
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.ts",
    "css": "src/styles/globals.css",
    "baseColor": "slate",
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/happly-ui/happly-ui-utils",
    "ui": "@/components/happly-ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  }
}

Configuration options

Next Steps

Now that HapplyUI is set up, explore the components:

• Button — Start with the most common component