Blade Forkawesome Laravel Package

Getting Started

Install with a single Composer command — Laravel's package auto-discovery handles the service provider registration:

composer require codeat3/blade-forkawesome

No config file, no publishing step, no .env change, and no bundler configuration is required. Icons live in vendor/codeat3/blade-forkawesome/resources/svg/ and are auto-registered as Blade components with the forkawesome prefix. Render your first icon immediately:

<x-forkawesome-github class="w-4 h-4 text-gray-500" />

Where to look first:

1. vendor/codeat3/blade-forkawesome/resources/svg/ — the canonical list of every available icon name. Component names derive from these filenames (git-branch.svg → <x-forkawesome-git-branch />). Do not guess from Font Awesome class names; Fork Awesome has divergences.
2. composer.json of the package — check the blade-ui-kit/blade-icons constraint, since that transitive dependency is what actually makes the components work and gates your Laravel version support.
3. The package is a thin wrapper over blade-ui-kit/blade-icons; for anything beyond rendering, consult that library's docs (caching, sprite mode, Svg facade).

First realistic use case: drop a handful of icons into an existing navigation, empty state, or settings page to confirm the install works end-to-end, then run php artisan icons:cache in a staging deploy before rolling out to prod. If you have more than a few icon consumers, add a thin local wrapper (<x-icon name="github" />) before you spread the raw component tags around — see the next section.

Implementation Patterns

Direct usage inside Blade views. The natural pattern for one-off icons; icons inherit class, width, height, and color from the rendered SVG, so styling is just Tailwind/CSS on the tag:

<x-forkawesome-bell class="h-5 w-5" />
<span class="sr-only">Notifications</span>

Wrapper abstraction (strongly recommended). Since the package is a thin shell around blade-icons, sibling packages (blade-heroicons, blade-tabler, blade-bootstrap-icons) share the same component shape. A one-file wrapper isolates you from an icon-set swap and centralizes fallbacks:

{{-- resources/views/components/icon.blade.php --}}
@props(['name', 'class' => 'w-4 h-4'])
@php
    $component = "forkawesome-{$name}";
@endphp
<x-dynamic-component :component="$component" {{ $attributes->merge(['class' => $class]) }} />

Then call sites are <x-icon name="github" /> and the migration to Heroicons is a single edit.

Bundling a common icon set once. For admin dashboards and nav bars, keep an icon map in a helper or config so designers and engineers share vocabulary instead of guessing names in views:

// config/icons.php
return ['nav' => ['home' => 'home', 'users' => 'users', 'settings' => 'cog']];

Livewire / Inertia-with-Blade layouts. The components are plain Blade, so they work anywhere Blade renders. In Livewire, remember that re-rendered fragments re-execute the component — fine for static SVGs, but avoid passing dynamic user input directly into name without validation (see gotchas).

Sprite / definitions mode for icon-heavy pages. blade-icons supports SVG sprite output. If you have pages rendering dozens of icons (data tables, kanban cards, dashboards), the response-size tax of inline SVG adds up quickly. Configure blade-icons sprite mode or emit <use> references to a cached sprite so the browser downloads each glyph once. This is the single biggest lever for icon-dense apps.

Deploy-time caching. blade-icons scans the SVG directory to build the component registry. In production, bake this once per deploy:

php artisan icons:cache     # post-deploy / release hook
php artisan icons:clear     # rollback hook or before composer updates

Skipping icons:cache is fine in dev (discovery is cheap), but on a large icon set it's a measurable boot cost and — more importantly — caching means your prod set is deterministic per deploy.

Testing your icon inventory. Because every icon is a component name known at build time, you can render every icon in a test to guarantee no SvgNotFound reaches production:

public function test_all_icons_render(): void
{
    $files = glob(base_path('vendor/codeat3/blade-forkawesome/resources/svg/*.svg'));
    foreach ($files as $f) {
        $name = basename($f, '.svg');
        $this->view('components.icon', ['name' => $name])->assertSee('<svg');
    }
}

That test pays for itself the first time an upstream rename or a typo in a template would have taken a page down.

Gotchas and Tips

Unknown icon names throw a hard exception, not a blank render. blade-ui-kit/blade-icons throws SvgNotFound when the component name is not in the registry, which fails the entire request — not just that one icon. Any user-supplied or CMS-driven name must be validated against an allowlist, and every template icon reference should be covered by the inventory test above. A single typo in a nav bar is a 500 for the whole page, not a missing glyph.

Fork Awesome naming ≠ Font Awesome 6 naming. Fork Awesome forked FA 4.7, so names like cog, beer, envelope differ from FA6's gear, beer-mug-empty, envelope. Do not copy icon names from a modern Font Awesome picker or from Heroicons docs. Always read the filename list in resources/svg/.

Icon cache and rollback are a coupled deploy step. icons:cache on deploy and icons:clear on rollback. If a rollback leaves a cache baked for the wrong version, components can 404 even though the SVGs exist on disk. Wire both into your pipeline, not just the happy path.

Response size is the real production tax. Inline SVG is not browser-cached the way an external sprite is, and icon-heavy pages (tables, dashboards, long navigation) can add tens of KB per response. Two mitigations in order of effort: (1) enable blade-icons sprite/definitions mode; (2) audit your icon density — many "icons" on a page turn out to be decorative and can be a single CSS background instead.

Verify your Laravel support matrix at the blade-icons layer, not this package. 1.12.0 widened the composer.json constraint to admit Laravel 13, but the package's real L13 story is only as strong as blade-ui-kit/blade-icons' L13 support. Before treating the bump as an L13 green light: pin the minor ("codeat3/blade-forkawesome": "^1.12"), pin blade-ui-kit/blade-icons explicitly rather than letting it float, and do the L13 validation in a staging branch that renders your icon inventory with the cache warm. Do not begin an L13 migration on the strength of this release alone.

Licensing is the one blocker-shaped item. Fork Awesome's icon license differs from the FA 4.7 lineage it forked. Confirm the SVG license and any attribution obligation before shipping in a commercial or redistributed product; this is the long-lead item, and it is the only one here that can genuinely stop adoption. Record the decision in your dependency register.

Upstream is dormant, not rotted. Static SVGs don't decay, so there is no operational risk from the frozen Fork Awesome upstream. There is a design-staleness risk: glyphs will not grow, and the visual language reads as FA 4.7-era. Treat the package as a stopgap and keep the wrapper abstraction in place so the swap to Heroicons/Lucide/Tabler is a single component-file edit. Add it to your third-party register as "replaceable, non-critical."

Extension points are thin, deliberately. You cannot add new icons via this package's API — the set is fixed. If you need to extend, publish the package's blade-icons config (if not already published by a sibling) and point the SVG path at a directory you own, or bypass this package entirely and register blade-icons yourself with a custom path. For day-to-day work, the practical extension point is your wrapper (<x-icon>), not the package.