Hey fellow Rails developers, please read!
Want to use rack-zippy with a Rails v4.2 or greater app?
Its recommended you don't! Rails 4.2+ now supports serving gzipped files directly so there's no need for rack-zippy in Rails 4.2+ apps.
Want to use rack-zippy with a Rails v4.1 or less app?
You'll need to use v3.0 of rack-zippy, see the README here: https://github.com/eliotsykes/rack-zippy/tree/v3.0.1
rack-zippy
rack-zippy v4+ is a Rack middleware for serving .gz files in Rack apps that are not Rails 4.2+ apps. (If you need to use rack-zippy in a Rails <= 4.1 app, then use v3.0 of rack-zippy, see README here: https://github.com/eliotsykes/rack-zippy/tree/v3.0.1)
rack-zippy has convenient directory request handling:
- Requests for
/
and/index
respond withpublic/index.html
if present - Requests for
/foo/
and/foo
respond with first file present out ofpublic/foo.html
,public/foo/index.html
(Same behaviour for subdirectories)
rack-zippy decorates actionpack's ActionDispatch::Static
middleware for non-Rails Rack apps to provide rack-zippy's own choice of caching headers and whitelisting of permitted static file extensions. (As an alternative to rack-zippy, you can use actionpack's ActionDispatch::Static
directly without rack-zippy.)
Installation in Rack app (that isnβt a Rails app)
Add this line to your application's Gemfile:
gem 'rack-zippy'
And then execute:
$ bundle
In config.ru
:
require 'rack-zippy'
# Set asset_root to an absolute or relative path to the directory holding your asset files
# e.g. '/path/to/my/apps/static-assets' or 'public'
asset_root = '/path/to/my/apps/public'
use Rack::Zippy::AssetServer, asset_root
Usage
Follow the installation instructions above and rack-zippy will serve any static assets, including gzipped assets, from your application's public/ directory and will respond with sensible caching headers.
Options
max_age_fallback
max_age_fallback
, is an integer value in seconds that should be used as the max_age fallback for files served by rack-zippy that live outside the /assets
subdirectory and aren't /favicon.ico
.
A typical use for max_age_fallback
is to define how long the cache lifetime for static HTML files served by rack-zippy should be. For one of my sites I have this set to 15 minutes:
max_age_in_secs = 15*60 # 15 mins = 900 secs
use Rack::Zippy::AssetServer, asset_root, max_age_fallback: max_age_in_secs
Any files given the max_age_fallback
would have the following Cache-Control
header:
Cache-Control: public, max-age=900
Configuration
Supported Extensions Whitelist
rack-zippy handles only files with whitelisted extensions. Default extensions are stored in the static_extensions
array with an entry for each of these:
css js html htm txt ico png jpg jpeg gif pdf svg zip gz eps psd ai woff woff2 ttf eot otf swf
You can modify this list to support other extensions by appending the lowercased file extension to the static_extensions
array:
Rack::Zippy.configure do |config|
# Add support for the given extensions:
config.static_extensions.push('map', 'csv', 'xls', 'rtf', ...EXTENSIONS TO ADD...)
end
It is not recommended, however if you use rack-zippy 4.0+ with a Rails 4.2+ app, you can skip the rack-zippy rails version check and log output. Put the following in an initializer:
# config/initializers/zippy.rb
Rack::Zippy::Railtie.skip_version_check = true
Troubleshooting
NameError: uninitialized constant Rack::Zippy
- Check
Gemfile
doesn't limit rack-zippy to a subset of environment groups - Run
bundle install
- Check
Gemfile.lock
contains an entry for rack-zippy - Ensure
require 'rack-zippy'
is present near the top ofconfig.ru
Contributing
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Run tests (
rake test
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new Pull Request
Optional for contributors
To try a local branch of rack-zippy out as the gem dependency in a local app, configure bundler with a local gem override as follows:
In your-app/Gemfile
: edit the rack-zippy dependency to the following:
# The branch your-local-branch-name **must** exist otherwise bundler will shout obscenities at you
gem 'rack-zippy', :github => 'eliotsykes/rack-zippy', :branch => 'your-local-branch-name'
At the command line, inside your-app
, configure bundler to set a local git repo to override the one we specified in the previous step for rack-zippy:
$> bundle config --local local.rack-zippy /path/to/your/local/rack-zippy
Now when you run your-app with bundle exec
, the rack-zippy gem dependency will resolve to /path/to/your/local/rack-zippy
.
Cleanup time! When youβre finished testing, delete the local override and set your Gemfile dependency back to the original:
# At the command line:
$> bundle config --delete local.rack-zippy
# In your-app/Gemfile change rack-zippy dependency to this (or similar):
gem 'rack-zippy', '~> 9.8.7' # Replace 9.8.7 with the rack-zippy release version you want to use.
How to Run a Single Test
# Single test file
ruby -Ilib:test test/assert_server_test.rb
# Single test method
ruby -Ilib:test test/assert_server_test.rb --name test_serves_static_file_as_directory
# Test methods matching a regex
ruby -Ilib:test test/assert_server_test.rb --name /serves_static/
Contributors
- Eliot Sykes https://eliotsykes.com
- Kieran Topping https://github.com/ktopping
- Luke Wendling https://github.com/lukewendling
- Anton Petrunich https://github.com/solenko
- ssemakov https://github.com/ssemakov
- Kai Schlichting https://github.com/lacco
Releasing a new gem
- Update pre-release version to the release version in
lib/rack-zippy/version.rb
, e.g.1.0.1.pre
becomes1.0.1
- Update
CHANGELOG.md
version and date. Update Contributors inREADME.md
. - Tests pass? (
rake test
) - Commit and push changes to origin.
- Build the gem (
rake build
) - Release on rubygems.org (
rake release
) - Update version to the next pre-release version in
lib/rack-zippy/version.rb
, e.g.1.0.1
becomes1.0.2.pre
. - Add new heading to
CHANGELOG
for the next pre-release - Commit and push the updated
lib/rack-zippy/version.rb
andCHANGELOG
files.