Hanami::Assets

Assets management for Ruby web projects

Status

Contact

Home page: http://hanamirb.org
Community: http://hanamirb.org/community
Guides: https://guides.hanamirb.org
Mailing List: http://hanamirb.org/mailing-list
API Doc: http://rubydoc.info/gems/hanami-assets
Forum: https://discourse.hanamirb.org
Chat: http://chat.hanamirb.org

Installation

Hanami::Assets supports Ruby (MRI) 3.1+

Add this line to your application's Gemfile:

gem "hanami-assets"

And then execute:

$ bundle

Or install it yourself as:

$ gem install hanami-assets

Usage

Command Line (CLI)

During development run bundle exec hanami server. Your app will start the assets management.

Helpers

Hanami Assets provides asset-specific helpers to be used in templates. They resolve one or multiple sources into corresponding HTML tags. Those sources can be either a name of a local asset or an absolute URL.

Given the following template:

<!doctype HTML>
<html>
  <head>
    <title>Assets example</title>
    <%= stylesheet_tag "reset", "app" %>
  </head>

  <body>
  <!-- ... -->
  <%= javascript_tag "app" %>
  <%= javascript_tag "https://cdn.somethirdparty.script/foo.js", async: true %>
  </body>
</html>

It will output this markup:

<!doctype HTML>
<html>
  <head>
    <title>Assets example</title>
    <link href="/assets/reset.css" type="text/css" rel="stylesheet">
    <link href="/assets/app.css" type="text/css" rel="stylesheet">
  </head>

  <body>
  <!-- ... -->
  <script src="/assets/app.js" type="text/javascript"></script>
  <script src="https://cdn.somethirdparty.script/foo.js" type="text/javascript" async></script>
  </body>
</html>

Available Helpers

The hanami gem ships with the following helpers for assets:

asset_url
javascript_tag
stylesheet_tag
favicon_tag
image_tag
video_tag
audio_tag
path_tag

App Structure

Hanami applications are generated via hanami new CLI command.

Among other directories, it generates a specific structure for assets:

$ tree app/assets
├── images
│   └── favicon.ico
├── js
│   └── app.ts
└── css
    └── app.css

Entry Points

Entry Points are the JavaScript files or modules that serve as the starting points of your application. They define the scope of your bundling process and determine which parts of your code will be included in the final output. By understanding the dependencies of your entry points, Hanami Assets can create efficient and optimized bundles for your JavaScript or TypeScript applications.

When Hanami Assets encounters an import or require statement for an asset, it process the asset file to the output directory. This process includes any kind of asset: other JavaScript files, stylesheets, images referenced from the Entry Point.

The default entry points are:

app/assets/js/app.ts
slices/[slice-name]/assets/js/app.ts

You can specify custom Entry Points, by adding an app.{js,ts,mjs,mts,tsx,jsx} file into the assets directory of the app or a slice.

An example is: app/assets/js/login/app.ts to define a new Entry Point for a Login page where you want to have a more lightweight bundle.

Static Assets

Except for js and css directories, all the other directories are considered static. Their files will be copied as they are to the destination directory.

If you have a custom directory app/assets/fonts, all the fonts are copied to the destination direcotry.

Destination Directory

The destination directory is public/assets.

Deployment

To process the assets during deployment run bundle exec hanami assets compile.

The destination directory will contain the processed assets with an hashed name.

Fingerprint Mode

Asset fingerprinting is a technique that involves adding a unique identifier to the filenames of static assets to ensure cache-busting. By doing so, you can safely cache and deliver updated versions of assets to client browsers, avoiding the use of outdated cached versions and ensuring a consistent and up-to-date user experience.

During the deployment process, Hanami Assets appends to the file name a unique hash.

Example: app/assets/js/app.ts -> public/assets/app-QECGTTYG.js

It creates a /public/assets.json to map the original asset name to the fingerprint name.

The simple usage of the js helper, will be automatically mapped for you:

<%= assets.js "app" %>

<script src="/assets/app-QECGTTYG.js" type="text/javascript"></script>

Subresource Integrity (SRI) Mode

Subresource Integrity (SRI) is a security mechanism that allows browsers to verify the integrity of external resources by comparing their content against a cryptographic hash. It helps protect against unauthorized modifications to external scripts and enhances the security and trustworthiness of web applications.

module MyApp
  class App < Hanami::App
    config.assets.subresource_integrity = ["sha-384"]
  end
end

Once turned on, it will look at /public/assets.json, and helpers such as javascript will include an integrity and crossorigin attribute.

<%= assets.js "app" %>

<script src="/assets/app-QECGTTYG.js" type="text/javascript" integrity="sha384-d9ndh67iVrvaACuWjEDJDJlThKvAOdILG011RxYJt1dQynvf4JXNORcUiZ9nO7lP" crossorigin="anonymous"></script>

Content Delivery Network (CDN) Mode

A Content Delivery Network (CDN) is a globally distributed network of servers strategically located in multiple geographical locations. CDNs are designed to improve the performance, availability, and scalability of websites and web applications by reducing latency and efficiently delivering content to end users.

A Hanami project can serve assets via a Content Delivery Network (CDN).

module MyApp
  class App < Hanami::App
    config.assets.base_url = "https://123.cloudfront.net"
  end
end

From now on, helpers will return the absolute URL for the asset, hosted on the CDN specified.

<%= javascript 'application' %>

<script src="https://123.cloudfront.net/assets/application-d1829dc353b734e3adc24855693b70f9.js" type="text/javascript"></script>

<%= assets.js "app" %>

<script src="https://123.cloudfront.net/assets/app-QECGTTYG.js" type="text/javascript"></script>

NOTE: We suggest to use SRI mode when using CDN.

Development

Install:

Node
NPM

$ npm install
$ bundle exec rake test

Versioning

Hanami::Assets uses Semantic Versioning 2.0.0

Contributing

Fork it (https://github.com/hanami/assets/fork)
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request