Installation

This guide will walk you through installing and setting up Harukit UI in your project.

Prerequisites

Before installing Harukit UI, make sure you have:

• Node.js (version 16 or higher)
• npm, yarn, pnpm, or bun package manager

Quick Installation

Step 1: Initialize Harukit

bunx --bun harukit@latest init

npx harukit@latest init

pnpm dlx harukit@latest init

yarn dlx harukit@latest init

Note: Harukit will automatically detect your package manager (npm, yarn, pnpm, or bun) and install all required dependencies for you. You do not need to run a separate install command.

Step 3: Add your first component

bunx --bun harukit@latest add button

npx harukit@latest add button

pnpm dlx harukit@latest add button

yarn dlx harukit@latest add button

Step 4: Use the component

import { Button } from "@/components/button";

export default function Page() {
  return (
    <div className="p-8">
      <Button>Hello Harukit!</Button>
    </div>
  );
}

For Existing Projects

1. Navigate to your project

cd your-existing-project

2. Initialize Harukit

# Initialize Harukit in your existing project
bunx --bun harukit@latest init

# Initialize Harukit in your existing project
npx harukit@latest init

# Initialize Harukit in your existing project
pnpm dlx harukit@latest init

# Initialize Harukit in your existing project
yarn dlx harukit@latest init

Note: If your project already has some of the required dependencies, Harukit will skip installing them and only install the missing ones.

3. Add Components

# Add the components you need
bunx --bun harukit@latest add button card input

# Add the components you need
npx harukit@latest add button card input

# Add the components you need
pnpm dlx harukit@latest add button card input

# Add the components you need
yarn dlx harukit@latest add button card input

Package Manager Support

Harukit automatically detects your package manager and installs dependencies accordingly. The detection follows this priority:

1. CLI Package Manager: Detects the package manager used to run the CLI (npx → npm, yarn → yarn, etc.)
2. Project Lock Files: Falls back to the package manager indicated by lock files in your project
3. System Preference: Uses bun if available, otherwise defaults to npm

Project Structure After Installation

After running the initialization command, your project will have this structure:

your-project/
├── harukit.json          # Configuration file
├── components/           # Your UI components
│   ├── button.tsx
│   ├── card.tsx
│   └── ...
├── lib/
│   └── utils.ts         # Utility functions
├── app/
│   └── globals.css      # Global styles with CSS variables
├── package.json
└── tailwind.config.js

Configuration File

The harukit.json file contains your project configuration:

{
  "$schema": "https://harukit.com/schema.json",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "css": "app/globals.css",
    "baseColor": "default",
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "iconLibrary": "lucide",
  "packageManager": "pnpm"
}

Verification

To verify that Harukit is properly installed:

1. Check the configuration file:

   cat harukit.json

2. Check the components directory:

   ls components/

3. Check the lib directory:

   ls lib/

4. Test a component:

   import { Button } from "@/components/button";
   
   export default function TestPage() {
     return <Button>Test Button</Button>;
   }

Troubleshooting Installation

Common Issues

"Command not found: harukit"

• Make sure you're using the latest version: npx harukit@latest
• Check that Node.js is properly installed: node --version

"Package manager detection failed"

• Make sure you have a package.json file in your project root
• Ensure you're using a supported package manager (npm, yarn, pnpm, or bun)
• The CLI will automatically detect your package manager and install dependencies

"Dependencies not installed"

• Harukit automatically installs all required dependencies during initialization
• If installation fails, try running the init command again
• Check that your package manager is working correctly

"Permission denied"

• On Unix-like systems, you might need to use sudo for global installations
• Consider using npx instead of global installation

"Network error during installation"

• Check your internet connection
• Try using a different npm registry or package manager
• Clear your package manager cache:

bun cache clear

npm cache clean --force

pnpm store prune

yarn cache clean

Support

• GitHub: Github Repository
• Issues: Github Issues