@hyperobjekt/cli

CLI tools and generators for Hyperobjekt projects, including component swizzling and other development utilities.

Installation

# In a Hyperobjekt project
pnpm add @hyperobjekt/cli

# Or install globally
pnpm add -g @hyperobjekt/cli

Usage

Component Swizzling

Swizzle components from @hyperobjekt/ui to customize them for your project:

Interactive Package and Component Selection

pnpm swizzle
# or
hyperobjekt swizzle

This will prompt you to:

1. Select which package to swizzle from (currently only @hyperobjekt/ui)
2. Choose a component from the available list
3. Specify where to place the swizzled component
4. Choose whether to copy associated CSS files

Direct Component Selection

pnpm swizzle ui
# or
hyperobjekt swizzle ui

This skips the package selection and goes directly to component selection.

Direct Component Swizzling

pnpm swizzle ui/Hero
pnpm swizzle ui/button
pnpm swizzle ui/CONTAINER
# or
hyperobjekt swizzle ui/Hero

This directly swizzles the specified component. Component names are case-insensitive.

List Available Components

pnpm list-components
# or
hyperobjekt list-components

Shows all available components that can be swizzled from @hyperobjekt/ui.

What is Swizzling?

Swizzling is the process of copying a component from a library into your project so you can modify it without affecting the original library component. This is useful when you need to:

• Customize the appearance or behavior of a component
• Add project-specific functionality
• Override default styles or props
• Create variations of existing components

Project Setup

To use the CLI in your project, add it as a dependency and create npm scripts:

{
  "dependencies": {
    "@hyperobjekt/cli": "workspace:*"
  },
  "scripts": {
    "swizzle": "hyperobjekt swizzle",
    "list-components": "hyperobjekt list-components"
  }
}

Available Components

The following components are available for swizzling from @hyperobjekt/ui:

• AnchorLink
• Breadcrumbs
• Button
• ButtonLink
• Container
• Footer
• Header
• Heading
• Hero
• HorizontalRule
• Paragraph
• Text
• Typography

File Structure

Swizzled components are placed in your src/ directory. By default, they go into src/components/ComponentName/, but you can specify a custom path during the swizzling process.

Example structure after swizzling the Hero component:

src/
  components/
    Hero/
      index.jsx
      styles.module.css
      README.md

Using Swizzled Components

After swizzling, update your imports to use the local component instead of the library version:

// Before swizzling
import { Hero } from '@hyperobjekt/ui';

// After swizzling
import { Hero } from './components/Hero';

Development

This package uses plop.js internally to handle code generation and file copying. The CLI automatically detects the location of @hyperobjekt/ui components whether you're in a monorepo or using it as an installed dependency.

Future Enhancements

This CLI package is designed to be extensible. Future versions may include:

• Component generation templates
• Project scaffolding tools
• Code migration utilities
• Custom generator plugins

Contributing

When adding new generators or features:

1. Add the generator to src/plopfile.js
2. Update the CLI documentation
3. Test with both monorepo and standalone project setups
4. Ensure proper error handling and user feedback