Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Draft
EvilGenius13 wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

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

EvilGenius13 wants to merge 1 commit into from

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 file syncs do not affect hot reloads so we shouldn't see a slow down there.

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!

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 against`
  • 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.51% (+0.28% 🔼)
 14342/18039
🟡 Branches
73.68% (+0.57% 🔼)
 7076/9604
🟡 Functions
79.65% (+0.28% 🔼)
 3667/4604
🟡 Lines
79.88% (+0.3% 🔼)
 13561/16977
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%
🔴
... / 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% 50% 100% 75%
🔴
... / 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
 92.06% 86.05% 100% 93.55%
🟢
... / 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%
🟢
... / 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%
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
87.9% (-6.93% 🔻)
77.19% (-4.06% 🔻)
85.19% (-14.81% 🔻)
90.07% (-6.39% 🔻)
🟢
... / deploy-release.ts
97.4% (-2.6% 🔻)
96.55% (-3.45% 🔻)
 100% 100%
🟢
... / 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% 🔻)
🟢
... / 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% 🔻)
🔴
... / app-management-client.ts
53.69% (-0.16% 🔻)
 47.47%
50% (-0.45% 🔻)
52.53% (-0.17% 🔻)
🟢
... / api.ts
87.07% (-0.43% 🔻)
76.71% (-0.1% 🔻)
 100%
86.49% (-0.43% 🔻)
🟢
... / 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.12% (-0.93% 🔻)
 68.75% 78.57%
66.67% (-0.98% 🔻)

Test suite run success

3652 tests passing in 1428 suites.

Report generated by 🧪jest coverage report action from bc862ab

@EvilGenius13 EvilGenius13 force-pushed the add-debounce-on-theme-file-watcher branch from 2ea5a6b to bc862ab Compare January 22, 2026 21:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@EvilGenius13