Turbolinks

Turbolinks® makes navigating your web application faster. Get the performance benefits of a single-page application without the added complexity of a client-side JavaScript framework. Use HTML to render your views on the server side and link to pages as usual. When you follow a link, Turbolinks automatically fetches the page, swaps in its , and merges its , all without incurring the cost of a full page load.

Features

• Optimizes navigation automatically. No need to annotate links or specify which parts of the page should change.
• No server-side cooperation necessary. Respond with full HTML pages, not partial page fragments or JSON.
• Respects the web. The Back and Reload buttons work just as you’d expect. Search engine-friendly by design.
• Supports mobile apps. Adapters for iOS and Android let you build hybrid applications using native navigation controls.

Supported Browsers

Turbolinks works in all modern desktop and mobile browsers. It depends on the HTML5 History API and Window.requestAnimationFrame. In unsupported browsers, Turbolinks gracefully degrades to standard navigation.

Installation

Turbolinks automatically initializes itself when loaded via a standalone `

If you have traditionally placed application scripts at the end of `` for performance reasons, consider using the [`

Ensuring Specific Pages Trigger a Full Reload

You can ensure visits to a certain page will always trigger a full reload by including a element in the page’s.

  ...
  

This setting may be useful as a workaround for third-party JavaScript libraries that don’t interact well with Turbolinks page changes.

Setting a Root Location

By default, Turbolinks only loads URLs with the same origin—i.e. the same protocol, domain name, and port—as the current document. A visit to any other URL falls back to a full page load.

In some cases, you may want to further scope Turbolinks to a path on the same origin. For example, if your Turbolinks application lives at /app, and the non-Turbolinks help site lives at /help, links from the app to the help site shouldn’t use Turbolinks.

Include a element in your pages’ to scope Turbolinks to a particular root location. Turbolinks will only load same-origin URLs that are prefixed with this path.

  ...
  

Following Redirects

When you visit location /one and the server redirects you to location /two, you expect the browser’s address bar to display the redirected URL.

However, Turbolinks makes requests using XMLHttpRequest, which transparently follows redirects. There’s no way for Turbolinks to tell whether a request resulted in a redirect without additional cooperation from the server.

To work around this problem, send the Turbolinks-Location header in the final response to a visit that was redirected, and Turbolinks will replace the browser’s topmost history entry with the value you provide.

The Turbolinks Rails engine sets Turbolinks-Location automatically when using redirect_to in response to a Turbolinks visit.

Redirecting After a Form Submission

Submitting an HTML form to the server and redirecting in response is a common pattern in web applications. Standard form submission is similar to navigation, resulting in a full page load. Using Turbolinks you can improve the performance of form submission without complicating your server-side code.

Instead of submitting forms normally, submit them with XHR. In response to an XHR submit on the server, return JavaScript that performs a Turbolinks.visit to be evaluated by the browser.

If form submission results in a state change on the server that affects cached pages, consider clearing Turbolinks’ cache with Turbolinks.clearCache().

The Turbolinks Rails engine performs this optimization automatically for non-GET XHR requests that redirect with the redirect_to helper.

Setting Custom HTTP Headers

You can observe the turbolinks:request-start event to set custom headers on Turbolinks requests. Access the request’s XMLHttpRequest object via event.data.xhr, then call the setRequestHeader method as many times as you wish.

For example, you might want to include a request ID with every Turbolinks link click and programmatic visit.

document.addEventListener("turbolinks:request-start", function(event) {
  var xhr = event.data.xhr
  xhr.setRequestHeader("X-Request-Id", "123...")
})

API Reference

Turbolinks.visit

Usage:

Turbolinks.visit(location)
Turbolinks.visit(location, { action: action })

Performs an Application Visit to the given location (a string containing a URL or path) with the specified action (a string, either "advance" or "replace").

If location is a cross-origin URL, or falls outside of the specified root (see Setting a Root Location), or if the value of Turbolinks.supported is false, Turbolinks performs a full page load by setting window.location.

If action is unspecified, Turbolinks assumes a value of "advance".

Before performing the visit, Turbolinks fires a turbolinks:before-visit event on document. Your application can listen for this event and cancel the visit with event.preventDefault() (see Canceling Visits Before They Start).

Turbolinks.clearCache

Usage:

Turbolinks.clearCache()

Removes all entries from the Turbolinks page cache. Call this when state has changed on the server that may affect cached pages.

Turbolinks.setProgressBarDelay

Usage:

Turbolinks.setProgressBarDelay(delayInMilliseconds)

Sets the delay after which the progress bar will appear during navigation, in milliseconds. The progress bar appears after 500ms by default.

Note that this method has no effect when used with the iOS or Android adapters.

Turbolinks.supported

Usage:

if (Turbolinks.supported) {
  // ...
}

Detects whether Turbolinks is supported in the current browser (see Supported Browsers).

Full List of Events

Turbolinks emits events that allow you to track the navigation lifecycle and respond to page loading. Except where noted, Turbolinks fires events on the document object.

• turbolinks:click fires when you click a Turbolinks-enabled link. The clicked element is the event target. Access the requested location with event.data.url. Cancel this event to let the click fall through to the browser as normal navigation.

• turbolinks:before-visit fires before visiting a location, except when navigating by history. Access the requested location with event.data.url. Cancel this event to prevent navigation.

• turbolinks:visit fires immediately after a visit starts.

• turbolinks:request-start fires before Turbolinks issues a network request to fetch the page. Access the XMLHttpRequest object with event.data.xhr.

• turbolinks:request-end fires after the network request completes. Access the XMLHttpRequest object with event.data.xhr.

• turbolinks:before-cache fires before Turbolinks saves the current page to cache.

• turbolinks:before-render fires before rendering the page. Access the new `` element with event.data.newBody.

• turbolinks:render fires after Turbolinks renders the page. This event fires twice during an application visit to a cached location: once after rendering the cached version, and again after rendering the fresh version.

• turbolinks:load fires once after the initial page load, and again after every Turbolinks visit. Access visit timing metrics with the event.data.timing object.

Contributing to Turbolinks

Turbolinks is open-source software, freely distributable under the terms of an MIT-style license. The source code is hosted on GitHub. Development is sponsored by Basecamp.

We welcome contributions in the form of bug reports, pull requests, or thoughtful discussions in the GitHub issue tracker.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Building From Source

Turbolinks is written in TypeScript. To build from source, first make sure you have the Yarn package manager installed. Then issue the following commands to build the distributable files in dist/:

$ yarn install
$ yarn build

Include the resulting dist/turbolinks.js file in your application’s JavaScript bundle.

Running Tests

Turbolinks is tested with the Intern testing library.

To run the test suite, follow the instructions for Building From Source above, then run:

$ yarn test

If you are testing changes to the Turbolinks source, remember to run yarn build before each test run. Or, run yarn watch to build automatically as you work.

© 2019 Basecamp, LLC.