Rustelo/docs/howto/using-cargo-rustelo.md

Using Cargo Rustelo - The Easy Way

Rustelo provides a powerful Cargo subcommand that makes creating and managing Rustelo sites incredibly simple.

🚀 Installation

Install Rustelo CLI as a Cargo subcommand:

# Install from local development
cargo install --path rustelo/crates/rustelo-cli

# Or install from crates.io (when published)
cargo install cargo-rustelo

🎯 Quick Start - 30 Seconds to a Working Site

# 1. Create a new site (does everything automatically!)
cargo rustelo init my-awesome-site

# 2. Navigate to the project
cd my-awesome-site  

# 3. Start development server
cargo rustelo dev

# 4. Visit http://127.0.0.1:3030 🎉

That's it! You have a fully functional Rustelo site with:

• ✅ Framework-as-dependency architecture
• ✅ Asset fallback system (Local → Framework → Generated)
• ✅ Complete project structure
• ✅ Development server with hot reload
• ✅ Production build configuration

📋 Available Commands

Project Management

cargo rustelo init <name> - Create New Site

Creates a complete Rustelo implementation with all necessary files.

# Basic usage
cargo rustelo init my-site

# With custom path
cargo rustelo init my-blog --path ./sites/my-blog

# With different template
cargo rustelo init my-app --template advanced

What it creates:

• Complete Cargo.toml with framework dependencies
• Main application file with working examples
• Asset directories and configuration
• Justfile with framework fallbacks
• Leptos configuration for development
• All directory structure needed

cargo rustelo dev - Development Server

Starts development server with hot reload and asset watching.

# Start server on default port (3030)
cargo rustelo dev

# Custom port
cargo rustelo dev --port 8080

# Enable file watching (default)
cargo rustelo dev --watch

cargo rustelo build - Production Build

Builds optimized production version with asset resolution.

# Production build
cargo rustelo build --release

# Development build with assets
cargo rustelo build

# Skip asset processing
cargo rustelo build --no-assets

# Build specific asset categories only
cargo rustelo build --categories static,content

# Organize assets by category in output
cargo rustelo build --organize-by-category

cargo rustelo update - Framework Updates

Updates framework version while preserving local customizations.

# Update to latest version
cargo rustelo update

# Update to specific version
cargo rustelo update 1.2.3

# Force update (overwrites conflicts)
cargo rustelo update --force

Asset Management

cargo rustelo assets list - View Assets

Shows all available assets and their resolution paths.

# List all assets
cargo rustelo assets list

# Filter by category
cargo rustelo assets list --categories static,content

# Show category statistics
cargo rustelo assets list --stats

cargo rustelo assets check - Asset Conflicts

Checks for conflicts between local and framework assets.

# Check all assets
cargo rustelo assets check

# Check specific categories
cargo rustelo assets check --categories config

cargo rustelo assets resolve <path> - Asset Resolution

Shows exactly where a specific asset resolves to.

# Resolve specific asset
cargo rustelo assets resolve styles/main.css

# Shows: Local → Framework → Generated priority

cargo rustelo assets organize - Organize Assets

Organizes assets by category in target directory.

# Organize all assets
cargo rustelo assets organize ./organized-assets

# Organize specific categories
cargo rustelo assets organize ./dist --categories static,content

Build Pipeline

cargo rustelo pipeline init - Setup Build Pipeline

Initializes advanced build pipeline configuration.

# Initialize pipeline config
cargo rustelo pipeline init

# Force overwrite existing config
cargo rustelo pipeline init --force

cargo rustelo pipeline targets - List Build Targets

Shows all available build targets (dev, prod, cross-linux, etc.).

cargo rustelo pipeline run <target> - Run Build Target

Executes specific build target with hooks and asset processing.

# Run production build target
cargo rustelo pipeline run prod

# Run with custom variables
cargo rustelo pipeline run dev --vars debug=true,mode=development

Cross-Compilation (for CI/CD)

cargo rustelo cross init - Setup Cross-Compilation

Configures Docker-based cross-compilation for building Linux binaries on macOS.

# Initialize cross-compilation
cargo rustelo cross init

# Custom target and image
cargo rustelo cross init --target x86_64-unknown-linux-gnu --image rust:latest

# Force overwrite existing config
cargo rustelo cross init --force

cargo rustelo cross build - Cross-Compile

Builds application for Linux using Docker containers.

# Build for Linux (production)
cargo rustelo cross build

# Development build
cargo rustelo cross build --mode dev

# Custom target
cargo rustelo cross build --target aarch64-unknown-linux-gnu

# Verbose output
cargo rustelo cross build --verbose

# Skip Docker image build if exists
cargo rustelo cross build --skip-image-build

cargo rustelo cross test - Cross-Platform Testing

Runs tests in cross-compilation environment.

# Run tests in Linux container
cargo rustelo cross test

# Test specific target
cargo rustelo cross test --target x86_64-unknown-linux-gnu

🎯 Common Workflows

Starting a New Project

cargo rustelo init my-site
cd my-site
cargo rustelo dev

Adding Features

# Check available assets
cargo rustelo assets list

# Check what gets overridden
cargo rustelo assets check

# Build with specific features
cargo rustelo build --categories auth,content

Production Deployment

# Build optimized version
cargo rustelo build --release --organize-by-category

# Or use build pipeline
cargo rustelo pipeline run prod

# For Linux servers (from macOS)
cargo rustelo cross build --mode release

Framework Updates

# Update framework dependencies
cargo rustelo update

# Check if any assets need attention
cargo rustelo assets check

# Rebuild with new framework version
cargo rustelo build

✨ Benefits Over Manual Setup

Aspect	Manual Setup	cargo rustelo init
Time	30+ minutes	30 seconds
Files Created	8+ files manually	Everything automated
Configuration	Error-prone manual config	Perfect config every time
Dependencies	Must know exact versions	Latest compatible versions
Asset System	Must understand fallback logic	Working out of the box
Leptos Config	Complex metadata setup	Configured automatically
Framework Updates	Manual dependency management	cargo rustelo update

🔄 Typical Development Cycle

# 1. Create project
cargo rustelo init my-project && cd my-project

# 2. Development with hot reload
cargo rustelo dev

# 3. Check assets and build
cargo rustelo assets list
cargo rustelo build

# 4. Update framework when needed  
cargo rustelo update

# 5. Deploy to production
cargo rustelo cross build  # For Linux servers

🎉 Result

With cargo rustelo, you get a true framework-as-dependency architecture with:

• ✅ No forking required - Pure dependency usage
• ✅ 30-second setup - From zero to working site instantly
• ✅ Asset fallback system - Local overrides work automatically
• ✅ Framework updates - cargo rustelo update gets latest features
• ✅ Professional tooling - All the power, none of the complexity
• ✅ Production ready - Optimized builds, cross-compilation, CI/CD support

This is exactly what modern framework tooling should be! 🚀