CLI for installing Astral UI components in any codebase
npm install @cloudwick/astral-ui-cliA command-line tool for installing and managing Astral UI components in any codebase.
For most projects, we recommend using the CLI with npx or yarn dlx instead of installing it globally:
``bashUsing npx
npx @cloudwick/astral-ui-cli init
If you frequently use the CLI in your workflow, you can install it globally:
`bash
Install globally with npm (only if needed)
npm install -g @cloudwick/astral-ui-cliInstall globally with yarn (only if needed)
yarn global add @cloudwick/astral-ui-cli
`Quick Start
`bash
Initialize your project
npx @cloudwick/astral-ui-cli initAdd components
npx @cloudwick/astral-ui-cli add button cardStart using in your code
import { Button } from '@components/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 - 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 applicationCommands
$3
Initialize a project with Astral Core configuration.
`bash
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
- Display detailed path alias setup instructions based on your project type (Next.js, Vite, Webpack, CRA, etc.)#### Options
| Option | Alias | Description |
|--------|-------|-------------|
|
--yes | -y | Skip confirmation prompts |
| --defaults | -d | Use default configuration |
| --cwd | -c | Specify the working directory |
| --silent | -s | Mute output |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.
$3
Add components to your project.
`bash
npx @cloudwick/astral-ui-cli add [component...]
`#### Options
| Option | Alias | Description |
|--------|-------|-------------|
|
--cwd | -c | Specify the working directory |
| --all | -a | Add all available components |
| --path | -p | Specify the path to add the component to |
| --silent | -s | Mute output |
| --skip-dependencies | | Skip installing internal component dependencies |
| --list | -l | List all available components |Note: When a component already exists, you will be prompted before replacing it. A backup is automatically created when replacing.
#### Examples
`bash
List all available components
npx @cloudwick/astral-ui-cli add --listList components in silent mode (component names only)
npx @cloudwick/astral-ui-cli add --list --silentAdd specific components
npx @cloudwick/astral-ui-cli add button card selectAdd all components
npx @cloudwick/astral-ui-cli add --allAdd a component to a specific directory
npx @cloudwick/astral-ui-cli add button --path ./components/customSkip installing internal component dependencies
npx @cloudwick/astral-ui-cli add button --skip-dependencies
`$3
Repair Tailwind configuration when setup fails - only use if experiencing issues with Tailwind.
`bash
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
| Option | Alias | Description |
|--------|-------|-------------|
|
--cwd | -c | Specify the working directory |
| --silent | -s | Mute output |Note: The command will prompt before replacing existing files and automatically create backups.
#### Example Usage
`bash
Basic repair
npx @cloudwick/astral-ui-cli repair-tailwindRepair in a specific directory
npx @cloudwick/astral-ui-cli repair-tailwind --cwd ./my-project
`Configuration
$3
The
components.json file is created during initialization and contains configuration for your project:`json
{
"$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.$3
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.For full details, see
schema/components-config.schema.json in your project.Available Components
To see a complete list of all available components, run:
`bash
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:
`bash
npx @cloudwick/astral-ui-cli add --list --silent
`$3
| 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:
$3
`tsx
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 (
My Card
Card content goes here
className={cn("mt-4", "custom-class")}
variant="outline"
>
Click Me
);
}
`$3
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 aliasesThe
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
$3
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)
$3
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
$3
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
- 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$3
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 configurationFor information on developing and contributing to the CLI, please see the CONTRIBUTING.md file in the root of the repository.
MIT