Shim

Overview

Use the Shim CLI to initialize configuration and install components with their dependencies directly into your project.

Usage

Run commands on demand via pnpm dlx (no local install required):

Initialize Shim and add components

pnpm dlx @kkga/shim init
pnpm dlx @kkga/shim add button dialog form

Tip: Add a script to your package.json for shorter commands:

package.json

{
  "scripts": {
    "shim": "pnpm dlx @kkga/shim"
  }
}

Then run

pnpm shim init
pnpm shim add button dialog form

Commands

shim init

Initialize Shim in your project. Automatically installs required dependencies, creates the configuration file, and installs utility and CSS files.

Checks if Tailwind CSS is installed (required prerequisite)
Installs all required 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

Terminal

shim init [options]

Option	Description
`--components-path <path>`	Destination for components (default: `components`).
`--utils-path <path>`	Destination for utility files (default: `utils`).
`--css-path <path>`	Destination for CSS files (default: `styles`).
`-f, --force`	Overwrite existing config and installed files.

shim add

Install one or more components by name. Automatically installs component dependencies.

Terminal

shim add <components...> [options]

Option	Description
`<components...>`	One or more component names (e.g. `button dialog form`).
`-p, --path <path>`	Destination for installed components (overrides config `componentsPath`).
`-f, --overwrite`	Overwrite files that already exist.

Features

Import transformation: component import paths are rewritten based on your configured destinations.
Dependency resolution: component dependencies are installed automatically.
Utility management: style.ts, theme.tsx, and theme.css are created and kept in your chosen directories.

Examples

Initialize with defaults

pnpm dlx @kkga/shim init

Initialize with custom paths

pnpm dlx @kkga/shim init \
  --components-path src/ui \
  --utils-path src/lib \
  --css-path src/styles

Install components

pnpm dlx @kkga/shim add button dialog form

Install to a different directory

pnpm dlx @kkga/shim add button --path src/features/ui

Overwrite existing files

pnpm dlx @kkga/shim add dialog --overwrite

Use a package script

# package.json: { "scripts": { "shim": "pnpm dlx @kkga/shim" } }
pnpm shim add button

Configuration File

Running shim init creates a configuration file in your project root:

shim.config.json

{
  "componentsPath": "components",
  "utilsPath": "utils",
  "cssPath": "styles"
}

Option	Description
`componentsPath`	Default destination for installed components.
`utilsPath`	Destination for downloaded utility files.
`cssPath`	Destination for downloaded CSS files.

Troubleshooting

Tailwind CSS is not installed

shim init requires Tailwind CSS to be installed. If you see this error, install and configure Tailwind first:

pnpm add -D tailwindcss postcss autoprefixer
pnpm tailwindcss init -p

See the Tailwind installation guide for framework-specific setup.

Component not found

If you get a "component not found" error, check your spelling. To see available components, visit the components section or check the registry.

Files already exist

Use --overwrite (for add) or --force (for init) to replace existing files:

pnpm dlx @kkga/shim add button --overwrite
pnpm dlx @kkga/shim init --force

Invalid path error

Paths should be relative to your project root (where package.json is):

# ✓ Good
pnpm dlx @kkga/shim init --components-path src/components

# ✗ Bad (absolute filesystem path)
pnpm dlx @kkga/shim init --components-path /Users/name/project/src/components