My Problem With Turbolinks

I made a few snarky comments about Turbolinks recently and figured I should write down my thoughts more clearly.

If you're not aware of Turbolinks, it captures all local links that look like HTML pages, makes an Ajax request for the content, and then replaces the body with the response's body. It does a few other clever things, like extracting and replacing the title, and executing scripts in the response.

Overall, it's a clever way to get some increased speed while still using a traditional server-rendered-HTML architecture.


Like any other solution, it comes with some caveats.

Probably the most important one is that normal HTML-rendered pages have their own clean global scope every time a new page is rendered.

This is not a mere quibble: a lot of existing JavaScript operates under the assumption of a clean scope, and a single DOMContentLoaded event. In a perfect world, popular JavaScript plugins would be architected to work well with a solution like Turbolinks, but the assumption of a clean global scope per server-rendered HTML page is baked into a lot of the JavaScript and jQuery libraries that people tend to use.

It is possible to deal with problems like this on a case-by-case basis (see, for example), but in my opinion, this is going to end up in a game of whack-a-mole as each new patch breaks other valid use-cases.

At the end of the day, unless Turbolinks can perfectly emulate the browser's behavior, attempts to use Turbolinks with third-party JavaScript will either fail often or require an ever-growing library that handles more and more targeted edge-cases.

jQuery Turbolinks ( is a good example of something that tries to make the solution more transparent,  but introduces problems as it now triggers ready callbacks multiple times, and idempotence is not typically a requirement of ready handlers. I encourage you to review the open and closed issues on these projects to get a sense of the specific kinds of problems that can occur.

The Good

That said, for applications that are willing to carefully think through the requirements of Turbolinks, this solution does provide a nice transitional way to keep building applications without a lot of architectural changes with improved speed.

If you are thinking about using Turbolinks, make sure:

• Your JavaScript is designed to be long-lived across many different
  HTML pages without a refresh
• Your refresh handlers are idempotent. Don't register event handlers
  or other bindings in a refresh handler unless you reliably tear them down.
• You audit all third-party code that you use to make sure that they do not
  rely on DOM Ready events, or if they do, that they DOM Ready events are
  idempotent. If you don't feel comfortable auditing and cleaning up
  third-party code, don't use any. (note that the "turbolinks community",
  such as it is, might vet existing libraries for compliance, and that would
Shared publiclyView activity