Installation
Step-by-step guide to installing and setting up Astero UI in your project, including requirements, commands, and troubleshooting.
System Requirements
Before you begin, ensure your development environment meets these requirements:
- Node.js: Version 18.0 or higher
- pnpm: Version 10.0 or higher
- 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
pnpm install
# Start development server
pnpm run dev
Your development server will be available at http://localhost:9001
Method 2: Download ZIP
- Download the latest release from the GitHub repository
- Extract the ZIP file to your desired project directory
- Open terminal in the project directory
- Install dependencies:
pnpm install - Start development:
pnpm 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
pnpm run dev
# Watch for file changes (alternative)
pnpm run watch
Building
# Build for production
pnpm run build
# Build for offline use
pnpm run build:offline
Assets
# Process CSS files
pnpm run css
# Process JavaScript files
pnpm run js
# Process all assets
pnpm run assets
Code Quality
# Run linting
pnpm run lint
# Fix linting issues
pnpm run fixlint
# Format code
pnpm run format:html
Utilities
# Clean build files
pnpm run clean
# Serve built files locally
pnpm run serve
# Serve offline build
pnpm run serve:offline
Configuration
Environment Setup
-
Development: The development server runs on
localhost:9001by default -
Build Output: Production builds are output to the
dist/directory - 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:
-
Start Development Server:
pnpm run dev -
Open Browser: Navigate to
http://localhost:9001 -
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
# Reinstall dependencies
rm -rf node_modules
pnpm install
Build Errors
# Clean build files and try again
pnpm run clean
pnpm run build
Getting Help
If you encounter issues during installation:
- Check the GitHub Issues
- Review the troubleshooting section
- Ensure you meet the system requirements
- Try clearing cache and reinstalling dependencies
Next Steps
Once installation is complete:
- 🚀 Getting Started - Create your first project
- 🧩 Components - Explore available components
- 🎨 Customization - Customize the framework
- 📐 Layouts - Understanding layout system
Ready to start building? Let's create something amazing with Astero UI!