Material Dashboard Laravel Package

Getting Started

1. Install the package

   composer require laravel-frontend-presets/material-dashboard
   

   The package ships a service provider that registers an Artisan preset command (in the laravel-frontend-presets family this is usually php artisan ui material-dashboard). Confirm the exact command name against the README before running it — this package targets Laravel 11+, which no longer ships the old preset command, so all scaffolding is driven by the package's own command.

2. Scaffold the frontend

   php artisan ui material-dashboard
   # optionally scaffold auth views too
   php artisan ui material-dashboard --auth
   

   This publishes Blade layouts, a dashboard view, auth views (if requested), and the Material Dashboard CSS/JS assets. Run this on a clean branch — the preset will overwrite resources/views/layouts/, resources/views/auth/, resources/css/, resources/js/, and possibly routes/web.php.

3. Install frontend dependencies and build

   npm install
   npm run dev   # or npm run build for production
   

4. Where to look first

   • resources/views/layouts/ — the master layout with sidebar, navbar, and content slot.
   • resources/views/dashboard.blade.php (or equivalent) — the reference page demonstrating cards, tables, and chart widgets.
   • resources/views/auth/ — login/register/password-reset views if you used --auth.
   • The package's src/ directory (in vendor/laravel-frontend-presets/material-dashboard/) — the preset command code and stub paths tell you exactly which files get copied and where.

5. First use case: point an authenticated route at the dashboard view and use the layout as the shell for an admin area:

   Route::get('/dashboard', fn () => view('dashboard'))
       ->middleware(['auth'])->name('dashboard');
   

Implementation Patterns

Extend the provided layout, don't rebuild it. The preset's value is the layout shell (sidebar, topbar, footer, asset includes). New pages should inherit it:

@extends('layouts.app')

@section('content')
    <div class="row">
        <div class="col-md-4">
            @include('partials.stat-card', ['title' => 'Users', 'value' => $userCount])
        </div>
    </div>
@endsection

If the layout uses named sections (@yield('content'), @yield('title'), @stack('scripts')), match those names exactly — they're defined in the published layout, not in Laravel core.

Keep the preset's partials as reference components. Most Material Dashboard presets ship reusable card/table/chart snippets. Copy one into a Blade partial (resources/views/partials/) and pass data in via @include or a Blade component rather than duplicating markup per page.

Sidebar navigation is usually hand-maintained. The sidebar links typically live in the layout or a sidebar.blade.php. Centralize the menu as an array so you can mark the active item:

@php
$menu = [
    ['route' => 'dashboard', 'icon' => 'dashboard', 'label' => 'Dashboard'],
    ['route' => 'users.index', 'icon' => 'person', 'label' => 'Users'],
];
@endphp
@foreach ($menu as $item)
    <li class="nav-item {{ request()->routeIs($item['route']) ? 'active' : '' }}">
        <a class="nav-link" href="{{ route($item['route']) }}">
            <i class="material-icons">{{ $item['icon'] }}</i>
            <p>{{ $item['label'] }}</p>
        </a>
    </li>
@endforeach

Integrate, don't replace, your auth stack. Laravel 11 apps commonly use Breeze or Jetstream. Two viable patterns:

• Full preset auth: use --auth and let the preset own resources/views/auth/* and the login route. Remove or disable Breeze's auth views to avoid duplicate/conflicting layouts.
• Preset shell only: keep Breeze for auth flow and apply the Material layout to the authenticated area. You'll need to bridge Breeze's Blade components (or replace them) with the preset's markup.

Pick one early — mixing both layouts on the same route produces a confusing double-navbar result.

Wire data at the controller, keep the view dumb. Dashboard cards and tables should receive data from a controller or view composer, not query inside Blade:

public function index()
{
    return view('dashboard', [
        'stats'   => $this->statsService->summary(),
        'recent'  => User::latest()->take(5)->get(),
    ]);
}

Use the preset's chart/table markup as a template for your own widgets. Chart widgets usually expect a <canvas> plus a small init script; keep those scripts in @push('scripts') so they load only on pages that need them.

Version-control the scaffold as a single commit. After running the preset command, commit the generated files before customizing. This makes it trivial to see exactly what the preset changed and to revert if you later swap to Breeze/Tailwind.

Gotchas and Tips

• Laravel 11+ has no built-in preset or ui command. If php artisan ui ... fails with "command not found," the package's service provider wasn't auto-discovered (check bootstrap/providers.php in Laravel 11) or the command name differs. Run php artisan list and grep for the preset command.
• The preset overwrites files silently. Commit a clean state first. Files at risk: resources/views/layouts/*, resources/views/auth/*, resources/css/app.css, resources/js/app.js, routes/web.php, vite.config.js. Diff after running.
• Vite vs Mix mismatch is the #1 breakage. Newer releases of this package target Vite (Laravel 11 default); older Material Dashboard templates assume Laravel Mix. If npm run dev produces no styles, check whether the preset modified vite.config.js to include the Material CSS/JS entry points, or whether it dropped compiled assets into public/assets/ that you should reference via asset().
• Asset paths are often absolute. Material Dashboard themes hardcode paths like /assets/css/material-dashboard.css or use a {{ asset('...') }} wrapper. In subdirectory deployments, search-and-replace these paths or centralize them in a config value.
• Bootstrap/jQuery version drift. Material Dashboard templates are typically Bootstrap 4-based with jQuery for the sidebar toggle and chart initializers. Don't mix Bootstrap 5 utilities into these views — classes like ml-3 vs ms-3, float-left vs float-start will silently no-op.
• @stack('scripts') is easy to miss. Chart widget snippets often rely on a stack defined at the bottom of the layout. If your chart doesn't render, confirm the layout includes @stack('scripts') and that your page uses @push('scripts') (not @section).
• Clearing caches after publishing. If new views aren't picked up: php artisan view:clear && php artisan route:clear && php artisan config:clear.
• Rollback is manual. There's no preset:uninstall. Keep a clean commit or a fresh branch per attempt; restoring the prior frontend means git checkout of the affected paths and re-running npm install.
• Extension points: the preset command's stub files (in vendor/laravel-frontend-presets/material-dashboard/src/) can be published/overridden if the package exposes a vendor:publish tag. Check php artisan vendor:publish --provider="..." — overriding stubs is cleaner than patching published output if you'll re-run the preset on multiple apps.
• Zero dependents and a 2024-11 release date mean this is a low-traffic package. Read the preset command source before running it in a production codebase, and pin the version in composer.json so a future update doesn't rewrite your routes/web.php mid-sprint.
• Auth scaffolding may assume its own controllers/routes. If --auth was used and your app already has Auth\LoginController or Breeze's AuthenticatedSessionController, resolve the conflict before running — otherwise you'll get duplicate route definitions for login/register.