isolate_assets 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b42e51e51aa619c08d02e6d2e7c02aca58aab0cbab94b7d629449940bb2d32df
+  data.tar.gz: a5872849a66dd7b213a3341e6e905af3403b1d66bf2d00c911e137b8b9411fd5
+SHA512:
+  metadata.gz: 03bce00b9fb6117c4c0e2b202e38a99dd37b89dd60d4f767f94d3a7ca253d4b48dbd5da62d83852f054ded4466151cdc6c4aa65e20ad96564e65e806f7414dea
+  data.tar.gz: af6aae32f9f05cac171c7e9f761f877ae07afa7419656bf6996424e2c474ab082cb431794e7b339b7e43d9c9744e6341e2183d36b0654638e134088586746113

data/.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: CI
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby: ["3.2", "3.3", "3.4", "4.0"]
+        gemfile: [rails_7_2, rails_8_0, rails_8_1]
+
+    env:
+      BUNDLE_GEMFILE: gemfiles/${{ matrix.gemfile }}.gemfile
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - name: Run tests
+        run: bundle exec rake

data/Appraisals

@@ -0,0 +1,11 @@
+appraise "rails-7-2" do
+  gem "rails", "~> 7.2.0"
+end
+
+appraise "rails-8-0" do
+  gem "rails", "~> 8.0.0"
+end
+
+appraise "rails-8-1" do
+  gem "rails", "~> 8.1.0"
+end

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Micah Geisel
+
+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,111 @@
+# IsolateAssets
+
+Self-contained asset serving for Rails engines. Serve JavaScript, CSS, and other assets from your engine without depending on Sprockets, Propshaft, or the host application's asset pipeline.
+
+## Why?
+
+Rails engines that include UI components need to serve assets, but integrating with the host app's asset pipeline is problematic:
+
+- **Sprockets/Propshaft conflicts** - Different versions, configurations, or the host might not use them at all
+- **Webpacker/esbuild/Vite** - Modern setups don't expect engine assets
+- **Configuration burden** - Users must manually configure asset paths
+- **Version compatibility** - Asset pipeline APIs change between Rails versions
+
+IsolateAssets solves this by letting your engine serve its own assets through a simple controller, with fingerprinting and caching handled automatically.
+
+## Installation
+
+Add to your engine's gemspec:
+
+```ruby
+spec.add_dependency "isolate_assets"
+```
+
+## Usage
+
+### 1. Set up your engine
+
+In your engine file, add `isolate_assets` alongside `isolate_namespace`:
+
+```ruby
+# lib/my_engine/engine.rb
+require "isolate_assets"
+
+module MyEngine
+  class Engine < ::Rails::Engine
+    isolate_namespace MyEngine
+    isolate_assets
+  end
+end
+```
+
+### 2. Add your assets
+
+Place assets in `app/engine_assets/`:
+
+```
+my_engine/
+  app/
+    engine_assets/
+      javascripts/
+        application.js
+        components/
+          widget.js
+      stylesheets/
+        application.css
+        theme.css
+```
+
+### 3. Include the helper
+
+In your engine's application helper:
+
+```ruby
+# app/helpers/my_engine/application_helper.rb
+module MyEngine
+  module ApplicationHelper
+    include MyEngine.isolated_assets_helper
+  end
+end
+```
+
+### 4. Use in your views
+
+```erb
+<%# Basic stylesheet %>
+<%= engine_stylesheet_link_tag "application" %>
+
+<%# Basic script tag %>
+<%= engine_javascript_include_tag "application" %>
+
+<%# ES6 import maps with CDN dependencies %>
+<%= engine_javascript_importmap_tags "application", {
+  "jquery" => "https://cdn.jsdelivr.net/npm/jquery@3.7.1/+esm",
+} %>
+```
+
+Example output:
+
+```html
+<script type="importmap">
+{
+  "imports": {
+    "jquery": "https://cdn.jsdelivr.net/npm/jquery@3.7.1/+esm",
+    "my_engine/application": "/my_engine/assets/application.js?v=a1b2c3d4",
+    "my_engine/components/widget": "/my_engine/assets/components/widget.js?v=e5f6g7h8"
+  }
+}
+</script>
+<script type="module">
+  import "my_engine/application"
+</script>
+```
+
+## Requirements
+
+- Ruby 3.2+
+- Rails 7.2+
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "cucumber/rake/task"
+
+RSpec::Core::RakeTask.new(:spec)
+Cucumber::Rake::Task.new(:cucumber)
+
+task default: [:spec, :cucumber]

data/cucumber.yml

@@ -0,0 +1 @@
+default: --publish-quiet

data/features/asset_serving.feature

@@ -0,0 +1,28 @@
+Feature: Asset Serving
+  As a Rails engine developer
+  I want to serve JavaScript and CSS assets from my engine
+  So that my engine's UI works without depending on the host app's asset pipeline
+
+  Scenario: Serving a JavaScript file
+    When I request "/dummy/assets/application.js"
+    Then I should receive a successful response
+    And the content type should be "application/javascript"
+    And the response should contain "Dummy engine loaded"
+
+  Scenario: Serving a CSS file
+    When I request "/dummy/assets/application.css"
+    Then I should receive a successful response
+    And the content type should be "text/css"
+    And the response should contain "font-family: sans-serif"
+
+  Scenario: Asset fingerprinting
+    When I request "/dummy/assets/application.js"
+    Then the response should have caching headers
+
+  Scenario: Missing asset returns 404
+    When I request "/dummy/assets/nonexistent.js"
+    Then I should receive a not found response
+
+  Scenario: Path traversal is blocked
+    When I request "/dummy/assets/../../lib/dummy.rb"
+    Then I should receive a not found response

data/features/step_definitions/asset_steps.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+When("I request {string}") do |path|
+  visit path
+end
+
+Then("I should receive a successful response") do
+  expect(page.status_code).to eq(200)
+end
+
+Then("I should receive a not found response") do
+  expect(page.status_code).to eq(404)
+end
+
+Then("the content type should be {string}") do |content_type|
+  expect(page.response_headers["Content-Type"]).to include(content_type)
+end
+
+Then("the response should contain {string}") do |text|
+  expect(page.body).to include(text)
+end
+
+Then("the response should have caching headers") do
+  expect(page.response_headers["Cache-Control"]).to match(/max-age=\d+/)
+  expect(page.response_headers["Cache-Control"]).to include("public")
+  expect(page.response_headers["ETag"]).to be_present
+end

data/features/step_definitions/view_helper_steps.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+When("I visit the dummy engine root") do
+  visit "/dummy"
+end
+
+Then("the page should have a stylesheet link to {string}") do |path|
+  expect(page).to have_css("link[rel='stylesheet'][href^='#{path}']", visible: false)
+end
+
+Then("the stylesheet link should include a fingerprint parameter") do
+  link = page.find("link[rel='stylesheet']", visible: false)
+  expect(link[:href]).to match(/\?v=[a-f0-9]{8}/)
+end
+
+Then("the page should have an import map") do
+  expect(page).to have_css("script[type='importmap']", visible: false)
+end
+
+Then("the import map should include {string}") do |key|
+  script = page.find("script[type='importmap']", visible: false)
+  import_map = JSON.parse(script.text(:all))
+  expect(import_map["imports"]).to have_key(key)
+end

data/features/support/env.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
+
+ENV["RAILS_ENV"] = "test"
+require_relative "../../spec/dummy_host/config/environment"
+
+require "capybara/cucumber"
+
+Capybara.app = Rails.application

data/features/view_helpers.feature

@@ -0,0 +1,14 @@
+Feature: View Helpers
+  As a Rails engine developer
+  I want view helpers to generate asset tags
+  So that I can easily include my engine's assets in views
+
+  Scenario: Stylesheet link tag includes fingerprint
+    When I visit the dummy engine root
+    Then the page should have a stylesheet link to "/dummy/assets/application.css"
+    And the stylesheet link should include a fingerprint parameter
+
+  Scenario: Import map includes engine JavaScript files
+    When I visit the dummy engine root
+    Then the page should have an import map
+    And the import map should include "dummy/application"

data/gemfiles/rails_7_2.gemfile

@@ -0,0 +1,15 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rake", "~> 13.0"
+gem "appraisal"
+gem "rails", "~> 7.2.0"
+
+group :test do
+  gem "rspec", "~> 3.0"
+  gem "cucumber", "~> 9.0"
+  gem "capybara", "~> 3.0"
+end
+
+gemspec path: "../", name: "isolate_assets"

data/gemfiles/rails_8_0.gemfile

@@ -0,0 +1,15 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rake", "~> 13.0"
+gem "appraisal"
+gem "rails", "~> 8.0.0"
+
+group :test do
+  gem "rspec", "~> 3.0"
+  gem "cucumber", "~> 9.0"
+  gem "capybara", "~> 3.0"
+end
+
+gemspec path: "../", name: "isolate_assets"

data/gemfiles/rails_8_1.gemfile

@@ -0,0 +1,15 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rake", "~> 13.0"
+gem "appraisal"
+gem "rails", "~> 8.1.0"
+
+group :test do
+  gem "rspec", "~> 3.0"
+  gem "cucumber", "~> 9.0"
+  gem "capybara", "~> 3.0"
+end
+
+gemspec path: "../", name: "isolate_assets"

data/lib/isolate_assets/assets.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module IsolateAssets
+  class Assets
+    attr_reader :engine, :assets_subdir
+
+    def initialize(engine:, assets_subdir: "engine_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
+    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)
+    end
+
+    def fingerprint(source, type)
+      cache_key = "#{source}.#{type}"
+
+      if ::Rails.env.production?
+        @fingerprints[cache_key] ||= calculate_fingerprint(source, type)
+      else
+        calculate_fingerprint(source, type)
+      end
+    end
+
+    def content_type(type)
+      case type.to_s
+      when "js", "javascript"
+        "application/javascript"
+      when "css", "stylesheet"
+        "text/css"
+      else
+        "application/octet-stream"
+      end
+    end
+
+    def javascript_files
+      engine.root.glob("app/#{assets_subdir}/javascripts/**/*.js")
+    end
+
+    private
+
+    def normalize_type(type)
+      case type.to_s
+      when "javascript" then "js"
+      when "stylesheet" then "css"
+      else type.to_s
+      end
+    end
+
+    def calculate_fingerprint(source, type)
+      file_path = asset_path(source, type)
+
+      if file_path && File.exist?(file_path)
+        Digest::SHA256.file(file_path).hexdigest[0...8]
+      else
+        "missing"
+      end
+    end
+  end
+end

data/lib/isolate_assets/controller.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module IsolateAssets
+  class Controller < ActionController::API
+    include ActionController::MimeResponds
+
+    class_attribute :isolated_assets
+
+    def show
+      file_path = safe_file_path
+
+      if file_path && File.exist?(file_path)
+        expires_in 1.year, public: true
+        fresh_when(etag: File.mtime(file_path), public: true)
+
+        send_file file_path,
+          type: content_type,
+          disposition: "inline"
+      else
+        head :not_found
+      end
+    end
+
+    private
+
+    def safe_file_path
+      requested = params[:file].gsub("..", "")
+      format = params[:format] || request.format.symbol.to_s
+      isolated_assets.asset_path(requested, format)
+    end
+
+    def content_type
+      format = params[:format] || request.format.symbol.to_s
+      isolated_assets.content_type(format)
+    end
+  end
+end

data/lib/isolate_assets/engine_extension.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module IsolateAssets
+  module EngineExtension
+    def isolate_assets(assets_subdir: "engine_assets")
+      engine_class = self
+
+      # Create a unique controller class for this engine
+      controller_class = Class.new(IsolateAssets::Controller)
+
+      # 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
+        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 }
+        end
+
+        # Draw routes
+        engine_class.routes.prepend do
+          get "/assets/*file", to: controller_class.action(:show), as: :isolated_asset
+        end
+      end
+    end
+  end
+end

data/lib/isolate_assets/helper.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module IsolateAssets
+  module Helper
+    # 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)
+      tag.link(
+        rel: "stylesheet",
+        href: engine_asset_url(source, "css"),
+        **options
+      )
+    end
+
+    def engine_javascript_include_tag(source, **options)
+      tag.script(
+        src: engine_asset_url(source, "js"),
+        **options
+      )
+    end
+
+    def engine_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")
+      end
+      [
+        tag.script(type: "importmap") do
+          JSON.pretty_generate({"imports" => imports.merge(engine_imports)}).html_safe
+        end,
+        tag.script(<<~JS.html_safe, type: "module")
+          import "#{isolated_assets.engine.engine_name}/#{entry_point}"
+        JS
+      ].join("\n").html_safe
+    end
+  end
+end

data/lib/isolate_assets/version.rb

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

data/lib/isolate_assets.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "digest/sha2"
+require "active_support/core_ext/class/attribute"
+require_relative "isolate_assets/version"
+
+module IsolateAssets
+  autoload :Assets, "isolate_assets/assets"
+  autoload :Controller, "isolate_assets/controller"
+  autoload :Helper, "isolate_assets/helper"
+  autoload :EngineExtension, "isolate_assets/engine_extension"
+end
+
+# Extend Rails::Engine with isolate_assets
+Rails::Engine.extend(IsolateAssets::EngineExtension)

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: isolate_assets
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Micah Geisel
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-01-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+description: Serve JavaScript, CSS, and other assets from your Rails engine without
+  depending on Sprockets, Propshaft, or the host application's asset pipeline.
+email:
+- micah@botandrose.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- Appraisals
+- LICENSE
+- README.md
+- Rakefile
+- cucumber.yml
+- features/asset_serving.feature
+- features/step_definitions/asset_steps.rb
+- features/step_definitions/view_helper_steps.rb
+- features/support/env.rb
+- features/view_helpers.feature
+- gemfiles/rails_7_2.gemfile
+- gemfiles/rails_8_0.gemfile
+- gemfiles/rails_8_1.gemfile
+- lib/isolate_assets.rb
+- lib/isolate_assets/assets.rb
+- lib/isolate_assets/controller.rb
+- lib/isolate_assets/engine_extension.rb
+- lib/isolate_assets/helper.rb
+- lib/isolate_assets/version.rb
+homepage: https://github.com/botandrose/isolate_assets
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/botandrose/isolate_assets
+  source_code_uri: https://github.com/botandrose/isolate_assets
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Self-contained asset serving for Rails engines
+test_files: []