Use tree-shaking to automatically subset and include only the icons you're using.
Beginning with the excellent tool Rollup.js(opens new window) by Rich Harris, the concept of tree-shaking attempts to eliminate any unused code. Webpack 2 now includes this as well.
Using Font Awesome with Tree-shaking
The Font Awesome icon packages support tree-shaking out of the box but only if your tool
is tree-shaking compatible.
In this example, only
faCoffee is imported from
only that icon will be included in the production optimized bundle:
Alternative to Tree-shaking: Deep Imports
If your tool does not yet support tree-shaking you can still
benefit from only importing the icons you use by following this example:
Known Issues with Tree-shaking
Webpack only performs tree-shaking when the
--mode=production(opens new window) flag is used. This enables the
UglifyJsPlugin which performs the
optimization. To nerd out for a second; this plugin is actually doing "dead
code elimination" which is a slower process than the canonical tree-shaking but
the results are similar.
Rollup enables tree-shaking by default but it does so only with ES modules(opens new window) . Font Awesome provides ES modules in all of its NPM packages so you should be good-to-go.
You may experience surprisingly slow build times with Webpack 4, [email protected] and [email protected] For instance, when running a production build with Webpack 4, it might seem to hang for a long time with a status of:
92% chunk asset optimization.
angular-cli 6.0 uses Webpack 4 under the hood, as does
vue-cli 3.0, and perhaps other similar zero-configuration development framework tools.
Here's more background:
uglify-es is a minifier based on
uglify-js. A minifier can eliminate unused code, and this is how Webpack achieves tree-shaking. It delegates dead code elimination to the minifier used for production bundles. Unfortunately, as of
[email protected] and
[email protected], there's a significant performance problem(opens new window) in this minifier code base that happens to effect modules that are formatted like our icon packages. Also, the
uglify-es project has transitioned ownership and been renamed
We expect that future releases of Webpack will depend upon
terser instead of
and will include the performance fix(opens new window) that will make tree-shaking fast again in Webpack 4. In the meantime, if you're facing this problem, there are a few workarounds that you might consider.
Workaround 1: Use deep imports - Each icon is available as a submodule in CommonJS format and can be imported like the example below. This avoids tree-shaking entirely.
Workaround 2: Switch to Babel Minify - Configure webpack to use
babel-minify(opens new window) instead of
uglifyjs, like this:
Workaround 3: Disable collapse_vars - Stick with
uglify-js 3.x, but configure webpack to disable the
collapse_vars compression option(opens new window) . This would impact your whole build, of course, not just the Font Awesome modules.
If you're using a tool like
angular-cli that uses Webpack 4 under the hood, it may be necessary to eject from the tool's configuration management if you want to make any of the Webpack configuration modifications suggested above.
If ejecting is too undesirable, then your best options are probably to either downgrade
to a version of that tool set that uses Webpack 3 until the fix for this performance regression is available, or switch to using deep imports as described above until the fix is available.