Sinatra extension providing helper methods to output tags for static assets.
Pull request Compare This branch is 19 commits behind wbzyl:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Sinatra Extension: StaticAssets

Gem sinatra-static-assets implements the following helpers methods:

  • image_tag
  • stylesheet_link_tag
  • javascript_script_tag
  • link_to

To install it, run:

sudo gem install sinatra-static-assets -s

All these methods are simple wrappers around the url_for method from the sinatra-url-for gem.

When will you need it?

Whenever you use the Passenger module for Apache2 or use Rack::URLMap to dispatch an application to sub URI.

Example: Suppose that we already have a virtual host hitch.local and two Sinatra applications that live in /home/me/www/summer and /home/me/www/winter directories, respectively. We want our Sinatra applications to be accessible from the following sub URI:




To configure Apache2 and Passenger to serve our applications we need to create a new configuration file with the following content:

<VirtualHost *:80>
  ServerName hitch.local
  DocumentRoot /srv/www/hitch.local
  RackBaseURI /summer
  RackBaseURI /winter

and a link to the applications directories in /srv/www/hitch.local:

ln -s /home/me/www/summer/public /srv/www/hitch.local/summer
ln -s /home/me/www/winter/public /srv/www/hitch.local/winter

After restarting an Apache2 server and visiting, for example, the first application at http://hitch.local/summer we see that links to images, stylesheets and javascripts are broken.

The hitch here is that in Sinatra applications we usually refer to images/stylesheets/javascripts with absolute URI:

/images/tatry1.jpg    /stylesheets/app.css    /javascripts/app.js

That setup works whenever we are running applications locally. The absolute URI above tells a browser to request images (stylesheets and javascripts) from:


which in turn, tells a server to send a file:


The public directory is the default directory where static files should be served from. So, the /images/tatry1.jpg picture will be there and will be served unless we had changed that default directory.

But these absolute URIs do not work when, for example, the summer application is dispatched to /summer sub URI. As a result the images are at:


but we request them from:


And this does not work because there is no application dispatched to images sub URI.

The recommended way to deal with an absolute URI is to use a helper method that automatically converts /images/tatry1.jpg to /summer/images/tatry1.jpg for application dispatched to /summer sub URI.

In the above example you can simply remove the <img> HTML tag and replace it with a Ruby inline code like this:

<%= image_tag("/images/tatry1.jpg", :alt => "Błyszcz, 2159 m") %>

See also, How to fix broken images/CSS/JavaScript URIs in sub-URI deployments

Usage examples

In HTML (and HTML5) <link> and <img> tags have no end tag. In XHTML, on the contrary, these tags must be properly closed.

We can choose the appropriate behaviour with closed option:

image_tag "/images/tatry1.jpg", :alt => "Błyszcz, 2159 m", :closed => true

The default value of closed option is false. We can change the default value with:

enable :xhtml

We can pass mutliple stylesheets or scripts:

stylesheet_link_tag "/stylesheets/screen.css", "/stylesheets/summer.css", :media => "projection"
javascript_script_tag "/javascripts/jquery.js", "/javascripts/summer.js", :charset => "iso-8859-2"
link_to "Tatry Mountains Rescue Team", "/topr"

In order to use include the following in a Sinatra application:

gem 'sinatra-static-assets'
require 'sinatra/static_assets'

Or, if subclassing Sinatra::Base, include helpers manually:

gem 'sinatra-url-for'
require 'sinatra/url_for'
gem 'sinatra-static-assets'
require 'sinatra/static_assets'
class Summer < Sinatra::Base
  helpers Sinatra::UrlForHelper
  register Sinatra::StaticAssets
  # ...

Dispatching reusable Sinatra applications

With the latest version of Sinatra it is possible to build reusable Sinatra applications. This means that multiple Sinatra applications can be run in isolation and co-exist peacefully with other Rack based applications. Subclassing Sinatra::Base creates such a reusable application.

The example directory contains two reusable Sinatra applications: rsummer, rwinter and a rackup file which dispatches these applications to /summer and /winter sub URI:

require 'summer'

require 'winter'

map '/summer' do
map '/winter' do

Run file with:

rackup -p 3000

This file could also be used to deploy to virtual host's root with Passenger.

To this end, create an Apache2 configuration file with the following content:

<VirtualHost *:80>
    ServerName hitch.local
    DocumentRoot /srv/www/hitch.local

Next, create directories required by Passenger:

mkdir /srv/www/hitch.local/{public,tmp}

and, finally, copy into /srv/www/hitch.local and update LOAD_PATH in the copied file.

With everything in place, after restarting Apache2, the applications are accessible from the





Miscellaneous stuff

1. The examples directory contains summer and winter applications.

2. In order to create a virual host add the following to /etc/hosts/:       localhost.localdomain localhost hitch.local

or, read editing /etc/hosts is waste of my time.