isolate_assets 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ac311515e556ca2199cbfdb72559a19bffed148c18184c1ac364e742b31d2d6
-  data.tar.gz: ff9aeb49469e913c4b48c20ee1b82790778410f553606b62f10702a37373623a
+  metadata.gz: b7a0b5e25e5067341e5e3c33c79159bbe1b9fe946efd2683a9c7a1dad13f8d9a
+  data.tar.gz: 9374de1fe6e919a09f742e8d0b483720f9f115e05423487ef88abd3680e1a02c
 SHA512:
-  metadata.gz: 0f25291c4ff1393aa72c764d52492e9baaba70f61880ce31403292b15796120a3f1e751cc53db01a8a9fe2e3eb4524ef20767a60bd739cbe3dc2dd96e0b915e5
-  data.tar.gz: c4aac80bac4d4fc9cf59367afa765024e6f2f3574da76637159875c617a3ddae5b0bbbfd175cd4afad1eed32aae5bb0fa316c53a753045ea738383dcb4401b1c
+  metadata.gz: 98df37ce2970ad2849dced942d34ba434f8e22f4a0590be3fb3b9e693fd557638793f4d88d201b963b2d976d2cefbe7c96c712b67f307c848d7fb89e0c92f325
+  data.tar.gz: '08b88c5fd5862e0ac159c714fef265168554a1d25fbafa60f1aef12cf6e28c34f9b13bd67e74a38f71bdc01458f960a64f904f5a4da802e57b0e1390c946f563'

data/.github/workflows/ci.yml

@@ -4,6 +4,7 @@ jobs:
   test:
     runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
       matrix:
         ruby: ["3.2", "3.3", "3.4", "4.0"]
         gemfile: [rails_7_2, rails_8_0, rails_8_1]

data/README.md

@@ -54,13 +54,44 @@ my_engine/
       stylesheets/
         application.css
         theme.css
+      images/
+        logo.png
+        icons/
+          menu.svg
+      fonts/
+        custom.woff2
 ```
 
 IsolateAssets automatically excludes your engine's `app/assets/` directory from the host app's asset pipeline (Sprockets/Propshaft), so your assets won't conflict with or be processed by the host application.
 
-### 3. Include the helper
+### 3. Use in your views
 
-In your engine's application helper:
+Call helper methods directly on your engine's namespace:
+
+```erb
+<%# Stylesheets %>
+<%= MyEngine.stylesheet_link_tag "application" %>
+
+<%# JavaScript %>
+<%= MyEngine.javascript_include_tag "application" %>
+
+<%# Images %>
+<%= MyEngine.image_tag "logo.png", alt: "Logo" %>
+<%= MyEngine.image_path "icon.svg" %>
+
+<%# Other assets %>
+<%= MyEngine.font_path "custom.woff2" %>
+<%= MyEngine.asset_path "data.json" %>
+
+<%# ES6 import maps with CDN dependencies %>
+<%= MyEngine.javascript_importmap_tags "application", {
+  "jquery" => "https://cdn.jsdelivr.net/npm/jquery@3.7.1/+esm",
+} %>
+```
+
+### Alternative: Include helper for unprefixed access
+
+If you prefer `stylesheet_link_tag` over `MyEngine.stylesheet_link_tag`, include the helper in your engine's ApplicationHelper:
 
 ```ruby
 # app/helpers/my_engine/application_helper.rb
@@ -71,22 +102,32 @@ module MyEngine
 end
 ```
 
-### 4. Use in your views
+Then in views:
 
 ```erb
-<%# Basic stylesheet %>
-<%= engine_stylesheet_link_tag "application" %>
+<%= stylesheet_link_tag "application" %>
+<%= image_tag "logo.png", alt: "Logo" %>
+```
 
-<%# Basic script tag %>
-<%= engine_javascript_include_tag "application" %>
+Note: This shadows Rails' built-in asset helpers within your engine's views.
 
-<%# ES6 import maps with CDN dependencies %>
-<%= engine_javascript_importmap_tags "application", {
-  "jquery" => "https://cdn.jsdelivr.net/npm/jquery@3.7.1/+esm",
-} %>
-```
+### Available helpers
 
-Example output:
+| Helper | Description |
+|--------|-------------|
+| `stylesheet_link_tag(source, **options)` | `<link>` tag for CSS |
+| `javascript_include_tag(source, **options)` | `<script>` tag for JS |
+| `javascript_importmap_tags(entry_point, imports)` | ES6 import map |
+| `image_tag(source, **options)` | `<img>` tag |
+| `image_path(source)` | URL path for images |
+| `asset_path(source)` | URL path for any asset (infers type from extension) |
+| `font_path(source)` | URL path for fonts |
+| `audio_tag(source, **options)` | `<audio>` tag |
+| `audio_path(source)` | URL path for audio |
+| `video_tag(source, **options)` | `<video>` tag |
+| `video_path(source)` | URL path for video |
+
+### Example output
 
 ```html
 <script type="importmap">
@@ -113,6 +154,27 @@ This exclusion relies on filtering `config.assets.paths` after engines register
 isolate_assets assets_subdir: "isolated_assets"  # uses app/isolated_assets/
 ```
 
+## Non-isolated engines
+
+`isolate_assets` assumes `isolate_namespace` and a mounted route set. For an engine that isn't isolated — one that draws its routes directly into the application router — use `IsolateAssets.register` instead, then draw the asset route yourself with whatever path and name you want:
+
+```ruby
+# lib/my_engine.rb
+module MyEngine
+  class Engine < ::Rails::Engine; end
+  Assets = IsolateAssets.register(namespace: self, engine: Engine, route_name: :my_engine_asset)
+end
+```
+
+```ruby
+# config/routes.rb (drawn into the application router)
+Rails.application.routes.draw do
+  MyEngine::Assets.draw(self, "/my_engine/assets")
+end
+```
+
+This gives you the same namespaced helpers as the isolated path — `MyEngine.stylesheet_link_tag "app"`, `MyEngine.javascript_include_tag "app"`, etc. — fingerprinted against your chosen route.
+
 ## Requirements
 
 - Ruby 3.2+

data/features/asset_serving.feature

@@ -15,6 +15,11 @@ Feature: Asset Serving
     And the content type should be "text/css"
     And the response should contain "font-family: sans-serif"
 
+  Scenario: Serving an image file
+    When I request "/dummy/assets/logo.png"
+    Then I should receive a successful response
+    And the content type should be "image/png"
+
   Scenario: Asset fingerprinting
     When I request "/dummy/assets/application.js"
     Then the response should have caching headers

data/features/step_definitions/view_helper_steps.rb

@@ -22,3 +22,12 @@ Then("the import map should include {string}") do |key|
   import_map = JSON.parse(script.text(:all))
   expect(import_map["imports"]).to have_key(key)
 end
+
+Then("the page should have an image tag with src starting with {string}") do |path|
+  expect(page).to have_css("img[src^='#{path}']", visible: false)
+end
+
+Then("the image tag should include a fingerprint parameter") do
+  img = page.find("img", visible: false)
+  expect(img[:src]).to match(/\?v=[a-f0-9]{8}/)
+end

data/features/view_helpers.feature

@@ -12,3 +12,8 @@ Feature: View Helpers
     When I visit the dummy engine root
     Then the page should have an import map
     And the import map should include "dummy/application"
+
+  Scenario: Image tag includes fingerprint
+    When I visit the dummy engine root
+    Then the page should have an image tag with src starting with "/dummy/assets/logo.png"
+    And the image tag should include a fingerprint parameter

data/gemfiles/rails_7_2.gemfile

@@ -10,6 +10,7 @@ group :test do
   gem "rspec", "~> 3.0"
   gem "cucumber", "~> 9.0"
   gem "capybara", "~> 3.0"
+  gem "sprockets-rails"
 end
 
 gemspec path: "../", name: "isolate_assets"

data/gemfiles/rails_8_0.gemfile

@@ -10,6 +10,7 @@ group :test do
   gem "rspec", "~> 3.0"
   gem "cucumber", "~> 9.0"
   gem "capybara", "~> 3.0"
+  gem "sprockets-rails"
 end
 
 gemspec path: "../", name: "isolate_assets"

data/gemfiles/rails_8_1.gemfile

@@ -10,6 +10,7 @@ group :test do
   gem "rspec", "~> 3.0"
   gem "cucumber", "~> 9.0"
   gem "capybara", "~> 3.0"
+  gem "sprockets-rails"
 end
 
 gemspec path: "../", name: "isolate_assets"

data/lib/isolate_assets/assets.rb

@@ -2,26 +2,88 @@
 
 module IsolateAssets
   class Assets
-    attr_reader :engine, :assets_subdir
+    attr_reader :engine, :assets_subdir, :route_name
+    attr_accessor :controller
 
-    def initialize(engine:, assets_subdir: "assets")
+    ASSET_DIRECTORIES = {
+      "js" => "javascripts",
+      "javascript" => "javascripts",
+      "css" => "stylesheets",
+      "stylesheet" => "stylesheets",
+      "png" => "images",
+      "jpg" => "images",
+      "jpeg" => "images",
+      "gif" => "images",
+      "svg" => "images",
+      "webp" => "images",
+      "ico" => "images",
+      "woff" => "fonts",
+      "woff2" => "fonts",
+      "ttf" => "fonts",
+      "otf" => "fonts",
+      "eot" => "fonts",
+      "mp3" => "audio",
+      "ogg" => "audio",
+      "wav" => "audio",
+      "mp4" => "video",
+      "webm" => "video",
+      "ogv" => "video"
+    }.freeze
+
+    CONTENT_TYPES = {
+      "js" => "application/javascript",
+      "javascript" => "application/javascript",
+      "css" => "text/css",
+      "stylesheet" => "text/css",
+      "png" => "image/png",
+      "jpg" => "image/jpeg",
+      "jpeg" => "image/jpeg",
+      "gif" => "image/gif",
+      "svg" => "image/svg+xml",
+      "webp" => "image/webp",
+      "ico" => "image/x-icon",
+      "woff" => "font/woff",
+      "woff2" => "font/woff2",
+      "ttf" => "font/ttf",
+      "otf" => "font/otf",
+      "eot" => "application/vnd.ms-fontobject",
+      "mp3" => "audio/mpeg",
+      "ogg" => "audio/ogg",
+      "wav" => "audio/wav",
+      "mp4" => "video/mp4",
+      "webm" => "video/webm",
+      "ogv" => "video/ogg"
+    }.freeze
+
+    def initialize(engine:, assets_subdir: "assets", route_name: :isolated_asset, url_helpers: nil)
       @engine = engine
       @assets_subdir = assets_subdir
+      @route_name = route_name
+      @url_helpers = url_helpers || -> { engine.routes.url_helpers }
       @fingerprints = {}
     end
 
+    # Draws the catch-all asset route into the given router (the application
+    # router for non-isolated engines, the engine's own for isolated ones).
+    def draw(mapper, path)
+      mapper.get "#{path}/*file", to: controller.action(:show), as: route_name
+    end
+
     def asset_path(source, type)
-      case type.to_s
-      when "js", "javascript"
-        engine.root.join("app/#{assets_subdir}/javascripts", "#{source}.js")
-      when "css", "stylesheet"
-        engine.root.join("app/#{assets_subdir}/stylesheets", "#{source}.css")
-      end
+      directory = ASSET_DIRECTORIES[type.to_s]
+      return nil unless directory
+
+      normalized = normalize_type(type)
+      engine.root.join("app/#{assets_subdir}/#{directory}", "#{source}.#{normalized}")
     end
 
     def asset_url(source, type)
       fingerprint_value = fingerprint(source, type)
-      engine.routes.url_helpers.isolated_asset_path("#{source}.#{normalize_type(type)}", v: fingerprint_value)
+      @url_helpers.call.public_send(
+        "#{route_name}_path",
+        "#{source}.#{normalize_type(type)}",
+        v: fingerprint_value,
+      )
     end
 
     def fingerprint(source, type)
@@ -35,14 +97,7 @@ module IsolateAssets
     end
 
     def content_type(type)
-      case type.to_s
-      when "js", "javascript"
-        "application/javascript"
-      when "css", "stylesheet"
-        "text/css"
-      else
-        "application/octet-stream"
-      end
+      CONTENT_TYPES[type.to_s] || "application/octet-stream"
     end
 
     def javascript_files

data/lib/isolate_assets/engine_extension.rb

@@ -5,8 +5,10 @@ module IsolateAssets
     def isolate_assets(assets_subdir: "assets")
       engine_class = self
 
-      # Exclude engine assets from host's asset pipeline
+      # Exclude engine assets from host's asset pipeline (if one exists)
       initializer "#{engine_name}.isolate_assets.exclude_from_pipeline", before: :load_config_initializers do |app|
+        next unless app.config.respond_to?(:assets) && app.config.assets
+
         asset_base = engine_class.root.join("app", assets_subdir)
         app.config.assets.excluded_paths ||= []
         if asset_base.exist?
@@ -18,29 +20,21 @@ module IsolateAssets
 
       # Sprockets doesn't respect excluded_paths, so filter manually
       initializer "#{engine_name}.isolate_assets.filter_asset_paths", after: :load_config_initializers do |app|
-        if app.config.assets.excluded_paths.present?
-          excluded = app.config.assets.excluded_paths.map(&:to_s)
-          app.config.assets.paths = app.config.assets.paths.reject do |path|
-            excluded.include?(path.to_s)
-          end
+        next unless app.config.respond_to?(:assets) && app.config.assets
+        next unless app.config.assets.excluded_paths.present?
+
+        excluded = app.config.assets.excluded_paths.map(&:to_s)
+        app.config.assets.paths = app.config.assets.paths.reject do |path|
+          excluded.include?(path.to_s)
         end
       end
 
       initializer "#{engine_name}.isolate_assets", before: :set_routes_reloader do
         assets = IsolateAssets::Assets.new(engine: engine_class, assets_subdir: assets_subdir)
+        controller_class = IsolateAssets.build_controller(assets)
 
-        # Subclass the controller so that multiple engines using this gem get their own controller
-        controller_class = Class.new(IsolateAssets::Controller)
-        controller_class.isolated_assets = assets
-
-        # Hack in the helpers. There's gotta be a better way than this...
-        helper_module = Module.new do
-          define_method(:isolated_assets) { assets }
-          include IsolateAssets::Helper
-        end
         if engine_class.respond_to?(:railtie_namespace) && engine_class.railtie_namespace
-          engine_class.railtie_namespace.singleton_class.define_method(:isolated_assets) { assets }
-          engine_class.railtie_namespace.singleton_class.define_method(:isolated_assets_helper) { helper_module }
+          IsolateAssets.expose_helpers(engine_class.railtie_namespace, assets)
         end
 
         engine_class.routes.prepend do

data/lib/isolate_assets/helper.rb

@@ -2,40 +2,33 @@
 
 module IsolateAssets
   module Helper
+    include ActionView::Helpers::TagHelper
+    include ActionView::Helpers::AssetTagHelper
+
     # Note: isolated_assets method is defined by the including module,
     # created dynamically in EngineExtension#isolate_assets
 
-    def engine_asset_url(source, type)
-      fingerprint_value = isolated_assets.fingerprint(source, type)
-      normalized_type = case type.to_s
-      when "javascript" then "js"
-      when "stylesheet" then "css"
-      else type.to_s
-      end
-      isolated_asset_path("#{source}.#{normalized_type}", v: fingerprint_value)
-    end
-
-    def engine_stylesheet_link_tag(source, **options)
+    def stylesheet_link_tag(source, **options)
       tag.link(
         rel: "stylesheet",
-        href: engine_asset_url(source, "css"),
+        href: isolated_assets.asset_url(source, "css"),
         **options
       )
     end
 
-    def engine_javascript_include_tag(source, **options)
+    def javascript_include_tag(source, **options)
       tag.script(
-        src: engine_asset_url(source, "js"),
+        src: isolated_assets.asset_url(source, "js"),
         **options
       )
     end
 
-    def engine_javascript_importmap_tags(entry_point = "application", imports = {})
+    def javascript_importmap_tags(entry_point = "application", imports = {})
       assets_root = isolated_assets.engine.root.join("app/#{isolated_assets.assets_subdir}/javascripts")
       engine_imports = isolated_assets.javascript_files.each_with_object({}) do |path, hash|
         relative_path = path.relative_path_from(assets_root).to_s
         key = "#{isolated_assets.engine.engine_name}/#{relative_path.sub(/\.js\z/, "")}"
-        hash[key] = engine_asset_url(relative_path.sub(/\.js\z/, ""), "js")
+        hash[key] = isolated_assets.asset_url(relative_path.sub(/\.js\z/, ""), "js")
       end
       [
         tag.script(type: "importmap") do
@@ -46,5 +39,28 @@ module IsolateAssets
         JS
       ].join("\n").html_safe
     end
+
+    def asset_path(source)
+      ext = File.extname(source).delete_prefix(".")
+      source_without_ext = source.sub(/\.#{Regexp.escape(ext)}\z/, "")
+      isolated_assets.asset_url(source_without_ext, ext)
+    end
+
+    alias_method :image_path, :asset_path
+    alias_method :font_path, :asset_path
+    alias_method :audio_path, :asset_path
+    alias_method :video_path, :asset_path
+
+    def image_tag(source, **options)
+      tag.img(src: image_path(source), **options)
+    end
+
+    def audio_tag(source, **options)
+      tag.audio(src: audio_path(source), **options)
+    end
+
+    def video_tag(source, **options)
+      tag.video(src: video_path(source), **options)
+    end
   end
 end

data/lib/isolate_assets/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module IsolateAssets
-  VERSION = "0.2.0"
+  VERSION = "0.4.0"
 end

data/lib/isolate_assets.rb

@@ -9,6 +9,55 @@ module IsolateAssets
   autoload :Controller, "isolate_assets/controller"
   autoload :Helper, "isolate_assets/helper"
   autoload :EngineExtension, "isolate_assets/engine_extension"
+
+  HELPER_METHODS = %i[
+    stylesheet_link_tag javascript_include_tag javascript_importmap_tags
+    asset_path image_path image_tag font_path audio_path audio_tag video_path video_tag
+  ].freeze
+
+  # Wires up an engine that draws its asset route into the application router
+  # rather than mounting an isolated route set. Returns the Assets handle; draw
+  # the route from the engine's routes file with `assets.draw(self, path)`.
+  def self.register(namespace:, engine:, route_name:, assets_subdir: "assets")
+    assets = Assets.new(
+      engine: engine,
+      assets_subdir: assets_subdir,
+      route_name: route_name,
+      url_helpers: -> { Rails.application.routes.url_helpers },
+    )
+    build_controller(assets)
+    expose_helpers(namespace, assets)
+    assets
+  end
+
+  def self.build_controller(assets)
+    controller = Class.new(Controller)
+    controller.isolated_assets = assets
+    assets.controller = controller
+    controller
+  end
+
+  # Defines isolated_assets + the asset tag helpers (stylesheet_link_tag, etc.)
+  # as singleton methods on the given module, e.g. Dummy.stylesheet_link_tag.
+  def self.expose_helpers(namespace, assets)
+    helper_module = Module.new do
+      define_method(:isolated_assets) { assets }
+      include Helper
+    end
+    namespace.singleton_class.define_method(:isolated_assets) { assets }
+    namespace.singleton_class.define_method(:isolated_assets_helper) { helper_module }
+
+    helper_context = Class.new do
+      include Helper
+      define_method(:isolated_assets) { assets }
+    end.new
+    HELPER_METHODS.each do |method_name|
+      namespace.singleton_class.define_method(method_name) do |*args, **kwargs, &block|
+        helper_context.send(method_name, *args, **kwargs, &block)
+      end
+    end
+    helper_module
+  end
 end
 
 # Extend Rails::Engine with isolate_assets

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: isolate_assets
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Micah Geisel
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-01-10 00:00:00.000000000 Z
+date: 2026-06-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties