Jeff Thomas

Posted on Jun 1 • Originally published at preflight.technology

Using PreFlight to Debug Your Shopify App's Storefront Issues

#shopify #shopifyapps #javascript #webdev

You're staring at 14 support tickets before your second coffee.

"Your app broke my store."
"Checkout button disappeared after your update."
"The cart popup is under the nav now."

Every one of these tickets means opening Chrome DevTools, navigating to the merchant's store, hunting through layers of CSS, and trying to figure out if your app actually caused it or if some other app installed three days ago is the real culprit.

That's the life of a Shopify app developer or app owner. Your app injects UI into hundreds or thousands of storefronts, each one a different combination of theme, apps, and custom code. When something breaks, the merchant blames the most recent change — which is usually you.

PreFlight exists to change this workflow.

What PreFlight Actually Does

PreFlight is a diagnostic engine that scans a merchant's live Shopify storefront and identifies frontend conflicts. Not a staging environment — the live page, exactly as the merchant's customers see it.

It checks for five categories of issues:

Z-index stacking conflicts — your modal is behind the theme's header because both are z-index: 999
CSS specificity collisions — the theme's .product-form button selector is overriding your app's button styles
Overflow and clipping — your widget is getting cut off by a parent element with overflow: hidden
Visibility rule conflicts — something is setting display: none or opacity: 0 on elements you expect to be visible
Third-party app interference — another installed app is modifying DOM elements your app depends on

The key distinction: PreFlight doesn't need access to the theme code or merchant cooperation. It scans the rendered page — the actual DOM, computed styles, and JavaScript execution environment your app is running in.

The Workflow: Ticket to Diagnosis in 60 Seconds

Here's how it actually works in practice.

Step 1: Extract the store URL from the ticket

You get a support ticket. The merchant's store is merchant-store.myshopify.com. That's all you need.

Step 2: Run the PreFlight scan

// Example API request (illustrative — full API surface not yet public)
const response = await fetch('https://api.preflight.technology/v1/scan', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${PREFLIGHT_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    store_url: 'merchant-store.myshopify.com',
    app_name: 'your-app-name'
  })
});

const report = await response.json();

The app_name parameter is important. It tells PreFlight's detection engine which DOM elements, scripts, and stylesheets belong to your app versus the theme versus other installed apps.

Step 3: Read the diagnostic report

{
  "scan_id": "scan_8f3a92c1",
  "store_url": "merchant-store.myshopify.com",
  "summary": {
    "total_issues": 3,
    "critical": 1,
    "warnings": 2,
    "your_app_caused": 0
  },
  "issues": [
    {
      "type": "z_index_conflict",
      "severity": "critical",
      "element": ".your-app-modal",
      "conflicting_element": ".theme-header",
      "your_app_z_index": 999,
      "conflicting_z_index": 1000,
      "source": "theme",
      "suggested_fix": "Increase z-index on .your-app-modal to 1001 or higher"
    }
  ]
}

Notice summary.your_app_caused: 0. That field is the one that matters most.

The 'Not Our Fault' Field

summary.your_app_caused tells you how many of the detected issues are attributable to your app's code versus the theme or other apps.

When it's zero, you have evidence. Not a hunch — evidence. You can reply to the merchant:

"We ran a diagnostic scan of your store. The conflict is caused by your theme's z-index configuration, not our app. Here's the report showing the specific elements involved."

That's a conversation that used to take 30 minutes of manual investigation. Now it takes 60 seconds.

When it's non-zero, you know exactly what to fix before you even open an editor.

Why This Matters for App Owners (Not Just Developers)

The numbers tell the real story.

Workflow	Time per ticket	Monthly cost (50 tickets)
Manual DevTools investigation	15-30 min	12-25 hrs
PreFlight scan + report	30-60 sec	< 1 hr

That 8 hours/month reclaimed is illustrative — your actual time savings depend on ticket volume, store complexity, and your team's debugging speed. But the directional math is real.

The bigger unlock is proactive monitoring. Instead of waiting for merchants to file tickets, you can scan your top 100 merchants periodically. If a theme update introduced a z-index conflict last Tuesday, you find out before the merchant does.

For app owners running support teams, this shifts the economics. Your support agents open tickets that already have a diagnosis attached. Less senior developer time spent on "is this even our bug" triage.

How PreFlight Adapts to Your App

The core scanning engine is universal — it works for any Shopify app. But the detection rules are customer-specific.

When you onboard with PreFlight, you configure:

Your DOM selectors — which elements belong to your app
Expected behavior rules — "this element should always be visible on product pages"
Known conflict patterns — z-index ranges your app uses, CSS classes that conflict historically

This means PreFlight finds your app's problems in the context of each merchant's specific storefront.

Where PreFlight Fits in Your Stack

The current workflow:

Merchant files ticket -> Support agent reads it -> Dev investigates -> Fix deployed

The PreFlight workflow:

Ticket arrives -> PreFlight scans -> Diagnostic attached -> Agent opens pre-diagnosed ticket

The fully automated version — where every incoming support ticket triggers a scan and the report is attached before a human reads it — is on the roadmap. Right now, PreFlight works best in the "manual trigger" model: get a ticket, run a scan, have an answer in 60 seconds.

Try PreFlight

If you're shipping Shopify apps and spending real developer hours on storefront conflict investigations, PreFlight is worth testing.

Early access: preflight.technology

Series: PreFlight Store Audits

This is Article #5 in the preflight-53-store-audit series.

DEV Community