Build System and Tooling - seojedaperez/IgnisMap GitHub Wiki

Overview

IgnisMap uses a modern build system based on Vite with React and TypeScript, optimized for Progressive Web Application deployment. 1 The system supports multiple deployment targets including Netlify and includes comprehensive optimization strategies for Azure cloud integration.

Build Architecture

graph TB
    subgraph "Development Environment"
        Source["Source Code<br/>TypeScript + React"]
        Vite["Vite Dev Server<br/>Hot Module Replacement"]
        ESLint["ESLint + TypeScript<br/>Code Quality"]
    end
    
    subgraph "Build Pipeline"
        TypeScript["TypeScript Compiler<br/>tsc"]
        ViteBuild["Vite Build Process<br/>Rollup + Terser"]
        PWAPlugin["vite-plugin-pwa<br/>Service Worker Generation"]
        ChunkOptimization["Manual Chunk Splitting<br/>Vendor + Feature Chunks"]
    end
    
    subgraph "Output Artifacts"
        DistFolder["dist/ Directory"]
        StaticAssets["Static Assets<br/>Images, Icons, Fonts"]
        ServiceWorker["Service Worker<br/>Offline Capabilities"]
        Chunks["Optimized JS Chunks<br/>react-vendor, azure-vendor, etc."]
    end
    
    subgraph "Deployment Targets"
        Netlify["Netlify<br/>Static Hosting"]
        Azure["Azure Static Web Apps<br/>Cloud Integration"]
    end
    
    Source --> Vite
    Source --> ESLint
    TypeScript --> ViteBuild
    ViteBuild --> PWAPlugin
    ViteBuild --> ChunkOptimization
    
    PWAPlugin --> DistFolder
    ChunkOptimization --> Chunks
    Chunks --> DistFolder
    StaticAssets --> DistFolder
    ServiceWorker --> DistFolder
    
    DistFolder --> Netlify
    DistFolder --> Azure

Build Scripts and Commands

The build system provides several npm scripts for different development and deployment scenarios: 2

Development Commands

flowchart LR
    Dev["npm run dev"] --> ViteServer["Vite Dev Server<br/>Port 5173"]
    Preview["npm run preview"] --> PreviewServer["Production Preview<br/>Local Testing"]
    TypeCheck["npm run type-check"] --> TSC["TypeScript Compiler<br/>Type Validation Only"]
    Lint["npm run lint"] --> ESLintCheck["ESLint Analysis<br/>Code Quality Check"]

Production Build Commands

flowchart TD
    Build["npm run build"] --> TSCompile["tsc<br/>TypeScript Compilation"]
    TSCompile --> ViteBuild["vite build<br/>Production Bundle"]
    
    NetlifyBuild["npm run build:netlify"] --> Build
    
    AnalyzeBuild["npm run build:analyze"] --> Build
    AnalyzeBuild --> BundleAnalyzer["vite-bundle-analyzer<br/>Bundle Size Analysis"]
    
    Clean["npm run clean"] --> CleanDist["Remove dist/"]
    Clean --> CleanCache["Remove node_modules/.vite"]

Vite Configuration

The build system uses Vite with extensive optimization for the Azure-integrated PWA: 3

PWA Configuration

graph TB
    subgraph "PWA Features"
        Manifest["App Manifest<br/>IgnisMap PWA"]
        ServiceWorker["Service Worker<br/>Auto-Update Strategy"]
        OfflineCache["Offline Caching<br/>Critical Resources"]
    end
    
    subgraph "Cache Strategies"
        WeatherCache["Weather API Cache<br/>CacheFirst - 24h"]
        AzureMapsCache["Azure Maps Cache<br/>NetworkFirst - 2h"]
        StaticCache["Static Assets<br/>Long-term Caching"]
    end
    
    Manifest --> ServiceWorker
    ServiceWorker --> OfflineCache
    OfflineCache --> WeatherCache
    OfflineCache --> AzureMapsCache
    OfflineCache --> StaticCache

Build Optimization Strategy

The build system implements sophisticated chunk splitting for optimal loading performance: 4

graph TB
    subgraph "Vendor Chunks"
        ReactVendor["react-vendor<br/>React Core Libraries"]
        UIVendor["ui-vendor<br/>UI Components"]
        MapVendor["map-vendor<br/>Leaflet + Drawing Tools"]
        AzureVendor["azure-vendor<br/>Azure SDK Components"]
        ChartVendor["chart-vendor<br/>Recharts Visualization"]
        GeoVendor["geo-vendor<br/>Geospatial Libraries"]
    end
    
    subgraph "Feature Chunks"
        EmergencyServices["emergency-services<br/>Core Emergency Logic"]
        DataServices["data-services<br/>External API Integration"]
        TacticalComponents["tactical-components<br/>Tactical Planning UI"]
    end
    
    subgraph "Optimization Features"
        Terser["Terser Minification<br/>Console/Debugger Removal"]
        TreeShaking["Tree Shaking<br/>Dead Code Elimination"]
        CodeSplitting["Dynamic Imports<br/>Route-based Splitting"]
    end
    
    ReactVendor --> Terser
    EmergencyServices --> TreeShaking
    DataServices --> CodeSplitting

Deployment Configuration

Netlify Deployment

The system includes comprehensive Netlify configuration for static hosting: 5

graph TB
    subgraph "Netlify Build Process"
        BuildCommand["npm run build:netlify"]
        NodeEnv["Node.js 18<br/>Production Dependencies"]
        DistPublish["Publish dist/ Directory"]
    end
    
    subgraph "HTTP Headers & Security"
        CacheHeaders["Static Asset Caching<br/>31536000s (1 year)"]
        SecurityHeaders["Security Headers<br/>XSS, CSRF Protection"]
        CSP["Content Security Policy<br/>Azure Maps Integration"]
    end
    
    subgraph "Performance Optimizations"
        SPARedirects["SPA Routing<br/>/* → /index.html"]
        ResourcePreload["Critical Resource Preload<br/>react-vendor, CSS"]
        FontOptimization["Font Caching<br/>WOFF2 Optimization"]
    end
    
    BuildCommand --> DistPublish
    DistPublish --> CacheHeaders
    CacheHeaders --> SecurityHeaders
    SecurityHeaders --> CSP
    CSP --> SPARedirects
    SPARedirects --> ResourcePreload
    ResourcePreload --> FontOptimization

Development Dependencies

The build system relies on a comprehensive set of development tools: 6

TypeScript Toolchain

graph LR
    subgraph "TypeScript Stack"
        TSCompiler["typescript: ^5.2.2"]
        ReactTypes["@types/react<br/>@types/react-dom"]
        LeafletTypes["@types/leaflet<br/>@types/leaflet-draw"]
        Proj4Types["@types/proj4"]
    end
    
    subgraph "Linting & Quality"
        ESLint["@typescript-eslint/eslint-plugin"]
        Parser["@typescript-eslint/parser"]
        ViteReact["@vitejs/plugin-react"]
    end
    
    TSCompiler --> ReactTypes
    ReactTypes --> LeafletTypes
    ESLint --> Parser
    Parser --> ViteReact

Azure Integration Build Considerations

The build system is specifically optimized for Azure cloud services integration: 7

Azure SDK Bundle Optimization

graph TB
    subgraph "Azure Core Services"
        CoreAuth["@azure/core-auth<br/>Authentication"]
        Identity["@azure/identity<br/>Identity Management"]
        Cosmos["@azure/cosmos<br/>Database Operations"]
    end
    
    subgraph "Azure AI Services"
        TextAnalytics["@azure/ai-text-analytics<br/>Text Processing"]
        ComputerVision["@azure/cognitiveservices-computervision<br/>Image Analysis"]
        AnomalyDetector["@azure/ai-anomaly-detector<br/>Pattern Detection"]
    end
    
    subgraph "Azure Storage & Communication"
        StorageBlob["@azure/storage-blob<br/>File Storage"]
        KeyVault["@azure/keyvault-secrets<br/>Secret Management"]
        SignalR["@microsoft/signalr<br/>Real-time Communication"]
    end
    
    subgraph "Bundle Strategy"
        AzureVendorChunk["azure-vendor Chunk<br/>Core Azure Components"]
        LazyLoading["Lazy Loading<br/>AI Services on Demand"]
        TreeShaking["Tree Shaking<br/>Unused SDK Methods"]
    end
    
    CoreAuth --> AzureVendorChunk
    TextAnalytics --> LazyLoading
    StorageBlob --> TreeShaking

Performance Monitoring

The build system includes comprehensive performance monitoring and analysis tools:

Bundle Analysis

flowchart TD
    BuildAnalyze["npm run build:analyze"] --> ViteBuild["Production Build"]
    ViteBuild --> BundleAnalyzer["vite-bundle-analyzer"]
    BundleAnalyzer --> StatsHTML["dist/stats.html<br/>Bundle Visualization"]
    
    StatsHTML --> ChunkSizes["Chunk Size Analysis"]
    StatsHTML --> DependencyTree["Dependency Tree View"]
    StatsHTML --> OptimizationTips["Optimization Recommendations"]

Build Performance Metrics

The build system monitors and optimizes for:

Chunk Size Warning Limit: 1000KB per chunk 8
Tree Shaking: Automatic dead code elimination
Minification: Terser with console/debugger removal 9
Cache Optimization: Long-term caching for static assets

Notes

The build system is specifically designed for emergency response applications with Azure cloud integration. The configuration prioritizes offline capabilities, security headers, and optimized loading for critical emergency services. The chunk splitting strategy separates Azure services, mapping components, and emergency-specific logic for optimal performance in field operations.