Skip to content

add debounce for theme filewatcher to stop unwanted file deletes#6791

Open
EvilGenius13 wants to merge 2 commits intomainfrom
add-debounce-on-theme-file-watcher
Open

add debounce for theme filewatcher to stop unwanted file deletes#6791
EvilGenius13 wants to merge 2 commits intomainfrom
add-debounce-on-theme-file-watcher

Conversation

@EvilGenius13
Copy link
Contributor

@EvilGenius13 EvilGenius13 commented Jan 22, 2026 •
edited
Loading

WHY are these changes introduced?

With the increase in LLM's editing files, file updates can happen in small batches in very quick succession. This can kick off multiple file syncs when we upload the changed file.

Adding a debounce will lower the amount of file changes sent.

WHAT is this pull request doing?

Add a 250ms debounce.

The following screenshots are from a script that updated the same file 25 times, firing an update every 100ms.

Before: (Sometimes the file watcher grouped a few updates together, overall it synced 17 times)
image

After: (One single update)
image

How to test your changes?

You too can run the script! It will target the layout/theme.liquid file and add a comment just above the closing html tag. When it's done you can rip out the comment.

Details 
#!/usr/bin/env ruby
# frozen_string_literal: true

# Run this in a theme directory while `shopify theme dev` is running
# to verify the debounce is working correctly.
#
# Usage:
#   ruby test_debounce.rb

THEME_LIQUID_PATH = "layout/theme.liquid"
NUM_CHANGES = 25
DELAY_BETWEEN_CHANGES_MS = 100

def main
  unless File.exist?(THEME_LIQUID_PATH)
    puts "Error: #{THEME_LIQUID_PATH} not found."
    puts "Please run this script from the root of a Shopify theme directory."
    exit 1
  end

  original_content = File.read(THEME_LIQUID_PATH)

  # Find the closing </html> tag
  unless original_content.include?("</html>")
    puts "Error: Could not find </html> tag in #{THEME_LIQUID_PATH}"
    exit 1
  end

  puts "=" * 60
  puts "Theme File Watcher Debounce Test"
  puts "=" * 60
  puts ""
  puts "This script will make #{NUM_CHANGES} rapid changes to #{THEME_LIQUID_PATH}"
  puts "with #{DELAY_BETWEEN_CHANGES_MS}ms between each change."
  puts ""
  puts "Watch your `shopify theme dev` output:"
  puts "  - WITHOUT debounce: May see sync issues or file delete warnings"
  puts "  - WITH debounce: Should see calm, stable syncing"
  puts ""
  puts "Press Enter to start (Ctrl+C to cancel)..."
  gets

  words = %w[
    alpha bravo charlie delta echo foxtrot golf hotel india juliet
    kilo lima mike november oscar papa quebec romeo sierra tango
    uniform victor whiskey xray yankee zulu one two three four five
  ]

  puts "Starting rapid file changes..."
  puts ""

  NUM_CHANGES.times do |i|
    word = words[i % words.length]
    marker = "<!-- debounce-test: #{word}-#{i + 1} -->"

    # Replace any existing marker or add before </html>
    new_content = if original_content.include?("<!-- debounce-test:")
      original_content.gsub(/<!-- debounce-test: .+? -->/, marker)
    else
      original_content.gsub("</html>", "#{marker}\n</html>")
    end

    # Update our reference for subsequent iterations
    original_content = new_content if i == 0 && !original_content.include?("<!-- debounce-test:")

    File.write(THEME_LIQUID_PATH, new_content)
    puts "  [#{i + 1}/#{NUM_CHANGES}] Changed marker to: #{word}-#{i + 1}"

    # Update original_content with the new marker for next iteration
    original_content = new_content

    sleep(DELAY_BETWEEN_CHANGES_MS / 1000.0)
  end

  puts ""
  puts "=" * 60
  puts "Test complete!"
  puts "=" * 60
  puts ""
  puts "To clean up, remove the <!-- debounce-test: ... --> comment from"
  puts "#{THEME_LIQUID_PATH} or just revert the file."
end

# Handle Ctrl+C gracefully
trap("INT") do
  puts "\n\nCancelled. Note: #{THEME_LIQUID_PATH} may have been modified."
  puts "Check the file and revert if needed."
  exit 0
end

main
  • pull down the branch
  • build the branch
  • run theme dev in a terminal instance
  • Add the script to the root of the theme directory you are running theme dev on
  • In another terminal instance run ruby test_debounce.rb

Post-release steps

Measuring impact

How do we know this change was effective? Please choose one:

  • n/a - this doesn't need measurement, e.g. a linting rule or a bug-fix
  • Existing analytics will cater for this addition
  • PR includes analytics changes to measure impact

Checklist

  • I've considered possible cross-platform impacts (Mac, Linux, Windows)
  • I've considered possible documentation changes

@github-actions
Copy link
Contributor

github-actions bot commented Jan 22, 2026 •
edited
Loading

Coverage report

St.❔
 Category Percentage Covered / Total
🟡 Statements
79.66% (+0.43% 🔼)
 14457/18148
🟡 Branches
73.98% (+0.87% 🔼)
 7171/9693
🟡 Functions
79.8% (+0.43% 🔼)
 3689/4623
🟢 Lines
80.02% (+0.44% 🔼)
 13669/17081
Show new covered files 🐣
St.❔
 File Statements Branches Functions Lines
🟢
... / admin-as-app.ts
 100% 100% 100% 100%
🟢
... / metafield_definitions.ts
 100% 100% 100% 100%
🟢
... / metaobject_definitions.ts
 100% 100% 100% 100%
🟢
... / bulk-operation-cancel.ts
 100% 100% 100% 100%
🟢
... / bulk-operation-run-mutation.ts
 100% 100% 100% 100%
🟢
... / bulk-operation-run-query.ts
 100% 100% 100% 100%
🟢
... / get-bulk-operation-by-id.ts
 100% 100% 100% 100%
🟢
... / list-bulk-operations.ts
 100% 100% 100% 100%
🟢
... / staged-uploads-create.ts
 100% 100% 100% 100%
🟢
... / fetch_store_by_domain.ts
 100% 100% 100% 100%
🟢
... / organization_exp_flags.ts
 100% 100% 100% 100%
🔴
... / import-custom-data-definitions.ts
 0% 100% 0% 0%
🔴
... / cancel.ts
 0% 100% 0% 0%
🔴
... / execute.ts
 0% 0% 0% 0%
🔴
... / status.ts
 0% 0% 0% 0%
🔴
... / pull.ts
 0% 100% 0% 0%
🟡
... / execute-operation.ts
 75.68% 50% 100% 75.68%
🔴
... / pull.ts
 0% 0% 0% 0%
🟢
... / bulk-operation-status.ts
 96.55% 92.11% 100% 100%
🟢
... / cancel-bulk-operation.ts
 100% 100% 100% 100%
🟢
... / constants.ts
 100% 100% 100% 100%
🟢
... / download-bulk-operation-results.ts
 100% 100% 100% 100%
🟢
... / execute-bulk-operation.ts
 87.14% 83.67% 100% 88.41%
🟢
... / format-bulk-operation-status.ts
 100% 100% 100% 100%
🟢
... / run-mutation.ts
 100% 100% 100% 100%
🟢
... / run-query.ts
 100% 100% 100% 100%
🟡
... / stage-file.ts
 73.53% 62.5% 85.71% 72.73%
🟢
... / watch-bulk-operation.ts
 100% 94.74% 100% 100%
🟢
... / utilities.ts
 100% 100% 100% 100%
🟢
... / declarative-definitions.ts
 98.54% 93.18% 100% 98.51%
🟢
... / common.ts
 97.62% 95% 100% 97.06%
🟢
... / execute-command-helpers.ts
 100% 100% 100% 100%
🟢
... / file-formatter.ts
 100% 100% 100% 100%
🔴
... / promiseWithResolvers.ts
 33.33% 50% 50% 33.33%
🟢
... / theme-listing.ts
 100% 100% 100% 100%
Show files with reduced coverage 🔻
St.❔
 File Statements Branches Functions Lines
🔴
... / execute.ts
 0%
0% (-100% 🔻)
 0% 0%
🟢
... / loader.ts
94.06% (+0.2% 🔼)
86.41% (-0.42% 🔻)
97.17% (+0.11% 🔼)
94.85% (+0.18% 🔼)
🟢
... / extension-instance.ts
84.8% (+0.23% 🔼)
77.6% (-0.91% 🔻)
92.06% (+0.13% 🔼)
85.11% (+0.24% 🔼)
🟡
... / specification.ts
69.64% (+0.55% 🔼)
75.61% (+2.44% 🔼)
76.47% (-1.31% 🔻)
69.39% (+0.64% 🔼)
🟢
... / ui_extension.ts
88.61% (-6.22% 🔻)
78.57% (-2.68% 🔻)
85.19% (-14.81% 🔻)
90.79% (-5.67% 🔻)
🟢
... / store-context.ts
 100%
82.35% (-0.98% 🔻)
 100% 100%
🟢
... / Logs.tsx
 90%
90.91% (-5.97% 🔻)
 100% 90%
🟢
... / fetch.ts
84.21% (+0.88% 🔼)
82.35% (-0.98% 🔻)
 75%
85.29% (+1.42% 🔼)
🟢
... / app-event-watcher-handler.ts
86.36% (-4.11% 🔻)
 75% 86.67%
85.71% (-5.19% 🔻)
🟡
... / middlewares.ts
77.33% (-0.87% 🔻)
 75%
68.42% (-1.58% 🔻)
76.39% (-0.94% 🔻)
🔴
... / server.ts
1.23% (-0.02% 🔻)
 0% 0%
1.3% (-0.02% 🔻)
🟢
... / setup-dev-processes.ts
93.62% (+0.14% 🔼)
66.67% (-4.76% 🔻)
 90%
92.86% (+0.17% 🔼)
🟢
... / bundle.ts
 93.22%
63.33% (-3.33% 🔻)
94.12% (+5.88% 🔼)
 96.3%
🟢
... / developer-platform-client.ts
84.62% (-1.5% 🔻)
71.43% (+0.84% 🔼)
81.82% (+1.82% 🔼)
93.75% (+0.42% 🔼)
🔴
... / http-reverse-proxy.ts
58.97% (-4.91% 🔻)
37.04% (-2.96% 🔻)
58.33% (-5.3% 🔻)
59.46% (-5.25% 🔻)
🟢
... / api.ts
87.07% (-0.43% 🔻)
76.71% (-0.1% 🔻)
 100%
86.49% (-0.43% 🔻)
🟢
... / device-authorization.ts
88.24% (-0.83% 🔻)
76.47% (-2.94% 🔻)
 100%
88.24% (-0.83% 🔻)
🟢
... / ConcurrentOutput.tsx
98.36% (-1.64% 🔻)
92% (-4% 🔻)
 100%
98.33% (-1.67% 🔻)
🟢
... / SingleTask.tsx
84.21% (-15.79% 🔻)
50% (-50% 🔻)
80% (-20% 🔻)
84.21% (-15.79% 🔻)
🔴
... / environment.ts
35% (-5% 🔻)
 41.18%
40% (-10% 🔻)
36.84% (-5.26% 🔻)
🔴
... / ui.tsx
50.82% (-0.79% 🔻)
42.86% (-5.53% 🔻)
54.55% (+1.42% 🔼)
50% (-0.82% 🔻)
🟢
... / console.ts
81.82% (+15.15% 🔼)
75% (-25% 🔻)
100% (+33.33% 🔼)
81.82% (+15.15% 🔼)
🟢
... / init.ts
88% (-0.89% 🔻)
71.43% (+4.76% 🔼)
86.67% (+4.85% 🔼)
88% (-0.89% 🔻)
🟢
... / storefront-renderer.ts
90.2% (-0.54% 🔻)
 78.95%
81.82% (-1.52% 🔻)
90.2% (-0.54% 🔻)
🟡
... / theme-polling.ts
67.57% (-0.49% 🔻)
 68.75% 78.57%
66.18% (-1.47% 🔻)

Test suite run success

3715 tests passing in 1438 suites.

Report generated by 🧪jest coverage report action from 75d8f3a

@EvilGenius13 EvilGenius13 force-pushed the add-debounce-on-theme-file-watcher branch 2 times, most recently from bc862ab to def9984 Compare January 23, 2026 18:07
@EvilGenius13 EvilGenius13 marked this pull request as ready for review January 23, 2026 19:34
@EvilGenius13 EvilGenius13 requested review from a team as code owners January 23, 2026 19:34
@EvilGenius13 EvilGenius13 force-pushed the add-debounce-on-theme-file-watcher branch 3 times, most recently from 021499d to acc85ca Compare January 23, 2026 19:38
@EvilGenius13 EvilGenius13 requested a review from karreiro January 26, 2026 16:59
karreiro
karreiro reviewed Jan 27, 2026
View reviewed changes
Copy link
Contributor

@karreiro karreiro left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks a lot for this PR, @EvilGenius13! 🚀 I've left only only one minor question :)

packages/theme/src/cli/utilities/theme-fs.ts Outdated
}

const timeout = setTimeout(() => {
pendingEvents.delete(fileKey)
Copy link
Contributor

@karreiro karreiro Jan 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe it would be nice if we could debounce per file name and per event type.

However, I believe this line implies that an unlink event could cancel an add event.

If that’s accurate, do you think we could update it so unlink just debounces other unlink events (and so on)?

Copy link
Contributor Author

@EvilGenius13 EvilGenius13 Jan 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes absolutely, great call out!

@EvilGenius13 EvilGenius13 force-pushed the add-debounce-on-theme-file-watcher branch from 58b68fe to 75d8f3a Compare January 30, 2026 16:43
@EvilGenius13 EvilGenius13 requested a review from karreiro January 30, 2026 16:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@karreiro karreiro Awaiting requested review from karreiro

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@EvilGenius13 @karreiro