Install Font Awesome Free in Your Bootstrap-Themed Rails App

I've been working on a pet project with a Bootstrap theme I purchased. The theme requires Font Awesome 5 Free, and adding it to Rails assets is a struggle. I'm documenting it here so the future me or someone might still find it helpful.

Here's a step-by-step guide on how I was able to install Font Awesome in a new Rails project using the Bootstrap template and ESBuild as the JavaScript bundler:

Step 1: Create a new Rails project
Open your terminal and run the following command to create a new Rails project with the Bootstrap template and ESBuild as the JavaScript bundler:

rails new fontawesome-blog -c=bootstrap -j=esbuild

This command creates a new Rails project named "fontawesome-blog" with Bootstrap and ESBuild configurations.

Step 2: Change into the project directory

Navigate into the project directory using the following command:

cd fontawesome-blog

Then add necessary changes to integrate your Bootstrap theme.

Step 3: Add Font Awesome using Yarn

yarn add @fortawesome/fontawesome-free@5.15.1

This commands installs the Font Awesome 5 Free package with a specific version (5.15.1) using the Yarn package manager. It adds the package as a dependency in your project, making the Font Awesome icons and stylesheets available.

Step 4.a: Update the assets initializer

Open the config/initializers/assets.rb file and the following line:

Rails.application.config.assets.paths << Rails.root.join("node_modules/@fortawesome/fontawesome-free/webfonts")

This configuration change ensures that the web fonts directory of the Font Awesome package (node_modules/@fortawesome/fontawesome-free/webfonts) is included in the list of asset paths that Rails searches when serving assets. It allows Rails to locate and serve the Font Awesome web fonts when they are referenced in stylesheets or views.

By appending this asset path to the config.assets.paths array, Rails knows to include the specified directory in its asset pipeline, making the Font Awesome web fonts accessible and serving them when needed.

Step 4.b: Update the manifest file

If you are not using ESBuild or don't like the above approach, you may use this step. Open app/assets/config/manifest.js and add this line

//= link_tree ../../../node_modules/@fortawesome/fontawesome-free/webfonts

This directive instructs Rails to include the Font Awesome web fonts located in the webfonts directory of the @fortawesome/fontawesome-free package, which is installed in the node_modules directory of the project. The link_tree method scans the specified directory and includes all the files in the asset pipeline, making the Font Awesome web fonts available to be served by the Rails application.

By adding this directive, Rails ensures that the Font Awesome web fonts are accessible and can be loaded properly when referenced in the application's stylesheets or views.

Step 5: Update the application CSS

Open app/assets/stylesheets/application.bootstrap.scss and and the following lines:

// Fontawesome

$fa-font-path: ".";
@import "@fortawesome/fontawesome-free/scss/fontawesome";
@import "@fortawesome/fontawesome-free/scss/brands";
@import "@fortawesome/fontawesome-free/scss/solid";
@import "@fortawesome/fontawesome-free/scss/regular";
@import "@fortawesome/fontawesome-free/scss/v4-shims";

These lines configure the SCSS file to import the necessary Font Awesome stylesheets, including base styles, brand icons, solid icons, regular icons, and compatibility shims. The $fa-font-path variable is set to the current directory, indicating where Font Awesome should look for the font files.

Step 6: Update the application JS
If you're using Webpacker or ESBuid in your Rails project, check the configuration to ensure that it's correctly handling the Font Awesome imports. Verify that the Font Awesome files are being included in your bundled JavaScript.

// In your JavaScript file (e.g., application.js)
import '@fortawesome/fontawesome-free/js/all';

Step 7: Start the server
In your terminal, start the Rails server:

rails server

Step 8: Verify installation
Open your web browser and visit http://localhost:3000. You should see the default Rails welcome page.

You may try running rails assets:precompile if Font Awesome doesn't seem to load.

Step 9: Use Font Awesome icons
To use Font Awesome icons in your views, you can add HTML code with the appropriate class names. For example:

<i class="fas fa-camera"></i>

This will display the Font Awesome camera icon.

Finally, verify that the Bootstrap theme components using FontAwesome are working. In my case I have a dark-mode component that uses FontAwesome like this:

// Change font-family if using different version
$fa-font-family: 'Font Awesome 5 Free'; 

// Dark mode switch
.modeswitch {
  // ... some CSS declarations

  &:before {
    content: "\f042";
    font-family: $fa-font-family;
    font-weight: 900;
    // ... some CSS declarations
  }
  &:hover {
    cursor: pointer;
  }
}

Which looks like this: