Skip to content

[2.x] feat: upgrade FontAwesome from 6.x to 7.x#4388

Merged
imorland merged 8 commits into2.xfrom
im/fontawesome-7
Feb 25, 2026
Merged

[2.x] feat: upgrade FontAwesome from 6.x to 7.x#4388
imorland merged 8 commits into2.xfrom
im/fontawesome-7

Conversation

@imorland
Copy link
Member

@imorland imorland commented Feb 25, 2026 •
edited
Loading

Summary

Upgrades the bundled FontAwesome library from Free 6.5.2 (via the unmaintained components/font-awesome mirror) to Free 7.x (via the official fortawesome/font-awesome Composer package). Fully backward-compatible — all existing fas/far/fab class names continue to work via FA7's shipped CSS aliases.

Also adds FontAwesome source configuration (Local / CDN / Kit) to the admin Advanced page, with a lazy-loaded icon preview modal, and fixes a pre-existing gap where the admin jsDirectory was never registered (preventing async admin chunks from being served).

Changes

Backend

  • composer.json — components/font-awesome: ^6.5.2 → fortawesome/font-awesome: ^7.0
  • FrontendServiceProvider.php — updated vendor path for LESS import
  • PublishAssets.php — updated vendor path for webfont publishing
  • AssetsPublishCommand.php — updated vendor path for assets:publish command
  • AdminServiceProvider.php — registered missing jsDirectory so async admin chunks are served correctly

Frontend

  • Admin Advanced page — added FontAwesome source selector (Local / CDN / Kit) with conditional CDN URL / Kit URL inputs, config.php override display, and a lazy-loaded icon preview modal
  • Application.tsx — updated app.refs.fontawesome URL to version-agnostic fontawesome.com/icons
  • Select.less — fixed .Select wrapper not stretching to full width inside a FormSection column
  • core.yml — updated icon_text help string to show both FA5/6 (fas fa-flag) and FA7 (fa-solid fa-flag) prefix styles

Tests

  • Added PublishAssetsTest unit tests (previously untested): verifies correct vendor path, file copying, revert behaviour, and woff2-only output from FA7

Backward Compatibility

  • fas, far, fab shorthand aliases are explicitly defined in FA7's CSS — no icon references in extensions need to change
  • LESS import surface unchanged: FA is imported with @import (inline) on the pre-built CSS; url("../webfonts/") paths are identical in FA7
  • FA7 ships .woff2 only (no .eot, .ttf, .woff, .svg) — all modern browsers support WOFF2

Upgrade Notes for Existing Installs

After upgrading, old font files in public/assets/fonts/ are not automatically removed. Admins should run:

rm -rf public/assets/fonts
php flarum assets:publish

Docs PR: flarum/docs#501

Test plan

  • Fresh install: verify public/assets/fonts/ contains only .woff2 files
  • Verify forum renders icons correctly with local source
  • Switch to CDN source, verify local fonts are not loaded and CDN CSS is injected
  • Switch to Kit source, verify kit JS snippet is loaded
  • Verify config.php override for each source disables the admin UI inputs
  • Open icon preview modal on Advanced page, verify Free icons render, Pro icons show broken boxes
  • Test icon with FA7-only class (fas fa-bus-side) renders correctly
  • Verify existing extensions using fas fa-cog etc. still render (alias compatibility)
  • Run php flarum assets:publish on an upgraded install, verify stale FA6 files are removed after manual clear

🤖 Generated with Claude Code

imorland and others added 8 commits February 25, 2026 10:18
@imorland @claude
feat: upgrade FontAwesome from 6.5.2 to 7.x
0959650 
Switches the Composer dependency from the unmaintained
`components/font-awesome` shim (capped at 6.5.2) to the canonical
`fortawesome/font-awesome` package at ^7.0 (currently 7.2.0).

FA7 ships .woff2 only (no ttf/woff/eot), keeps identical CSS filenames
(fontawesome.css, solid.css, regular.css, brands.css), identical
../webfonts/ url() paths, and retains the .fas/.far/.fab shorthand
aliases — so zero changes are required to LESS imports, LessCompiler
URL rewriting, icon class strings in JS, or any Theme extender
customisation surfaces.

Changes:
- framework/core/composer.json: fortawesome/font-awesome ^7.0
- FrontendServiceProvider: LESS import dir → fortawesome/font-awesome/css
- PublishAssets: webfonts source → fortawesome/font-awesome/webfonts
- AssetsPublishCommand: webfonts source → fortawesome/font-awesome/webfonts
- Add PublishAssetsTest unit tests (previously untested)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@imorland @claude
feat(admin): update FA7 references and add icon preview to Advanced page
134ddda 
- Update CDN placeholder URL from FA 6.5.2 to 7.2.0
- Update app.refs.fontawesome link from /v6/icons to /icons (version-agnostic)
- Add icon preview area to the FontAwesome section of the Advanced page
  showing three tiers: FA5/FA6 aliases, FA7 class names (including one
  FA7-only icon: fa-bus-side), and Pro-only styles (Light/Thin/Duotone)
  so admins can visually verify their local/CDN/Kit setup at a glance
- Add FontAwesomePreview LESS styles to AdvancedPage.less
- Add locale strings for preview labels

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@imorland @claude
refine(admin): improve FontAwesome icon preview visual design
179d36b 
- Replace flat row layout with per-tier cards (--control-bg background)
- Add uppercase section headers with a hairline divider
- Larger tiles (44px) with label underneath each icon
- Hover state: primary-color border + subtle ring
- Tooltip on tile shows the full CSS class string

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@imorland @claude
fix(admin): replace fade() LESS function in FontAwesomePreview hover …
b5df0e3 
…state

fade() cannot operate on CSS custom properties. Replace with a
--control-bg-shaded box-shadow ring which works with the LESS compiler.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@imorland @claude
refactor(admin): move FA icon preview into a lazy-loaded modal
bd34833 
Replace the inline preview section on the Advanced page with a
"Preview Icons" button that lazy-loads FontAwesomePreviewModal on click.
The modal is only downloaded when needed, keeping the Advanced page compact.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@imorland @claude
fix(admin): register admin jsDirectory for async chunk serving
cc0e20e 
Without this, async chunks emitted into js/dist/admin/ (such as the
FontAwesomePreviewModal chunk) are never registered with the asset
server and return 404 when dynamically imported.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@imorland @claude
fix(admin): expand Select wrapper to full width inside FormSection
a8f73ac 
The .Select span wrapper was display:inline-block which caused it to
shrink-wrap to content width even inside a FormSection column. Added a
.FormSection & rule to make it display:block and width:100%, consistent
with the existing rule that already set width:100% on the inner <select>
element.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@imorland @claude
fix(locale): update icon_text to reference both FA5 and FA7 prefix st…
1dc071e 
…yles

The existing help text only showed the legacy 'fas fa-' prefix. Updated
to show both the legacy shorthand (fas fa-flag) and the FA7 canonical
form (fa-solid fa-flag) as examples.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@imorland imorland requested a review from a team as a code owner February 25, 2026 13:36
imorland added a commit to flarum/docs that referenced this pull request Feb 25, 2026
@imorland @claude
docs: add FontAwesome 7 upgrade documentation
a32864e 
- Add dedicated FontAwesome page covering Local/CDN/Kit sources,
  icon class name reference, renamed icons table, and extension dev notes
- Add FontAwesome page to Management sidebar
- Update config.md: prose and CDN example URL to FA7
- Update themes.md: version reference and link to new FA page
- Update extend/i18n.md: replace dead fortawesome.github.io URL
- Update extend/update-2_0.md: add FontAwesome 5→7 upgrade section
  under Backend > Dependencies

Relates to flarum/framework#4388

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@imorland imorland changed the title feat: upgrade FontAwesome from 6.x to 7.x [2.x] feat: upgrade FontAwesome from 6.x to 7.x Feb 25, 2026
@imorland imorland added type/feature dependencies Pull requests that update a dependency file type/theme(ing) labels Feb 25, 2026
@imorland imorland added this to the 2.0.0-beta.8 milestone Feb 25, 2026
@imorland imorland mentioned this pull request Feb 25, 2026
Open
4 tasks
@imorland imorland merged commit dca8d24 into 2.x Feb 25, 2026
35 checks passed
@imorland imorland deleted the im/fontawesome-7 branch February 25, 2026 14:21
@imorland imorland mentioned this pull request Feb 26, 2026
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

dependencies Pull requests that update a dependency file type/feature type/theme(ing)

Projects

None yet

Milestone

2.0.0-beta.8

Development

Successfully merging this pull request may close these issues.

1 participant

@imorland