Installation

System Requirements

Before you begin, ensure your development environment meets these requirements:

• Node.js: Version 18.0 or higher
• npm: Version 8.0 or higher (or pnpm/yarn equivalent)
• Git: For version control (recommended)

Installation Methods

Method 1: Clone Repository (Recommended)

The easiest way to get started is by cloning the Astero UI repository:

# Clone the repository
git clone https://github.com/asterodigital/asteroui.git your-project-name

# Navigate to project directory
cd your-project-name

# Install dependencies
npm install

# Start development server
npm run dev

Your development server will be available at http://localhost:9001

Method 2: Download ZIP

1. Download the latest release from the GitHub repository
2. Extract the ZIP file to your desired project directory
3. Open terminal in the project directory
4. Install dependencies: npm install
5. Start development: npm run dev

Project Structure

After installation, your project will have this structure:

your-project/
├── src/
│   ├── astro/              # Astro components and pages
│   │   ├── components/     # Reusable UI components
│   │   ├── layouts/        # Page layouts
│   │   ├── pages/          # Route pages
│   │   └── templates/      # Template library
│   ├── docs/               # Documentation (MDX files)
│   ├── styles/             # SCSS styling system
│   ├── scripts/            # JavaScript modules
│   └── assets/             # Static assets
├── tools/                  # Build tools and scripts
├── config/                 # Configuration files
├── dist/                   # Built files (generated)
└── package.json           # Project dependencies

Development Commands

Once installed, you can use these commands:

Development

# Start development server with hot reload
npm run dev

# Watch for file changes (alternative)
npm run watch

Building

# Build for production
npm run build

# Build for offline use
npm run build:offline

Assets

# Process CSS files
npm run css

# Process JavaScript files
npm run js

# Process all assets
npm run assets

Code Quality

# Run linting
npm run lint

# Fix linting issues
npm run fixlint

# Format code
npm run format:html

Utilities

# Clean build files
npm run clean

# Serve built files locally
npm run serve

# Serve offline build
npm run serve:offline

Configuration

Environment Setup

1. Development: The development server runs on localhost:9001 by default
2. Build Output: Production builds are output to the dist/ directory
3. Asset Processing: Assets are automatically processed and optimized

Customization

You can customize Astero UI by modifying:

• SCSS Variables: Edit files in src/styles/variables/
• Component Styles: Modify component-specific SCSS files
• Bootstrap Overrides: Customize Bootstrap variables
• Build Configuration: Update configuration files in config/

Verification

To verify your installation is working correctly:

1. Start Development Server:

   npm run dev
   

2. Open Browser: Navigate to http://localhost:9001

3. Check Features:

   • Main landing page loads
   • Admin templates accessible at /templates/admin
   • Documentation accessible at /docs
   • Hot reload works when you edit files

Troubleshooting

Common Issues

Port Already in Use

# If port 9001 is busy, the server will automatically use the next available port
# Check the terminal output for the actual URL

Node Version Issues

# Check your Node.js version
node --version

# Update Node.js if needed (use nvm if available)
nvm install 18
nvm use 18

Dependency Issues

# Clear npm cache and reinstall
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Build Errors

# Clean build files and try again
npm run clean
npm run build

Getting Help

If you encounter issues during installation:

1. Check the GitHub Issues
2. Review the troubleshooting section
3. Ensure you meet the system requirements
4. Try clearing cache and reinstalling dependencies

Next Steps

Once installation is complete:

1. 🚀 Getting Started - Create your first project
2. 🧩 Components - Explore available components
3. 🎨 Customization - Customize the framework
4. 📐 Layouts - Understanding layout system

Ready to start building? Let's create something amazing with Astero UI!