FontAwesome npm Installation And Basic Usage

January 23, 2018

UDPATE: Refer to the new guide.

The article focus on FontAwesome application using npm.

Installation

Install fontawesome free packages.

npm install @fortawesome/fontawesome --save
npm install @fortawesome/fontawesome-free-solid --save
npm install @fortawesome/fontawesome-free-brands --save

To install fontawesome pro, download the latest release (I am using fontawesome-5.0.0-beta7-linux fontawesome-5.0.0-rc5-linux fontawesome-pro-5.0.4). Extract it to a permanent directory, goto packages advanced-options/use-with-node-js directory and execute npm link to the packages.

Go to project directory to install the packages using npm link <PACKAGE_NAME>.

cd fontawesome-pro-5.0.4
cd advanced-options/use-with-node-js
cd fontawesome-pro-brands && sudo npm link && cd ..
cd fontawesome-pro-light && sudo npm link && cd ..
cd fontawesome-pro-regular && sudo npm link && cd ..
cd fontawesome-pro-solid && sudo npm link && cd ..

cd my-project
npm link @fortawesome/fontawesome-pro-brands
npm link @fortawesome/fontawesome-pro-light
npm link @fortawesome/fontawesome-pro-regular
npm link @fortawesome/fontawesome-pro-solid

If ESLint complaint of import/no-extraneous-dependencies, edit package.json to add the following. Version number can be found at fontawesome-5.0.0-rc5-linux/advanced-options/use-with-node-js/fontawesome-pro-solid/package.json.

{
  ...
  "dependencies": {
    "@fortawesome/fontawesome-pro-solid": "1.1.2",
    ...
  }
  ...
}

Usage

The sample below load a icon and replace a HTML element with a SVG icon.

import fontawesome from '@fortawesome/fontawesome'
import faFreeSolid from '@fortawesome/fontawesome-free-solid'
// import faProSolid from '@fortawesome/fontawesome-pro-solid'
 
var icon = fontawesome.icon(faFreeSolid)
$('#replace-icon').html(icon.html)
// the following work as well
// $('#replace-icon').replaceWith(icon.node[0])
<div id="replace-icon">Show Icon Here</div>

You can also load icon by string.

import fontawesome from '@fortawesome/fontawesome'
import faFreeSolid from '@fortawesome/fontawesome-free-solid'

fontawesome.library.add(faFreeSolid)

var icon = fontawesome.icon({prefix: 'fas', iconName: 'user'})

Load icon by string using prefix fa or omission of prefix doesn’t work at the moment, unless you apply a hack to the libraries (v0.0.14).

NOTE: Since v1.1.2 / fontawesome-pro-5.0.4, no hack is required.

import fontawesome from '@fortawesome/fontawesome'
import faFreeSolid from '@fortawesome/fontawesome-free-solid'

fontawesome.library.add(faFreeSolid)

// NO LONGER REQUIRED since fontawesome-5.0.4
// HACK: to enable access of icon using prefix 'fa'
// fontawesome.library.definitions.fa = fontawesome.library.definitions.fas

var icon = fontawesome.icon({prefix: 'fa', iconName: 'user'})
var icon2 = fontawesome.icon({iconName: 'user'})

SPECIAL NOTE: Selective Import FontAwesome Icon To Reduce Size For Webpack

Automatic SVG Replacement (Javacript)

Assuming you want to replace all fa-* classes with svg icon, it’s quite easily done using javascript.

<head>
  <script src="js/packs/solid.js"></script> 
  <script src="js/fontawesome.js"></script> 
</head>
<body>
  <i class="fa fa-user"></i>
</body>

OR

<head>
  <script src="js/packs/solid.js"></script> 
  <script>
    import fontawesome from '@fortawesome/fontawesome'
    fontawesome.dom.i2svg()
  </script> 
</head>
<body>
  <i class="fa fa-user"></i>
</body>

Automatic SVG Replacement (npm)

To replace all fa-* classes with svg icon using npm is a bit tricky and require a hack as well (v0.0.14).

NOTE: Since v1.1.2 / fontawesome-pro-5.0.4, no hack is required. Just call fontawesome.library.add and fontawesome.dom.i2svg.

import fontawesome from '@fortawesome/fontawesome'
import faFreeSolid from '@fortawesome/fontawesome-free-solid'

fontawesome.library.add(faFreeSolid)

// NO LONGER REQUIRED since fontawesome-5.0.4
// HACK: to enable access of icon using prefix 'fa'
// fontawesome.library.definitions.fa = fontawesome.library.definitions.fas

// NO LONGER REQUIRED since fontawesome-5.0.4
// HACK: to enable dom.i2svg to work in npm
// var NAMESPACE_IDENTIFIER = '___FONT_AWESOME___'
// window[NAMESPACE_IDENTIFIER].packs.fa = fontawesome.library.definitions.fa

// will automatically find any <i> tags in the page and replace those with <svg> elements
fontawesome.dom.i2svg()
<i class="fa fa-user"></i>
OR
<i class="fas fa-user"></i>

Webpack

If you are using Webpack, you will probably notice fontawesome-pro doesn’t split properly into vendor.js (only affect PRO version). Reason is we use npm link and the resolved path is not /node_modules. I use /use-with-node-js/ to detect fontawesome packages.

Edit webpack.conf.js.

module.exports = {
  ...
  plugins: [
    ...
    new webpack.optimize.CommonsChunkPlugin({
      name: 'vendor',
      minChunks: function (module) {
        return (
          module.resource &&
          /\.(js|css|sass|scss|less|json)$/.test(module.resource) &&
          (module.resource.indexOf(path.join(__dirname, '../node_modules')) === 0 || module.resource.indexOf('/use-with-node-js/') >= 0)
        )
      }
    }),
  ],
  ...
});

References

This work is licensed under a
Creative Commons Attribution-NonCommercial 4.0 International License.