bughit/less-rails

:-1: :train: Less.js For Rails

The dynamic stylesheet language for the Rails 4+ asset pipeline.

This gem provides integration for Rails projects using the Less stylesheet language in the asset pipeline.

Installing

Just bundle up less-rails in your Gemfile. This will pull in less as a runtime dependency too.

gem 'less-rails', '~> 4.0.0'

But be warned, less.rb relies on a JavaScript runtime gem too. Just like ExecJS, it will look for a gem that is appropriate to your system. Typically, this means you will need one of the following.

gem 'therubyracer' # Ruby
gem 'therubyrhino' # JRuby

Configuration

This gem was made for other gems to properly hook into one place to provide paths to the Less::Parser. For example, the less-rails-bootstrap project at http://github.com/metaskills/less-rails-bootstrap and each project should do the path configuration for you. If you need to, you can configure less-rails with additional paths. These paths have higher priority than those from your applications assets load paths.

MyProject::Application.configure do
  config.less.paths << "#{Rails.root}/lib/less/protractor/stylesheets"
  config.less.compress = true
end

About Compression

If config.assets.compress is set to true, we will set the config.less.compress to true as well. Less has real basic compression and it is recommended that you set the rails config.assets.css_compressor to something more stronger like :yui in your config/environments/production.rb file. Note, this requires the yui-compressor gem but does an excellent job of compressing assets.

Import Hooks

Any @import to a .less file will automatically declare that file as a sprockets dependency to the file importing it. This means that you can edit imported framework files and see changes reflected in the parent during development. So this:

@import "frameworks/bootstrap/mixins";

#leftnav { .border-radius(5px); }

Will end up acting as if you had done this below:

/*
 *= depend_on "frameworks/bootstrap/mixins.less"
*/

@import "frameworks/bootstrap/mixins";

#leftnav { .border-radius(5px); }

Passing parameters to less.rb

You can pass any parameters that the less.rb gem (which less-rails is based upon) supports by modifying Rails.application.config.less.raw. For example, less.rb uses lessc --relative-urls by default. This means that url('../ralative/paths.png') for @imported files will be modified according to .less file location. To return back to default lessc behavior, add these lines to config/initializers/assets.rb:

Rails.application.config.less.raw.relativeUrls = false

For more parameters supported by less.rb, please consult less.rb gem.

Helpers

When referencing assets use the following helpers in LESS.

asset-path(@relative-asset-path)  /* Returns a string to the asset. */
asset-path("rails.png")           /* Becomes: "/assets/rails.png" */

asset-url(@relative-asset-path)   /* Returns url reference to the asset. */
asset-url("rails.png")            /* Becomes: url(/assets/rails.png) */

As a convenience, for each of the following asset classes there are corresponding -path and -url helpers image, font, video, audio, javascript and stylesheet. The following examples only show the -url variants since you get the idea of the -path ones above.

image-url("rails.png")            /* Becomes: url(/assets/rails.png) */
font-url("rails.ttf")             /* Becomes: url(/assets/rails.ttf) */
video-url("rails.mp4")            /* Becomes: url(/videos/rails.mp4) */
audio-url("rails.mp3")            /* Becomes: url(/audios/rails.mp3) */
javascript-url("rails.js")        /* Becomes: url(/assets/rails.js) */
stylesheet-url("rails.css")       /* Becomes: url(/assets/rails.css) */

Lastly, we provide a data url method for base64 encoding assets.

asset-data-url("rails.png")       /* Becomes: url(data:image/png;base64,iVBORw0K...) */

Please note that these helpers are only available server-side, and something like ERB templates should be used if client-side rendering is desired.

Generators

Installation of the gem will set your applications stylesheet engine to use Less. It is possible to have many gems that set the stylesheet engine, for instance the sass-rails and/or stylus gems. In this case, you can resolve the ambiguity by setting the stylesheet engine in your config/application.rb file like so. Doing so would mean all generated assets will be in the a fresh css.less template.

config.app_generators.stylesheet_engine :less

We have generators for both assets and scaffold in the less namespace. For instance the following would generate a blank app/assets/stylesheets/posts.css.less template.

$ rails generate less:assets posts

We also have a generator for rails scaffold CSS. Just like the Sass gem, we simply parse the scaffold.css in the default rails generator and save it as a scaffolds.css.less file. This is done automatically during other scaffold generator actions.

Contributing

This gem is fully tested from Rails 4.0 to Rails 5.1. We run our tests on Travis CI in both Ruby 1.9, 2.x, and JRuby 9000. If you detect a problem, open up a github issue or fork the repo and help out. After you fork or clone the repository, the following commands will get you up and running on the test suite.

$ bundle
$ bundle exec appraisal install
$ bundle exec appraisal rake

We use the appraisal gem from Thoughtbot to help us generate the individual gemfiles for each Rails version and to run the tests locally against each generated Gemfile. The rake appraisal test command actually runs our test suite against all Rails versions in our Appraisal file. If you want to run the tests for a specific Rails version, use rake -T for a list. For example, the following command will run the tests for Rails 4.0 only.

$ bundle exec rake appraisal:rails40 test

Our current build status is:

License

Less::Rails is Copyright (c) 2011-2013 Ken Collins, [email protected] and is distributed under the MIT license.