@hotwired/turbo-rails
Advanced tools
The speed of a single-page web application without having to write any JavaScript
@hotwired/turbo-rails is a package that integrates Turbo, a part of the Hotwire framework, with Ruby on Rails applications. Turbo is designed to speed up web applications by reducing the need for full page reloads and enabling partial updates to the DOM. It provides tools for handling navigation, form submissions, and real-time updates efficiently.
Turbo Drive
Turbo Drive makes navigation faster by using AJAX to load new pages and update the DOM without a full page reload. This event listener logs a message when Turbo Drive is enabled.
document.addEventListener('turbo:load', () => { console.log('Turbo Drive is enabled!'); });Turbo Frames
Turbo Frames allow you to update only a portion of the page by loading content into a specific frame. This example shows how to define a Turbo Frame that loads content from a specified source.
<turbo-frame id="frame_id" src="/path/to/content"></turbo-frame>Turbo Streams
Turbo Streams enable real-time updates to the DOM by defining actions like append, prepend, replace, etc. This example appends a new message to the target element with the ID 'messages'.
<turbo-stream action="append" target="messages"><template><div>New message</div></template></turbo-stream>Turbo Forms
Turbo Forms enhance form submissions by handling them via AJAX, allowing for partial page updates. This example shows a form that will be submitted using Turbo.
<form data-turbo="true" action="/submit" method="post"><input type="text" name="name"><button type="submit">Submit</button></form>pjax (pushState + AJAX) is a jQuery plugin that uses AJAX and pushState to deliver fast, single-page app-like experiences. It is similar to Turbo Drive in that it loads new content without a full page reload, but it is more limited in scope and relies on jQuery.
Unpoly is a framework for creating fast and flexible frontends. It allows partial page updates and offers features similar to Turbo Frames and Turbo Streams. Unpoly is more feature-rich and flexible but also more complex to set up compared to @hotwired/turbo-rails.
Stimulus is a modest JavaScript framework for enhancing static HTML. While it is often used alongside Turbo, it can also be used independently to add interactivity to web pages. Stimulus focuses on connecting JavaScript behavior to HTML elements, whereas Turbo focuses on optimizing navigation and form submissions.
Turbo gives you the speed of a single-page web application without having to write any JavaScript. Turbo accelerates links and form submissions without requiring you to change your server-side generated HTML. It lets you carve up a page into independent frames, which can be lazy-loaded and operate as independent components. And finally, helps you make partial page updates using just HTML and a set of CRUD-like container tags. These three techniques reduce the amount of custom JavaScript that many web applications need to write by an order of magnitude. And for the few dynamic bits that are left, you're invited to finish the job with Stimulus.
On top of accelerating web applications, Turbo was built from the ground-up to form the foundation of hybrid native applications. Write the navigational shell of your Android or iOS app using the standard platform tooling, then seamlessly fill in features from the web, following native navigation patterns. Not every mobile screen needs to be written in Swift or Kotlin to feel native. With Turbo, you spend less time wrangling JSON, waiting on app stores to approve updates, or reimplementing features you've already created in HTML.
Turbo is a language-agnostic framework written in TypeScript, but this gem builds on top of those basics to make the integration with Rails as smooth as possible. You can deliver turbo updates via model callbacks over Action Cable, respond to controller actions with native navigation or standard redirects, and render turbo frames with helpers and layout-free responses.
Turbo is a continuation of the ideas from the previous Turbolinks framework, and the heart of that past approach lives on as Turbo Drive. When installed, Turbo automatically intercepts all clicks on <a href> links to the same domain. When you click an eligible link, Turbo prevents the browser from following it. Instead, Turbo changes the browser’s URL using the History API, requests the new page using fetch, and then renders the HTML response.
During rendering, Turbo replaces the current <body> element outright and merges the contents of the <head> element. The JavaScript window and document objects, and the HTML <html> element, persist from one rendering to the next.
Whereas Turbolinks previously just dealt with links, Turbo can now also process form submissions and responses. This means the entire flow in the web application is wrapped into Turbo, making all the parts fast. No more need for data-remote=true.
Turbo reinvents the old HTML technique of frames without any of the drawbacks that lead to developers abandoning it. With Turbo Frames, you can treat a subset of the page as its own component, where links and form submissions replace only that part. This removes an entire class of problems around partial interactivity that before would have required custom JavaScript.
It also makes it dead easy to carve a single page into smaller pieces that can all live on their own cache timeline. While the bulk of the page might easily be cached between users, a small personalized toolbar perhaps cannot. With Turbo::Frames, you can designate the toolbar as a frame, which will be lazy-loaded automatically by the publicly-cached root page. This means simpler pages, easier caching schemes with fewer dependent keys, and all without needing to write a lick of custom JavaScript.
Partial page updates that are delivered asynchronously over a web socket connection is the hallmark of modern, reactive web applications. With Turbo Streams, you can get all of that modern goodness using the existing server-side HTML you're already rendering to deliver the first page load. With a set of simple CRUD container tags, you can send HTML fragments over the web socket (or in response to direct interactions), and see the page change in response to new data. Again, no need to construct an entirely separate API, no need to wrangle JSON, no need to reimplement the HTML construction in JavaScript. Take the HTML you're already making, wrap it in an update tag, and, voila, your page comes alive.
With this Rails integration, you can create these asynchronous updates directly in response to your model changes. Turbo uses Active Jobs to provide asynchronous partial rendering and Action Cable to deliver those updates to subscribers.
The JavaScript for Turbo can either be run through the asset pipeline, which is included with this gem, or through the package that lives on NPM, through Webpacker.
turbo-rails gem to your Gemfile: gem 'turbo-rails'./bin/bundle install./bin/rails turbo:installRunning turbo:install will install through NPM if Webpacker is installed in the application. Otherwise the asset pipeline version is used.
If you're using Webpack and need to use the cable consumer, you can import cable (import { cable } from "@hotwired/turbo-rails"), but ensure that your application actually uses the members it imports when using this style (see turbo-rails#48).
The Turbo instance is automatically assigned to window.Turbo upon import:
import "@hotwired/turbo-rails"
You can watch the video introduction to Hotwire, which focuses extensively on demonstration Turbo in a Rails demo. Then you should familiarize yourself with Turbo handbook to understand Drive, Frames, and Streams in-depth. Finally, dive into the code documentation by starting with Turbo::FramesHelper, Turbo::StreamsHelper, Turbo::Streams::TagBuilder, and Turbo::Broadcastable.
Turbo can coexist with Rails UJS, but you need to take a series of upgrade steps to make it happen. See the upgrading guide.
bundle exec rake.
bundle installcd tests/dummy; RAILS_ENV=test ./bin/rails db:migrateyarn buildTurbo is released under the MIT License.
FAQs
The speed of a single-page web application without having to write any JavaScript
We found that @hotwired/turbo-rails demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.