Turbolinks [Rails 4 Countdown to 2013]

Posted on

This post is part of a series of 31 Rails 4 articles being released each day in December 2012.

Being included by default in Rails 4 is Turbolinks, a JavaScript plugin very similar to PJAX. PJAX(pushState + AJAX) is a jQuery plugin created by Chris Wanstrath, which allows you to update a specific section of a page with an AJAX request without having to do a full HTTP request. By using pushState, PJAX updates the browser's current URL without reloading any page resources such as JavaScript or Stylesheets.

Turbolinks also uses pushState and does the exact same thing as PJAX, except that it does not require a custom partial response from the server. Turbolinks will perform an HTTP Request just as the browser would, but then replaces the <title> and <body> currently loaded in the DOM with the response from the server. It is a more automatic solution, that removes the need to manage which sections of your page will be replaced.

If a Turbolinks enabled web application is accessed from a browser that doesn't support pushState, the web application will degrade gracefully and do a complete HTTP request. Browsers that support pushState and all related APIs are:

  • Safari 6.0+
  • IE10
  • Chrome 5.0+
  • Firefox 4.0+

Turbolinks can also be used with Rails 3 applications today. To enable it, add the turbolinks gem to your Gemfile and include it in the JavaScript manifest file:

# Gemfile
gem 'turbolinks'
// app/assets/javascripts/application.js
//= require jquery
//= require jquery_ujs
//= require turbolinks
//= require_tree .

Excluding links

All internal links within a page are automatically Turbolinks enabled. If you would like certain containers and links to not be enabled, add data-no-turbolink to the element.


<div data-no-turbolink>

jQuery Turbolinks

Turbolinks will require changes to the way you write your application JavaScript code. For example, any code that listens for the ready event on a document will only be triggered on the initial page load. Subsequent Turbolink requests will not fire any ready events, thus potentially not binding events your application requires.

There are four events which Turbolinks does fire:

  • page:fetch: Page is beginning to fetch a response from the server.
  • page:load: Page is being fetched from the server.
  • page:restore: Page is being loaded from client-side cache.
  • page:change: Page has has changed to fetched version.

Moving forward, you will have to bind events to both ready(for degradation purposes) and page:load. Or you can use jQuery Turbolinks, a jQuery plugin that is a drop-in fix for binding event issues with Turbolinks.


Turbolinks is not without issues. Many JavaScript libraries are not fully compatible with the feature. This has caused a bit of controversy, as some JavaScript libraries will have to be modified just to work with Rails 4. Another area of controversy is that this method goes against the push to move more stuff to the client by using JavaScript MVC frameworks, such as Backbone.js and Ember.js.

Opting Out Completely

If Turbolinks is not for you, you can remove it from your Rails 4 application by doing the following:

  • Remove gem 'turbolinks' from your Gemfile
  • Remove //= require turbolinks from your JavaScript manifest file: app/assets/javascripts/application.js

More Resources


This post is by Kevin Faustino. Kevin is the Chief Craftsman of Remarkable Labs and also the founder of the Toronto Ruby Brigade.


comments powered by Disqus