Awesemo for Craft CMS

Installation

Requirements

  • Craft CMS 5.3 or later
  • PHP 8.2 or later

No runtime dependencies. The CKEditor and Redactor integrations switch themselves on only when those plugins are installed, so neither is required.

Install

composer require justinholtweb/craft-awesemo
php craft plugin/install awesemo
php craft awesemo/catalog/build

Or find Awesemo in the Craft Plugin Store and install it from there, then build the catalogue from Awesemo → Icons.

Awesemo is free. There are no editions and no licence key.

What happens the moment it installs

Awesemo starts serving Font Awesome 6 Free from jsDelivr, on every front-end request, and removes any other copy of Font Awesome it finds in the response. If the site had no Font Awesome before, it has one now. If the site already loaded its own, read Sites that already load Font Awesome, below, before you do anything else.

Nothing is rewritten on the way in. Awesemo never edits your content or your templates — the markup an author already wrote keeps working exactly as it did.

Build the catalogue

The catalogue is the icon list: names, labels, search terms, categories, aliases, the v4 shim table and the SVG path data, downloaded once from the source you configured.

php craft awesemo/catalog/build

Until it exists, nothing can be searched, the picker is empty and every name counts as unknown. It takes a few seconds and one download. Do it again after any deploy that wipes storage/ — nothing is lost that a single download cannot restore.

Check what you got:

php craft awesemo/catalog/info

The first icon

{{ awesemo('user') }}

That renders <i class="fa-solid fa-user" aria-hidden="true"></i> — solid because that is the default style, hidden from screen readers because an icon beside a word that already says "Account" should be.

Then open Awesemo → Icons in the control panel and search for something. Every icon in the installed version is there, with the Twig, the HTML, the name and the code point one click away.

Sites that already load Font Awesome

Two copies of Font Awesome on one page is the most common way icons break in a CMS: whichever stylesheet loads last owns the class names, and half the site goes blank. Awesemo assumes it is the one in charge and strips the others.

You have two ways to go, and both are fine:

  • Let Awesemo own it. Delete the <link> or kit <script> from your templates. Set the version in settings to match what you were loading, and everything already written keeps rendering.
  • Keep loading it yourself. Set the source to Loaded by the site itself in settings. Awesemo then delivers nothing and strips nothing; you still get the picker, the fields, the editor buttons and the usage scan.

What you should not do is leave your own tag in place and let Awesemo deliver a different version. Run php craft awesemo/health/check — that is precisely the case it is looking for.

Verify

php craft awesemo/health/check

It exits non-zero on an error, which is what makes it worth putting in a deploy pipeline: a build that would have shipped a page of blank squares fails where somebody is looking. Add --strict to fail on warnings too.

Next

  • Configuration — the source, the render mode and every other setting
  • Usage — Twig, fields, rich text, custom icons and the console