Installing Font Awesome from NPM in Phoenix

SeriesPhoenix on Rails clock3 min read

It's easy to add Font Awesome, a free icon webfont, to Phoenix project using nothing but Brunch to do so.

Update: The method presented in this article doesn't work anymore with latest Brunch release. Thanks @iwarshak for reporting it in the comments! I've written a follow-up article, Front-end packages with Phoenix and Brunch, in which you can find a list of alternative solutions for installing both Font Awesome and any other front-end packages in Phoenix.

Problem with font assets (or anything not JS/CSS)

First of all, you could just drop Font Awesome to web/static/assets, but then you would pollute the repo and lose package versioning along with an easy way to update (which is a must as Font Awesome has great regular updates). And when there will be tens of such randomly dropped assets in the app, it'll quickly become a maintenance hell.

That's why I decided to go with NPM package and to use Phoenix's default Brunch, keeping it simple and consistent with Phoenix conventions. There are three challenges when including assets like Font Awesome directly from versioned package:

  1. Brunch doesn't yet have a built-in universal way of importing packages with fonts or images from NPM. This is what Bower used to do for us (not without its own issues), but it seems the NPM is now a preferred source for all front-end packages. 
  2. Font Awesome package needs to be within Sass include paths in order to be used.
  3. Webfont files must be placed appropriately in public directory for the browser to get them. 

These issues are also present when using Bower or Rails asset pipeline (or both). In fact, there's an ongoing discussion between Brunch devs about how to approach this in Brunch.

Fortunately, I've been able to successfully include both font styles and assets into Brunch pipeline using nothing but the most basic options in brunch-config.js. In this method I assume Sass presence in the project. I strongly recommend using Sass with Phoenix & Brunch anyway for a number of reasons:

  • it's widely used in NPM packages (including Font Awesome)
  • its import directive replaces require from Rails asset pipeline
  • all processing benefits (indented syntax, variables, mixins, nesting...)

OK, let's get to work.

Installing package

First, install the Font Awesome package as usual:

npm install --save font-awesome

Copying assets

Then, configure brunch-config.js to look into the package for assets (conventions), but to pick only the files we really need in the public directory (paths):

conventions: {
  assets: [
    /* ... */

paths: {
  watched: [
    /* ... */

Font files will be copied by native Brunch asset copying facility (as opposed to packages like copycat-brunch). Moreover, as we obey the original package's relative paths, it's not even necessary to change the default font path (which is possible via $fa-font-path).

Including stylesheets

Assuming you've already added sass-brunch to the project and converted app.css to use it, add this to app.sass or app.scss:

@import 'node_modules/font-awesome/scss/font-awesome'

Note: You could also add Font Awesome as one of Sass include paths in brunch-config.js, but as the project root is also a Sass include path, I prefer to just go with it. This makes for more explicit imports in app.sass.

That's it! Font Awesome will now be available in both development and production.


I've shown how to add Font Awesome, but I can confirm the same method works with many more NPM packages. And in case of problems, you can always fallback to copying packages manually to web/static/assets.