V1.3: Preprocessors


Hanami is able to run assets preprocessors and lazily compile them under public/assets.

Imagine to have application.css.scss in apps/web/assets/stylesheets and reset.css under apps/web/vendor/stylesheets.

The extensions structure is important. The first one is mandatory and it’s used to understand which asset type we are handling: .css for stylesheets. The second one is optional and it’s for a preprocessor: .scss for Sass.

For a given asset application.css.scss, the last extension (.scss) is used to determine the right preprocessor.

Preprocessors are optional, an application can work with plain javascripts or stylesheets. In this case we have to name our assets with only one extension (eg application.css).

# apps/web/application.rb
require 'sass'

module Web
  class Application < Hanami::Application
    configure do
      # ...

      assets do
        sources << [
          # apps/web/assets is added by default
          'vendor/assets' # app/web/vendor/assets

From a template we do:

<%= stylesheet 'reset', 'application' %>

When we’ll load the page the compiler will preprocess or copy the assets into public/assets.

$ tree public
└── assets
    ├── application.css
    └── reset.css

Preprocessors will compile/copy assets only if the Compile mode is on.

Preprocessors are enabled by default in development and test environments.

For performance reasons, this feature is turned off in production env, where we should precompile our assets.


Hanami uses Tilt to provide support for the most common preprocessors, such as Sass (including sassc-ruby), Less, ES6, JSX, CoffeScript, Opal, Handlebars, JBuilder.

In order to use one or more of them, be sure to include the corresponding gem into your Gemfile and require the library.

# Gemfile
# ...
gem 'sassc'

Some preprocessors may require Node.js. Please check the documentation.

EcmaScript 6

We strongly suggest to use EcmaScript 6 for your next project, because that is the next version of JavaScript. It isn’t fully supported yet by browser vendors, but this is changing quickly.

As of today, you need to transpile ES6 code into something understandable by current browsers, which is ES5. For this purpose we support Babel.

Babel requires Node.js.