From f2f74ef417d05b1599bb81a4c99edb59313fe829 Mon Sep 17 00:00:00 2001
From: Matt Brictson <matt@mattbrictson.com>
Date: Tue, 2 Jul 2024 16:45:53 -0700
Subject: [PATCH] docs: More robust solution to Safari dev cache bug

---
 docs/src/guide/troubleshooting.md | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/docs/src/guide/troubleshooting.md b/docs/src/guide/troubleshooting.md
index af2e3d74..b2d0e274 100644
--- a/docs/src/guide/troubleshooting.md
+++ b/docs/src/guide/troubleshooting.md
@@ -158,11 +158,18 @@ This is probably the case if you are seeing errors such as `#<Errno::EMFILE: Too
 
 Follow [this article][ulimit] for information on how to increase the limit of file descriptors in your OS.
 
-### Safari does not reflect CSS changes in development
+### Safari does not reflect CSS and JS changes in development
 
-Safari [ignores](https://apple.stackexchange.com/questions/439451/safari-is-caching-hard-i-have-to-empty-for-each-change-in-my-css) the `Cache-Control: no-cache` header for CSS stylesheets, which is inconvenient in development as HMR for CSS does not work as expected, requiring the cache to be cleared manually in order to see changes.
+Safari [ignores](https://bugs.webkit.org/show_bug.cgi?id=193533) the `Cache-Control: no-cache` header for preloaded CSS and JS files, which is inconvenient in development as HMR does not work as expected, requiring the cache to be cleared manually in order to see changes.
 
-A workaround is to import the CSS from a [`vite_javascript_tag` entrypoint][smart output] instead of using `vite_stylesheet_tag`. When the CSS is requested in this way it becomes a JS request in development, avoiding the bug in Safari.
+By default, Rails javascript and stylesheet tag helpers cause a `Link: ... rel=preload` header to be emitted, which triggers the Safari bug. As a workaround, you can disable the preload behavior in development using `preload_links_header: false`. For example, in your `application.html.erb` layout:
+
+```erb
+<%= vite_javascript_tag("application", preload_links_header: !Rails.env.development?) %>
+<%= vite_stylesheet_tag("application", preload_links_header: !Rails.env.development?) %>
+```
+
+With preloading disabled, Safari will properly refresh changed files and HMR will work.
 
 ## Fixed Issues