Sphere

Sphere is a asset packer and compressor, for Rails, built (primarily) to be used with Heroku + AWS/S3. Inspired by Jammit and Compass

Quick Start

Create a config/shere.yml file and define your packages. Here an example file:

# Use packaged assets in views [production: true, other: false].
# Hint: Don't hard-code option this in the configuration file,
#       instead use your config/environments/* files.
# Example:
#     # config/environments/staging.rb
#     # ...
#     Sphere.config.package = true
# package: true

# Where (within Rails.public_path) to store packaged assets [assets -> public/assets]
asset_path: assets

# Compression backend [closure]
backend: closure

# Use compression when packaging assets [production: true, other: false]
compress: true

# Define your javascript packages here:
javascripts:
  # Example assuming default settings (Rails.public_path: public, asset_path: assets):
  #   Fetch content from http://ajax.googleapis.com and merge/compress it with all files
  #   matching public/javascripts/vendor/*.js + public/javascripts/custom/*.js into public/assets/application.js
  application:
    - http://ajax.googleapis.com/ajax/libs/jquery/1.4.1/jquery.js
    - javascripts/vendor/*.js
    - javascripts/custom/*.js

# Define your stylesheet packages here:
stylesheets:
  # Example assuming default settings (Rails.public_path: public, asset_path: assets):
  #   Merge/compress public/stylesheets/compiled/screen.css into public/assets/screen.css
  #   Merge/compress public/stylesheets/compiled/print.css into public/assets/print.css
  screen:
    - stylesheets/compiled/screen.css
  print:
    - stylesheets/compiled/print.css

In your layout/application.html.erb

<%= include_stylesheets :screen, :media => 'screen, projection' %>
<%= include_stylesheets :print, :media => 'print' %>
<%= include_javascripts :application %>

If the package_assets option is enabled (production), this will produce (given that config.action_controller.asset_host = "http://my-asset-host-bucket.s3.amazonaws.com"):

<link href="http://my-asset-host-bucket.s3.amazonaws.com/assets/screen.css" media="screen, projection" rel="stylesheet" type="text/css" />
<link href="http://my-asset-host-bucket.s3.amazonaws.com/assets/print.css" media="print" rel="stylesheet" type="text/css" />
<script src="http://my-asset-host-bucket.s3.amazonaws.com/assets/application.js" type="text/javascript"></script>

If the package_assets option is disabled (development), this will produce:

<link href="/stylesheets/compiled/screen.css" media="screen, projection" rel="stylesheet" type="text/css" />
<link href="/stylesheets/compiled/print.css" media="print" rel="stylesheet" type="text/css" />

<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.4.1/jquery.js" type="text/javascript"></script>
<script src="/javascripts/vendor/jquery.enumerable.js" type="text/javascript"></script>
<script src="/javascripts/custom/rails.js" type="text/javascript"></script>

Include Rake Tasks

Create a new lib/tasks/sphere.rake file in your Rails application. Include the following lines:

# Adds the sphere:compile task
load 'sphere/tasks/sphere.rake'

# [Optional] Extends the sphere:compile:css task; pre-compiles Compass/SASS files to CSS before packaging
load 'sphere/tasks/compass.rake'

# [Optional] Adds sphere:upload & sphere:deploy tasks for automated S3 upload
load 'sphere/tasks/upload.rake'

# [Optional] Adds sphere:commit:hook task you can run to ensure all assets are up-to-date.
# Just e.g. add "rake sphere:commit:hook -s" to your .git/hooks/pre-commit hook.
load 'sphere/tasks/commit.rake'