isolate_assets 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b42e51e51aa619c08d02e6d2e7c02aca58aab0cbab94b7d629449940bb2d32df
-  data.tar.gz: a5872849a66dd7b213a3341e6e905af3403b1d66bf2d00c911e137b8b9411fd5
+  metadata.gz: dc92b30bb9f88b0d8f12eb3ed349f6a6f1f9decbe87a675b7200e70c8c9bd611
+  data.tar.gz: 5aa6ea46f8f8b348f913b1656a6187c3e0875536edb066929f453d997abf7186
 SHA512:
-  metadata.gz: 03bce00b9fb6117c4c0e2b202e38a99dd37b89dd60d4f767f94d3a7ca253d4b48dbd5da62d83852f054ded4466151cdc6c4aa65e20ad96564e65e806f7414dea
-  data.tar.gz: af6aae32f9f05cac171c7e9f761f877ae07afa7419656bf6996424e2c474ab082cb431794e7b339b7e43d9c9744e6341e2183d36b0654638e134088586746113
+  metadata.gz: 3bb014e542b5067a9b5543f0ae6c6a1c14e8578b1b6f8dbe2d717c304f4798ff11e7293baab555bcdcddba0162067ee172b6ccd6ddf5b92d25dfeb0bc18c2c94
+  data.tar.gz: 96bedf91563d0e5cbea9ac08075e3b5611bdd61a8275fa366058420a7dacbeed2c04845f7c7cce7b424453a2e0638ba0879f403f168cdce2309d38ba67228e59

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

@@ -41,12 +41,12 @@ end
 
 ### 2. Add your assets
 
-Place assets in `app/engine_assets/`:
+Place assets in the standard `app/assets/` directory:
 
 ```
 my_engine/
   app/
-    engine_assets/
+    assets/
       javascripts/
         application.js
         components/
@@ -54,11 +54,44 @@ my_engine/
       stylesheets/
         application.css
         theme.css
+      images/
+        logo.png
+        icons/
+          menu.svg
+      fonts/
+        custom.woff2
 ```
 
-### 3. Include the helper
+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.
 
-In your engine's application helper:
+### 3. Use in your views
+
+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
@@ -69,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
+
+| 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:
+### Example output
 
 ```html
 <script type="importmap">
@@ -101,6 +144,16 @@ Example output:
 </script>
 ```
 
+## How it works
+
+IsolateAssets automatically excludes your engine's asset directories from `config.assets.paths`, so Sprockets, Propshaft, and dartsass-rails won't process them. Your assets are served exclusively through the isolate_assets controller with their own fingerprinting and caching.
+
+This exclusion relies on filtering `config.assets.paths` after engines register their directories. While this works with current Rails asset tools, future versions could change path discovery. For guaranteed isolation, use a non-standard directory:
+
+```ruby
+isolate_assets assets_subdir: "isolated_assets"  # uses app/isolated_assets/
+```
+
 ## 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

@@ -4,19 +4,68 @@ module IsolateAssets
   class Assets
     attr_reader :engine, :assets_subdir
 
-    def initialize(engine:, assets_subdir: "engine_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")
       @engine = engine
       @assets_subdir = assets_subdir
       @fingerprints = {}
     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)
@@ -35,14 +84,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

@@ -2,32 +2,71 @@
 
 module IsolateAssets
   module EngineExtension
-    def isolate_assets(assets_subdir: "engine_assets")
+    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
+
+    def isolate_assets(assets_subdir: "assets")
       engine_class = self
 
-      # Create a unique controller class for this engine
-      controller_class = Class.new(IsolateAssets::Controller)
+      # 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?
+          asset_base.children.select(&:directory?).each do |subdir|
+            app.config.assets.excluded_paths << subdir.to_s
+          end
+        end
+      end
+
+      # Sprockets doesn't respect excluded_paths, so filter manually
+      initializer "#{engine_name}.isolate_assets.filter_asset_paths", after: :load_config_initializers do |app|
+        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
 
-      # Register an initializer to set up assets when Rails boots
       initializer "#{engine_name}.isolate_assets", before: :set_routes_reloader do
         assets = IsolateAssets::Assets.new(engine: engine_class, assets_subdir: assets_subdir)
 
-        # Create a unique helper module for this engine with the assets baked in
+        # 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
+
+        # Create helper module for inclusion in engine's ApplicationHelper
         helper_module = Module.new do
           define_method(:isolated_assets) { assets }
           include IsolateAssets::Helper
         end
 
-        # Wire up the controller
-        controller_class.isolated_assets = assets
-
-        # Store on the engine's namespace module
         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 }
+          namespace = engine_class.railtie_namespace
+
+          # Expose isolated_assets and helper module
+          namespace.singleton_class.define_method(:isolated_assets) { assets }
+          namespace.singleton_class.define_method(:isolated_assets_helper) { helper_module }
+
+          # Define helper methods directly on namespace (e.g., Dummy.stylesheet_link_tag)
+          helper_context = Class.new do
+            include IsolateAssets::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
         end
 
-        # Draw routes
         engine_class.routes.prepend do
           get "/assets/*file", to: controller_class.action(:show), as: :isolated_asset
         end

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.1.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: isolate_assets
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Micah Geisel