Blade Majestic Icons Laravel Package

Product Decisions This Supports

• Choosing the icon delivery mechanism — a real architectural and product call. This package is the low-effort expression of "inline SVG as Blade components" (<x-majesticons-home-line />, <x-majesticons-home-solid />) rather than an icon font, an SVG sprite, or an npm/Vite asset. That choice drives caching behaviour, theming, accessibility handling, and whether icons ship in the JS bundle. Adopt it deliberately as that option, not incidentally.
• Build vs. buy on commodity UI assets. Wrapping an icon set in-house is a few hours of work; adopting this package is the "buy" side, trading a small single-maintainer dependency for zero upkeep of naming, registration, and version reconciliation. Because the escape hatch (vendor the SVGs, register a local component path) is cheap and well-defined, the trade is defensible — provided you write the fallback down.
• Design-system standardization and library sprawl. Committing to one icon vocabulary is a design decision. Majesticons' coverage, line/solid variants, and license constrain you. The same maintainer publishes many near-identical blade-* icon packages, which is exactly how a codebase ends up with one icon dependency per squad. A PM decision worth making explicitly: standardise on one or two families, not one per team.
• Scoping where icons are permitted. Inline SVG is stripped by Gmail and only partially supported by DomPDF/mPDF. This package therefore draws a boundary worth documenting up front: web UI yes, transactional email and generated PDFs no. Better as a written constraint than a QA discovery.
• Velocity on non-differentiating surfaces. For admin panels, internal tools, and MVPs, this removes design involvement from a routine task. A legitimate "ship faster where UI consistency matters more than bespoke iconography" decision.
• Framework-upgrade planning as a tracked dependency line item. Release 2.3.0 is Laravel 13 compatibility only — a widened illuminate/* constraint via PR #13, with no API, naming, or markup changes. Support lands reactively, after each Laravel major ships, so the bump belongs on the upgrade checklist ordered before the framework bump, not treated as a surprise.
• Explicitly not a lever for anything differentiated. No performance-budget impact beyond rendered icons in HTML, no accessibility guarantees, no product capability. It should consume neither roadmap nor research capacity.

When to Consider This Package

Adopt when:

• You are on a supported Laravel version and accept that support arrives as a minor release shortly after each Laravel major. Verify the constraint against your target version rather than assuming forward compatibility; Laravel 13 consumers must be on ^2.3 or composer update will not resolve.
• Your UI is server-rendered Blade (optionally Livewire). The value collapses entirely on Inertia/React/Vue-only front ends — the components render only in Blade.
• You want zero JS and zero build-step integration: no npm dependency, no sprite generation, no icon-font loading. Icons inherit currentColor, so Tailwind text-*, dark:, and group-hover: variants work without extra plumbing, and only rendered icons reach the HTML.
• Majesticons' coverage, license, and visual style clear brand/legal review against your actual screens. Check the icon inventory and look before it spreads.
• You are already on the codeat3 / blade-ui-kit icon-package convention, so naming and usage match the rest of the codebase.
• You will wrap it in your own component (<x-icon name="home" variant="solid" />) with default size, aria-hidden, and — for data-driven icon names — an enum or allow-list. Component names are free strings derived from SVG filenames, so a typo is a runtime "unable to locate component" exception, not a build error. That guardrail is a product-quality decision the package does not make for you, and it is a prerequisite wherever names come from a CMS, API, or nav table.

Look elsewhere when:

• You need bespoke, design-owned, or heavily themed icons; customisation means forking or overriding component by component.
• You need accessibility guarantees. The package adds no aria-hidden, role, or labels — all of that stays in your wrapper and templates.
• You are not on Laravel, or on a major you cannot pin an older release against.
• Supply-chain or dependency-light constraints apply. Effectively one maintainer, no stars or dependents in our data, release cadence driven by Laravel releases. If that bus factor is unacceptable, copy the SVGs in and own them — the cost is genuinely small.
• You need icons as data — a search API, a runtime manifest, or user-selectable icon sets — rather than icons as compiled Blade templates.

How to Pitch It (Stakeholders)

For executives: This is a small, free, MIT-licensed building block that lets our Laravel engineers drop consistent, professionally drawn icons into the interface with no design time and no front-end build work. Release 2.3.0 exists solely to keep it compatible with the newest Laravel version, so it will not block our upgrade path — it just needs a line on that checklist. It carries no meaningful product risk as long as we treat it as a convenience dependency rather than critical infrastructure: the assets are MIT-licensed, we can own copies of the SVG files, and replacing it with an in-house equivalent is about a day of work. Its only real cost is that it is community-maintained by effectively one person, so we deliberately keep it off the critical path, keep it out of email and PDF output, and standardise on one or two icon families rather than accumulating one dependency per team.

For engineering: Version 2.3.0 is a maintenance release — a widened illuminate/* constraint for Laravel 13, no API changes, no renamed components, no config changes. Anything written against 2.2.x keeps working; the bump should be sequenced before the Laravel 13 upgrade so a resolution failure surfaces early rather than mid-upgrade. Integration is composer require, auto-discovery, and use — no provider registration, no publish step, no runtime process, no migrations. Three things to hold: first, component names come from SVG filenames, not the vendor's marketing site, and -line and -solid are separate components — ls vendor/codeat3/blade-majesticons/resources/svg is the source of truth; second, land a single app-level wrapper component (size, colour, aria-hidden defaults) before broad adoption, or class="size-5 shrink-0" will drift across hundreds of call sites; third, if any icon name is data-driven, ship the enum/allow-list first, because a bad name is a runtime exception, not a build failure. Keep it off the critical path and out of Gmail templates and DomPDF/mPDF output. If we ever need to diverge, vendor the SVGs and register a local anonymous component path — never edit vendor/. Register the dependency with an owner, a pin policy per Laravel major, and the documented fallback.