Adminlte Laravel Package

Getting Started

Minimal Setup for Laravel

1. Install the package:

   composer require colorlibhq/adminlte-laravel
   

   Publish assets and config:

   php artisan vendor:publish --provider="ColorlibHQ\AdminLTE\AdminLTEServiceProvider" --tag="adminlte-assets"
   php artisan vendor:publish --provider="ColorlibHQ\AdminLTE\AdminLTEServiceProvider" --tag="adminlte-config"
   

   On AdminLTE v4.10.1: the underlying theme ships CSS/JS fixes (Responsive/tablet header overflow, fullscreen icon sync, table semantics/labels, light–dark contrast). Re-run the adminlte-assets publish (with --force) whenever you bump the frontend version, otherwise you keep serving stale dist/ files and none of the fixes land.

2. Add AdminLTE to your layout: Include the published blade file in your resources/views/layouts/app.blade.php:

   @extends('adminlte::page')
   

3. First use case: Create a simple dashboard page at resources/views/dashboard.blade.php:

   @extends('adminlte::page')
   @section('title', 'Dashboard')
   @section('content_header')
       <h1>Dashboard</h1>
   @stop
   @section('content')
       <p>Welcome to your AdminLTE dashboard!</p>
   @stop
   

Key Files to Review

• config/adminlte.php: Customize theme, layout, and menu.
• resources/views/vendor/adminlte/: Published blade templates (modify as needed).
• Official Laravel Edition Docs and the AdminLTE v4.10.1 changelog for frontend-side fixes you inherit.

Runtime Requirements

• Consumers of the compiled package: Node.js >= 20 (unchanged in v4.10.1), npm 10+.
• Only if you build AdminLTE from source: Node.js 22.22.3+, 24.16.0+, or 26.3.0+ (declared via devEngines) and npm 10+. This does not affect composer required assets.

Implementation Patterns

1. Dynamic Menu Generation

Leverage the config-driven menu system to build navigation dynamically:

// config/adminlte.php
'menu' => [
    [
        'text' => 'Dashboard',
        'url'  => '/dashboard',
        'icon' => 'fas fa-tachometer-alt',
    ],
    [
        'text' => 'Users',
        'url'  => '/users',
        'icon' => 'fas fa-users',
        'submenu' => [
            ['text' => 'List', 'url' => '/users/list'],
            ['text' => 'Create', 'url' => '/users/create'],
        ],
    ],
],

Usage in Blade:

@include('adminlte::menu')

2. Theme Customization

Override default colors/skins via config:

// config/adminlte.php
'skin' => 'blue', // Options: 'blue', 'black', 'purple', 'yellow', 'red', 'green', 'teal', 'orange'
'sidebar_mini' => true, // Collapse sidebar by default

3. Layout Components

Use built-in sections:

@extends('adminlte::page')

@section('title', 'Page Title')
@section('content_header')
    <h1>Header Content</h1>
    <small>Subheader text</small>
@stop

@section('content')
    <!-- Main content -->
@stop

@section('css')
    <link rel="stylesheet" href="/css/custom.css">
@stop

@section('js')
    <script src="/js/custom.js"></script>
@stop

4. Authentication Scaffolding

Generate auth views with:

php artisan adminlte:auth

This creates:

• Login/Register/ResetPassword pages
• Middleware for guest routes
• Blade templates in resources/views/auth/.

5. Widgets and UI Elements

Include pre-built widgets:

<div class="row">
    <div class="col-12 col-sm-6 col-md-3">
        @include('adminlte::widget_box', [
            'title' => 'Quick Example',
            'icon' => 'fa fa-file-code-o',
            'content' => 'Create an amazing page',
        ])
    </div>
</div>

6. Accessible Tables and Cards (v4.10.x)

The 4.10.1 release specifically tightened table filter labels/grid semantics and isolated fullscreen toggles from card-maximize controls. Wrap tabular widgets accordingly so you inherit the fixes rather than overriding them:

<div class="card">
    <div class="card-header">
        <h3 class="card-title">Users</h3>
        <div class="card-tools">
            <label class="visually-hidden" for="user-filter">Filter users</label>
            <input id="user-filter" type="search" class="form-control form-control-sm" placeholder="Filter">
        </div>
    </div>
    <div class="card-body table-responsive p-0">
        <table class="table table-hover" role="grid" aria-label="Users">
            {{-- ... --}}
        </table>
    </div>
</div>

7. Asset Pipeline (Vite or Mix)

Laravel 11/12 apps default to Vite; Mix still works. Either way, compile your custom CSS/JS around AdminLTE rather than recompiling its dist/:

// webpack.mix.js (Mix apps)
mix.js('resources/js/app.js', 'public/js')
   .sass('resources/scss/app.scss', 'public/css')
   .copy('node_modules/admin-lte/dist', 'public/admin-lte');

// vite.config.js (Vite apps) — copy the prebuilt dist, don't re-bundle it
import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [laravel({ input: ['resources/css/app.css', 'resources/js/app.js'] })],
});

8. Third-Party Demo Integrations

AdminLTE's demo pages wire in CDN libraries. In 4.10.1 these were refreshed: FullCalendar migrated to 7.1.1, jsVectorMap asset paths corrected, and integrity hashes rotated. If you copied those demo snippets into your app, treat this release as the reference implementation and re-copy rather than hand-patching.

Gotchas and Tips

Pitfalls

1. Asset Paths:

   • After publishing assets, ensure paths in public/admin-lte are correct.
   • If using Laravel Mix/Vite, exclude AdminLTE's dist/ from compilation to avoid duplication.

2. Stale Assets After Upgrading (v4.10.x):

   • composer update alone does not refresh published assets. Run:

     php artisan vendor:publish --provider="ColorlibHQ\AdminLTE\AdminLTEServiceProvider" --tag="adminlte-assets" --force
     php artisan view:clear
     

   • Symptom of skipping this: fullscreen icons desync from card-maximize buttons, tablet headers overflow, dark-mode contrast still wrong — all fixed upstream in 4.10.1 but invisible until dist/ is refreshed.

3. CDN + SRI Hashes:

   • 4.10.1 rotated integrity hashes for the demo/integration CDN libraries. If you pinned AdminLTE or plugin assets via integrity="...", the browser silently blocks the file on mismatch (blank styles, dead widgets). Update the hashes or drop SRI in favour of a local build.

4. FullCalendar 7 Migration:

   • The demos moved from FullCalendar 6.x to 7.1.1, a major version. If you reused the calendar demo, expect breaking changes in plugin imports, event-source signatures, and CSS injection. Migrate deliberately; don't assume a drop-in swap.

5. jsVectorMap Paths:

   • Asset paths were corrected in 4.10.1. Old hardcoded /plugins/jvectormap/... references will 404. Point at the packaged path (node_modules/jsvectormap/dist/...) instead.

6. Bootstrap 5 Migration:

   • AdminLTE v4 uses Bootstrap 5. Update your custom CSS/JS to use BS5 classes (e.g., data-bs-toggle instead of data-toggle).
   • Common issues:
     • .modal classes may need adjustments (e.g., .modal-dialog sizing).
     • Custom dropdowns may break; use data-bs-toggle="dropdown".

7. Dark Mode:

   • Enable via config:

     'dark_mode' => true,
     

   • Or dynamically with JavaScript:

     document.body.setAttribute('data-bs-theme', 'dark');
     

   • Light/dark contrast was explicitly fixed in 4.10.1; re-test any custom overrides against both themes.

8. Sidebar Collapse:

   • Use data-lte-toggle="sidebar" for manual toggling:

     <button class="btn" data-lte-toggle="sidebar">
         <i class="fas fa-bars"></i>
     </button>
     

Debugging Tips

1. Clear Published Assets: If changes to resources/views/vendor/adminlte/ don't reflect, clear compiled views:

   php artisan view:clear
   

2. Check Config Overrides: Ensure no cached config is overriding your adminlte.php settings:

   php artisan config:clear
   

3. JavaScript Conflicts: AdminLTE uses vanilla JS. If plugins fail:

   • Verify no jQuery dependencies are loaded.
   • Check browser console for errors (e.g., missing adminlte.min.js).
   • After the 4.10.1 fullscreen-isolation fix, third-party code that bound click handlers to .card-tools .btn may now fire on the fullscreen button only — re-scope selectors to .card-maximize.

4. RTL Support: Enable in config:

   'rtl' => true,
   

   Ensure your app's locale is RTL-compatible (e.g., app.php in Laravel).

5. Build vs. Consume Confusion: If npm ci fails with an engine error, you're on a source-build path (AdminLTE repo checkout / devEngines) — it needs Node 22.22.3+/24.16.0+/26.3.0+. Plain package consumers only need Node >= 20.

6. npm audit Noise: 4.10.1 documents 20 high-severity findings inherited from the unpatched braces advisory. These live in dev-only tooling and are not in the published runtime dependency tree. Don't chase them in an app audit; they're upstream-blocked.

Extension Points

1. Custom Blade Directives: Extend AdminLTE's directives in AppServiceProvider:

   Blade::directive('adminlteBox', function ($expression) {
       return "<?php echo \\ColorlibHQ\\AdminLTE\\Widgets::box($expression); ?>";
   });
   

2. Override Widgets: Copy resources/views/vendor/adminlte/widgets/ to your project and modify.

3. Add Custom Plugins: Include third-party plugins in resources/views/layouts/app.blade.php:

   @section('extra_css')
       <link rel="stylesheet" href="https://cdn.datatables.net/1.11.5/css/dataTables.bootstrap5.min.css">
   @stop
   
   @section('extra_js')
       <script src="https://cdn.datatables.net/1.11.5/js/jquery.dataTables.min.js"></script>
       <script src="https://cdn.datatables.net/1.11.5/js/dataTables.bootstrap5.min.js"></script>
   @stop
   

4. Dynamic Theming: Change themes via JavaScript:

   function setTheme(theme) {
       document.body.setAttribute('data-bs-theme', theme);
       localStorage.setItem('adminlte-theme', theme);
   }
   

Performance Quirks

• Avoid Inlining Assets: Use Laravel Mix or Vite to bundle AdminLTE with your app.
• Lazy-Load Pages: For large apps, lazy-load non-critical JS:

  <script src="/admin-lte/dist/js/adminlte.min.js" defer></script>
  

• Critical CSS: Extract critical CSS for the dashboard to reduce render-blocking.
• Bundle Budgets: 4.10.1 enforces 15 bundle-size budgets and gzip limits upstream. If you fork or patch the dist bundle, measure before shipping — the fixes are cheap, but adding plugins is not.

Laravel-Specific Tips

1. Route Caching: After adding menu items, regenerate routes:

   php artisan route:clear
   

2. Middleware: Protect admin routes with admin middleware (included by default):

   Route::middleware(['auth', 'admin'])->group(function () {
       // Admin routes
   });
   

3. Localization: AdminLTE supports Laravel's localization. Override translations in resources/lang/.

4. Testing: Use adminlte::page in feature tests:

   $response = $this->actingAs($user)->get('/dashboard');
   $response->assertSee('Dashboard');
   

5. Upgrading to 4.10.1 Safely: There are no public component API changes and no Composer/PHP version bumps in this release, so a patch bump is low-risk. The upgrade checklist is: clear adminlte-assets cache via re-publish, rotate any SRI hashes, re-verify FullCalendar 7 and jsVectorMap usages, then re-run your own contrast/responsive smoke tests if you maintain dark-mode overrides.