@cloudwick/astral-ui-cli v0.5.0

Astral UI CLI

A command-line tool for installing and managing Astral UI components in any codebase.

Usage

For most projects, we recommend using the CLI with npx or yarn dlx instead of installing it globally:

# Using npx
npx @cloudwick/astral-ui-cli init

# Using yarn
yarn dlx @cloudwick/astral-ui-cli init

If you frequently use the CLI in your workflow, you can install it globally:

# Install globally with npm (only if needed)
npm install -g @cloudwick/astral-ui-cli

# Install globally with yarn (only if needed)
yarn global add @cloudwick/astral-ui-cli

Quick Start

# Initialize your project
npx @cloudwick/astral-ui-cli init

# Follow instructions to set up path aliases
npx @cloudwick/astral-ui-cli setup-aliases

# Add components
npx @cloudwick/astral-ui-cli add button card

# Start using in your code
import { Button } from '@components/ui/button';
import { cn } from '@utils';
import { keyboardKeys, mobileBreakPoint } from '@constants';

Workflow

For the best experience, follow these steps in order:

1. Initialize your project with npx @cloudwick/astral-ui-cli init
2. Set up path aliases using npx @cloudwick/astral-ui-cli setup-aliases and follow the instructions
3. Add components with npx @cloudwick/astral-ui-cli add [component...]
4. Repair Tailwind if needed with npx @cloudwick/astral-ui-cli repair-tailwind
5. Import and use components in your application

Commands

init

Initialize a project with Astral Core configuration.

npx @cloudwick/astral-ui-cli init

This command will:

• Create a components.json configuration file
• Set up necessary dependencies
• Install Tailwind CSS if not already present
• Add required configuration to existing Tailwind config or create a new one
• Add utility functions
• Add Inter font files for consistent typography
• Set up font CSS for proper font rendering

Options

setup-aliases

Display instructions for setting up path aliases in your project.

npx @cloudwick/astral-ui-cli setup-aliases

This command will:

• Analyze your project structure
• Detect the type of project (Next.js, Vite, Webpack, etc.)
• Provide specific instructions for configuring path aliases based on your project type
• Check for special configurations like tsconfig.app.json (used in Angular projects)

Options

Examples

# Generate instructions for current directory
npx @cloudwick/astral-ui-cli setup-aliases

# Generate instructions for a specific project
npx @cloudwick/astral-ui-cli setup-aliases --cwd ./my-project

add

Add components to your project.

npx @cloudwick/astral-ui-cli add [component...]

Options

Examples

# List all available components
npx @cloudwick/astral-ui-cli add --list

# List components in silent mode (component names only)
npx @cloudwick/astral-ui-cli add --list --silent

# Add specific components
npx @cloudwick/astral-ui-cli add button card select

# Add all components
npx @cloudwick/astral-ui-cli add --all

# Add a component to a specific directory
npx @cloudwick/astral-ui-cli add button --path ./components/custom

# Skip installing internal component dependencies
npx @cloudwick/astral-ui-cli add button --skip-dependencies

repair-tailwind

Repair Tailwind configuration when setup fails - only use if experiencing issues with Tailwind.

npx @cloudwick/astral-ui-cli repair-tailwind

This command will:

• Check for existing Tailwind configuration and create a timestamped backup
• Create a new Tailwind configuration with the appropriate file extension for your project
• Set up the complete CSS structure including:
  • Main CSS file with proper imports
  • Fonts stylesheet (fonts.min.css)
• Ensure proper dependencies are installed
• Create a backup of any existing Tailwind configuration before modifying it

The CSS structure created will match exactly what the init command creates, including:

• CSS variables for colors and theming
• Font imports and configuration
• Proper file organization

Options

Example Usage

# Basic repair
npx @cloudwick/astral-ui-cli repair-tailwind

# Force overwrite existing files
npx @cloudwick/astral-ui-cli repair-tailwind --force

# Repair in a specific directory
npx @cloudwick/astral-ui-cli repair-tailwind --cwd ./my-project

Configuration

components.json

The components.json file is created during initialization and contains configuration for your project:

{
  "$schema": "./schema/components-config.schema.json",
  "tailwind": {
    "config": "tailwind.config.js",
    "css": "src/styles/globals.css",
  },
  "aliases": {
    "components": "src/components",
    "utils": "src/utils",
    "constants": "src/constants"
  }
}

You can edit this file to customize:

• tailwind.config: Path to your Tailwind configuration file
• css: Path to your global CSS file
• aliases: Paths where components, utilities, and constants are installed

Note: The utils path in components.json is stored without a file extension. The CLI automatically adds .ts or .js extension based on whether your project uses TypeScript or JavaScript. When configuring path aliases, you should use the path without an extension as shown in the components.json file.

Components JSON Schema

Alongside your components.json, the CLI generates a JSON Schema file at schema/components-config.schema.json. You can use this schema in your editor or CI to validate your configuration. It defines:

• $schema (string): URI of this schema file.
• tailwind (object): Paths to your Tailwind config (config) and CSS file (css).
• aliases (object): Directories for components, utils, and constants.
• extensions (string[]): File extensions to search for components.

For full details, see schema/components-config.schema.json in your project.

Available Components

To see a complete list of all available components, run:

npx @cloudwick/astral-ui-cli add --list

This will display all components with their descriptions. You can also use the silent mode to get just the component names:

npx @cloudwick/astral-ui-cli add --list --silent

Popular Components

Using Components

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

React/Next.js Example

import { Button } from '@components/ui/button';
import { Card, CardHeader, CardContent } from '@components/ui/card';
import { cn } from '@utils';
import { keyboardKeys, mobileBreakPoint } from '@constants';

export function MyComponent() {
  return (
    <Card>
      <CardHeader>My Card</CardHeader>
      <CardContent>
        <p>Card content goes here</p>
        <Button 
          className={cn("mt-4", "custom-class")}
          variant="outline"
        >
          Click Me
        </Button>
      </CardContent>
    </Card>
  );
}

About the Utils File

The CLI creates a utility file with the cn function that helps combine Tailwind classes. This file:

• Is automatically created during initialization in the path specified in components.json (utils field)
• Has the appropriate file extension (.ts for TypeScript projects, .js for JavaScript projects) added automatically
• Should be imported in your components as import { cn } from '@utils' after setting up path aliases

The cn function allows you to conditionally combine class names and automatically handles Tailwind class conflicts.

Styling Components

The components in the registry require Tailwind CSS to be properly configured in your application. When you run npx @cloudwick/astral-ui-cli init, the CLI will:

1. Check for an existing Tailwind configuration and upgrade it with required settings
2. Create a CSS file with required CSS variables for component styling
3. Generate a STYLING.md file with documentation on the styling system

Tailwind Integration

The CLI intelligently handles existing Tailwind configurations:

• Automatically detects existing configuration files with any extension (.js, .ts, .mjs, .cjs)
• Creates a timestamped backup of any existing Tailwind configuration file
• Creates a new tailwind.config file with the appropriate extension based on your project type:
  • TypeScript projects: .ts extension
  • ESM projects: .mjs extension
  • CommonJS projects: .js extension
  • CommonJS in an ESM package (with "type": "module"): .cjs extension
• Preserves your project's language (TypeScript or JavaScript) and module system (ESM or CommonJS)

Required Tailwind features included in the configuration:

• Color system with RGB variables for primary, secondary, success, warning, error, and gray scales
• Custom box shadows for card components
• Dark mode support ("class" mode for theme toggling)

CSS Variables

The CSS file includes all necessary CSS variables that components reference, including:

• Base colors (primary, secondary, etc.)
• State colors (success, error, warning)
• Theme variables for light/dark mode

Troubleshooting

Path Alias Issues

If you're having problems with imports:

1. Check your configuration: Make sure the paths in tsconfig.json/jsconfig.json match your project structure
2. Framework-specific issues:
   • Next.js: Make sure you're using the correct import format for your Next.js version
   • Angular: Configure paths in tsconfig.app.json instead of tsconfig.json
   • Create React App: You'll need CRACO or similar to enable path aliases
3. Verify setup: Run npx @cloudwick/astral-ui-cli setup-aliases again to get fresh instructions
4. Check components.json: Make sure the paths in the "aliases" section match your project structure

Styling Issues

If components don't appear correctly styled:

1. Make sure the Tailwind CSS configuration is properly loaded in your application
2. Verify the CSS variables are included in your main CSS file
3. Check that your component is properly importing the required utilities
4. Run npx @cloudwick/astral-ui-cli repair-tailwind to create a fresh Tailwind configuration
5. If you need to combine the new configuration with your existing customizations, use your backup file as a reference

Contributing

For information on developing and contributing to the CLI, please see the CONTRIBUTING.md file in the root of the repository.

License

MIT