@ng-shangjc/cli

A powerful CLI tool for managing and installing ng-shangjc UI components in your Angular projects.

Official Documentation

Installation

Install the CLI globally:

npm install -g @ng-shangjc/cli

Or use npx to run without installation:

npx @ng-shangjc/cli <command>

Prerequisites

• Angular project (angular.json must be present)
• Node.js 16 or higher
• One of the following package managers:
  • npm (default)
  • yarn
  • pnpm

Commands

init

Initialize shangjc configuration in your Angular project.

ng-shangjc init

This command will:

• Verify you're in an Angular project
• Detect your project's package manager (npm, yarn, or pnpm)
• Create a shangjc.config.json configuration file
• Prompt for component installation preferences
• Set up your project for component installations

Configuration options:

• Components Path: Where to install components (default: src/ui/shangjc)
• Component Type: Standalone (recommended) or Module-based
• Project Type: Angular application setup
• Package Manager: Auto-detected (npm, yarn, or pnpm)
• Theme Configuration: Default theme and variants
• Tailwind Config: Whether to configure Tailwind CSS

install

Install a specific component into your project.

ng-shangjc install <component>

Options:

• -p, --path <path>: Override the installation path from config

Examples:

# Install button component
ng-shangjc install button

# Install to custom path
ng-shangjc install button --path src/components/ui

# Install dialog component
ng-shangjc install dialog

Available Components:

• accordion - Accordion component
• alert - Alert/notification component
• badge - Badge component
• button - Button component
• card - Card container component
• checkbox - Checkbox component
• dialog - Modal dialog component
• dropdown-menu - Dropdown Menu component
• input - Input field component
• select - Select dropdown component
• switch - Toggle switch component
• tabs - Tabs component
• textarea - Textarea component

Installation Process:

1. Validates component availability
2. Checks for existing installation
3. Uses your detected package manager for all installations
4. Installs dependencies (like @ng-shangjc/utils)
5. Copies component files to your project
6. Generates index.ts file
7. Updates shangjc.config.json
8. Provides usage instructions

variants

Show variant configurations for components.

# Show all component variants
ng-shangjc variants

# Show variants for specific component
ng-shangjc variants button

This command displays:

• Available variants for each component
• Default variant settings
• CSS classes for each variant
• Variant descriptions

Configuration File

The CLI creates and manages a shangjc.config.json file in your project root:

{
  "version": "1.0.0",
  "componentsPath": "src/ui/shangjc",
  "componentType": "standalone",
  "projectType": "angular",
  "packageManager": "npm",
  "theme": {
    "current": "default",
    "variants": {
      "button": ["primary", "secondary", "outline"],
      "card": ["default", "elevated"]
    }
  },
  "tailwindConfig": true,
  "installedComponents": ["button", "input"],
  "utilsVersion": "1.0.0"
}
``

## Component Usage

After installing components, you can import and use them in your Angular application:

```typescript
// Import the component
import { ButtonComponent } from './ui/shangjc/button';

// Use in your component
@Component({
  selector: 'app-example',
  template: `
    <shangjc-button variant="primary" size="md">
      Click me
    </shangjc-button>
  `,
  standalone: true,
  imports: [ButtonComponent]
})
export class ExampleComponent {}

Features

• Interactive Setup: Guided initialization with prompts
• Package Manager Detection: Automatically detects and uses npm, yarn, or pnpm
• Dependency Management: Automatic installation of required dependencies
• Configuration Management: Centralized config file for project settings
• Component Variants: Support for multiple component themes and styles
• Path Validation: Ensures components are installed in valid locations
• Reinstallation Support: Option to reinstall existing components
• Error Handling: Clear error messages and validation

Package Manager Support

The CLI automatically detects and uses your project's package manager:

Detection Priority

1. pnpm - If pnpm-lock.yaml exists
2. yarn - If yarn.lock exists
3. npm - If package-lock.json exists
4. Fallback - Checks PATH availability (pnpm → yarn → npm)

Installation Commands

• npm: npm install <package> and npm install --save-dev <package>
• yarn: yarn add <package> and yarn add --dev <package>
• pnpm: pnpm add <package> and pnpm add --save-dev <package>

The detected package manager is stored in shangjc.config.json and used for all subsequent installations.

Troubleshooting

"Not an Angular project" error

Ensure you're running the CLI from the root directory of your Angular project where angular.json is located.

Component installation fails

• Check that you have sufficient permissions
• Verify your network connection for dependency installation
• Ensure the target directory is writable

Configuration issues

• Delete shangjc.config.json and run ng-shangjc init again
• Check that your components path starts with src/

Development

For CLI development:

# Clone the repository
git clone <repository-url>

# Install dependencies
npm install

# Build the CLI
npm run build

# Run in development mode
npm run dev

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

This project is licensed under the MIT License.

Support

For issues and questions:

• Create an issue on GitHub
• Check the documentation
• Review existing issues for solutions