npm package: @kkga/shim
Description: Command-line tool for installing UI components from Shim
Latest version: 1.0.9

# Shim CLI

Command-line tool for installing UI components from
[Shim](https://shim.kkga.me).

[Documentation](https://shim.kkga.me) • [GitHub](https://github.com/kkga/shim) •
[npm](https://www.npmjs.com/package/@kkga/shim)

## Usage

```bash
pnpm dlx @kkga/shim add <component>
```

## Commands

### `add`

Install components to your project:

```bash
# Install a component
pnpm dlx @kkga/shim add button

# Install to custom path
pnpm dlx @kkga/shim add button --path src/ui

# Install multiple components
pnpm dlx @kkga/shim add button dialog form

# Overwrite existing files
pnpm dlx @kkga/shim add button --overwrite
```

Path is relative to your project root (where `package.json` is located).

### `init`

Initialize your project. Automatically installs required dependencies, then
creates configuration and utility files.

```bash
# Create config with default paths
pnpm dlx @kkga/shim init

# Create config with custom paths
pnpm dlx @kkga/shim init --components-path src/ui --utils-path src/lib --css-path src/styles

# Force overwrite existing config
pnpm dlx @kkga/shim init --force
```

Prerequisite:

- Tailwind CSS must be installed and configured in your project. If Tailwind is
  missing, `init` exits with a helpful message. Follow the official guide:
  https://tailwindcss.com/docs/installation

What `init` does:

- Installs dependencies: `react-aria-components`, `tailwind-variants`,
  `tailwind-merge`, `@radix-ui/colors`, `@phosphor-icons/react`
- Creates a `shim.config.json` configuration file
- Downloads required utility files (`style.ts`, `theme.tsx`) to your utils
  directory
- Downloads CSS theme file (`theme.css`) to your styles directory
- Ensures your project is ready for component installation

## Configuration

Create `shim.config.json` in your project root:

```json
{
  "componentsPath": "src/components",
  "utilsPath": "src/lib",
  "cssPath": "src/styles"
}
```

### Available Options

- `componentsPath`: Directory for component files (default: `"components"`)
- `utilsPath`: Directory for utility files (default: `"utils"`)
- `cssPath`: Directory for CSS files (default: `"styles"`)

## Features

### Import Transformation

Imports are automatically transformed based on your configured paths:

```typescript
// Original: import { Button } from "@/shim-ui/button";
// Becomes: import { Button } from "@/src/ui/button";
```

### Dependency Resolution

Components with dependencies are installed automatically.

### Utility Files

Essential utility files are managed automatically:

- `style.ts` - Styling utilities and design tokens
- `theme.tsx` - Theme configuration and React context
- `theme.css` - Complete CSS theme with design tokens, animations, and utilities

## Path Resolution

### Component Installation

1. `--path` flag (highest priority)
2. `componentsPath` in config file
3. `components/` directory (default)

### Utility Files

1. `--utils-path` flag during `init` (highest priority)
2. `utilsPath` in config file
3. `utils/` directory (default)

### CSS Files

1. `--css-path` flag during `init` (highest priority)
2. `cssPath` in config file
3. `styles/` directory (default)

All paths are relative to your project root (where `package.json` is located).

## Examples

```bash
# Initialize project
pnpm dlx @kkga/shim init

# Install components
pnpm dlx @kkga/shim add button dialog

# Custom paths
pnpm dlx @kkga/shim init --components-path src/ui --utils-path src/lib --css-path src/styles
```