# Creating a Site with Rustelo Framework This guide provides step-by-step instructions for creating a new website project using Rustelo as a framework dependency. ## 🎯 Overview Rustelo follows a **framework-as-dependency** architecture, meaning you don't fork the framework - you use it as a library dependency in your own project. This ensures you can: - ✅ Get framework updates automatically - ✅ Keep your customizations separate from framework code - ✅ Use the asset fallback system (Local → Framework → Generated) - ✅ Avoid maintaining a fork ## 📋 Prerequisites - Rust 1.70+ installed - Node.js 18+ (for frontend assets) - Just task runner: `cargo install just` - Git (recommended for version control) ## 🚀 Step-by-Step Guide ### Step 1: Create Your Project Directory ```bash # Create your site project mkdir my-awesome-site cd my-awesome-site # Initialize git repository (optional but recommended) git init ``` ### Step 2: Create Cargo.toml Create a `Cargo.toml` file with Rustelo dependencies: ```toml [package] name = "my-awesome-site" version = "0.1.0" edition = "2021" authors = ["Your Name "] description = "My awesome site built with Rustelo framework" # Main binary [[bin]] name = "server" path = "src/main.rs" [dependencies] # Core Rustelo framework dependencies rustelo-core = { path = "../rustelo/crates/rustelo-core" } rustelo-web = { path = "../rustelo/crates/rustelo-web" } # Optional framework components (uncomment as needed) # rustelo-auth = { path = "../rustelo/crates/rustelo-auth" } # rustelo-content = { path = "../rustelo/crates/rustelo-content" } # Web framework essentials leptos = { version = "0.8.6", features = ["ssr"] } leptos_axum = "0.8.5" axum = "0.8.4" tokio = { version = "1.47.1", features = ["rt-multi-thread", "signal"] } tower = "0.5.2" tower-http = { version = "0.6.6", features = ["fs"] } # Basic utilities tracing = "0.1" tracing-subscriber = "0.3" serde = { version = "1.0", features = ["derive"] } serde_json = "1.0" [features] default = [] # Optional features (enable as needed) # auth = ["rustelo-auth"] # content = ["rustelo-content"] # database = ["rustelo-core/database"] [profile.release] codegen-units = 1 lto = true opt-level = 'z' # Leptos configuration for development server [[workspace.metadata.leptos]] name = "my-awesome-site" bin-package = "my-awesome-site" bin-target-path = "src/main.rs" lib-profile-release = "wasm-release" ``` ### Step 3: Create Source Code Structure ```bash # Create source directory mkdir -p src # Create basic directory structure mkdir -p {content,assets,config,justfiles,public} ``` ### Step 4: Create Main Application File Create `src/main.rs`: ```rust //! My Awesome Site - Built with Rustelo Framework //! //! This demonstrates using Rustelo as a framework dependency for a production site. use axum::{ response::Html, routing::get, Router, }; use rustelo_core::config::RusteloConfig; use tower_http::services::ServeDir; use tracing_subscriber; /// Home page component async fn home() -> Html<&'static str> { Html(r#" My Awesome Site

🌟 My Awesome Site

Built with Rustelo Framework-as-Dependency Architecture

🦀 Framework-as-Dependency

Uses Rustelo as a library dependency, not a fork. Get framework updates automatically while keeping your customizations.

📁 Asset Fallback System

Local → Framework → Generated priority resolution. Override any framework asset with your local version.

🔧 Modular Features

Enable only the framework features you need: authentication, content management, database support, etc.

🚀 Production Ready

Built on Leptos + Axum with SSR, optimized builds, and cross-compilation support.

"#) } /// About page async fn about() -> Html<&'static str> { Html(r#" About - My Awesome Site

Home About API

About My Awesome Site

This site demonstrates the Rustelo framework-as-dependency architecture.

Key benefits:

No source code forking required
Automatic framework updates
Local asset overrides
Modular feature system

"#) } /// API endpoint showing framework integration async fn api_status() -> axum::Json { axum::Json(serde_json::json!({ "status": "ok", "framework": "rustelo", "architecture": "framework-as-dependency", "features": { "core": true, "web": true, "auth": false, "content": false }, "message": "🎉 Framework-as-dependency architecture working!" })) } #[tokio::main] async fn main() -> Result<(), Box> { // Initialize logging tracing_subscriber::fmt() .with_target(false) .init(); tracing::info!("🚀 Starting My Awesome Site..."); // Load framework configuration (with defaults if no config file exists) let _config = RusteloConfig::load().unwrap_or_default(); tracing::info!("📋 Framework configuration loaded"); // Build application routes let app = Router::new() .route("/", get(home)) .route("/about", get(about)) .route("/api/status", get(api_status)) // Serve static files if they exist .nest_service("/static", ServeDir::new("public")) .nest_service("/assets", ServeDir::new("assets")) .with_state(()); // Start server let addr = "127.0.0.1:3030"; tracing::info!("🌐 Server starting at http://{}", addr); tracing::info!("✨ Framework-as-dependency architecture active!"); let listener = tokio::net::TcpListener::bind(addr).await?; axum::serve(listener, app).await?; Ok(()) } ``` ### Step 5: Create Framework Configuration (Optional) Create `rustelo.toml` for framework configuration: ```toml [framework] name = "my-awesome-site" version = "0.1.0" description = "My awesome site built with Rustelo" [assets] # Asset resolution configuration local_path = "assets" framework_path = "../rustelo/assets" organize_by_category = false [server] host = "127.0.0.1" port = 3030 enable_tls = false [features] # Enable framework features as needed auth = false content = false database = false ``` ### Step 6: Create Justfile for Task Management Create `justfile` with framework fallback pattern: ```just # My Awesome Site - Task Runner with Framework Fallback # Local tasks take priority, framework tasks as fallback # Try to import local tasks, then framework tasks mod? local-base 'justfiles/base.just' # Local base tasks mod? base '../rustelo/justfiles/base.just' # Framework fallback # Local development server dev: @echo "🚀 Starting development server..." cargo run --bin server # Local build build mode="release": @echo "🔨 Building for {{mode}} mode..." @if [ "{{mode}}" = "release" ]; then \ cargo build --release; \ else \ cargo build; \ fi # Local test test: @echo "🧪 Running tests..." cargo test # Local clean clean: @echo "🧹 Cleaning build artifacts..." cargo clean rm -rf target/ # Check code quality check: @echo "🔍 Checking code quality..." cargo check cargo clippy cargo fmt --check # Format code fmt: @echo "✨ Formatting code..." cargo fmt # Install dependencies deps: @echo "📦 Installing dependencies..." cargo fetch # Show available tasks help: @echo "Available tasks:" @just --list ``` ### Step 7: Create Local Justfile Tasks (Optional) Create `justfiles/base.just` for site-specific tasks: ```just # Local base tasks for My Awesome Site # Custom deploy task deploy: @echo "🚀 Deploying My Awesome Site..." just build release # Add your deployment commands here # Custom content tasks content-update: @echo "📝 Updating content..." # Add content management commands here # Custom asset processing assets-build: @echo "🎨 Processing assets..." # Add asset processing commands here ``` ### Step 8: Run Your Site ```bash # Run development server just dev # Or run directly with cargo cargo run --bin server # Visit http://127.0.0.1:3030 ``` ## 🔧 Customization Options ### Enable Framework Features Uncomment features in `Cargo.toml` as needed: ```toml # Enable authentication rustelo-auth = { path = "../rustelo/crates/rustelo-auth" } # Enable content management rustelo-content = { path = "../rustelo/crates/rustelo-content" } [features] auth = ["rustelo-auth"] content = ["rustelo-content"] database = ["rustelo-core/database"] ``` ### Asset Fallback System 1. **Local Assets**: Place in `assets/` - highest priority 2. **Framework Assets**: Automatic fallback to framework assets 3. **Generated Assets**: Created by build system if needed ### Override Framework Justfile Tasks Create `justfiles/base.just` with your custom tasks to override framework defaults. ## 📁 Final Project Structure ``` my-awesome-site/ ├── Cargo.toml # Dependencies and configuration ├── rustelo.toml # Framework configuration (optional) ├── justfile # Task runner with framework fallback ├── src/ │ └── main.rs # Main application ├── justfiles/ # Local task overrides │ └── base.just # Custom tasks ├── assets/ # Local assets (override framework) ├── content/ # Site content ├── config/ # Configuration files ├── public/ # Static public files └── target/ # Build output ``` ## 🚀 Next Steps 1. **Add Content**: Create pages in `src/` or use `rustelo-content` crate 2. **Style Your Site**: Add CSS in `assets/` or `public/` 3. **Enable Features**: Add authentication, database, etc. 4. **Deploy**: Use `just deploy` or your preferred deployment method 5. **Update Framework**: `cargo update` gets latest framework versions ## ✨ Benefits Achieved - ✅ **No fork required** - Pure dependency usage - ✅ **Framework updates** - Automatic via `cargo update` - ✅ **Local customization** - Override any framework asset - ✅ **Asset fallback** - Local → Framework → Generated - ✅ **Modular features** - Enable only what you need - ✅ **Production ready** - Optimized builds and deployment This approach ensures you have a maintainable, updatable website that leverages the Rustelo framework without becoming dependent on a fork!