Assets management for Ruby web projects
- 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
Hanami::Assets supports Ruby (MRI) 3.1+
Add this line to your application's Gemfile:
gem "hanami-assets"And then execute:
$ bundleOr install it yourself as:
$ gem install hanami-assetsDuring development run bundle exec hanami server.
Your app will start the assets management.
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>The hanami gem ships with the following helpers for assets:
asset_urljavascript_tagstylesheet_tagfavicon_tagimage_tagvideo_tagaudio_tagpath_tag
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.cssEntry 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.tsslices/[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.
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.
The destination directory is public/assets.
To process the assets during deployment run bundle exec hanami assets compile.
The destination directory will contain the processed assets with an hashed name.
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) 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
endOnce 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>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
endFrom 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.
Install:
- Node
- NPM
$ npm install
$ bundle exec rake testHanami::Assets uses Semantic Versioning 2.0.0
- 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
Copyright © 2014–2024 Hanami Team – Released under MIT License