fontawesome_subsetter 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8d07501e79546fbe88ff5c7130cb5b0a5e90c2bc0dedc50bebf97989a966cf33
+  data.tar.gz: cbbd58e800778f1098353a673cbf11348b656cc13d9b832c5b53980dbb588ab9
+SHA512:
+  metadata.gz: d5dbc3c8c0109591d830a15f7828c4976239443bada05930b15d2c99a70a45159cd80c68b080c17665db2f6798cfc8739622dd62980436c138ad19c90d5bc1ef
+  data.tar.gz: 64d4f1265db3642169657c29008917a462ba0cec6bd92113766a109df9ebb7afcdd79c3c25f2253f2d1f4337f97a5af86216722f2aa6026d266d5ec57bfe8e58

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,113 @@
+# FontAwesome Subsetter
+
+A Rails gem that tree-shakes FontAwesome — scans your views and helpers for `icon()` calls, subsets WOFF2 font files to include only used glyphs, and generates minimal CSS.
+
+## Requirements
+
+- **FontAwesome** files in `vendor/fontawesome/` (metadata, scss, webfonts)
+- **pyftsubset** (from [fonttools](https://github.com/fonttools/fonttools)): `pip install fonttools brotli`
+- **sass-embedded** gem for SCSS compilation
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "fontawesome_subsetter"
+```
+
+Then run `bundle install`.
+
+## Setup
+
+### Directory Structure
+
+The gem expects FontAwesome Pro files in your project at:
+
+```
+vendor/
+  fontawesome/
+    metadata/
+      icons.yml
+    scss/
+      variables.scss
+      functions.scss
+      mixins.scss
+      core.scss
+      animated.scss
+      icons.scss
+      solid.scss
+      regular.scss
+      ...
+    webfonts/
+      fa-solid-900.woff2
+      fa-regular-400.woff2
+      fa-brands-400.woff2
+      fa-duotone-900.woff2
+      fa-thin-100.woff2
+```
+
+> **Note:** In `vendor/fontawesome/scss/variables.scss`, change `$icons` and `$brand-icons` to empty maps with `!default` so the subsetter can inject only the used icons.
+
+## Features
+
+### 1. Icon Helper
+
+The gem provides an `icon` helper available in all views:
+
+```slim
+= icon(:fas, :download, "Download", class: "mr-1")
+= icon(:far, :check)
+= icon(:fab, :github)
+```
+
+### 2. Puma Plugin (Development Watch Mode)
+
+Add to your `config/puma.rb`:
+
+```ruby
+if ENV.fetch("RAILS_ENV", "development") == "development"
+  plugin :fontawesome
+end
+```
+
+This watches `app/views/`, `app/helpers/`, and `app/components/` for changes and automatically rebuilds subsetted fonts.
+
+### 3. Rake Task (Deploy)
+
+The gem automatically hooks into `assets:precompile`:
+
+```bash
+rake assets:precompile  # fontawesome:subset runs first
+```
+
+You can also run it manually:
+
+```bash
+rake fontawesome:subset
+```
+
+## Configuration
+
+```ruby
+# config/initializers/fontawesome_subsetter.rb
+FontawesomeSubsetter.configure do | config |
+  # Paths to scan for icon() calls (defaults shown)
+  config.scan_globs = ["app/views/**/*.slim", "app/helpers/**/*.rb"]
+
+  # Regex to match icon() calls (default shown)
+  config.icon_regex = /icon\(\s*:(?<prefix>fas|far|fab|fad|fal|fat)\s*,\s*:(?<icon>[\w_\-]+)\b/
+
+  # Override default paths (optional — defaults use Rails.root)
+  # config.meta_path = Rails.root.join("vendor", "fontawesome", "metadata", "icons.yml")
+  # config.fonts_dir = Rails.root.join("vendor", "fontawesome", "webfonts")
+  # config.build_dir = Rails.root.join("app", "assets", "builds")
+
+  # Custom SCSS template (optional — receives @styles hash, must return SCSS string)
+  # config.scss_template = ->(styles) { "..." }
+end
+```
+
+## License
+
+[MIT](LICENSE.txt) — Copyright (c) 2026

data/lib/fontawesome_subsetter/engine.rb

@@ -0,0 +1,17 @@
+module FontawesomeSubsetter
+
+  class Engine < ::Rails::Engine
+
+    initializer "fontawesome_subsetter.helpers" do
+      ActiveSupport.on_load(:action_view) do
+        include FontawesomeSubsetter::IconHelper
+      end
+    end
+
+    rake_tasks do
+      load File.expand_path("../tasks/fontawesome_subsetter.rake", __dir__)
+    end
+
+  end
+
+end

data/lib/fontawesome_subsetter/icon_helper.rb

@@ -0,0 +1,21 @@
+module FontawesomeSubsetter
+
+  module IconHelper
+
+    def icon(style, name, text = nil, html_options = {}, &block)
+      text, html_options = nil, text if text.is_a?(Hash)
+
+      html_options[:class] = "#{ style } fa-#{ name.to_s.dasherize }#{ " #{ html_options[:class] }" if html_options.key? :class }"
+
+      html = content_tag :i, nil, html_options
+
+      html = "#{ html } #{ text }" if text.present?
+
+      html = "#{ html } #{ capture block }" if block_given?
+
+      html.html_safe
+    end
+
+  end
+
+end

data/lib/fontawesome_subsetter/subsetter.rb

@@ -0,0 +1,210 @@
+require "json"
+require "open3"
+require "fileutils"
+require "yaml"
+require "set"
+
+module FontawesomeSubsetter
+
+  class Subsetter
+
+    def initialize(root: nil)
+      @file_icon_map = {}
+      @root          = root || defined?(Rails) && Rails.root || Pathname.new(Dir.pwd)
+      @root          = Pathname.new(@root) unless @root.is_a?(Pathname)
+
+      config = FontawesomeSubsetter.configuration
+
+      @meta_path  = config.meta_path  || @root.join("vendor", "fontawesome", "metadata", "icons.yml")
+      @fonts_dir  = config.fonts_dir  || @root.join("vendor", "fontawesome", "webfonts")
+      @build_dir  = config.build_dir  || @root.join("app", "assets", "builds")
+      @webfonts_dir = @build_dir.join("webfonts")
+      @scan_globs = config.scan_globs
+      @icon_regex = config.icon_regex
+
+      @styles = {
+        "solid"   => { name: "solid",   prefix: "fas", unicode_cache: Set.new, icon_cache: Set.new, sass_icon_cache: Set.new, changed: false, file: "fa-solid-900.woff2"   },
+        "regular" => { name: "regular", prefix: "far", unicode_cache: Set.new, icon_cache: Set.new, sass_icon_cache: Set.new, changed: false, file: "fa-regular-400.woff2" },
+        "light"   => { name: "light",   prefix: "fal", unicode_cache: Set.new, icon_cache: Set.new, sass_icon_cache: Set.new, changed: false, file: "fa-thin-100.woff2"    },
+        "thin"    => { name: "thin",    prefix: "fat", unicode_cache: Set.new, icon_cache: Set.new, sass_icon_cache: Set.new, changed: false, file: "fa-thin-100.woff2"    },
+        "duotone" => { name: "duotone", prefix: "fad", unicode_cache: Set.new, icon_cache: Set.new, sass_icon_cache: Set.new, changed: false, file: "fa-duotone-900.woff2" },
+        "brands"  => { name: "brands",  prefix: "fab", unicode_cache: Set.new, icon_cache: Set.new, sass_icon_cache: Set.new, changed: false, file: "fa-brands-400.woff2"  }
+      }
+
+      @watch_paths = [
+        @root.join("app", "views"),
+        @root.join("app", "helpers"),
+        @root.join("app", "components")
+      ].select(&:exist?)
+
+      @watch_file_type_regex = config.watch_file_type_regex
+
+      FileUtils.rm_rf(@webfonts_dir)
+      FileUtils.mkdir_p(@webfonts_dir)
+
+      # Load FontAwesome metadata
+      @metadata = YAML.safe_load(File.read(@meta_path))
+
+      # Build unicode map, set entry to an array of all codepoints (main + secondary)
+      @metadata.each { | key, entry | @metadata[key]["unicodes"] = Set.new([ "U+#{ entry['unicode'].upcase }", *entry.dig("aliases", "unicodes", "secondary")&.map { | s | "U+#{ s.upcase }" } ]) }
+
+      # Build alias map
+      @metadata.merge!(@metadata.values.flat_map { | entry | (entry.dig("aliases", "names") || []).map { [ it, entry ] } }.to_h)
+
+      # Strip useless metadata
+      @metadata.each_value { it.except!("changes", "label", "voted", "search", "styles", "aliases") }
+    end
+
+    # Updates the cache for each style, returns the styles that have changed.
+    def scan_files_and_update_caches(files)
+      files.each do | path |
+
+        text = File.read(path)
+        text.scan(@icon_regex).each do | prefix, icon |
+
+          style = @styles.find { it&.last[:prefix] == prefix }&.last
+          next unless style
+
+          normalized = icon.tr("_", "-")
+          entry = @metadata[normalized]
+          next unless entry
+
+          # If the icon is new for this style, update the caches
+          if style[:icon_cache].add?(normalized)
+            style[:unicode_cache].merge(entry["unicodes"])
+            style[:sass_icon_cache].add("\"#{ normalized }\": \\#{ entry['unicode'] }")
+            style[:changed] = true
+          else
+            nil
+          end
+
+        end
+
+      end
+    end
+
+    # Takes an array of styles and creates a thread to subset each font file
+    def subset_webfonts(styles)
+      styles.map { | style | Thread.new(style) { subset_font(style) } }.each(&:join)
+    end
+
+    def subset_font(style)
+      file     = style[:file]
+      out_file = @webfonts_dir.join(file)
+      cmd      = "pyftsubset #{ @fonts_dir.join(file) } --flavor=woff2 --unicodes=#{ style[:unicode_cache].to_a.join(",") } --output-file=#{ out_file } --layout-features=* --no-hinting"
+
+      puts "[FontSubsetter][#{ style[:name] }] #{ cmd }"
+      stdout, stderr, status = Open3.capture3(cmd)
+      if status.success?
+        puts "[FontSubsetter][#{ style[:name] }] wrote #{ out_file }"
+      else
+        warn "[FontSubsetter][#{ style[:name] }] subset failed:\n#{ stderr }"
+        raise "pyftsubset failed (exit #{ status.exitstatus })"
+      end
+    end
+
+    def subset_stylesheets
+      styles = @styles.values.select { it[:sass_icon_cache].any? }
+
+      scss_template = FontawesomeSubsetter.configuration.scss_template
+
+      scss_string = if scss_template
+        scss_template.call(@styles)
+      else
+        default_scss_template(styles)
+      end
+
+      # Compile the dynamic SCSS. `load_paths` tells Sass where to find the imported files.
+      compiled_css = Sass.compile_string(scss_string, style: :compressed, load_paths: [ @root ]).css
+
+      # Forcefully remove all comments, including "loud" /*! ... */ comments for licenses.
+      compiled_css = compiled_css.gsub(/\/\*!.*?\*\//m, "")
+
+      # Output to builds folder, which is the standard for Propshaft
+      out_file = @build_dir.join("fontawesome.css")
+      File.write(out_file, compiled_css)
+      puts "[FontSubsetter] wrote #{ out_file } with styles: #{ styles.map { it[:name] }.join(', ') }"
+    end
+
+    def build(files_to_scan = nil)
+      files_to_scan ||= @scan_globs.flat_map { Dir.glob it }
+
+      scan_files_and_update_caches(files_to_scan)
+
+      styles = @styles.values.select { it[:changed] }
+
+      # Rebuild assets only if caches have changed
+      unless styles.empty?
+        subset_webfonts(styles)
+        subset_stylesheets
+        @styles.values.each { it[:changed] = false }
+      end
+    end
+
+    def build_watch
+      require "listen"
+
+      # Initial full scan and build
+      build()
+
+      puts "Starting FontAwesome watch mode..."
+
+      listener = Listen.to(*@watch_paths) do | modified, added, removed |
+
+        # NOTE: At most, it seems to take around 1.7 seconds to subset
+        start_time = Time.now
+
+        puts "Detected changes: modified=#{ modified }, added=#{ added }, removed=#{ removed }"
+
+        # Scan only modified and added files
+        build(modified + added)
+
+        elapsed = Time.now - start_time
+        puts "[FontSubsetter] Total subsetting time: #{ format('%.2f', elapsed) } seconds"
+
+      end
+
+      listener.start
+
+      # Keep the process alive
+      loop do
+
+        sleep 1
+
+      end
+    rescue Interrupt
+      puts "FontAwesome watch stopped"
+      listener&.stop
+    end
+
+    private
+
+    def default_scss_template(styles)
+      <<-SCSS
+
+        // NOTE: $icons and $brand-icons were changed in variables to just be empty arrays with !default.
+        @use "./vendor/fontawesome/scss/variables" with (
+          $font-path: "webfonts",
+          $icons: (#{ @styles.except("brands").values.reduce(Set.new) { | all_icons, style | all_icons.merge(style[:sass_icon_cache]) }.join(", ") }),
+          $brand-icons: (#{ @styles["brands"][:sass_icon_cache].to_a.join(", ") }));
+
+        @use "./vendor/fontawesome/scss/functions";
+        @use "./vendor/fontawesome/scss/mixins";
+        @use "./vendor/fontawesome/scss/core";
+        // @use "./vendor/fontawesome/scss/sizing";
+        // @use "./vendor/fontawesome/scss/widths";
+        // @use "./vendor/fontawesome/scss/list";
+        // @use "./vendor/fontawesome/scss/bordered";
+        @use "./vendor/fontawesome/scss/animated";
+        // @use "./vendor/fontawesome/scss/rotated-flipped";
+        // @use "./vendor/fontawesome/scss/stacked";
+        @use "./vendor/fontawesome/scss/icons";
+
+        #{ styles.map { "@use \"./vendor/fontawesome/scss/#{ it[:name] }.scss\";" }.join("\n") }
+
+      SCSS
+    end
+
+  end
+
+end

data/lib/fontawesome_subsetter/version.rb

@@ -0,0 +1,5 @@
+module FontawesomeSubsetter
+
+  VERSION = "0.1.1"
+
+end

data/lib/fontawesome_subsetter.rb

@@ -0,0 +1,35 @@
+require_relative "fontawesome_subsetter/version"
+require_relative "fontawesome_subsetter/icon_helper"
+require_relative "fontawesome_subsetter/subsetter"
+require_relative "fontawesome_subsetter/engine" if defined?(Rails)
+
+module FontawesomeSubsetter
+
+  class << self
+
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+  end
+
+  class Configuration
+
+    attr_accessor :meta_path, :fonts_dir, :build_dir, :scan_globs, :watch_paths,
+                  :watch_file_type_regex, :icon_regex, :scss_template, :styles
+
+    def initialize
+      @scan_globs = ["app/views/**/*.slim", "app/helpers/**/*.rb"]
+      @watch_file_type_regex = /\.(slim|rb)$/
+      @icon_regex = /icon\(\s*:(?<prefix>fas|far|fab|fad|fal|fat)\s*,\s*:(?<icon>[\w_\-]+)\b/
+    end
+
+  end
+
+end

data/lib/puma/plugin/fontawesome.rb

@@ -0,0 +1,93 @@
+require "puma/plugin"
+
+class Fontawesome
+end
+
+Puma::Plugin.create do
+
+  attr_reader :puma_pid, :fontawesome_pid, :log_writer
+
+  def start(launcher)
+    @log_writer = launcher.log_writer
+    @puma_pid = $PROCESS_ID
+
+    launcher.events.on_booted do
+
+      @fontawesome_pid = fork do
+
+        Thread.new { monitor_puma }
+
+        begin
+          # Set up signal handling for clean shutdown
+          trap("INT") { exit 0 }
+          trap("TERM") { exit 0 }
+
+          require "fontawesome_subsetter"
+          subsetter = FontawesomeSubsetter::Subsetter.new
+          subsetter.build_watch
+        rescue => e
+          @log_writer.log "FontAwesome subsetter error: #{ e.message }"
+          @log_writer.log e.backtrace.join("\n")
+          exit 1
+        end
+
+      end
+
+      in_background do
+
+        monitor_fontawesome
+
+      end
+
+    end
+
+    launcher.events.on_stopped { stop_fontawesome }
+  end
+
+  private
+
+  def stop_fontawesome
+    Process.waitpid(fontawesome_pid, Process::WNOHANG)
+    log "Stopping FontAwesome..."
+    Process.kill(:INT, fontawesome_pid) if fontawesome_pid
+    Process.wait(fontawesome_pid)
+  rescue Errno::ECHILD, Errno::ESRCH
+  end
+
+  def monitor_puma
+    monitor(:puma_dead?, "Detected Puma has gone away, stopping FontAwesome...")
+  end
+
+  def monitor_fontawesome
+    monitor(:fontawesome_dead?, "Detected FontAwesome has gone away, stopping Puma...")
+  end
+
+  def monitor(process_dead, message)
+    loop do
+
+      if send(process_dead)
+        log message
+        Process.kill(:INT, $PROCESS_ID)
+        break
+      end
+      sleep 2
+
+    end
+  end
+
+  def fontawesome_dead?
+    Process.waitpid(fontawesome_pid, Process::WNOHANG)
+    false
+  rescue Errno::ECHILD, Errno::ESRCH
+    true
+  end
+
+  def puma_dead?
+    Process.ppid != puma_pid
+  end
+
+  def log(...)
+    log_writer.log(...)
+  end
+
+end

data/lib/tasks/fontawesome_subsetter.rake

@@ -0,0 +1,15 @@
+namespace :fontawesome do
+
+  desc "Build FontAwesome, subsetting icons and shaking out unused CSS."
+  task :subset do
+    require "fontawesome_subsetter"
+
+    subsetter = FontawesomeSubsetter::Subsetter.new
+    subsetter.build()
+
+    puts "FontAwesome subset build completed successfully!"
+  end
+
+end
+
+Rake::Task["assets:precompile"].enhance(["fontawesome:subset"])

metadata

@@ -0,0 +1,126 @@
+--- !ruby/object:Gem::Specification
+name: fontawesome_subsetter
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- 16554289+optimuspwnius@users.noreply.github.com
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: actionview
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: sass-embedded
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: listen
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: puma
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: Scans your views and helpers for icon() calls, subsets FontAwesome Pro
+  WOFF2 fonts via pyftsubset, and generates minimal CSS. Includes a Puma plugin for
+  development watch mode, a Rails view helper, and a rake task that hooks into assets:precompile.
+email:
+- 16554289+optimuspwnius@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/fontawesome_subsetter.rb
+- lib/fontawesome_subsetter/engine.rb
+- lib/fontawesome_subsetter/icon_helper.rb
+- lib/fontawesome_subsetter/subsetter.rb
+- lib/fontawesome_subsetter/version.rb
+- lib/puma/plugin/fontawesome.rb
+- lib/tasks/fontawesome_subsetter.rake
+homepage: https://github.com/optimuspwnius/fontawesome-subsetter
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/optimuspwnius/fontawesome-subsetter
+  source_code_uri: https://github.com/optimuspwnius/fontawesome-subsetter
+  changelog_uri: https://github.com/optimuspwnius/fontawesome-subsetter/blob/main/CHANGELOG.md
+  allowed_push_host: https://rubygems.org
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.7
+specification_version: 4
+summary: FontAwesome Pro subsetter for Rails — tree-shakes unused icons from font
+  files and CSS.
+test_files: []