website-htmx-rustelo-code/scripts/build

Build Scripts Directory

This directory contains all build-related scripts for the Rustelo project. These tools are organized by common build tasks and contexts to help you find the right tool for your needs.

📋 Requirements

Required Tools:

• Nushell - All .nu scripts require Nushell to be installed
• Just - Task runner (recommended for easy command execution)
• For complete setup, see Rustelo Requirements - Tools

🏗️ Build Tools by Context

🚀 Production Build & Deployment

leptos-build.nu - Complete Production Build Pipeline

Purpose: Full production build with dependencies, CSS, and optimization
Task: Build production-ready Leptos application
Context: Use when preparing for deployment or creating release builds
Command: nu scripts/build/leptos-build.nu or just leptos-build-nu
Features:

• Installs all dependencies (main + end2end)
• Builds CSS assets with UnoCSS
• Compiles Leptos with release optimizations
• Enables TLS and content-static features
• Minifies JavaScript output

deploy.nu - Application Deployment Manager

Purpose: Complete deployment management with Docker Compose
Task: Deploy, manage, and monitor application environments
Context: Production, staging, and development deployments
Command: nu scripts/build/deploy.nu [OPTIONS] COMMAND
Main Arguments:

• -e, --env ENV - Environment (dev|staging|production)
• -f, --file FILE - Docker compose file
• -s, --scale N - Number of replicas
• --migrate - Run database migrations
• --backup - Create database backup
• --features FEATURES - Cargo features to enable

Commands:

• deploy - Deploy application with health checks
• stop/restart - Control application lifecycle
• status - Show deployment status and resource usage
• logs - View application logs
• scale - Scale replicas
• health - Check application health
• backup/migrate - Database operations
• clean - Clean up unused containers

Examples:

nu scripts/build/deploy.nu deploy -e production --migrate --backup
nu scripts/build/deploy.nu scale -s 3
nu scripts/build/deploy.nu health

📦 Distribution & Packaging

dist-pack.nu - Distribution Package Creator

Purpose: Create compressed distribution packages for deployment
Task: Package built application for different architectures
Context: CI/CD pipelines, manual distribution, release preparation
Command: nu scripts/build/dist-pack.nu [OS_ARCH] or just dist-pack-nu [target]
Arguments:

• OS_ARCH - Target architecture (e.g., linux-x64, darwin-arm64)

Features:

• Validates build artifacts exist
• Packages server binary, site assets, public files
• Creates compressed tar.gz archives
• Shows package size and contents

🔧 Cross-Platform Development

cross-build.nu - Docker Cross-Platform Builder

Purpose: Build application for different architectures using Docker
Task: Cross-compile for Linux from macOS/Windows
Context: Multi-platform releases, Linux deployment from dev machines
Command: nu scripts/build/cross-build.nu or just cross-build-nu
Features:

• Uses Docker for consistent Linux builds
• Handles volume mounts for project, node_modules, target
• Runs complete build pipeline in container
• Shows distribution file results

build-docker-cross.nu - Cross-Compilation Image Builder

Purpose: Build Docker image for cross-platform compilation
Task: Create/update build environment Docker image
Context: Setting up cross-compilation environment, updating build tools
Command: nu scripts/build/build-docker-cross.nu or just docker-cross-build-nu
Features:

• Builds custom Docker image for cross-compilation
• Validates Docker availability
• Shows image information and size

📚 Documentation & Examples

build-docs.nu - Documentation Generator with Assets

Purpose: Generate Cargo documentation with integrated logo assets
Task: Build comprehensive project documentation
Context: Documentation updates, release preparation, developer onboarding
Command: nu scripts/build/build-docs.nu or just docs-cargo-nu
Features:

• Generates cargo doc with private items
• Copies logo assets to documentation output
• Validates documentation structure
• Shows documentation size and location
• Provides next steps for viewing docs

build-examples.nu - Multi-Configuration Build Examples

Purpose: Demonstrate building with different Cargo feature combinations
Task: Test and showcase various application configurations
Context: Testing feature combinations, documentation examples, CI validation
Command: nu scripts/build/build-examples.nu [OPTIONS]
Arguments:

• -c, --clean - Clean build artifacts first
• -a, --all - Build all configurations (default)
• -m, --minimal - Minimal configuration only
• -f, --full - Full-featured configuration only
• -p, --prod - Production configuration only
• -q, --quick - Common configurations only

Configurations Built:

• Minimal (no database)
• TLS-only (secure static)
• Auth-only (authentication)
• Content-DB (database content)
• Full-featured (auth + content)
• Production (all features)
• Specialized combinations

🌍 Content & Localization

build-localized-content.nu - Markdown to HTML Content Builder

Purpose: Convert localized markdown content to HTML for web serving
Task: Process multilingual content with categories, tags, and metadata
Context: Content updates, adding new languages, preparing content for deployment
Command: nu scripts/build/build-localized-content.nu
Features:

• Reads content types from content-kinds.toml
• Processes English and Spanish content
• Converts markdown to HTML with frontmatter
• Generates category indices and filter indices
• Creates content manifest
• Validates JSON structure
• Shows content statistics

Content Processing:

• Discovers content types dynamically
• Handles category directory structures
• Extracts metadata (tags, categories, publishing status)
• Generates navigation indices
• Creates backward compatibility links

🛠️ Development Tools

dev-quiet.nu - Filtered Development Server

Purpose: Run development server with filtered, relevant output only
Task: Start Leptos development server without noise
Context: Daily development, focusing on important messages
Command: nu scripts/build/dev-quiet.nu or just dev-quiet-nu
Features:

• Runs cargo leptos watch
• Filters out verbose/irrelevant output
• Highlights errors, warnings, and important messages
• Shows clean, focused development feedback

kill-3030.nu - Development Port Process Killer

Purpose: Kill processes running on development ports (3030, 3031)
Task: Clean up stuck development servers
Context: Development workflow, server restart, port conflicts
Command: nu scripts/build/kill-3030.nu
Features:

• Finds processes using ports 3030 and 3031
• Safely kills development server processes
• Shows which processes were killed
• Handles cases where no processes are found

🎨 Asset Build Tools (JavaScript)

CSS & Theme Building

• build-css-bundles.js - CSS bundling and optimization
• build-design-system.js - Design system compilation
• build-theme.js - Theme file generation
• copy-css-assets.js - CSS asset management

JavaScript & Highlighting

• build-highlight-bundle.js - Syntax highlighting bundle creation
• build-inline-scripts.js - Inline script optimization

Usage: These are typically called through the main build pipeline or package.json scripts.

🚀 Quick Start Commands

# Complete production build
just leptos-build-nu

# Development with clean output
just dev-quiet-nu

# Deploy to production
nu scripts/build/deploy.nu deploy -e production --migrate

# Build all configuration examples
nu scripts/build/build-examples.nu --all

# Generate documentation
just docs-cargo-nu

# Create distribution package
just dist-pack-nu linux-x64

# Build localized content
nu scripts/build/build-localized-content.nu

# Clean development ports
nu scripts/build/kill-3030.nu

📁 File Organization

scripts/build/
├── README.md                    # This documentation
├── leptos-build.nu             # 🚀 Main production build
├── deploy.nu                   # 🚀 Deployment manager  
├── dist-pack.nu                # 📦 Distribution packaging
├── cross-build.nu              # 🔧 Cross-platform building
├── build-docker-cross.nu       # 🔧 Docker build environment
├── build-docs.nu               # 📚 Documentation generation
├── build-examples.nu           # 📚 Configuration examples
├── build-localized-content.nu  # 🌍 Content localization
├── dev-quiet.nu                # 🛠️  Development server
├── kill-3030.nu                # 🛠️  Port cleanup
└── [*.js files]                # 🎨 Asset build tools

🔄 Integration with Just

Most scripts are integrated with the project's justfile for convenient access:

just dev-quiet-nu              # Quiet development server
just docs-cargo-nu             # Build documentation  
just dist-pack-nu linux-x64    # Create distribution
just cross-build-nu            # Cross-platform build
just docker-cross-build-nu     # Build Docker image

🔧 Original Bash Scripts

Original bash scripts are preserved in scripts/sh/build/ for reference during the transition period. The Nushell versions provide enhanced error handling, structured data processing, and better cross-platform compatibility.