Install Font Awesome Free in Your Bootstrap-Themed Rails App
Tags: rails, esbuild, bootstrap
Published: 2023-06-24 01:57:04

> 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:

```bash
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:

```bash
cd fontawesome-blog
```

_Then add necessary changes to integrate your Bootstrap theme._

**Step 3: Add Font Awesome using Yarn**

```bash
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:

```ruby
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

```javascript
//= 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:

```sass
// 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.

```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:

```bash
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:

```html
<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:

```sass
// 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:


![Dark Mode Component](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/nkl24gljoijt5hyuvq7o.png)