Argon Laravel Package

Getting Started

The Argon preset is a code generator, not a runtime library. It copies Argon Design System (Creative Tim) Blade views, SCSS, JS, and assets into a fresh Laravel 11+ application, replacing Laravel's default welcome/auth screens with a Bootstrap-based admin dashboard shell. The package itself can be a --dev dependency; after scaffolding, the generated files are yours.

Minimal path from zero to a running UI:

# 1. Start from a fresh Laravel 11+ app and commit the clean state
laravel new acme && cd acme
git add -A && git commit -m "clean laravel"

# 2. Install the preset (generator only)
composer require laravel-frontend-presets/argon --dev

# 3. Scaffold base layout/assets, then auth screens
php artisan ui argon
php artisan ui argon-auth

# 4. Build assets and run
npm install
npm run dev
php artisan migrate
php artisan serve

Then visit /login, /register, and the authenticated landing page the preset wired up (typically /home or /dashboard).

Look here first, in this order:

1. resources/views/layouts/ — the master layout: @yield('content'), @stack definitions, sidebar/navbar markup, and the @vite/asset includes.
2. resources/views/auth/ — login, register, forgot/reset password, verify email. This is where the Argon styling is most visible and most useful.
3. resources/views/home.blade.php (or dashboard.blade.php) — the reference page showing cards, headers, and stat blocks; copy its structure for your own pages.
4. resources/scss/ and resources/js/ — Argon entrypoints; cross-check these paths against the input array in vite.config.js.
5. routes/web.php and any generated auth routes — confirm how the preset expects authentication to be wired.

First real use case: stand up a styled login/register flow plus a dashboard shell in an afternoon, then progressively replace the demo dashboard cards with your own data. The preset is strongest as a starting skeleton for internal admin tools, back-office CRUD, and quick client demos — not as a long-lived design system you pull updates from.

Implementation Patterns

Extend the generated layout instead of duplicating it. Every new screen should inherit the preset's master layout so navbar/sidebar/asset wiring stays in one place:

{{-- resources/views/reports/index.blade.php --}}
@extends('layouts.app')

@section('title', 'Reports')

@section('content')
  <div class="header bg-primary pb-6">
    <div class="container-fluid">
      <h1 class="text-white">Reports</h1>
    </div>
  </div>

  <div class="container-fluid mt--6">
    <x-argon.card title="Monthly revenue">
      {{-- your table/chart --}}
    </x-argon.card>
  </div>
@endsection

@push('js')
  <script src="{{ asset('assets/js/reports.js') }}"></script>
@endpush

Keep @push('js') / @push('css') usage consistent with the stacks the layout defines; if the layout doesn't declare them, add them once rather than injecting scripts inline.

Wrap Argon markup in Blade components. The preset gives you raw Bootstrap/Argon classes, which get noisy fast. Extract the recurring widgets once:

// app/View/Components/ArgonCard.php
class ArgonCard extends Component
{
    public function __construct(public string $title = '', public string $class = '') {}

    public function render()
    {
        return view('components.argon-card');
    }
}

{{-- resources/views/components/argon-card.blade.php --}}
<div {{ $attributes->merge(['class' => "card {$class}"]) }}>
  @if ($title)
    <div class="card-header"><h3 class="mb-0">{{ $title }}</h3></div>
  @endif
  <div class="card-body">{{ $slot }}</div>
</div>

Do the same for stat tiles, page headers, and table wrappers. This is the single biggest lever for keeping Argon's class soup out of every view.

Drive the sidebar from config, not hardcoded markup. The generated navbar is static. Move it to a config array and render with active-state detection so adding a page is one line:

// config/navigation.php
return [
    ['label' => 'Dashboard', 'route' => 'dashboard', 'icon' => 'ni ni-tv-2'],
    ['label' => 'Reports',   'route' => 'reports.index', 'icon' => 'ni ni-chart-bar-32'],
];

@foreach (config('navigation') as $item)
  <li class="nav-item">
    <a class="nav-link {{ request()->routeIs($item['route']) ? 'active' : '' }}"
       href="{{ route($item['route']) }}">
      <i class="{{ $item['icon'] }}"></i> {{ $item['label'] }}
    </a>
  </li>
@endforeach

Leave authentication logic alone; only touch views. The preset styles the auth screens but does not replace Laravel's auth controllers, requests, or password broker. Customize resources/views/auth/*.blade.php (labels, layout, marketing copy) and keep LoginRequest, RegisteredUserController, etc. untouched. If you need profile management, teams, or 2FA, that's Breeze/Jetstream territory — do not install both.

Page-specific assets by entrypoint, not by CDN. Add new pages' SCSS/JS as inputs in vite.config.js and reference them with @vite in the layout or the page's stack. Avoid sprinkling <script src="/assets/..."> tags; it defeats cache-busting and makes production builds inconsistent.

Integration expectations: this preset is Blade-first. With Livewire, keep the Argon layout and mount Livewire components inside @section('content') — that works cleanly. With Inertia or a JS SPA, you'll be manually porting the layout into your root component; the preset does not help there.

Upgrade workflow: because the installer overwrites files, treat generated views as your code. If you want to pull a newer preset version, do it on a branch and git diff before merging. Keep customizations in new files/components where possible so a re-run is cheap to reconcile.

Gotchas and Tips

• It overwrites files. resources/views, routes/web.php, vite.config.js, and package.json are all candidates. Always scaffold on a clean commit, or git stash first. Running it on an app with existing views silently destroys work.

• Command names drift across versions. Older tutorials show php artisan preset argon (Laravel ≤6) or php artisan ui argon --auth. The current package uses separate ui argon and ui argon-auth commands. If either is "not defined," run php artisan package:discover, confirm the service provider is registered (Laravel 11: bootstrap/providers.php), and confirm laravel/ui is installed — these presets typically extend laravel/ui's command.

• Laravel 11 does not ship auth routes automatically. The argon-auth command provides styled views (and usually relies on laravel/ui for the controllers/routes). If /login 404s, you're missing the route/controller layer, not the styling. Install laravel/ui and run its auth scaffold, or wire the routes manually.

• Legacy front-end dependencies vs modern Node. Argon derives from a Bootstrap 4-era design system. If the generated package.json pins node-sass, old popper.js, or a jQuery plugin set, builds will fail on Node 18+. Swap node-sass for sass (dart-sass), keep [email protected] if the markup expects BS4 classes, and remove unused plugins. If the package ships precompiled CSS under public/assets, prefer that and skip the SCSS pipeline entirely.

• @vite vs mix mismatch. If styles 404 in the browser, inspect the layout's asset directive and the input array in vite.config.js. The copied SCSS/JS paths must match exactly; run npm run build and confirm the manifest contains them.

• Validation markup is version-sensitive. Argon form controls expect is-invalid / invalid-feedback (Bootstrap 4 conventions). Pair them with Laravel's @error and old() so failed submissions actually render red:

  <input name="email" value="{{ old('email') }}"
         class="form-control @error('email') is-invalid @enderror">
  @error('email') <div class="invalid-feedback">{{ $message }}</div> @enderror
  

• Demo asset bloat. The preset may copy charts, maps, datatables, and image sets you'll never use. Prune public/assets and unused JS imports before shipping; bundle size balloons otherwise.

• Re-running the installer wipes customizations. There is no reliable "merge" mode. If you need repeatable scaffolding across many projects, fork the package's stubs (or publish them, if a vendor:publish tag exists) and maintain your own template rather than editing each generated app.

• Pin the version. Preset behavior (commands, file layout, dependency versions) changes between releases, and the last release targets Laravel 11.x. Pin an exact version in composer.json and upgrade deliberately; don't assume Laravel 12 compatibility without testing.

• Deployment: since it's a --dev requirement, composer install --no-dev in CI won't restore generated files — they must be committed. Build assets in CI (npm ci && npm run build) or commit public/build.

• Licensing: the package is MIT, but the bundled Argon Design System assets come from Creative Tim under their own license (free tier typically requires attribution/backlink). Verify terms before redistributing a commercial product; strip branded demo pages and add your own attribution/footer as required.

• Debugging checklist when the UI looks broken: (1) npm run build succeeded and manifest exists, (2) layout uses the correct asset directive, (3) public/assets paths match what the views reference, (4) Bootstrap version matches the class names in the markup, (5) no leftover resources/css/app.css from the default Laravel install overriding Argon styles.