Rustelo/crates/templates/README.md

Rustelo Templates

This directory contains the new template-based architecture for Rustelo projects. After the architectural refactoring, foundation crates can now be cloned locally and customized through trait-based implementations.

🏗️ Architecture Overview

rustelo/
├── traits/                    # Layer 1: Pure trait abstractions (zero deps)
│   ├── routing-traits/        
│   ├── component-traits/      
│   └── core-types/           
├── templates/                 # Layer 2: Template implementations
│   ├── core-lib-template/     
│   ├── client-template/       
│   ├── server-template/       
│   └── rustelo-cli/          # CLI tool for project management
└── foundation/               # Layer 3: Reference implementation (legacy)
    └── crates/               

🚀 Quick Start

1. Install the CLI Tool

cd rustelo-cli
cargo install --path .

2. Create a New Project

# Interactive project creation
rustelo new my-project

# Quick project with defaults
rustelo new my-project --quiet

3. Clone Foundation Crates for Customization

# Clone specific crate
rustelo clone core-lib --target local-crates

# Clone all foundation crates  
rustelo clone all --target local-crates

4. Migrate Existing Project

# Migrate existing project to new architecture
rustelo migrate --path /path/to/project

# Check project status
rustelo status --path /path/to/project

📋 Template Descriptions

core-lib-template

• Purpose: Core trait implementations for routing, content, and localization
• Customization: Edit src/traits_impl.rs to modify routing logic, content loading, etc.
• Zero Dependencies: No environment variables, pure trait-based configuration

client-template

• Purpose: Client-side routing and rendering using trait injection
• Features: WASM-compatible, reactive routing, trait-based component rendering
• Customization: Modify ClientRouteRenderer in src/routing.rs

server-template

• Purpose: Server-side rendering with trait-based dependency injection
• Features: SSR support, localization, metadata generation
• Customization: Modify ServerRouteRenderer in src/routing.rs

🎯 Usage Workflows

For New Projects

1. Create project: rustelo new my-project
2. Develop normally: cargo leptos watch
3. Customize as needed: Edit trait implementations

For Existing Projects

1. Check status: rustelo status
2. Migrate: rustelo migrate
3. Customize: Edit generated traits_impl.rs files
4. Test: cargo leptos watch

For Local Customization

1. Clone templates: rustelo clone all --target local-crates
2. Customize implementations: Edit local-crates/*/src/traits_impl.rs
3. Update dependencies: Point Cargo.toml to local crates
4. Develop: Full control over trait implementations

🔧 Customization Guide

Customizing Route Resolution

// In local-crates/core-lib/src/traits_impl.rs
impl RouteResolver for DefaultRouteResolver {
    fn resolve_route(&self, path: &str) -> RoutingResult<RouteResolution<Self::Component, Self::Parameters>> {
        // Your custom routing logic here
        // No environment variables needed - use configuration objects
        Ok(RouteResolution {
            component: Some("CustomComponent".to_string()),
            path: path.to_string(),
            parameters: HashMap::new(),
        })
    }
}

Customizing Component Rendering

// In local-crates/client/src/routing.rs  
impl RouteRenderer for ClientRouteRenderer {
    fn render_component(&self, component: &Self::Component, path: &str, language: &str, parameters: &Self::Parameters) -> RoutingResult<Self::View> {
        // Your custom rendering logic here
        match component.as_str() {
            "CustomComponent" => {
                let view = view! { <div>"My Custom Component"</div> }.into_any();
                Ok(view)
            },
            _ => self.render_not_found(path, language)
        }
    }
}

Customizing Content Loading

// In local-crates/core-lib/src/traits_impl.rs
impl ContentProvider for DefaultContentProvider {
    fn load_content(&self, content_type: &str, identifier: &str, language: &str) -> ComponentResult<ContentMetadata> {
        // Your custom content loading logic
        // Load from database, API, filesystem, etc.
        Ok(ContentMetadata {
            title: "Custom Content".to_string(),
            slug: identifier.to_string(),
            language: language.to_string(),
            // ... other fields
        })
    }
}

📁 Directory Structure After Cloning

your-project/
├── Cargo.toml                    # Updated with local crate references
├── local-crates/                 # Cloned and customized crates
│   ├── core-lib/
│   │   ├── src/traits_impl.rs   # ← Customize trait implementations
│   │   └── Cargo.toml           
│   ├── client/
│   │   ├── src/routing.rs       # ← Customize client routing
│   │   └── Cargo.toml
│   └── server/
│       ├── src/routing.rs       # ← Customize server routing  
│       └── Cargo.toml
└── src/
    └── main.rs                   # Uses local-crates instead of foundation

🔄 Migration Process

The CLI tool automates migration from the old foundation-based architecture:

1. Backup: Creates .backup-pre-migration/ with original files
2. Dependencies: Adds trait crate dependencies to Cargo.toml
3. Implementations: Creates traits_impl.rs files with default implementations
4. Routing: Updates routing files to use trait-based approach
5. Summary: Generates MIGRATION_SUMMARY.md with details

✨ Benefits of New Architecture

• 🔓 No Vendor Lock-in: Clone templates and customize freely
• 🚫 No Code Generation: Runtime trait resolution instead of build-time generation
• 🌍 Environment Agnostic: No dependency on environment variables
• 🔧 Full Customization: Every aspect can be modified locally
• 📦 Modular: Only include what you need
• 🧪 Testable: Mock trait implementations for testing
• ⚡ Performance: Runtime resolution with caching

🆘 Troubleshooting

Common Issues

Template not found

# Make sure you're in the rustelo project directory
cd /path/to/rustelo
rustelo clone core-lib

Compilation errors after cloning

# Update local trait dependency paths in Cargo.toml
[dependencies.rustelo-routing-traits]
path = "../traits/routing-traits"  # Adjust path as needed

Runtime routing failures

# Check your trait implementations in src/traits_impl.rs
# Make sure resolve_route returns valid components

Getting Help

• Check project status: rustelo status
• Review migration summary: cat MIGRATION_SUMMARY.md
• Restore from backup: Copy from .backup-pre-migration/

🎯 Next Steps

1. Try the CLI: cargo install --path rustelo-cli
2. Create test project: rustelo new test-project
3. Experiment with customization: Clone crates and modify trait implementations
4. Migrate existing projects: Use rustelo migrate on real projects
5. Provide feedback: Report issues and suggest improvements

This template-based architecture provides the granularity and flexibility requested while maintaining all the benefits of Rustelo's configuration-driven, language-agnostic design.