Rustelo/info

Axum-Leptos Full-Stack Application

A "2025" version of the official Axum-Leptos template

Tech Stack

• Frontend:

  • Leptos - A modern Rust web framework for building reactive web applications
  • UnoCSS - On-demand atomic CSS engine for fast styling
  • DaisyUI - Semantic component library for beautiful UI components
  • WebAssembly - For running Rust code in the browser
  • State Management - Global application state with persistence
  • Theme System - Dynamic light/dark/auto themes with system detection

• Backend:

  • Axum - Ergonomic and modular web framework built with Tokio, Tower, and Hyper
  • Tokio - Asynchronous runtime for Rust
  • Tower - Tower is a library of modular and reusable components for building robust networking clients and servers.
  • Tower-http - HTTP specific Tower utilities
  • Security Middleware - CSRF protection, rate limiting, security headers
  • Input Sanitization - XSS prevention and malicious input filtering

• Security & Configuration:

  • Rustls - Modern TLS library for secure HTTPS connections
  • dotenvy - Environment variable loading from .env files

• Testing:

  • Playwright - End-to-end testing framework

• Other:

  • reqwasm - A simple HTTP client for WebAssembly
  • serde - A data serialization framework for Rust
  • serde_json - A JSON serialization/deserialization library for Rust
  • cargo-leptos - Build tool for Leptos applications

Getting Started

Prerequisites

1. Install Rust (nightly):

rustup toolchain install nightly --allow-downgrade
rustup target add wasm32-unknown-unknown

2. Install cargo-leptos:

cargo install cargo-leptos --locked

3. Install Node.js dependencies (pnpm recommended):

pnpm install
# or
npm install

Quick Start

1. Automated setup (recommended):

./scripts/setup_dev.sh

This script will:

• Create your .env file from the template
• Install dependencies
• Build CSS
• Optionally generate TLS certificates for HTTPS development

2. Manual setup:

# Copy environment configuration
cp .env.example .env

# Install dependencies
pnpm install

# Build CSS
pnpm run build:css

# Start development server
cargo leptos watch

Development

1. Start the development server:

cargo leptos watch

This will start your application at 127.0.0.1:3030 (configurable via .env)

2. Watch for CSS changes (separate terminal):

pnpm run dev

3. For production build:

cargo leptos build --release

Configuration

The application uses environment variables for configuration. Key options:

• HTTP (default): SERVER_PROTOCOL=http
• HTTPS: SERVER_PROTOCOL=https (requires TLS certificates)
• Host/Port: SERVER_HOST=127.0.0.1 SERVER_PORT=3030
• Environment: ENVIRONMENT=DEV or ENVIRONMENT=PROD

See CONFIG.md for complete configuration documentation.

HTTPS Development

To enable HTTPS for local development:

1. Generate self-signed certificates:

./scripts/generate_certs.sh

2. Update .env:

SERVER_PROTOCOL=https

3. Access your app at https://127.0.0.1:3030

Testing

Run end-to-end tests:

cargo leptos end-to-end

Project Structure

• src/
  • main.rs - Server entry point with Axum configuration
  • lib.rs - Shared code and WASM hydration setup
  • app.rs - Main application component and routing setup
  • components/ - Reusable UI components
    • Counter.rs - Example counter component
    • mod.rs - Components module definitions
  • pages/ - Application pages/routes
    • Home.rs - Homepage component
    • About.rs - About page with API integration
    • mod.rs - Pages module definitions
  • server/ - Backend server code
    • handlers.rs - API endpoint handlers
    • routes.rs - API route definitions
    • mod.rs - Server module setup
• style/ - CSS and TailwindCSS files
• end2end/ - End-to-end tests with Playwright
  • tests/ - Test specifications
  • playwright.config.ts - Playwright configuration
• public/ - Static assets
• Cargo.toml - Rust dependencies and build configuration
• package.json - Node.js dependencies
• tailwind.config.js - TailwindCSS configuration

Features

🚀 Core Features

• Full-stack Rust development with shared types
• Server-side rendering (SSR) with hydration
• Client-side routing with Leptos Router
• Modern UI components with DaisyUI integration
• Fast CSS with UnoCSS atomic engine
• Flexible configuration with environment variables
• TLS/HTTPS support for secure development and production
• End-to-end testing setup with Playwright
• Development hot-reload for rapid iteration

🎨 UI/UX Enhancements

• Dynamic Theme System - Light/Dark/Auto themes with system detection
• Toast Notifications - Rich notifications with auto-dismiss and persistence
• Form Validation - Real-time validation with comprehensive error handling
• Loading States - Smart loading management and skeleton screens
• Responsive Design - Mobile-first approach with touch-friendly interactions

📊 State Management

• Global State - Centralized application state with automatic persistence
• User Management - Authentication, roles, and preferences
• Cache System - TTL-based caching with automatic cleanup
• Theme Persistence - Theme preferences saved across sessions
• Form State - Advanced form handling with validation

🔒 Security Features

• CSRF Protection - Secure token-based protection against cross-site request forgery
• Rate Limiting - Per-IP and global rate limiting with burst protection
• Security Headers - Comprehensive HTTP security headers (HSTS, CSP, etc.)
• Input Sanitization - XSS prevention and malicious input filtering
• Content Security Policy - Environment-specific CSP with strict production rules

Documentation

• CONFIG.md - Complete configuration guide
• DAISYUI_INTEGRATION.md - UI component usage guide
• scripts/setup_dev.sh - Automated development setup
• scripts/generate_certs.sh - TLS certificate generation

Example Pages

• Home: / - Landing page with hero section
• About: /about - About page with API integration
• DaisyUI Demo: /daisyui - Comprehensive UI component showcase
• Features Demo: /features-demo - NEW! Interactive demonstration of all new features:
  • State management with live examples
  • Theme system with real-time switching
  • Toast notifications showcase
  • Form validation demonstration
  • Security features overview

🆕 New Features Overview

This template now includes three major feature enhancements:

1. State Management System

• Global application state with automatic localStorage persistence
• Modular state architecture (app, user, theme, toast, form)
• Type-safe state access with Leptos signals
• Cache management with TTL and cleanup

2. UI/UX Improvements

• Theme System: Dynamic light/dark/auto themes with system preference detection
• Toast Notifications: Rich notification system with multiple types and auto-dismiss
• Form Validation: Real-time validation with comprehensive error handling
• Loading States: Smart loading management for better UX

3. Security Enhancements

• CSRF Protection: Token-based protection with automatic header injection
• Rate Limiting: Multi-level rate limiting (per-IP + global) with burst protection
• Security Headers: HSTS, CSP, and other security headers
• Input Sanitization: XSS prevention and malicious input filtering

For detailed implementation information, see FEATURES_IMPLEMENTATION_SUMMARY.md.

License

This project is released under the Unlicense. Feel free to use it as a starting point for your own applications.