# Axum-Leptos Full-Stack Application

_A "2025" version of the official [Axum-Leptos template](https://github.com/leptos-rs/leptos/tree/main/examples/tailwind_axum)_

## Tech Stack

- **Frontend**:
  - [Leptos](https://leptos.dev/) - A modern Rust web framework for building reactive web applications
  - [UnoCSS](https://unocss.dev/) - On-demand atomic CSS engine for fast styling
  - [DaisyUI](https://daisyui.com/) - 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](https://github.com/tokio-rs/axum) - Ergonomic and modular web framework built with Tokio, Tower, and Hyper
  - [Tokio](https://tokio.rs/) - Asynchronous runtime for Rust
  - [Tower](https://github.com/tower-rs/tower) - Tower is a library of modular and reusable components for building robust networking clients and servers.
  - [Tower-http](https://github.com/tower-rs/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](https://github.com/rustls/rustls) - Modern TLS library for secure HTTPS connections
  - [dotenvy](https://github.com/allan2/dotenvy) - Environment variable loading from .env files
  
- **Testing**:
  - [Playwright](https://playwright.dev/) - End-to-end testing framework

- **Other**:
  - [reqwasm](https://github.com/koute/reqwasm) - A simple HTTP client for WebAssembly
  - [serde](https://serde.rs/) - A data serialization framework for Rust
  - [serde_json](https://serde.rs/json.html) - A JSON serialization/deserialization library for Rust
  - [cargo-leptos](https://github.com/leptos-rs/cargo-leptos) - Build tool for Leptos applications

## Getting Started

### Prerequisites

1. Install Rust (nightly):
```bash
rustup toolchain install nightly --allow-downgrade
rustup target add wasm32-unknown-unknown
```

2. Install cargo-leptos:
```bash
cargo install cargo-leptos --locked
```

3. Install Node.js dependencies (pnpm recommended):
```bash
pnpm install
# or
npm install
```

### Quick Start

1. **Automated setup (recommended):**
```bash
./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:**
```bash
# 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:**
```bash
cargo leptos watch
```
This will start your application at `127.0.0.1:3030` (configurable via `.env`)

2. **Watch for CSS changes (separate terminal):**
```bash
pnpm run dev
```

3. **For production build:**
```bash
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](CONFIG.md) for complete configuration documentation.

### HTTPS Development

To enable HTTPS for local development:

1. Generate self-signed certificates:
```bash
./scripts/generate_certs.sh
```

2. Update `.env`:
```env
SERVER_PROTOCOL=https
```

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

### Testing

Run end-to-end tests:
```bash
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](CONFIG.md) - Complete configuration guide
- [DAISYUI_INTEGRATION.md](DAISYUI_INTEGRATION.md) - UI component usage guide
- [scripts/setup_dev.sh](scripts/setup_dev.sh) - Automated development setup
- [scripts/generate_certs.sh](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](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.