Astral CLI

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

Installation

# Install globally with npm
npm install -g astral-core-cli

# Install globally with yarn
yarn global add astral-core-cli

# Or run directly with npx/yarn without installing
npx astral-core-cli init
# or more simply:
npx astral init

Quick Start

# Initialize your project
npx astral init

# Follow instructions to set up path aliases
npx astral setup-aliases

# Add components
npx astral add button card

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

Workflow

For the best experience, follow these steps in order:

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

Commands

init

Initialize a project with Astral Core configuration.

astral 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

Options

| Option | Alias | Description | |--------|-------|-------------| | --yes | -y | Skip confirmation prompts | | --defaults | -d | Use default configuration | | --force | -f | Force overwrite of existing configuration | | --cwd <dir> | -c | Specify the working directory | | --silent | -s | Mute output |

setup-aliases

Display instructions for setting up path aliases in your project.

astral 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

| Option | Alias | Description | |--------|-------|-------------| | --cwd <dir> | -c | Specify the working directory | | --silent | -s | Mute output |

Examples

# Generate instructions for current directory
astral setup-aliases

# Generate instructions for a specific project
astral setup-aliases --cwd ./my-project

add

Add components to your project.

astral add [component...]

Options

| Option | Alias | Description | |--------|-------|-------------| | --yes | -y | Skip confirmation prompts | | --overwrite | -o | Overwrite existing files | | --cwd <dir> | -c | Specify the working directory | | --all | -a | Add all available components | | --path <path> | -p | Specify the path to add the component to | | --silent | -s | Mute output |

Examples

# Add specific components
astral add button card select

# Add all components
astral add --all

# Add a component to a specific directory
astral add button --path ./components/custom

repair-tailwind

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

astral 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
• Update CSS variables required by components
• Ensure proper dependencies are installed

Options

| Option | Alias | Description | |--------|-------|-------------| | --force | -f | Force overwrite of existing configuration without prompting | | --cwd <dir> | -c | Specify the working directory | | --silent | -s | Mute output |

Configuration

components.json

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

{
  "$schema": "https://astral.com/schema.json",
  "style": "default",
  "tailwind": {
    "config": "tailwind.config.js",
    "css": "src/styles/globals.css",
    "baseColor": "slate"
  },
  "aliases": {
    "components": "src/components",
    "utils": "src/lib/utils"
  }
}

You can edit this file to customize:

• tailwind.config: Path to your Tailwind configuration file
• css: Path to your global CSS file
• baseColor: Primary color palette to use
• aliases: Paths where components and utilities 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.

Available Components

| Component | Description | |-----------|-------------| | button | A button component with various styles, sizes, and states | | card | A card component for displaying content in a contained way | | select | A select component for selecting options from a list |

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';

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 astral 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)
• Animation utilities via tailwindcss-animate plugin

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 astral 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 astral 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

License

MIT