Hanami::Sprockets

Drop-in replacement for hanami-assets that uses Sprockets (like Rails) instead of npm/Node.js.

If you want the Rails asset pipeline in your Hanami app without dealing with npm, this is for you.

What you get

Rails-style Sprockets asset pipeline
No npm/package.json required
Works with existing Sprockets gems (sassc-rails, coffee-rails, etc.)
Same API as hanami-assets
Asset fingerprinting and precompilation
Development middleware for serving assets

Installation

Add this line to your application's Gemfile:

gem 'hanami-sprockets'

And then execute:

bundle install

Basic Usage

Configuration

require 'hanami-sprockets'

# Basic configuration
config = Hanami::Assets::Config.new(
  path_prefix: "/assets",
  digest: true,  # Enable fingerprinting for production
  subresource_integrity: [:sha256]  # Enable SRI
)

# Create assets instance
assets = Hanami::Assets.new(
  config: config,
  root: "/path/to/your/app"
)

Asset Structure

Follow Rails conventions:

app/
├── assets/
│   ├── stylesheets/
│   │   └── app.css
│   ├── javascripts/
│   │   └── app.js
│   └── images/
│       └── logo.png
├── lib/
│   └── assets/
└── vendor/
    └── assets/

CSS Image References

Reference images in CSS using ERB and the asset_path helper:

/* app.css.erb */
.header {
  background-image: url('<%= asset_path("logo.png") %>');
}

This generates fingerprinted URLs automatically in production. Plain CSS with relative paths also works:

/* Plain CSS */
.simple {
  background-image: url('../images/logo.png');
}

Development Server

Add the middleware to your Rack stack:

use Hanami::Assets::Middleware, assets

Using Assets

# Get an asset
asset = assets["app.css"]
puts asset.url  # => "/assets/app-abc123def.css"
puts asset.path # => "/assets/app-abc123def.css"
puts asset.sri  # => "sha256-..."

# Check if asset exists
begin
  asset = assets["missing.css"]
rescue Hanami::Assets::AssetMissingError
  puts "Asset not found"
end

Template Helpers

Include the helpers in your templates:

class MyView
  include Hanami::Assets::Helpers

  private

  def hanami_assets
    @hanami_assets # Inject your assets instance
  end
end

Then use them in templates:

<!DOCTYPE html>
<html>
<head>
  <%= stylesheet_tag "reset", "app" %>
</head>
<body>
  <%= image_tag "logo", alt: "Logo" %>
  <%= javascript_tag "app", async: true %>
</body>
</html>

Precompilation

For production:

# Precompile assets
manifest = assets.precompile("/path/to/public/assets")
puts "Compiled assets:", manifest.assets.keys

Command Line Interface

The gem includes CLI commands similar to Hanami's asset commands:

Compile Assets

Compile assets for production deployment:

bundle exec hanami-sprockets compile

With custom output directory:

bundle exec hanami-sprockets compile -o public/dist

Watch Assets

Watch assets for changes during development:

bundle exec hanami-sprockets watch

The watch command monitors your asset directories for changes and automatically recompiles when files are modified. Requires the listen gem to be available.

CLI Options

Usage: hanami-sprockets [COMMAND] [OPTIONS]

Commands:
  compile    Compile assets for production
  watch      Watch assets for changes and recompile

Options:
  -r, --root ROOT      Application root directory
  -o, --output OUTPUT  Output directory for compiled assets
  -h, --help           Show help message

Integration with Hanami CLI

When used within a Hanami application, hanami-sprockets provides command classes that can be automatically discovered by Hanami's CLI system. This allows you to use:

# Instead of hanami-sprockets compile
hanami assets compile

# Instead of hanami-sprockets watch
hanami assets watch

These commands integrate seamlessly with Hanami's application structure and automatically discover your app's configuration. The gem provides compatible command classes in the Hanami::CLI::Commands::App::Assets namespace that follow Hanami's CLI conventions.

Advanced Configuration

config = Hanami::Assets::Config.new do |config|
  config.path_prefix = "/assets"
  config.digest = Rails.env.production?
  config.compress = Rails.env.production?
  config.subresource_integrity = [:sha256, :sha512]
  config.base_url = ENV['CDN_URL'] # For CDN support
  config.asset_paths = [
    "vendor/assets/custom",
    "lib/special_assets"
  ]
  config.precompile = %w[
    app.js
    app.css
    *.png
    *.jpg
    *.svg
  ]
end

Adding processors

Just add the gems you want:

gem 'sassc-rails'      # SCSS/Sass
gem 'coffee-rails'     # CoffeeScript
gem 'uglifier'         # JS compression

Development vs Production

Development: Assets served on-demand via middleware
Production: Precompile assets with assets.precompile("/path/to/public/assets")

API Reference

Hanami::Assets

Main class for asset management.

Methods

#[](path) - Find and return an asset
#precompile(target_dir) - Precompile assets for production
#logical_paths - Get all available asset paths
#subresource_integrity? - Check if SRI is enabled
#crossorigin?(url) - Check if URL is cross-origin

Hanami::Assets::Asset

Represents a single asset.

Asset Methods

#url - Full URL to asset
#path - Path to asset (without base URL)
#sri - Subresource integrity hash
#logical_path - Original path without fingerprint
#digest_path - Fingerprinted path

Hanami::Assets::Helpers

Template helpers for generating asset HTML tags.

Helper Methods

stylesheet_tag(*sources, **options) - Generate <link> tags
javascript_tag(*sources, **options) - Generate <script> tags
image_tag(source, **options) - Generate <img> tags
asset_url(source) - Get URL for asset
asset_path(source) - Get path for asset

License

The gem is available as open source under the terms of the MIT License.