Skip to content

Latest commit

 

History

History
96 lines (67 loc) · 3.84 KB

UPGRADING.md

File metadata and controls

96 lines (67 loc) · 3.84 KB

Upgrading Guide

See the CHANGELOG.md for detailed information about what has changed between versions.

This guide is useful to figure out what you need to do between breaking changes.

As always, submit issues that you run into with this guide or with these upgrades to us.

2.0.0 to 3.0.0

The package has been migrated to an Ember Addon v2. This is an important and necessary step to ensure compatibility with future Ember versions. As part of this transition, outdated and unsupported dependencies have been removed, reducing the number of required dependencies to a minimum.

Icons

Previously, icons were defined as strings inside config/icons.js. During the build process, the specified icons were searched for in Font Awesome icon packages and imported automatically.

module.exports = function () {
  return {
    'free-solid-svg-icons': [
      'coffee',
      'magic',
      'trash-alt',
    ],
    'free-regular-svg-icons': 'all',
    'free-brands-svg-icons': 'all',
  };
};

The icon imports must now be added to the app/font-awesome.js/ts file, as shown in this example:

// app/font-awesome.ts
import { library } from '@fortawesome/fontawesome-svg-core';
import {
  faCoffee,
  faMagic,
  faTrashAlt,
} from '@fortawesome/free-solid-svg-icons';
import * as freeRegularSvgIcons from '@fortawesome/free-regular-svg-icons';
import * as freeBrandSvgIcons from '@fortawesome/free-brands-svg-icons';

library.add(
  faCoffee,
  faMagic,
  faTrashAlt,
);

library.add(freeBrandSvgIcons['fab']); // option to import all icons of fab
library.add(freeRegularSvgIcons['far']); // option to import all icons of far

In your app.js/ts file you need to add this import

// app/app.ts
import './font-awesome';

Switching to this approach reduces maintenance costs for the addon while allowing you to use any newly released Font Awesome icon package without requiring updates to this addon. Additionally, you no longer need to restart your Ember when adding new icons.

Style

Previously, the addon automatically included the basic Font Awesome CSS styles. With the v2 addon format, this behavior has been removed, meaning you must now manually import the styles into your project.

To do so, add the following lines to your app.js/ts:

// app/font-awesome.ts
import { config } from '@fortawesome/fontawesome-svg-core';
import '@fortawesome/fontawesome-svg-core/styles.css';

config.autoAddCss = false;

You might wonder why we manually import the CSS and disable config.autoAddCss.

  1. The default value (config.autoAddCss = true) does not work properly with Fastboot.
  2. When using autoAddCss, styles are loaded too late, causing icons to appear incorrectly at app startup.

In previous versions (<3.0), this configuration was handled automatically within the addon. To avoid unwanted behavior, we recommend adding these lines explicitly to your project.

After making these changes, your app/font-awesome.js/ts and app/app.js/ts file should match the structure described in the installation guide.

If you are using .gjs / .gts, check out the installation guide for an alternative setup option.

Note: If you passed the icon definition (object) to @icon, the only change you may need to make is importing the styles. Everything else should work as before.

Glint support

If you are using glint, you can set it up as described here