jinql
/
gentelella
mirror of https://github.com/ColorlibHQ/gentelella
1
0
Fork 0
Code Issues Releases Wiki Activity
gentelella/BOOTSTRAP5_UPGRADE_PLAN.md

5.9 KiB
Raw Blame History

Bootstrap 5 Modernization Plan 🚀

Project Overview

Upgrade Gentelella Admin Template from Bootstrap 4.6.2 to Bootstrap 5.3.6 with modern dependencies while maintaining functionality and layout.

Phase 1: Dependency Analysis & Planning ✅ COMPLETE

Current Dependencies Status

Package Current Target Breaking Changes
bootstrap 4.6.2 5.3.6 MAJOR - jQuery removal, class renames
chart.js 2.9.4 4.4.2 MAJOR - API changes, new options structure
jquery 3.6.1 REMOVE Bootstrap 5 no longer needs jQuery
font-awesome 4.7.0 6.6.0 MINOR - new icons, class structure
jquery-ui 1.14.1 KEEP Still needed for some widgets
datatables.net 2.3.2 2.x.x Update to latest
moment 2.30.1 dayjs Replace with modern alternative

Phase 2: Bootstrap 5 Core Migration

2.1 Bootstrap Installation & Configuration

  • Update Bootstrap to 5.3.6
  • Remove jQuery dependency from Bootstrap components
  • Update Popper.js to v2.x (required by Bootstrap 5)
  • Configure Bootstrap 5 with custom Sass variables

2.2 CSS Class Migration

Bootstrap 5 class changes to apply:

  • .ml-*, .mr-* → .ms-*, .me-* (margin start/end)
  • .pl-*, .pr-* → .ps-*, .pe-* (padding start/end)
  • .text-left, .text-right → .text-start, .text-end
  • .float-left, .float-right → .float-start, .float-end
  • .badge-* → .bg-* for background colors
  • .btn-block → .d-grid wrapper
  • .form-group → remove (use margins/utilities)
  • .form-control-file → .form-control
  • .custom-select → .form-select
  • .no-gutters → .g-0

2.3 Component Updates

  • Cards: Update .card-deck → CSS Grid layout
  • Forms: Migrate to new form structure
  • Navbars: Add required container structure
  • Dropdowns: Update data attributes data-toggle → data-bs-toggle
  • Modals: Update data attributes and remove jQuery dependency
  • Tooltips/Popovers: Update to Bootstrap 5 JS API

2.4 Data Attribute Migration

  • data-toggle → data-bs-toggle
  • data-target → data-bs-target
  • data-dismiss → data-bs-dismiss
  • data-slide → data-bs-slide
  • data-parent → data-bs-parent

Phase 3: JavaScript Modernization

3.1 Bootstrap JS Migration

  • Remove jQuery dependencies from Bootstrap components
  • Update Bootstrap component initialization
  • Migrate event listeners to vanilla JS
  • Update component APIs (Modal, Dropdown, etc.)

3.2 Chart.js v4 Migration

  • Update Chart.js to 4.4.2
  • Migrate chart configurations:
    • scales.yAxes → scales.y
    • scales.xAxes → scales.x
    • Update responsive options
    • Update legend configuration
    • Update tooltip configuration

3.3 Widget Library Updates

  • jQuery UI: Keep for progressbar, maintain compatibility
  • DataTables: Update to latest compatible version
  • Gauge.js: Fix loading issues, ensure compatibility
  • jqVMap: Test compatibility or find alternative
  • Bootstrap-progressbar: Find Bootstrap 5 compatible version

3.4 Custom JavaScript Refactoring

  • Update src/js/sidebar.js for Bootstrap 5 navbar
  • Update src/js/init.js for new component initialization
  • Replace jQuery utilities with vanilla JS where possible
  • Maintain jQuery for specific widgets that require it

Phase 4: Modern Dependencies

4.1 Package Updates

  • Font Awesome 4.7.0 → 6.6.0
  • Moment.js → Day.js (smaller, modern)
  • Update all vendor CSS/JS to latest versions
  • Remove deprecated packages

4.2 Build System Optimization

  • Optimize Vite configuration for Bootstrap 5
  • Update CSS preprocessing for Bootstrap 5 Sass structure
  • Configure proper tree-shaking for reduced bundle size
  • Add CSS/JS minification for production

Phase 5: Testing & Quality Assurance

5.1 Visual Testing

  • Dashboard layout consistency
  • All widget functionality
  • Responsive design across breakpoints
  • Dark mode compatibility (if implementing)

5.2 Functionality Testing

  • All charts rendering correctly
  • Forms validation working
  • Modal/dropdown interactions
  • Data table operations
  • Navigation and sidebar

5.3 Performance Testing

  • Bundle size optimization
  • Loading speed improvements
  • Memory usage validation

Phase 6: Outstanding Issues Resolution

6.1 Current TODOs

  • Fix gauge.js loading ✅ COMPLETED
  • Investigate broken map.html page
  • Add proper error handling for widget failures
  • Implement fallbacks for failed library loads

6.2 New Modern Features

  • Add CSS custom properties for easy theming
  • Implement CSS Grid layouts where appropriate
  • Add accessibility improvements (ARIA labels, focus management)
  • Consider adding dark mode support
  • Add PWA capabilities (optional)

Implementation Timeline

Week 1: Core Bootstrap Migration

  • Days 1-2: Install Bootstrap 5, update basic layouts
  • Days 3-4: CSS class migration across all HTML files
  • Days 5-7: Component structure updates

Week 2: JavaScript & Charts

  • Days 1-3: Bootstrap JS component migration
  • Days 4-5: Chart.js v4 migration
  • Days 6-7: Widget library updates

Week 3: Testing & Polish

  • Days 1-3: Comprehensive testing
  • Days 4-5: Bug fixes and optimizations
  • Days 6-7: Documentation and cleanup

Success Metrics

  • ✅ Zero console errors
  • ✅ All widgets functional
  • ✅ Responsive design maintained
  • ✅ Loading speed improved by 20%+
  • ✅ Bundle size optimized
  • ✅ Future-proof dependencies

Risk Mitigation

  • Create feature branch for each phase
  • Maintain backup of working version
  • Test individual components before integration
  • Document all custom modifications
  • Plan rollback strategy for critical issues

Next Steps: Begin Phase 2 with Bootstrap 5 installation and basic CSS migration.