Nanoc::Sprockets3

A nanoc extension to use Sprockets 3.x, a Ruby library for compiling and serving web assets.

You are using nanoc-sprockets-filter or nanoc-sprockets-datasource and you would like to use Sprockets 3.x to take advantages of the news features then nanoc-sprockets3 is what you are looking for !

Compatible with Nanoc 3.x and Nanoc 4.x

Note: Unlike nanoc-sprockets-filter or nanoc-sprockets that lack a support for dependency tracking, which is annoying when working with partials and/or livereload, nanoc-sprockets3 is built on top of Sprockets 3.x and integrates seamlessly with Nanoc3/nanoc4 and livereload. With nanoc-sprockets3 no need to clear the cache or purge the output to regenerate your assets whenever partials or dependencies change !

Installation

Add this line to your application's Gemfile:

gem 'nanoc-sprockets3'

And then execute:

$ bundle

Or install it yourself as:

$ gem install nanoc-sprockets3

Configuration

nanoc-sprockets3 does not require any mandatory configuration, however you may want to configure it for your needs.

Currently you can configure nanoc-sprockets3 with the following parameters:

• prefix [default: '/asset'] which is the prefix to give to all assets
• digest [default: false] which when true will return digest paths instead of logical path
• environment which is the Sprockets environment to use
• debug [default: false] which when set to true activate verbosity

The default environment is configured with the following paths

• content/assets/
• vendor/assets/
• static/assets/

concatenated with the following sub-paths

• stylesheets
• stylesheets/pages
• stylesheets/vendor
• javascripts
• javascripts/pages
• javascripts/vendor
• fonts

To load the default nanoc-sprockets configuration do as follow:

include Nanoc::Sprockets::Helper

To fully customize the nanoc-sprockets configuration do as follow:

include Nanoc::Sprockets::Helper

Nanoc::Sprockets::Helper.configure do |config|
  config.environment = ::Sprockets::Environment.new(File.expand_path('.')) do |env|
    # append defaults paths (if you want to)
    Nanoc::Sprockets::Helper::DEFAULT_PATHS.each { |path| env.append_path path }
    # append extra paths
    env.append_path 'app/assets/javascripts'
    env.append_path 'lib/assets/javascripts'
    env.append_path 'vendor/assets/jquery'
    env.append_path 'bower'
  end
  config.prefix      = '/assets'
  config.digest      = true
  config.debug       = false
end

Note: you can find more advanced configuration on the sprockets website.

Usage

We recommend the use of uglifier gem to minify javascripts. You may use any other compressor supported by Sprockets.

Add compile rule for stylesheets and javascripts, css_compressorand js_compressor is optional and value can be replaced by any compressor supported by Sprockets. Add route rule for all assets and use Nanoc::Sprockets::Helper.asset_path(item) to generate file path.

compile %r{/assets/(stylesheets|javascripts)/.+/} do
  filter :sprockets, {
    :css_compressor => :scss,
    :js_compressor  => :uglifier
  }
end

route '/assets/*/' do
  Nanoc::Sprockets::Helper.asset_path(item)
end

You can use nanoc-gzip-filter to create a gzipped version of stylesheets and javascripts files.

compile %r{/assets/(stylesheets|javascripts)/.+/} do
  filter :sprockets, {
    :css_compressor => :scss,
    :js_compressor  => :uglifier
  }
  snapshot :text
  filter :gzip
end

route '/assets/*/', :snapshot => :text do
  Nanoc::Sprockets::Helper.asset_path(item)
end

route '/assets/*/' do
  Nanoc::Sprockets::Helper.asset_path(item) + '.gz'
end

Note: Don't forget to require 'nanoc-sprockets' (e.g in lib/default.rb)

Contributing

1. Fork it ( http://github.com//nanoc-sprockets/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

Acknowledgement

I wrote this plugin to bring the support of Sprockets 3.x to nanoc and take benefit of the dependencies tracking system introduced in Sprockets 3.x.

This plugin is inspired by nanoc-sprockets-filter which support Sprockets 2.x but lacks a support for dependency tracking which makes it annoying to use with livereload and partials.