Codestin Search App

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.

Checks if Tailwind CSS is installed (required prerequisite)
Installs dependencies (react-aria-components, tailwind-variants, tailwind-merge, @radix-ui/colors, @phosphor-icons/react)
Creates a shim.config.json configuration file
Downloads utility files (style.ts, theme.tsx) to your utils directory
Downloads CSS theme file (theme.css) to your styles directory

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.

Dependency resolution: any required peer components are installed automatically
Import transforms: imports inside installed components are rewritten to match the configured paths

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.

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 init creates a configuration file in your project root:

shim.config.json

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

Paths are relative to your project root (where package.json is).

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. 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, see the registry API endpoint, or check the registry source.

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