Skip to main content

Frontend Assets and Build System

Overview​

The www application uses a modern frontend build system with SASS, JavaScript bundling, and asset optimization for optimal performance and maintainability.

Asset Architecture​

Directory Structure​

src/assets/
├── sass/                 # SASS/SCSS stylesheets
│   ├── theme/           # Bootstrap theme customization
│   ├── custom/          # Custom component styles
│   ├── print.scss       # Print-specific styles
│   └── public.scss      # Main stylesheet entry point
└── scripts/             # JavaScript source files
    ├── app/             # Application-specific scripts
    ├── theme/           # Theme-related JavaScript
    └── utils.js         # Utility functions

Compiled Assets​

src/public/
├── css/                 # Compiled stylesheets
│   ├── public.css       # Main compiled CSS
│   ├── print.css        # Print stylesheet
│   └── chatbot.css      # Chatbot-specific styles
├── js/                  # Compiled JavaScript
│   ├── theme.js         # Theme functionality
│   ├── utils.js         # Utility functions
│   └── vendor/          # Third-party libraries
├── fonts/               # Web fonts
├── img/                 # Images and graphics
└── ico/                 # Icons and favicons

SASS/CSS Architecture​

Theme System​

Based on Bootstrap 5.1.3 with extensive customizations:

1. Variables Layer (theme/1-variables/)​

  • App Variables (_app.scss): Application-specific variables
  • Dark Theme (_dark.scss): Dark mode color scheme
  • Fonts (_fonts.scss): Typography definitions

2. Mixins Layer (theme/2-mixins/)​

  • Background Mixins: Background utilities
  • Button Mixins: Button style variations
  • Modal Mixins: Modal component styles
  • Theme Mixins: Theme switching utilities

3. Components Layer (theme/3-components/)​

Comprehensive component library:

  • Navigation components (navbar, sidebar)
  • Form components and validation
  • Cards, modals, and layouts
  • Charts and data visualization
  • Custom UI elements

4. Utilities Layer (theme/4-utilities/)​

  • Background utilities
  • Border and spacing utilities
  • Typography utilities
  • Position and z-index management

Custom Styles (custom/)​

  • Chatbot Styles (_chatbot.scss): AI chatbot interface
  • Print Styles (_print.scss): Print-specific layouts
  • Index Styles (_index.scss): Custom component styles

Responsive Design​

  • Mobile-first approach
  • Bootstrap breakpoint system
  • Custom responsive utilities
  • Touch-friendly interface elements

JavaScript Architecture​

Application Scripts (scripts/app/)​

Account Management​

Comprehensive account functionality:

  • Profile Management: User profile editing and updates
  • Logbook System: Flight logging with validation
  • Dashboard: User dashboard with data visualization
  • Safety Training: Interactive training modules
  • Payment Processing: Fee management and checkout

Authentication​

  • Login/Registration: User authentication forms
  • Verification: Email and SMS verification
  • Silent Login: Background authentication
  • OAuth Integration: Google OAuth handling

Public Features​

  • Chatbot: AI-powered assistance
  • Contact Forms: Contact and inquiry forms
  • Tunnel Directory: Tunnel search and filtering

Theme Scripts (scripts/theme/)​

  • Bootstrap Integration: Bootstrap component initialization
  • Sidebar Management: Navigation sidebar functionality
  • Theme Switching: Light/dark mode toggle
  • Vector Maps: Interactive map components
  • Feather Icons: Icon management

Utility Scripts​

  • Common Utilities: Shared helper functions
  • Form Validation: Client-side form validation
  • API Helpers: AJAX request utilities
  • Local Storage: Browser storage management

Build System​

Build Tools​

  • ESBuild: Fast JavaScript bundling
  • SASS: CSS preprocessing with Dart Sass
  • Terser: JavaScript minification
  • PostCSS: CSS post-processing
  • Autoprefixer: Vendor prefix automation

Build Scripts​

Development Build​

npm run dev      # Start development server with hot reload
npm run watch    # Watch for file changes
npm run debug    # Start with debugging enabled

Production Build​

npm run build    # Build optimized assets
npm run sass:build    # Compile SASS only
npm run scripts:build # Bundle JavaScript only

Build Configuration​

SASS Compilation​

// Automated SASS compilation with:
// - Autoprefixer for vendor prefixes
// - Source maps for debugging
// - Minification for production
// - Watch mode for development

JavaScript Bundling​

// ESBuild configuration:
// - Tree shaking for smaller bundles
// - Module resolution
// - Transpilation for browser compatibility
// - Source maps for debugging

Asset Optimization​

Performance Features​

  • Code Splitting: Separate bundles for different sections
  • Lazy Loading: On-demand asset loading
  • Compression: Gzip compression for static assets
  • Caching: Browser cache optimization

Image Optimization​

  • Multiple Formats: WebP, PNG, JPG support
  • Responsive Images: Multiple sizes for different devices
  • Icon Fonts: Font Awesome and Feather icons
  • SVG Optimization: Compressed vector graphics

Font Management​

  • Web Fonts: Custom font loading
  • Font Display: Optimized font rendering
  • Font Subsetting: Reduced font file sizes
  • Fallback Fonts: System font fallbacks

Development Workflow​

Local Development​

  1. Install dependencies: npm install
  2. Start development server: npm run dev
  3. Edit SASS/JS files in src/assets/
  4. Watch automatic compilation and reload

Asset Pipeline​

SASS Source → Compilation → Autoprefixer → Minification → public/css/
JS Source → Bundling → Transpilation → Minification → public/js/

Hot Reload​

  • Automatic browser refresh on file changes
  • SASS compilation on save
  • JavaScript bundling on save
  • EJS template reloading

Third-Party Libraries​

CSS Frameworks​

  • Bootstrap 5.1.3: UI framework foundation
  • Font Awesome: Icon library
  • Feather Icons: Lightweight icon set

JavaScript Libraries​

  • jQuery: DOM manipulation (legacy components)
  • Chart.js: Data visualization
  • Vector Maps: Interactive mapping
  • SimpleMar: Custom scrollbars

Development Tools​

  • Nodemon: Development server with auto-restart
  • Prettier: Code formatting
  • ESLint: JavaScript linting

Browser Support​

Target Browsers​

  • Chrome 90+
  • Firefox 88+
  • Safari 14+
  • Edge 90+

Progressive Enhancement​

  • Core functionality works without JavaScript
  • Enhanced features for modern browsers
  • Graceful degradation for older browsers
  • Accessibility-first approach

Performance Metrics​

Asset Sizes (Production)​

  • CSS Bundle: ~150KB compressed
  • JavaScript Bundle: ~200KB compressed
  • Total Asset Size: ~2MB (including images and fonts)

Loading Performance​

  • First Contentful Paint: <2s
  • Largest Contentful Paint: <3s
  • Cumulative Layout Shift: <0.1