DEV Community: Ali Hamdi Ali Fadel

Enforcing Phlex Adoption in Rails: A GitHub Action to Prevent New ERB Files

Ali Hamdi Ali Fadel — Mon, 23 Sep 2024 21:15:44 +0000

In the world of Ruby on Rails development, choosing a templating language is a significant decision that impacts the maintainability and performance of your application. Traditionally, ERB (Embedded Ruby) has been the go-to for many developers. However, with the rise of more efficient alternatives like Phlex, which offers better performance and a more elegant, Ruby-like syntax, developers are increasingly moving away from ERB (At least me and my friends 😁).

After fully/partially migrating to Phlex in your Rails project, the last thing you want is to regress by inadvertently adding new ERB files. This article will walk you through a GitHub Action designed to enforce the exclusive use of Phlex in your Rails project by preventing the addition of new ERB files in pull requests (And direct pushes, if you do this…).

Why Is This Important?

Maintain Consistency: Allowing a mix of ERB and Phlex templates can lead to confusion and inconsistency in your codebase. By enforcing a single templating language, you ensure that all team members adhere to the same conventions, making the codebase more uniform and easier to navigate.
Improve Performance: Phlex is known for its performance benefits over ERB. By preventing new ERB files, you maintain the performance gains achieved by migrating to Phlex.
Reduce Technical Debt: If your project has fully embraced Phlex, any addition of new ERB files can be seen as a step backward, introducing potential technical debt that you'll need to address later.

The GitHub Action: How It Works

The following GitHub Action configuration is designed to check for any new ERB files added in a pull request and prevent the merge if any are found.

name: CI

permissions:
  actions: write
  contents: read

on:
  pull_request:
  push:
    branches: [ main ]

jobs:
  no-new-erbs:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Count ERB files in the PR
        run: |
          erb_files_pr=$(find app -type f -name "*.erb" ! -name "*.turbo_stream.erb" | wc -l)
          echo "ERB_FILES_PR=${erb_files_pr}" >> $GITHUB_ENV

      - name: Count ERB files in the main branch
        run: |
          git fetch origin main
          git checkout origin/main
          erb_files_main=$(find app -type f -name "*.erb" ! -name "*.turbo_stream.erb" | wc -l)
          echo "ERB_FILES_MAIN=${erb_files_main}" >> $GITHUB_ENV

      - name: Compare ERB file counts
        run: |
          if [ "$ERB_FILES_PR" -gt "$ERB_FILES_MAIN" ]; then
            echo "Error: The number of ERB files has increased in this PR."
            exit 1
          else
            echo "Success: The number of ERB files has not increased."
          fi

Step-by-Step Breakdown

Trigger Conditions: This action triggers on two events: pull_request and push to the main branch. This ensures that the check runs on any code changes affecting the main branch or any pull request targeting it.
Checkout Code: The action first checks out the code from the repository using the actions/checkout@v4 action.
Count ERB Files in the Pull Request: It counts the number of ERB files in the app directory, excluding .turbo_stream.erb files, as Turbo Streams are better to live in ERBs than controllers. The result is stored in the ERB_FILES_PR environment variable.
Count ERB Files in the Main Branch: It fetches and checks out the latest code from the main branch. It counts the ERB files in the app directory, using the same exclusion criteria. The result is stored in the ERB_FILES_MAIN environment variable.
Compare ERB File Counts: The action compares the counts of ERB files between the pull request and the main branch. If the count of ERB files in the pull request (ERB_FILES_PR) is greater than in the main branch (ERB_FILES_MAIN), the action fails with an error message. Otherwise, it outputs a success message indicating no new ERB files have been added.

How to Utilize This Action

Add the Action to Your Repository: Copy the YAML configuration above and add it to your .github/workflows directory in your repository as ci.yml.
Customize If Necessary: If you have specific directories other than app where ERB files might reside, or you want to change the exclusion criteria, adjust the find command based on your needs.
Test It: Create a pull request and intentionally add an ERB file to verify that the action correctly fails. Once confirmed, remove the ERB file and test again to ensure the action passes.
Enforce the Rule: Communicate this new rule to your team to ensure everyone understands that new ERB files are no longer allowed.

Conclusion

Migrating to a new templating language is a significant step towards modernizing your Rails application, but maintaining that change requires vigilance. This GitHub Action offers a simple, automated way to enforce your commitment to Phlex by preventing the addition of new ERB files. Implementing it not only helps you maintain consistency and performance but also keeps your codebase clean and focused on the new standard you've set.

By using this action, you can confidently say that your project is Phlex-only, safeguarding your codebase from accidental reintroductions of ERB templates and ensuring that your Rails application stays lean and efficient.

A RuboCop Configuration Tailored for Phlex

Ali Hamdi Ali Fadel — Fri, 20 Sep 2024 16:17:24 +0000

As a developer working with Ruby on Rails and the Phlex framework, I encountered a common pain point: writing Phlex views that are clean, readable, and efficient, while also adhering to RuboCop’s default style guidelines. While RuboCop is a fantastic tool for enforcing coding standards and preventing messy codebases, it can feel a bit restrictive when applied to view code, especially when using frameworks like Phlex along with something like TailwindCSS.

The Problem: Lengthy and Complex Phlex Views and Components

Phlex takes a more Ruby-centric approach to generating HTML by using Ruby classes and methods instead of traditional template files like ERB or HAML. While this is great for reusability and code organization (And writing more Ruby 🤩), it can lead to long methods and classes, especially when building complex components or pages. Adding TailwindCSS into the mix further increases line lengths because of its utility-first CSS approach, where multiple classes are often stacked together.

The result? RuboCop flags violations left and right for:

Line length: Phlex views with TailwindCSS often lead to long lines of code due to the many utility classes.
Method length: Complex view logic can lead to long methods, especially if you’re rendering deeply nested HTML elements.
Class length: Phlex encourages structuring views and components as classes, which may grow large if they represent complex components or full pages.
Cyclomatic complexity: The complexity of HTML structures, conditionals, and loops can trigger RuboCop’s complexity metrics.

While these checks make sense for general Ruby code, enforcing them strictly on views and components doesn’t always add value. Instead, they add friction to writing clear, concise views, especially in the context of Phlex.

The Solution: Tailoring RuboCop for Phlex Views

To reduce this friction, I decided to customize my RuboCop configuration specifically for Phlex views. My goal was to exclude certain style checks from my app/views/**/* directory (I’m still using Phlex v1.x, if you already upgraded to v2.x, you will need to exclude app/components/**/* in addition to app/views/**/*), allowing me to write Phlex views without unnecessary interruptions. Below is the configuration I settled on:

Layout/LineLength:
  Exclude:
    - 'app/views/**/*'

Metrics/AbcSize:
  Exclude:
    - 'app/views/**/*'

Metrics/BlockLength:
  Exclude:
    - 'app/views/**/*'

Metrics/ClassLength:
  Exclude:
    - 'app/views/**/*'

Metrics/CyclomaticComplexity:
  Exclude:
    - 'app/views/**/*'

Metrics/MethodLength:
  Exclude:
    - 'app/views/**/*'

Metrics/ParameterLists:
  Exclude:
    - 'app/views/**/*'

Metrics/PerceivedComplexity:
  Exclude:
    - 'app/views/**/*'

Style/IfUnlessModifier:
  Exclude:
    - 'app/views/**/*'

Why Disable These Specific RuboCop Cops?

Let’s break down why each of these exclusions makes sense for Phlex views and components:

Layout/LineLength: When using TailwindCSS, it’s common to end up with long lines due to multiple class names being stacked together. Breaking these up into smaller lines often makes the code harder to follow and ugly. By excluding this check, I avoid cluttering the view with unnecessary line breaks.
Metrics/AbcSize: Phlex views often have higher abstraction levels, meaning they will naturally include a fair amount of assignments, branches, and conditionals. Disabling this check avoids constant warnings about the complexity of view logic.
Metrics/BlockLength: HTML structures can get quite large, and Phlex components represent these as Ruby blocks. Disabling this check prevents RuboCop from flagging long blocks in view components.
Metrics/ClassLength: Phlex encourages building views as Ruby classes, which can become lengthy when rendering full pages or complex components. Excluding this check allows me to write robust views without breaking them into unnecessarily small pieces.
Metrics/CyclomaticComplexity & Metrics/PerceivedComplexity: HTML is inherently nested and conditional in nature. Phlex views often use loops and conditionals to build the right structure dynamically. Excluding these checks keeps RuboCop from flagging views for the normal complexity of HTML generation.
Metrics/MethodLength: Phlex components can sometimes require long methods to structure complex views. Breaking them down into smaller methods doesn’t always improve readability, so I excluded this check to avoid being overly granular.
Metrics/ParameterLists: When passing data into Phlex views, sometimes a larger list of parameters is necessary. Excluding this check avoids warnings when building view components that require more complex input.

Style/IfUnlessModifier (It needs a separate section 😁)

In Phlex views and components, I often need to conditionally apply classes based on state or variables. The traditional if/else block syntax, while clear in Ruby logic, can become cumbersome when embedding conditional logic into class attributes for HTML elements. Disabling the Style/IfUnlessModifier cop allows me to write more concise conditionals directly in-line, which enhances readability and keeps the code compact.

For example, with this cop disabled, I can write:

('bottom-0 top-auto translate-y-0 end-1/2 start-1/2 -translate-x-1/2 rtl:translate-x-1/2 gap-2 p-4 fixed' if @floating)

Instead of the more verbose:

(if @floating
  'bottom-0 top-auto translate-y-0 end-1/2 start-1/2 -translate-x-1/2 rtl:translate-x-1/2 gap-2 p-4 fixed'
end)

This flexibility is especially important in Phlex views and components, where the recommended syntax for passing classes to HTML tags looks something like this:

a(
  class: [
    ("button"),
    ("active" if is_active),
    ("disabled" if is_disabled)
  ]
) { "Click me" }

Here, the inline conditional syntax keeps the class attribute clean and readable, even if the line becomes long. This is particularly useful when working with TailwindCSS, where class names can quickly stack up. Disabling Style/IfUnlessModifier gives me the flexibility to manage these complex view structures without sacrificing code clarity.

Custom RuboCop Settings Instead of Disabling Cops

While disabling specific RuboCop cops was a practical solution for easing development with Phlex views, another approach worth exploring is customizing the default values for these cops. Adjusting the configuration to align with the particular needs of Phlex views and components (Maybe different defaults!) could provide a balanced solution that maintains code quality while accommodating the unique aspects of Phlex.

For instance, instead of completely excluding checks like Layout/LineLength, Metrics/ClassLength, or Metrics/MethodLength, you could modify their thresholds to better suit the complexity of view code. This way, you ensure that the RuboCop rules still offer guidance without being overly restrictive.

Unfortunately, I didn’t have the time to thoroughly investigate the appropriate values for each cop to strike this balance.

Conclusion

By tailoring RuboCop’s configuration to exclude certain checks in my app/views/ directory, I’ve created a smoother development experience that allows me to write Phlex views more naturally. This setup enables me to take full advantage of Phlex’s Ruby-based approach to view generation without getting bogged down by irrelevant code style warnings.

The key takeaway is that enforcing consistent code style across your entire application is important, but flexibility in your linting tools can also be valuable — especially when dealing with areas like view generation, where different rules may apply.

Icons gem for Phlex

Ali Hamdi Ali Fadel — Fri, 20 Sep 2024 15:54:18 +0000

Introduction

When it comes to building sleek, interactive UIs, having access to a robust set of icons is essential. Over the last few weeks, I've been migrating one of my projects from ERBs to Phlex. During this process, I found myself frequently reaching for SVG icons from popular libraries like Heroicons, Bootstrap icons, and Flag icons. After some frustration with manual integration into a Shared::Icon Phlex component, I had an idea - why not create a gem to simplify this process?

Thus, Phlex::Icons was born. This gem provides Phlex components for a variety of popular icon packs, all in one place. By leveraging the phlexing gem, Phlex::Icons automates the generation of over 12,000 icon components across seven different sources. Whether you're looking for a Bootstrap house icon, a Flag for a country, or a Heroicon for pagination, Phlex::Icons makes it easy.

Why I Built Phlex::Icons

Initially, I stumbled upon phlex-heroicons, which provided Phlex components for Heroicons. This was a great start, but I needed icons from other sources as well. After searching for a solution and coming up short, I decided to build a more generic solution. Phlex::Icons now supports:

Bootstrap Icons (2,000+)
Flag Icons (250+)
Heroicons (300+)
Lucide Icons (1,500+)
RadixUI Icons (300+)
Remix Icons (2,800+)
Tabler Icons (4,800+)

With Phlex::Icons, you can seamlessly integrate these icons into your Phlex projects, dramatically cutting down the time spent on setting up and managing SVG icons.

Key Features of Phlex::Icons

Centralized Icon Access: Phlex::Icons brings together multiple icon packs, offering developers more than 12,000 icons, eliminating the need for individual icon pack integration.
Automatic Updates: A GitHub Actions workflow ensures icon packs are updated weekly. This means any new icons introduced by the source libraries are automatically included in your project.
Flexible Integration: Don’t want to load all 12,000 icons into your app? You can use specific gems for individual icon packs like phlex-icons-bootstrap, phlex-icons-flag, phlex-icons-hero, phlex-icons-lucide, phlex-icons-radix, phlex-icons-remix, or phlex-icons-tabler.
Lazy Loading: The gem supports lazy-loading icons, ensuring minimal impact on your app’s memory consumption.
Phlex::Kit Integration: By leveraging Phlex::Kit, you can directly integrate icon packs into your UI components with minimal configuration, ensuring seamless rendering and a more streamlined workflow for Phlex projects.

Installation and Configuration

Getting started with Phlex::Icons is easy. To add it to your Rails project, simply execute:

bundle add phlex-icons

If you want more granular control and prefer adding individual icon packs, you can install specific packs like this:

bundle add phlex-icons-bootstrap
bundle add phlex-icons-hero

You can also configure global options for all icon packs, such as default CSS classes:

Phlex::Icons.configure do |config|
  config.default_classes = 'size-4'
end

Each icon pack can be further configured individually. For example, you can configure Flag icons to default to a rectangular variant:

Phlex::Icons::Flag.configure do |config|
  config.default_variant = :rectangle
end

Using Phlex::Icons in Your Application

Integrating Phlex::Icons into your project is straightforward. Here’s an example of how to use multiple icons in a view:

class PhlexIcons < Phlex::HTML
  include Phlex::Icons

  def view_template
    div do
      Bootstrap::House(classes: 'size-4')
      Flag::Sa(variant: :rectangle, classes: 'size-4')
      Hero::Home(variant: :solid, classes: 'size-4')
      Lucide::House(classes: 'size-4')
      Radix::Home(classes: 'size-4')
      Remix::HomeLine(classes: 'size-4')
      Tabler::Home(variant: :filled, classes: 'size-4')
    end
  end
end

Alternatively, if you don’t want to use Phlex::Kit, you can render the icons like this:

render Phlex::Icons::Bootstrap::House.new(classes: 'size-4')
render Phlex::Icons::Flag::Sa.new(variant: :rectangle, classes: 'size-4')
render Phlex::Icons::Hero::Home.new(variant: :solid, classes: 'size-4')
render Phlex::Icons::Lucide::House.new(classes: 'size-4')
render Phlex::Icons::Radix::Home.new(classes: 'size-4')
render Phlex::Icons::Remix::HomeLine.new(classes: 'size-4')
render Phlex::Icons::Tabler::Home.new(variant: :filled, classes: 'size-4')

Custom Icons

Phlex::Icons is designed with flexibility in mind, allowing you to add your custom icons as well. Simply create a phlex/icons/custom directory inside views/components and define your own icons within:

module Phlex
  module Icons
    module Custom
      class MyIcon < Phlex::Icons::Base
        def view_template
          # SVG code here
        end
      end
    end
  end
end

Now, you can use this custom icon like any other icon provided by Phlex::Icons:

render Phlex::Icons::Custom::MyIcon.new(classes: 'size-4')

Also, global configurations will be applied to the newly added icon.

Future Development and Contributions

Phlex::Icons is constantly evolving, and I’m always open to adding more icon packs and improving the gem’s functionality. If you have feedback or feature requests, feel free to open an issue or contribute to the project via GitHub. A big thanks to nejdetkadir for laying the groundwork with phlex-heroicons, which served as the foundation for this gem.

Conclusion

Phlex::Icons streamlines the process of integrating a wide range of icons into your Phlex projects. With over 12,000 icons and growing, this gem saves you the time and hassle of manually incorporating SVGs, while ensuring that your project stays up to date with the latest icon packs.

Give it a try, and let me know what you think! Contributions are always welcome on GitHub.

This post was inspired by my journey of migrating to Phlex and developing a better way to handle icons. If you’re working with Phlex, PhlexUI, or simply want to make your icon integration more efficient, Phlex::Icons might just be the solution you’ve been looking for.