Awesome
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
Copyright
Copyright © 2014–2024 Hanami Team – Released under MIT License