Complete guide to installing and integrating Cloak UI in your Next.js or React project. Learn best practices for structure and migration strategies.

Setup & Integration

This guide covers everything you need to integrate Cloak UI into your project, from basic installation to advanced configuration patterns.

New to Cloak UI? Check out the Quick Start Guide for a faster introduction.

Installation Methods

Choose the installation method that best fits your project structure:

Method 1: Direct Package Installation (Recommended)

Install Cloak UI packages directly from npm:

# For shadcn/ui
pnpm add @cloakui/shadcn-core

# For Hero UI  
pnpm add @cloakui/heroui-core

# Or install both if you want flexibility
pnpm add @cloakui/shadcn-core @cloakui/heroui-core

Method 2: Monorepo/Local Packages

If you're working in a monorepo or want to customize the wrappers:

# Clone the repository
git clone https://github.com/your-org/cloak-ui.git

# Install dependencies
pnpm install

# Link packages locally
pnpm link packages/heroui-core
pnpm link packages/shadcn-core

Project Setup

Step 1: Configure TypeScript

Add path aliases to your tsconfig.json for cleaner imports:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/components/*": ["components/*"],
      "@/lib/*": ["lib/*"],
      "@/styles/*": ["styles/*"]
    }
  }
}

Step 2: Configure Tailwind CSS

Both shadcn/ui and Hero UI use Tailwind CSS. Ensure your tailwind.config.js is properly configured:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    './pages/**/*.{js,ts,jsx,tsx,mdx}',
    './components/**/*.{js,ts,jsx,tsx,mdx}',
    './app/**/*.{js,ts,jsx,tsx,mdx}',
    // Add Cloak UI package paths
    './node_modules/@cloakui/**/*.{js,ts,jsx,tsx}',
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

Step 3: Add Global Styles

Create or update your global CSS file:

/* styles/globals.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* Add any custom styles here */

Import it in your root layout:

// app/layout.tsx or pages/_app.tsx
import '@/styles/globals.css'

Integration Patterns

Pattern 1: Direct Import (Simple Projects)

For smaller projects, import components directly from Cloak UI packages:

// components/my-button.tsx
import { Button } from '@cloakui/shadcn-core'

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

Pros:

✅ Simple and straightforward
✅ No additional configuration needed
✅ Good for small projects

Cons:

❌ Harder to switch design systems later
❌ Import statements need updating when migrating

Pattern 2: Centralized Wrapper (Recommended)

Create a centralized components file that re-exports Cloak UI components:

// lib/ui.ts
export {
  Button,
  Card,
  Input,
  Dialog,
  Badge,
  Avatar,
  // ... other components
} from '@cloakui/shadcn-core'

// Or switch to Hero UI by changing one line:
// } from '@cloakui/heroui-core'

Use in your app:

// components/my-component.tsx
import { Button, Card } from '@/lib/ui'

export function MyComponent() {
  return (
    <Card>
      <Button variant="primary">Submit</Button>
    </Card>
  )
}

Pros:

✅ Single point of change for migrations
✅ Clean imports throughout your app
✅ Easy to add custom defaults

Cons:

❌ Requires one extra file

Pattern 3: Component-Level Wrappers (Advanced)

Create individual wrapper files for each component with custom defaults:

// components/ui/button.tsx
import { Button as CloakButton } from '@cloakui/shadcn-core'
import { cn } from '@/lib/utils'

export function Button({ className, ...props }) {
  return (
    <CloakButton 
      className={cn('your-custom-defaults', className)}
      {...props}
    />
  )
}

Pros:

✅ Maximum customization per component
✅ Can add project-specific defaults
✅ Easy to override behavior

Cons:

❌ More boilerplate code
❌ Requires wrapper for each component

Migration Strategies

Strategy 1: All-at-Once Migration

Switch all components in one go by changing a single import source:

// lib/ui.ts

// Before
export * from '@cloakui/shadcn-core'

// After
export * from '@cloakui/heroui-core'

Best for: Small to medium projects, scheduled downtime available

Strategy 2: Gradual Migration

Migrate one component or feature at a time:

// lib/ui.ts
// Mix both design systems during migration
export { Button, Card } from '@cloakui/heroui-core'  // Migrated
export { Input, Dialog } from '@cloakui/shadcn-core' // Not yet migrated

Best for: Large projects, production apps, risk-averse teams

Strategy 3: Feature Flag Migration

Use feature flags to toggle between design systems:

// lib/ui.ts
const USE_HERO_UI = process.env.NEXT_PUBLIC_USE_HERO_UI === 'true'

export const Button = USE_HERO_UI
  ? require('@cloakui/heroui-core').Button
  : require('@cloakui/shadcn-core').Button

// ... repeat for other components

Best for: A/B testing, gradual rollout, client-specific customization

Framework-Specific Setup

Next.js App Router

// app/layout.tsx
import '@/styles/globals.css'
import { ThemeProvider } from '@/components/theme-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <ThemeProvider attribute="class" defaultTheme="system">
          {children}
        </ThemeProvider>
      </body>
    </html>
  )
}

Next.js Pages Router

// pages/_app.tsx
import '@/styles/globals.css'
import type { AppProps } from 'next/app'
import { ThemeProvider } from '@/components/theme-provider'

export default function App({ Component, pageProps }: AppProps) {
  return (
    <ThemeProvider attribute="class" defaultTheme="system">
      <Component {...pageProps} />
    </ThemeProvider>
  )
}

Vite + React

// src/main.tsx
import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App'
import './index.css'

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
)

Best Practices

1. Use TypeScript

Cloak UI is built with TypeScript and provides excellent type safety:

import { Button } from '@cloakui/shadcn-core'
import type { ButtonProps } from '@cloakui/shadcn-core'

// Get full autocomplete and type checking
export function CustomButton(props: ButtonProps) {
  return <Button {...props} />
}

2. Centralize UI Imports

Always import UI components from a central location:

// ✅ Good
import { Button } from '@/lib/ui'

// ❌ Avoid
import { Button } from '@cloakui/shadcn-core'

3. Test After Migration

After switching design systems, test thoroughly:

✅ Visual regression testing
✅ Accessibility testing
✅ Interaction testing
✅ Responsive design testing

4. Document Your Choice

Document which design system you're using and why:

// lib/ui.ts
/**
 * Central UI component exports
 * 
 * Currently using: shadcn/ui
 * Reason: Better customization for our use case
 * Migration date: 2024-01-15
 */
export * from '@cloakui/shadcn-core'

Troubleshooting

Issue: Components Not Styling Correctly

Solution: Ensure Tailwind CSS is configured to scan Cloak UI packages:

// tailwind.config.js
content: [
  './node_modules/@cloakui/**/*.{js,ts,jsx,tsx}',
]

Issue: TypeScript Import Errors

Solution: Clear TypeScript cache and restart your editor:

rm -rf node_modules/.cache
pnpm install

Issue: Conflicting Styles

Solution: Ensure you're not importing from multiple design systems in the same component.

What's Next?

You're all set! Your project is now configured to use Cloak UI.

Explore Components

Browse the component documentation to see what's available:

Learn More

Need help? Check our Resources & FAQ or reach out to the community.

Setup & Integration

On this page