Fork Awesome Laravel Package

Getting Started

Fork Awesome is a drop-in fork of Font Awesome 4.x distributed as CSS/SCSS/LESS plus font files — it is not a Composer package, so there is no composer require. Pull it in through your front-end toolchain and compile it like any other stylesheet.

1. Install via your asset manager:

   npm install fork-awesome --save
   

   (Alternatively reference the CDN fork-awesome.min.css for prototypes only.)
2. Import the SCSS into your Laravel stylesheet entrypoint, e.g. resources/sass/app.scss:

   // Override the font path BEFORE the import if you want stable URLs
   $fa-font-path: "/build/fonts";
   @import "~fork-awesome/scss/fork-awesome";
   

3. Compile with Vite (npm run dev) — Vite rewrites the url() references in the CSS to hashed font assets automatically, so you normally don't need to touch vite.config.js.
4. Drop icons into Blade views using Font Awesome 4 syntax — the base class is fa, not fas/fa-solid:

   <i class="fa fa-github" aria-hidden="true"></i>
   <span class="sr-only">GitHub</span>
   

Where to look first: the repo's src/ directory (scss/, less/, fonts/) and the icons.yml / src/icons/ metadata, which is the authoritative list of available icon names. _variables.scss holds $fa-font-path, $fa-css-prefix, and sizing tokens.

First real use case: replacing ad-hoc emoji/SVG buttons in a Blade layout with a consistent icon set — navigation items, table action buttons, status badges — while keeping one stylesheet and one font payload.

Implementation Patterns

Blade component wrapper. Rather than sprinkling <i class="fa fa-..."> everywhere, wrap it once:

{{-- resources/views/components/icon.blade.php --}}
@props(['name', 'label' => null])
<i {{ $attributes->class(['fa', "fa-{$name}"]) }}
   @if($label) role="img" aria-label="{{ $label }}" @else aria-hidden="true" @endif></i>
@if($label === null && isset($slot) && $slot->isNotEmpty())
    <span class="sr-only">{{ $slot }}</span>
@endif

Usage: <x-icon name="trash" class="text-red-600" /> or <x-icon name="check" label="Completed" />.

Config-driven icon maps. For nav bars, status enums, or menu structures, keep the icon name in PHP config rather than the template:

// config/ui.php
return ['status' => ['paid' => 'check-circle', 'failed' => 'times-circle', 'pending' => 'clock-o']];

Then <x-icon :name="config('ui.status.'.$order->status)" />. This makes the icon set swappable later (see migration note in Gotchas).

Vite + font handling. Because Fork Awesome's CSS references ../fonts/forkawesome-webfont.*, Vite fingerprints those files and emits them into public/build/assets. If you set $fa-font-path, prefer an absolute URL (/build/fonts) so CSS-relative resolution doesn't break when the stylesheet itself is hashed. If you use laravel-vite-plugin with buildDirectory customized, re-verify the emitted url() values.

Laravel Mix (legacy apps). Same import, but ensure mix.sass(...) runs with sassOptions including includePaths: ['node_modules'] if the ~ tilde resolution trips you up — Mix's default node-sass/sass-loader handles it, but Dart Sass in newer versions does not.

Sizing and stacking. Use fa-lg, fa-2x…fa-5x and fa-fw for fixed-width alignment in lists/tables. fa-stack + fa-stack-1x/fa-stack-2x gives you badge-on-icon composition (e.g. a shield with a number) without images.

Animation. fa-spin and fa-pulse are CSS keyframes; gate them behind @media (prefers-reduced-motion: no-preference) in your own override if you care about a11y. Don't apply fa-spin to whole containers.

CDN fallback for email/PDF. Icon fonts do not render in most email clients and in dompdf/wkhtmltopdf. For those renderers, generate inline SVGs server-side (or use a Blade @include of an SVG sprite) — do not rely on the webfont.

Gotchas and Tips

• This package is archived and deprecated. There will be no new icons, no bug fixes, and font-license/CSS quirk fixes are frozen. Treat it as a vendored dependency: pin the version in package.json, commit the lockfile, and plan a migration to @fortawesome/fontawesome-free (v5+/v6). Note that FA5+ changed the base class from fa to fas/far/fab, so the migration is mostly a mechanical rewrite of fa fa-* → fa-solid fa-* — which is exactly why the Blade component wrapper above pays for itself.
• Wrong prefix is the #1 bug report. class="fas fa-user" silently renders nothing because Fork Awesome ships FA4's single fa base class. Same for fa-solid, fa-regular, fa-brands.
• PurgeCSS/Tailwind content scanning will eat your icons. Icon class names are typically built dynamically ("fa fa-{$icon}"), so the scanner never sees them. Either use a safelist pattern (/^fa-/), or enumerate every icon in a PHP map that the scanner does see as literal strings in a config file — the latter is more reliable.
• FOUT and layout shift. The webfont is ~100KB+ and loads after first paint; icons briefly render as empty boxes. Preload the woff2 (<link rel="preload" as="font" type="font/woff2" crossorigin>) and give icon containers fixed dimensions.
• $fa-font-path must be set before the @import. Sass variables are order-sensitive; setting it after silently has no effect and you get 404s on the font files.
• Accessibility: decorative icons need aria-hidden="true"; meaningful icons need role="img" + aria-label. Never rely on the icon alone for a destructive action button — pair with text or a tooltip that's also in the accessible name.
• CSP: if you serve the font from your own domain, add font-src 'self' (plus your CDN if used). Inline style attributes emitted by some icon helpers may require style-src 'unsafe-inline'.
• fa-spin in lists. Applying spin to many elements is a measurable CPU cost; cap concurrent spinners.
• Testing: assertSee('fa-check') is brittle and couples tests to presentation. Prefer asserting on aria-label or a data attribute you control.
• Extension points: $fa-css-prefix lets you namespace classes (e.g. icon) to avoid collisions with other icon libraries during a phased migration; $fa-version and $fa-border-color/$fa-inverse control the remaining theme tokens. Custom icons can be added by editing icons.yml and rebuilding the font upstream — not something you'll want to do inside a Laravel app, which is another argument for migrating off a deprecated icon font.