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

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

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

Workflow

For the best experience, follow these steps in order:

1. Initialize your project with npx @cloudwick/astral-ui-cli init - this will display path alias setup instructions for your project type
2. Configure path aliases in your project following the instructions shown during initialization
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 Noto Sans font files for consistent typography
• Set up font CSS for proper font rendering
• Display detailed path alias setup instructions based on your project type (Next.js, Vite, Webpack, CRA, etc.)

Options

Note: When files already exist, backups are automatically created before replacing them.

The init command automatically detects your project type and provides specific path alias configuration instructions for:

• Next.js: Uses tsconfig.json/jsconfig.json for aliases
• Vite: Provides vite.config.js/ts configuration
• Webpack: Provides webpack.config.js configuration
• Create React App: Provides CRACO setup instructions
• Generic: Provides base configuration for other project types

Additionally, the CLI detects tsconfig.app.json (used by some frameworks for application-specific TypeScript settings) and provides guidance for configuring it.

add

Add components to your project.

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

Options

Note: When a component already exists, you will be prompted before replacing it. A backup is automatically created when replacing.

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

Note: The command will prompt before replacing existing files and automatically create backups.

Example Usage

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

# 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",
    "hooks": "src/hooks"
  }
}

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, constants, and hooks 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, constants, and hooks. The hooks entry is optional — configs created by older CLI versions omit it and fall back to src/hooks (lib/hooks on Next.js).

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/button';
import { Card, CardHeader, CardContent } from '@components/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.

About the Hooks Directory

The CLI also installs a directory of shared React hooks (useAsyncOptions, useFilterQuery, useInfiniteScroll, useListboxKeyboardNav, useIsTruncated, useWindowSize, and others). This directory:

• Is automatically created during initialization in the path specified in components.json (hooks field)
• Is exposed through the @hooks alias, which must be configured alongside @components, @utils, and @constants
• Is required by several components — Select, TransferList, MultiSelectTransfer, Scrollbar, and CtaGroup all import from @hooks, so those components will fail to resolve without this alias

Import hooks as import { useWindowSize } from '@hooks' — always from the barrel, not from individual files.

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. All four aliases are required: @components/*, @utils, @constants, and @hooks. A Cannot find module '@hooks' error means that alias is missing.
2. Framework-specific issues:
   • Next.js: Make sure you're using the correct import format for your Next.js version
   • tsconfig.app.json: If your project uses tsconfig.app.json, configure paths there as well
   • Create React App: You'll need CRACO or similar to enable path aliases
3. Verify setup: The path alias setup instructions are shown during init - you can run npx @cloudwick/astral-ui-cli init again to see them
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