Rustelo/docs/guides/tooling-integration.md

Rustelo Tooling Integration

🎯 Overview

Complete tooling template coverage ensures that all development tools work seamlessly with the unified template system and layered override architecture. This integration provides:

• Feature-aware tooling that adapts to enabled features
• Layered configuration merging for all tools
• Consistent development workflows across all project templates
• Hot-reload integration with the override system

🛠️ Integrated Tools

1. Just (Command Runner)

Integration Points:

• Feature-specific commands added automatically
• Local overrides for custom workflows
• Template-based recipe generation
• Environment-aware execution

Example Structure:

config/
├── local/justfile           # Local command overrides
├── features/
│   ├── analytics/justfile   # Analytics-specific commands
│   └── smart-build/justfile # Build optimization commands
└── templates/justfile       # Base commands from template

Command Examples:

# Base template commands
dev:
    cargo leptos watch

build:
    cargo leptos build --release

# Feature-specific commands (analytics)
analytics-report:
    cargo run --bin analytics -- report --hours 24

# Local overrides
dev-debug:
    RUST_LOG=debug cargo leptos watch

2. CSS/UnoCSS System

Integration Points:

• Layered UnoCSS configurations
• Feature-specific styling
• Component-aware class generation
• Development vs production builds

Configuration Layers:

// config/templates/uno.config.ts (Base)
export default {
  presets: ['@unocss/preset-uno', '@unocss/preset-wind'],
  theme: {
    colors: {
      primary: '#3b82f6',
    }
  }
}

// config/features/analytics/uno.config.ts
export default {
  theme: {
    colors: {
      analytics: '#10b981',
    }
  },
  shortcuts: {
    'metric-card': 'bg-white shadow-md rounded-lg p-4',
  }
}

// config/local/uno.config.ts (Highest precedence)
export default {
  theme: {
    colors: {
      primary: '#ef4444',  // Override
      brand: '#8b5cf6',    // Local addition
    }
  }
}

3. Package.json Management

Integration Points:

• Dependency management across layers
• Script merging and overrides
• Feature-specific Node.js tools
• Development vs production configs

Layer Structure:

// config/templates/package.json
{
  "scripts": {
    "css:build": "unocss 'src/**/*.rs' -o public/app.css",
    "css:watch": "unocss 'src/**/*.rs' -o public/app.css --watch"
  },
  "devDependencies": {
    "@unocss/cli": "^0.58.0"
  }
}

// config/features/analytics/package.json  
{
  "scripts": {
    "analytics:dev": "node scripts/analytics-dev.js"
  },
  "dependencies": {
    "chart.js": "^4.0.0"
  }
}

// config/local/package.json
{
  "scripts": {
    "dev": "concurrently \"cargo leptos watch\" \"npm run css:watch\"",
    "test": "cargo test && npm run test:frontend"
  }
}

4. Cargo.toml Workspace Configuration

Integration Points:

• Workspace dependency management
• Feature flag coordination
• Crate-specific configurations
• Build optimization settings

Layer Examples:

# config/templates/Cargo.toml (Base workspace)
[workspace]
members = ["crates/*"]

[workspace.dependencies]
leptos = "0.6"
tokio = { version = "1.0", features = ["full"] }

# config/features/analytics/Cargo.toml
[workspace.dependencies]
prometheus = "0.13"
chrono = { version = "0.4", features = ["serde"] }

# config/local/Cargo.toml (Local overrides)
[workspace.dependencies] 
leptos = "0.7"  # Override version
anyhow = "1.0"  # Local addition

[profile.dev]
opt-level = 1  # Local optimization

5. Development Scripts

Integration Points:

• Layered script execution
• Feature-aware automation
• Environment detection
• Cross-platform compatibility

Script Structure:

scripts/
├── local/           # Local automation scripts
│   ├── custom-build.sh
│   └── deploy-staging.sh
├── features/        # Feature-specific scripts
│   ├── analytics/
│   │   ├── collect-metrics.sh
│   │   └── generate-reports.sh
│   └── smart-build/
│       └── cache-management.sh
└── templates/       # Base template scripts
    ├── setup.sh
    ├── build.sh
    └── test.sh

6. Build System Integration

Integration Points:

• Build.rs script composition
• Asset pipeline coordination
• Route generation integration
• Optimization settings

Build Configuration:

// crates/client/build.rs (Generated)
fn main() {
    // Layer-aware CSS build
    let css_config = resolve_layered_config::<UnoConfig>("uno.config.ts")?;
    build_css_with_config(&css_config)?;
    
    // Layer-aware route generation
    let routes = resolve_layered_routes()?;
    generate_route_code(&routes)?;
    
    // Feature-specific build steps
    if feature_enabled("analytics") {
        build_analytics_assets()?;
    }
}

🔧 Implementation Strategy

1. Template Generation

Enhanced Template System:

• Templates include complete tooling setup
• Feature selection determines which tools are included
• Layered override structure created automatically

CLI Integration:

# Create project with full tooling
cargo rustelo new my-project --template basic --features analytics,smart-build

# Result: Complete tooling setup with:
# - Just commands for development
# - UnoCSS configuration with analytics styles
# - Package.json with analytics dependencies
# - Build scripts with smart caching

2. Configuration Resolution

Unified Configuration Engine:

pub struct ToolingManager {
    config_resolver: LayeredConfig,
    project_root: PathBuf,
}

impl ToolingManager {
    pub fn resolve_just_config(&mut self) -> Result<JustConfig> {
        self.config_resolver.resolve("justfile")
    }
    
    pub fn resolve_css_config(&mut self) -> Result<UnoConfig> {
        self.config_resolver.resolve("uno.config.ts")
    }
    
    pub fn resolve_package_config(&mut self) -> Result<PackageConfig> {
        self.config_resolver.resolve("package.json")
    }
}

3. Feature Integration

Automatic Tool Updates:

# Adding feature updates all related tooling
cargo rustelo add analytics

# Updates:
# - justfile (adds analytics commands)
# - uno.config.ts (adds analytics styles)  
# - package.json (adds analytics dependencies)
# - build scripts (adds analytics builds)

4. Development Workflows

Hot Reload Integration:

• CSS changes trigger UnoCSS rebuild
• Configuration changes reload layered configs
• Component overrides trigger selective rebuilds
• Script changes restart development server

Watch System:

# Comprehensive development mode
just dev

# Runs:
# - cargo leptos watch (Rust hot reload)
# - unocss --watch (CSS hot reload)
# - node scripts/config-watcher.js (Config hot reload)

📋 Tooling Templates

Just Template (Feature-Aware)

# Base development commands
dev:
    @echo "🚀 Starting development server..."
    cargo leptos watch

build:
    @echo "🏗️ Building for production..."
    cargo leptos build --release

test:
    @echo "🧪 Running tests..."
    cargo test

# CSS commands (always included)
css-build:
    @echo "🎨 Building CSS..."
    unocss 'src/**/*.rs' -o public/app.css

css-watch:
    @echo "👀 Watching CSS..."
    unocss 'src/**/*.rs' -o public/app.css --watch

{{#if features.analytics}}
# Analytics commands (feature-specific)
analytics-report:
    @echo "📊 Generating analytics report..."
    cargo run --bin analytics -- report --hours 24

analytics-dashboard:
    @echo "📈 Starting analytics dashboard..."
    cargo run --bin analytics -- dashboard
{{/if}}

{{#if features.smart-build}}
# Smart build commands (feature-specific)
build-cached:
    @echo "⚡ Building with smart cache..."
    cargo run --bin smart-build -- build --cached

cache-clean:
    @echo "🧹 Cleaning build cache..."
    cargo run --bin smart-build -- cache clean
{{/if}}

# Local overrides marker
{{#if local_commands}}
# === Local Commands (Override) ===
{{local_commands}}
{{/if}}

UnoCSS Template (Layered)

// Base configuration with feature composition
import { defineConfig } from 'unocss'

export default defineConfig({
  // Base presets (always included)
  presets: [
    '@unocss/preset-uno',
    '@unocss/preset-wind',
    '@unocss/preset-typography',
  ],
  
  // Base theme
  theme: {
    colors: {
      primary: '{{theme.primary_color}}',
      secondary: '{{theme.secondary_color}}',
      {{#each theme.colors}}
      '{{@key}}': '{{this}}',
      {{/each}}
    },
    fontFamily: {
      sans: {{theme.font_sans}},
      serif: {{theme.font_serif}},
      mono: {{theme.font_mono}},
    },
  },
  
  // Base shortcuts
  shortcuts: {
    'btn': 'px-4 py-2 rounded transition-colors',
    'btn-primary': 'btn bg-primary text-white hover:bg-primary/80',
    'card': 'bg-white shadow-md rounded-lg p-4',
    {{#each shortcuts}}
    '{{@key}}': '{{this}}',
    {{/each}}
  },
  
  {{#if features.analytics}}
  // Analytics feature styles
  rules: [
    [/^metric-(\d+)$/, ([, d]) => ({ 'font-size': `${d}px` })],
  ],
  shortcuts: {
    ...shortcuts,
    'metric-card': 'card border-l-4 border-analytics',
    'chart-container': 'w-full h-64 bg-gray-50 rounded',
  },
  {{/if}}
  
  // Content sources (layer-aware)
  content: [
    'src/**/*.rs',
    'templates/**/*.html',
    {{#if features.analytics}}
    'src/components/features/analytics/**/*.rs',
    {{/if}}
    {{#if local_content}}
    'src/components/local/**/*.rs',
    {{/if}}
  ],
  
  // Safelist for always-included classes
  safelist: [
    'text-red-500',
    'text-green-500',
    'text-blue-500',
    {{#each safelist}}
    '{{this}}',
    {{/each}}
  ]
})

Package.json Template (Mergeable)

{
  "name": "{{project_name}}",
  "version": "{{project_version}}",
  "description": "{{project_description}}",
  "private": true,
  
  "scripts": {
    "css:build": "unocss 'src/**/*.rs' -o public/app.css",
    "css:watch": "unocss 'src/**/*.rs' -o public/app.css --watch",
    "build": "npm run css:build && cargo leptos build --release",
    "dev": "concurrently \"cargo leptos watch\" \"npm run css:watch\"",
    
    {{#if features.analytics}}
    "analytics:dev": "node scripts/features/analytics/dev-server.js",
    "analytics:report": "node scripts/features/analytics/generate-report.js",
    {{/if}}
    
    {{#if features.smart-build}}
    "build:smart": "node scripts/features/smart-build/cached-build.js",
    "cache:clean": "node scripts/features/smart-build/clean-cache.js",
    {{/if}}
    
    {{#each local_scripts}}
    "{{@key}}": "{{this}}",
    {{/each}}
  },
  
  "devDependencies": {
    "@unocss/cli": "^0.58.0",
    "@unocss/preset-uno": "^0.58.0",
    "@unocss/preset-wind": "^0.58.0",
    "concurrently": "^8.2.0",
    
    {{#if features.analytics}}
    "chart.js": "^4.0.0",
    "date-fns": "^2.30.0",
    {{/if}}
    
    {{#if features.smart-build}}
    "chokidar": "^3.5.0",
    "fast-glob": "^3.3.0",
    {{/if}}
    
    {{#each additional_dependencies}}
    "{{@key}}": "{{this}}",
    {{/each}}
  }
}

🎯 Benefits

For Developers

• Unified tooling across all project types
• Feature-aware automation - tools adapt to enabled features
• Local customization without losing update capability
• Consistent workflows regardless of project complexity

For Teams

• Standardized tooling across all Rustelo projects
• Shared configurations with local override capability
• Feature parity - same tools work the same way everywhere
• Easy onboarding - familiar tooling patterns

For Framework

• Tool integration - all tools work together seamlessly
• Update safety - tooling updates don't break customizations
• Feature composability - tools from different features integrate properly
• Performance optimization - smart caching and coordination

This comprehensive tooling integration ensures that Rustelo provides a complete, production-ready development experience with all the tools developers need working seamlessly together.