Hotwire Turbo 8 Performance Patterns: Real-Time Rails Applications

# BAD: Broadcasting individual updates creates N+1 server rendering
class Message < ApplicationRecord
  after_create_commit do
    broadcast_prepend_to "messages",
      partial: "messages/message",
      locals: { message: self },
      target: "messages"
  end
end

# With 100 concurrent users viewing the dashboard:
# - 1 message created
# - 100 broadcasts sent
# - 100 partial renders executed
# - 100 database queries for associated data
# - 100 ActionCable transmissions

# Result: 100x server load for a single event

# Turbo Frames don't automatically refresh after navigation
<turbo-frame id="user_profile" src="/users/123">
  <!-- Content loaded initially -->
  <div class="user-stats">
    <%= user.posts_count %> posts  <!-- This becomes stale -->
  </div>
</turbo-frame>

# User navigates to profile → creates new post → navigates back
# Frame still shows old posts_count because frame wasn't refreshed

// BAD: Creating ActionCable subscriptions without cleanup
class PostsController extends Controller {
  connect() {
    this.subscription = App.cable.subscriptions.create("PostsChannel", {
      received: (data) => {
        // Handle updates
      }
    });
  }

  // Missing disconnect cleanup!
  // Each navigation creates new subscription
  // Previous subscriptions remain in memory
}

// After 50 page navigations:
// - 50 active WebSocket connections
// - 400MB+ browser memory usage
// - Degraded browser performance

# BAD: Full frame replacement causes visible flicker
<turbo-frame id="comments">
  <%= render @comments %>
</turbo-frame>

# Each update replaces entire frame:
# 1. Old content removed (blank space appears)
# 2. Server renders new content
# 3. New content inserted (flicker visible)

# User perception: "The page feels slow and janky"

# BAD: Broadcasting to thousands of users simultaneously
class DashboardController < ApplicationController
  def index
    # 10,000 users viewing dashboard
    @stats = GlobalStats.current

    # Update broadcasts every second
    Turbo::StreamsChannel.broadcast_update_to "dashboard",
      target: "stats",
      html: render_to_string(partial: "stats", locals: { stats: @stats })
  end
end

# Server load:
# - 10,000 partial renders per second
# - 10,000 database queries per second
# - 10,000 WebSocket transmissions per second
# Result: Server collapse under load

// Traditional navigation (Turbo Drive disabled)
Total page load time: ~1200ms
  - DNS lookup: 50ms
  - TCP connection: 80ms
  - TLS handshake: 100ms
  - Server processing: 200ms
  - Response download: 300ms
  - HTML parsing: 150ms
  - CSS parsing: 120ms
  - JavaScript execution: 200ms

// Turbo Drive navigation (same-origin)
Total transition time: ~250ms
  - Server processing: 200ms
  - Response download: 30ms (smaller payload)
  - DOM morphing: 20ms
  - No DNS, TCP, TLS, CSS, or JS overhead

# First visit: Server renders sidebar (200ms)
# Cached in browser memory

# Second visit: Cache hit (0ms server time)
# Cache remains valid until navigation away from page

# Cache invalidation strategies:
# 1. Time-based: data-turbo-frame-cache="false"
# 2. Event-based: Manual cache clearing
# 3. Automatic: Turbo detects stale content

# Efficient targeted updates
<turbo-stream action="append" target="messages">
  <template>
    <%= render partial: "messages/message", locals: { message: @message } %>
  </template>
</turbo-stream>

# Only affected DOM sections update
# No full page refresh
# No frame replacement
# Minimal DOM manipulation

// Append operation benchmark
Turbo Stream append: 12ms
  - Server render: 8ms
  - Network transfer: 2ms
  - DOM insertion: 2ms

// Compared to full page refresh
Full page refresh: 450ms
  - 37x slower than targeted update

<!-- Server sends refresh signal -->
<turbo-stream action="refresh"></turbo-stream>

<!-- Turbo automatically:
  1. Fetches current page HTML
  2. Diffs new vs current DOM
  3. Morphs only changed elements
  4. Preserves scroll position
  5. Maintains form state
-->

# Morphing benchmark (page with 1000 DOM nodes)
Full replace: 180ms (destroy + rebuild all nodes)
Morph update: 23ms (update only 50 changed nodes)

# 7.8x faster perceived update speed

// Single WebSocket connection for all Turbo Streams
// No connection overhead for multiple subscriptions

// Traditional approach (multiple connections)
const subscriptions = [
  cable.subscriptions.create("MessagesChannel"),
  cable.subscriptions.create("NotificationsChannel"),
  cable.subscriptions.create("DashboardChannel")
];
// 3 WebSocket connections = 3x handshake overhead

// Turbo Streams approach (single connection)
// All channels multiplex over one WebSocket
// 67% reduction in connection overhead

# config/environments/production.rb
Rails.application.configure do
  # Aggressive caching for Turbo-enabled apps
  config.public_file_server.headers = {
    'Cache-Control' => 'public, s-maxage=31536000, immutable',
    'Expires' => 1.year.from_now.to_formatted_s(:rfc822)
  }

  # Turbo-specific cache headers
  config.action_controller.default_static_extension = ".html"
  config.action_dispatch.default_headers.merge!({
    'Turbo-Cache-Control' => 'no-preview'  # Disable preview cache for stale data
  })
end

# BAD: Broadcasting every keystroke in collaborative editing
class Document < ApplicationRecord
  after_update_commit do
    broadcast_replace_to "document_#{id}",
      partial: "documents/document",
      locals: { document: self }
  end
end

# User types "Hello World" (11 characters)
# Result: 11 broadcasts, 11 renders, 11 transmissions
# Server load: Excessive
# Client experience: Janky, flickering updates

# GOOD: Debounced broadcasting with job coalescing
class Document < ApplicationRecord
  after_update_commit :broadcast_update_later

  private

  def broadcast_update_later
    BroadcastDocumentUpdateJob.set(wait: 1.second).perform_later(id)
  end
end

class BroadcastDocumentUpdateJob < ApplicationJob
  queue_as :broadcasts

  # Uniqueness prevents duplicate jobs within 1 second window
  unique :until_executing, on_conflict: :replace

  def perform(document_id)
    document = Document.find(document_id)

    broadcast_replace_to "document_#{document.id}",
      partial: "documents/document",
      locals: { document: document }
  end
end

# User types "Hello World" (11 characters in 2 seconds)
# Result: 1 broadcast after debounce period
# Server load: 91% reduction
# Client experience: Smooth, single update

# High-frequency update scenario (100 updates/second)
Without debouncing:
  - 100 broadcasts/second
  - Server CPU: 85%
  - Database queries: 100/second
  - Client updates: Flickering

With debouncing (1 second):
  - 1 broadcast/second
  - Server CPU: 12%
  - Database queries: 1/second
  - Client updates: Smooth

# BAD: Individual stream broadcasts cause multiple DOM updates
class CommentNotificationJob < ApplicationJob
  def perform(comment_ids)
    comment_ids.each do |id|
      comment = Comment.find(id)

      # Each broadcast triggers separate DOM update
      broadcast_append_to "notifications",
        partial: "comments/notification",
        locals: { comment: comment }
    end
  end
end

# 50 new comments = 50 separate DOM operations
# Browser layout recalculation: 50 times
# Total DOM update time: ~1500ms

# GOOD: Single stream with multiple actions
class CommentNotificationJob < ApplicationJob
  def perform(comment_ids)
    comments = Comment.where(id: comment_ids).includes(:user, :post)

    # Collect all actions into single stream
    Turbo::StreamsChannel.broadcast_action_to "notifications",
      action: :append,
      target: "notifications",
      html: render_to_string(
        partial: "comments/notifications",
        locals: { comments: comments }
      )
  end
end

# app/views/comments/_notifications.html.erb
<% comments.each  do |comment| %>
  <%= render comment %>
<% end  %>

# 50 new comments = 1 DOM operation
# Browser layout recalculation: 1 time
# Total DOM update time: ~45ms
# 33x faster

# For very large updates, chunk to avoid single large payload
class BulkNotificationJob < ApplicationJob
  CHUNK_SIZE = 50

  def perform(comment_ids)
    comment_ids.each_slice(CHUNK_SIZE).with_index do |chunk, index|
      comments = Comment.where(id: chunk).includes(:user, :post)

      # Delay each chunk slightly to smooth client updates
      wait_time = index * 0.1.seconds

      BroadcastChunkJob.set(wait: wait_time).perform_later(comments.map(&:id))
    end
  end
end

# 1000 comments chunked into 20 batches of 50
# Smooth progressive updates instead of single large payload

// app/javascript/controllers/visibility_controller.js
import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static values = {
    threshold: { type: Number, default: 0.5 },
    rootMargin: { type: String, default: "50px" }
  }

  connect() {
    this.createObserver()
  }

  disconnect() {
    this.observer.disconnect()
  }

  createObserver() {
    const options = {
      root: null,
      rootMargin: this.rootMarginValue,
      threshold: this.thresholdValue
    }

    this.observer = new IntersectionObserver((entries) => {
      entries.forEach(entry => {
        if (entry.isIntersecting) {
          // Frame is visible, trigger load
          this.element.reload()

          // Stop observing after first load
          this.observer.unobserve(entry.target)
        }
      })
    }, options)

    this.observer.observe(this.element)
  }
}

# Page with 10 lazy frames
Without lazy loading:
  - Initial load: 11 requests (page + 10 frames)
  - Time to interactive: 2.4s
  - Total data transferred: 450KB

With lazy loading:
  - Initial load: 1 request (page only)
  - Time to interactive: 0.7s
  - Frames load progressively as user scrolls
  - Total data transferred: 450KB (same, but spread over time)
  - Perceived performance: 3.4x faster

// app/javascript/controllers/optimistic_comment_controller.js
import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static targets = ["body", "frame"]

  submitWithOptimism(event) {
    event.preventDefault()

    // 1. Create optimistic comment element
    const optimisticComment = this.createOptimisticComment()
    this.frameTarget.prepend(optimisticComment)

    // 2. Submit form via Turbo
    const form = event.target
    fetch(form.action, {
      method: form.method,
      body: new FormData(form),
      headers: {
        "Accept": "text/vnd.turbo-stream.html"
      }
    })
    .then(response => response.text())
    .then(html => {
      // 3. Replace optimistic with server response
      Turbo.renderStreamMessage(html)

      // Clear form
      this.bodyTarget.value = ""
    })
    .catch(error => {
      // 4. Remove optimistic comment on error
      optimisticComment.remove()
      alert("Failed to post comment")
    })
  }

  createOptimisticComment() {
    const template = document.createElement('div')
    template.classList.add('comment', 'optimistic')
    template.innerHTML = `
      <div class="comment-body">${this.bodyTarget.value}</div>
      <div class="comment-meta">Posting...</div>
    `
    return template
  }
}

Without optimistic updates:
  - User action → 260ms delay → visual feedback
  - Perceived responsiveness: Slow

With optimistic updates:
  - User action → 0ms delay → visual feedback (optimistic)
  - Server confirmation → Morph to real comment
  - Perceived responsiveness: Instant

// BAD: Turbo Drive enabled globally causes issues
// - Third-party widgets break
// - Analytics scripts don't fire
// - Complex JavaScript apps conflict with Turbo

// app/javascript/controllers/turbo_config_controller.js
import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  connect() {
    // Disable Turbo Drive for external domains
    document.addEventListener("turbo:click", (event) => {
      const url = new URL(event.detail.url)

      if (url.hostname !== window.location.hostname) {
        event.detail.resume = () => {
          event.preventDefault()
          window.location.href = url.href
        }
      }
    })

    // Disable Turbo for pages with data-turbo-track="reload"
    document.addEventListener("turbo:before-visit", (event) => {
      const hasReloadTracking = event.target.querySelector('[data-turbo-track="reload"]')

      if (hasReloadTracking && this.hasPageChanged(hasReloadTracking)) {
        // Force full page reload to get fresh assets
        event.preventDefault()
        window.location.href = event.detail.url
      }
    })
  }

  hasPageChanged(element) {
    const currentChecksum = element.dataset.turboTrack
    const cachedChecksum = this.getCachedChecksum(element)

    return currentChecksum !== cachedChecksum
  }

  getCachedChecksum(element) {
    // Implementation details
  }
}

# Turbo Drive enabled (most pages)
Navigation time: ~250ms
Benefits:
  - Faster navigation
  - Preserved scroll position
  - Smooth transitions
Costs:
  - Initial Turbo.js overhead (~15KB gzipped)

# Turbo Drive disabled (specific pages)
Navigation time: ~1200ms
Benefits:
  - Guaranteed clean state
  - Third-party script compatibility
Costs:
  - Slower navigation
  - Lost scroll position

# config/initializers/turbo_monitoring.rb
Rails.application.configure do
  # Track Turbo-specific metrics
  ActiveSupport::Notifications.subscribe("turbo.stream.render") do |name, start, finish, id, payload|
    duration = (finish - start) * 1000  # Convert to milliseconds

    # Send to APM (New Relic, DataDog, etc.)
    NewRelic::Agent.record_metric("Turbo/Stream/Render", duration)
    NewRelic::Agent.record_metric("Turbo/Stream/Target/#{payload[:target]}", duration)

    # Log slow renders
    if duration > 100
      Rails.logger.warn "Slow Turbo Stream render: #{payload[:target]} took #{duration.round(2)}ms"
    end
  end

  # Track frame load times
  ActiveSupport::Notifications.subscribe("turbo.frame.render") do |name, start, finish, id, payload|
    duration = (finish - start) * 1000

    NewRelic::Agent.record_metric("Turbo/Frame/Render", duration)
    NewRelic::Agent.record_metric("Turbo/Frame/#{payload[:id]}", duration)
  end
end

// app/javascript/monitoring/turbo_rum.js
import { Turbo } from "@hotwired/turbo-rails"

// Track page navigation performance
document.addEventListener("turbo:load", (event) => {
  // Use Performance API to track load time
  const perfData = performance.getEntriesByType("navigation")[0]

  if (perfData) {
    // Send to analytics
    gtag("event", "turbo_navigation", {
      page_load_time: perfData.loadEventEnd - perfData.fetchStart,
      dom_content_loaded: perfData.domContentLoadedEventEnd - perfData.fetchStart,
      url: window.location.href
    })
  }
})

// Track Turbo Stream application time
document.addEventListener("turbo:before-stream-render", (event) => {
  event.detail.startTime = performance.now()
})

document.addEventListener("turbo:stream-render", (event) => {
  const duration = performance.now() - event.detail.startTime

  // Send to analytics
  gtag("event", "turbo_stream_render", {
    target: event.detail.target,
    duration: Math.round(duration)
  })
})

// Track Frame load errors
document.addEventListener("turbo:frame-missing", (event) => {
  console.error("Turbo Frame missing:", event.detail)

  // Send error to monitoring service
  Sentry.captureException(new Error("Turbo Frame missing"), {
    extra: {
      frameId: event.detail.id,
      response: event.detail.response
    }
  })
})

# test/performance/turbo_load_test.rb
require 'benchmark'

class TurboLoadTest < ActionDispatch::IntegrationTest
  test "dashboard with real-time updates handles concurrent users" do
    # Simulate 100 concurrent users
    threads = 100.times.map do |i|
      Thread.new do
        # User views dashboard
        get dashboard_path

        # Subscribe to updates
        ActionCable.server.broadcast("dashboard",
          { action: "update", html: "<div>Update #{i}</div>" })

        # Measure response time
        Benchmark.measure do
          get dashboard_path
        end
      end
    end

    results = threads.map(&:value)
    average_time = results.sum(&:real) / results.size

    assert average_time < 0.5, "Average response time too high: #{average_time}s"
  end
end

# Use k6 for load testing Turbo applications
# scripts/load_test.js
import http from 'k6/http';
import { check, sleep } from 'k6';

export let options = {
  stages: [
    { duration: '2m', target: 100 },  // Ramp up to 100 users
    { duration: '5m', target: 100 },  // Stay at 100 users
    { duration: '2m', target: 0 },    // Ramp down to 0 users
  ],
};

export default function() {
  // Simulate Turbo navigation
  let response = http.get('https://example.com/dashboard', {
    headers: {
      'Accept': 'text/vnd.turbo-stream.html, text/html, application/xhtml+xml',
      'Turbo-Frame': 'dashboard_stats'
    }
  });

  check(response, {
    'status is 200': (r) => r.status === 200,
    'response time < 500ms': (r) => r.timings.duration < 500,
    'has turbo-stream': (r) => r.body.includes('<turbo-stream')
  });

  sleep(1);
}

# Run load test
$ k6 run scripts/load_test.js

# Establish performance baselines for critical operations
PERFORMANCE_BASELINES = {
  turbo_frame_render: 100,        # ms
  turbo_stream_broadcast: 50,     # ms
  page_navigation: 300,           # ms
  websocket_latency: 30,          # ms
  cache_hit_ratio: 0.85           # 85%
}

# Monitor deviations from baseline
class PerformanceMonitor
  def self.check_baseline(metric, value)
    baseline = PERFORMANCE_BASELINES[metric]

    if value > baseline * 1.5  # 50% degradation threshold
      alert_performance_degradation(metric, value, baseline)
    end
  end

  def self.alert_performance_degradation(metric, current, baseline)
    Sentry.capture_message("Performance degradation detected",
      level: 'warning',
      extra: {
        metric: metric,
        current_value: current,
        baseline_value: baseline,
        degradation_percentage: ((current - baseline) / baseline * 100).round(2)
      }
    )
  end
end

# config/deploy.rb (Capistrano)
namespace :deploy do
  desc "Restart Turbo Cable server without dropping connections"
  task :restart_cable do
    on roles(:web) do
      # Graceful WebSocket server restart
      execute :sudo, :systemctl, :reload, 'anycable'

      # Wait for new workers to start
      sleep 5

      # Broadcast reconnection to clients
      execute :rails, :runner,
        '"ActionCable.server.broadcast(\"system\", { action: \"reconnect\" })"'
    end
  end

  after :publishing, :restart_cable
end

# config/environments/production.rb
Rails.application.configure do
  # Ensure Turbo assets are fingerprinted
  config.assets.digest = true

  # Set appropriate cache headers
  config.public_file_server.headers = {
    'Cache-Control' => 'public, s-maxage=31536000, immutable'
  }

  # Turbo preview cache control
  config.action_controller.default_headers.merge!({
    'Turbo-Cache-Control' => 'no-preview'
  })
end

Turbo Frame "user_activity" takes 3+ seconds to load
Users see "Loading..." for extended periods

# Add instrumentation to identify bottleneck
# config/initializers/turbo_instrumentation.rb
ActiveSupport::Notifications.subscribe("process_action.action_controller") do |name, start, finish, id, payload|
  if payload[:headers]["Turbo-Frame"].present?
    duration = (finish - start) * 1000

    Rails.logger.info "Turbo Frame load: #{payload[:headers]["Turbo-Frame"]} " \
                      "took #{duration.round(2)}ms " \
                      "(DB: #{payload[:db_runtime].round(2)}ms, " \
                      "View: #{payload[:view_runtime].round(2)}ms)"

    # Typical bottleneck: Database queries taking 2500ms out of 3000ms total
  end
end

# 1. Add database indexes
# db/migrate/xxx_add_indexes_for_user_activity.rb
class AddIndexesForUserActivity < ActiveRecord::Migration[7.0]
  def change
    add_index :activities, [:user_id, :created_at]
    add_index :activities, [:user_id, :activity_type]
  end
end

# 2. Implement eager loading
# app/controllers/users/activities_controller.rb
class Users::ActivitiesController < ApplicationController
  def index
    @activities = current_user.activities
                    .includes(:activityable)  # Prevent N+1
                    .order(created_at: :desc)
                    .limit(20)
  end
end

# 3. Add fragment caching
# app/views/users/activities/index.html.erb
<% @activities.each  do |activity| %>
  <% cache activity do %>
    <%= render activity %>
  <% end %>
<% end  %>

# Results:
# Before: 3000ms (2500ms DB, 500ms View)
# After: 95ms (45ms DB with indexes, 50ms View with cache)

Browser memory usage grows from 150MB to 800MB after 30 minutes
Page becomes sluggish, eventually crashes

// Use Chrome DevTools Memory Profiler
// Take heap snapshot before and after navigation
// Look for "Detached HTMLElements" (indicates memory leak)

// Common cause: Event listeners not cleaned up

// BAD: Creates memory leak
import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  connect() {
    // Event listener added but never removed
    window.addEventListener("resize", this.handleResize)
  }

  handleResize() {
    // Handle resize
  }
}

// GOOD: Properly cleanup event listeners
import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  connect() {
    // Bind this so we can remove it later
    this.boundHandleResize = this.handleResize.bind(this)
    window.addEventListener("resize", this.boundHandleResize)
  }

  disconnect() {
    // Critical: Remove event listener on disconnect
    window.removeEventListener("resize", this.boundHandleResize)
  }

  handleResize() {
    // Handle resize
  }
}

// Even better: Use Stimulus built-in event handling
export default class extends Controller {
  connect() {
    // Stimulus automatically cleans up these listeners
  }

  resize(event) {
    // Handle resize
  }
}

// Template
<div data-controller="resizable" data-action="resize@window->resizable#resize">

Content flashes white/blank during updates
Elements jump around during refresh
Poor perceived performance despite fast server responses