Cloak UI Setup & Integration

Learn how to install your preferred design system and structure Cloak UI wrappers for seamless integration in Next.js + React projects.
Easily swap between Hero UI and shadcn/ui by changing a single import.

1. Install Your UI Library

# For shadcn/ui
pnpm add @shadcn/ui

# For Hero UI
pnpm add @heroui/core

2. Create Your Wrappers

Create a /wrappers folder at your project root.

Button Wrapper for shadcn/ui:

// wrappers/Button.tsx
import { Button as ShadcnButton } from "@shadcn/ui";

export function Button(props) {
  return <ShadcnButton {...props} />;
}

Button Wrapper for Hero UI:

// wrappers/Button.tsx
import { Button as HeroUIButton } from "@heroui/core";

export function Button(props) {
  return <HeroUIButton {...props} />;
}

📝 Copy the wrapper code for the library you want to use.
Each wrapper maps your component props to the underlying library’s API.

How it works:

• You choose which wrapper to use by copying the relevant code.
• Your app always imports from @wrappers/Button, keeping your UI code consistent.
• To migrate, just replace the wrapper file with the version for your new library—no changes needed in your app code.

3. Use Absolute Imports

Configure your tsconfig.json:

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

4. Use in Your App

import { Button } from "@wrappers/Button";

export default function Home() {
  return <Button variant="primary">Click Me</Button>;
}

5. Migrating Between Libraries

To switch from shadcn/ui to Hero UI,
just change the import in your wrapper:

// wrappers/Button.tsx

// import { Button as ShadcnButton } from "@shadcn/ui";
// export const Button = ShadcnButton;

import { Button as HeroUIButton } from "@heroui/core";
export const Button = HeroUIButton;

No changes needed in your app code!

6. Why This Pattern Works

• Framework Agnostic: Wrappers hide library-specific APIs.
• Easy Swapping: Change design systems by editing one file.
• Consistent Props: Your app always uses Cloak UI’s API.

Tip:
Apply this pattern for all components (Modal, Card, Switch, etc.) for seamless migration and unified UI logic.