Gathering detailed insights and metrics for @hotwired/turbo-rails
Gathering detailed insights and metrics for @hotwired/turbo-rails
Installations
npm install @hotwired/turbo-railsDeveloper
Developer Guide
BETA
Module System
CommonJS, ESM
Min. Node Version
Typescript Support
No
Node Version
20.17.0
NPM Version
10.8.2
Statistics
2,134 Stars
614 Commits
329 Forks
65 Watching
13 Branches
124 Contributors
Updated on 26 Nov 2024
Languages
Ruby (50.95%)
JavaScript (46.15%)
HTML (2.39%)
CSS (0.42%)
Shell (0.09%)
Total Downloads
Cumulative downloads
Total Downloads
31,809,897
Last day
0.5%
57,401
Compared to previous day
Last week
4.6%
299,947
Compared to previous week
Last month
6.3%
1,252,374
Compared to previous month
Last year
20.5%
13,550,888
Compared to previous year
Daily Downloads
Weekly Downloads
Monthly Downloads
Yearly Downloads
Dependencies
2
Dev Dependencies
4
Versions
Turbo
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 JavaScript, 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.
Navigate with Turbo Drive
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> 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 Drive can be disabled on a per-element basis by annotating the element or any of its ancestors with data-turbo="false". If you want Turbo Drive to be disabled by default, then you can adjust your import like this:
1import "@hotwired/turbo-rails" 2Turbo.session.drive = false
Then you can use data-turbo="true" to enable Drive on a per-element basis.
Decompose with Turbo Frames
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.
This gem provides a turbo_frame_tag helper to create those frames.
For instance:
1<%# app/views/todos/show.html.erb %> 2<%= turbo_frame_tag @todo do %> 3 <p><%= @todo.description %></p> 4 5 <%= link_to 'Edit this todo', edit_todo_path(@todo) %> 6<% end %> 7 8<%# app/views/todos/edit.html.erb %> 9<%= turbo_frame_tag @todo do %> 10 <%= render "form" %> 11 12 <%= link_to 'Cancel', todo_path(@todo) %> 13<% end %>
When the user clicks on the Edit this todo link, as a direct response to this user interaction, the turbo frame will be automatically replaced with the one in the edit.html.erb page.
A note on custom layouts
In order to render turbo frame requests without the application layout, Turbo registers a custom layout method.
If your application uses custom layout resolution, you have to make sure to return "turbo_rails/frame" (or false for TurboRails < 1.4.0) for turbo frame requests:
1layout :custom_layout 2 3def custom_layout 4 return "turbo_rails/frame" if turbo_frame_request? 5 6 # ... your custom layout logic
If you are using a custom, but "static" layout,
1layout "some_static_layout"
you have to change it to a layout method in order to conditionally return "turbo_rails/frame" for turbo frame requests:
1layout :custom_layout 2 3def custom_layout 4 return "turbo_rails/frame" if turbo_frame_request? 5 6 "some_static_layout"
Come Alive with Turbo Streams
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.
This gem provides a turbo_stream_from helper to create a turbo stream.
1<%# app/views/todos/show.html.erb %> 2<%= turbo_stream_from dom_id(@todo) %> 3 4<%# Rest of show here %>
Testing Turbo Stream Broadcasts
Receiving server-generated Turbo Broadcasts requires a connected Web Socket.
Views that render <turbo-cable-stream-source> elements with the
#turbo_stream_from view helper incur a slight delay before they're ready to
receive broadcasts. In System Tests, that delay can disrupt Capybara's built-in
synchronization mechanisms that wait for or assert on content that's broadcast
over Web Sockets. For example, consider a test that navigates to a page and then
immediately asserts that broadcast content is present:
1test "renders broadcasted Messages" do 2 message = Message.new content: "Hello, from Action Cable" 3 4 visit "/" 5 click_link "All Messages" 6 message.save! # execute server-side code to broadcast a Message 7 8 assert_text message.content 9end
If the call to Message#save! executes quickly enough, it might beat-out any
<turbo-cable-stream-source> elements rendered by the call to click_link "All Messages".
To wait for any disconnected <turbo-cable-stream-source> elements to connect,
call #connect_turbo_cable_stream_sources:
1 test "renders broadcasted Messages" do 2 message = Message.new content: "Hello, from Action Cable" 3 4 visit "/" 5 click_link "All Messages" 6+ connect_turbo_cable_stream_sources 7 message.save! # execute server-side code to broadcast a Message 8 9 assert_text message.content 10 end
By default, calls to #visit will wait for all <turbo-cable-stream-source> elements to connect. You can control this by modifying the config.turbo.test_connect_after_actions. For example, to wait after calls to #click_link, add the following to config/environments/test.rb:
1# config/environments/test.rb 2 3config.turbo.test_connect_after_actions << :click_link
To disable automatic connecting, set the configuration to []:
1# config/environments/test.rb 2 3config.turbo.test_connect_after_actions = []
Installation
This gem is automatically configured for applications made with Rails 7+ (unless --skip-hotwire is passed to the generator). But if you're on Rails 6, you can install it manually:
- Add the
turbo-railsgem to your Gemfile:gem 'turbo-rails' - Run
./bin/bundle install - Run
./bin/rails turbo:install
Running turbo:install will install through NPM or Bun if a JavaScript runtime is used in the application. Otherwise the asset pipeline version is used. To use the asset pipeline version, you must have importmap-rails installed first and listed higher in the Gemfile.
If you're using node 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:
1import "@hotwired/turbo-rails"
Usage
You can watch the video introduction to Hotwire, which focuses extensively on demonstrating 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.
Note that in development, the default Action Cable adapter is the single-process async adapter. This means that turbo updates are only broadcast within that same process. So you can't start bin/rails console and trigger Turbo broadcasts and expect them to show up in a browser connected to a server running in a separate bin/dev or bin/rails server process. Instead, you should use the web-console when needing to manaually trigger Turbo broadcasts inside the same process. Add "console" to any action or "<%= console %>" in any view to make the web console appear.
RubyDoc Documentation
For the API documentation covering this gem's classes and packages, visit the RubyDoc page. Note that this documentation is updated automatically from the main branch, so it may contain features that are not released yet.
- Turbo Drive Helpers
- Turbo Frames Helpers
- Turbo Streams View Helpers
- Turbo Streams Broadcast Methods
- Turbo Streams Channel
- Turbo Native Navigation
- Turbo Test Assertions
- Turbo Integration Test Assertions
- Turbo Broadcastable Test Helper
- Turbo System Test Helper
Compatibility with Rails UJS
Turbo can coexist with Rails UJS, but you need to take a series of upgrade steps to make it happen. See the upgrading guide.
Testing
The Turbo::TestAssertions concern provides Turbo Stream test helpers that assert the presence or absence ofs s <turbo-stream> elements in a rendered fragment of HTML. Turbo::TestAssertions are automatically included in ActiveSupport::TestCase and depend on the presence of rails-dom-testing assertions.
The Turbo::TestAssertions::IntegrationTestAssertions are built on top of Turbo::TestAssertions, and add support for passing a status: keyword. They are automatically included in ActionDispatch::IntegrationTest.
The Turbo::Broadcastable::TestHelper concern provides Action Cable-aware test helpers that assert that <turbo-stream> elements were or were not broadcast over Action Cable. Turbo::Broadcastable::TestHelper is automatically included in ActiveSupport::TestCase.
Rendering Outside of a Request
Turbo utilizes ActionController::Renderer to render templates and partials outside the context of the request-response cycle. If you need to render a Turbo-aware template, partial, or component, use ActionController::Renderer:
1ApplicationController.renderer.render template: "posts/show", assigns: { post: Post.first } # => "<html>…" 2PostsController.renderer.render :show, assigns: { post: Post.first } # => "<html>…"
As a shortcut, you can also call render directly on the controller class itself:
1ApplicationController.render template: "posts/show", assigns: { post: Post.first } # => "<html>…" 2PostsController.render :show, assigns: { post: Post.first } # => "<html>…"
Development
Run the tests with ./bin/test.
Using local Turbo version
Often you might want to test changes made locally to Turbo lib itself. To package your local development version of Turbo you can use yarn link feature:
1cd <local-turbo-dir> 2yarn link 3 4cd <local-turbo-rails-dir> 5yarn link @hotwired/turbo 6 7# Build the JS distribution files... 8yarn build 9# ...and commit the changes
Now you can reference your version of turbo-rails in your Rails projects packaged with your local version of Turbo.
Contributing
Having a way to reproduce your issue will help people confirm, investigate, and ultimately fix your issue. You can do this by providing an executable test case. To make this process easier, we have prepared an executable bug report Rails application for you to use as a starting point.
This template includes the boilerplate code to set up a System Test case. Copy the content of the template into a .rb file and make the necessary changes to demonstrate the issue. You can execute it by running ruby the_file.rb in your terminal. If all goes well, you should see your test case failing.
You can then share your executable test case as a gist or paste the content into the issue description.
License
Turbo is released under the MIT License.
No vulnerabilities found.
Reason
30 commit(s) and 6 issue activity found in the last 90 days -- score normalized to 10
Reason
no dangerous workflow patterns detected
Reason
no binaries found in the repo
Reason
license file detected
Details
- Info: project has a license file: MIT-LICENSE:0
- Info: FSF or OSI recognized license: MIT License: MIT-LICENSE:0
Reason
0 existing vulnerabilities detected
Reason
Found 17/26 approved changesets -- score normalized to 6
Reason
detected GitHub workflow tokens with excessive permissions
Details
- Warn: no topLevel permission defined: .github/workflows/ci.yml:1
- Info: no jobLevel write permissions found
Reason
dependency not pinned by hash detected -- score normalized to 0
Details
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:29: update your workflow using https://app.stepsecurity.io/secureworkflow/hotwired/turbo-rails/ci.yml/main?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/ci.yml:32: update your workflow using https://app.stepsecurity.io/secureworkflow/hotwired/turbo-rails/ci.yml/main?enable=pin
- Info: 0 out of 1 GitHub-owned GitHubAction dependencies pinned
- Info: 0 out of 1 third-party GitHubAction dependencies pinned
Reason
no effort to earn an OpenSSF best practices badge detected
Reason
security policy file not detected
Details
- Warn: no security policy file detected
- Warn: no security file to analyze
- Warn: no security file to analyze
- Warn: no security file to analyze
Reason
project is not fuzzed
Details
- Warn: no fuzzer integrations found
Reason
branch protection not enabled on development/release branches
Details
- Warn: branch protection not enabled for branch 'main'
Reason
SAST tool is not run on all commits -- score normalized to 0
Details
- Warn: 0 commits out of 22 are checked with a SAST tool
Score
4.9
/10
Last Scanned on 2024-11-18
The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.
Learn More