Forem: 137Foundry

Why Your Webhook Endpoint Keeps Getting Duplicate Events (And How to Fix It)

137Foundry — Sun, 05 Apr 2026 05:22:53 +0000

You checked the logs. The order was fulfilled. The confirmation email was sent. And yet the webhook provider is showing another retry in the delivery history, and now you have two fulfilled orders for one payment. The logic ran twice, and you have no idea when it started happening or how many times it has happened before.

Duplicate webhook event processing is one of those problems that sits invisible in production for weeks or months, then surfaces suddenly as a customer complaint or a billing discrepancy. Understanding exactly why it happens makes it straightforward to prevent.

Why Duplicate Events Happen

Webhook providers retry delivery when your endpoint does not return a successful response within their timeout window. The provider does not know whether the timeout happened because your server was down, because your processing was slow, or because your handler successfully ran but crashed before sending the response. From their perspective, the delivery failed. So they try again.

The specific scenario that causes most duplicate processing is this: your endpoint starts processing a payment event, completes the order fulfillment logic, and then your process crashes, restarts, or hits an uncaught exception before executing res.status(200).send(). The event processing succeeded. The response never went out. The provider retries. You process it again.

This is not a provider bug. Retry-on-failure is a core design feature of reliable event delivery systems. The problem is on your side: your endpoint is processing events without any protection against running the same logic twice.

Photo by Christina Morillo on Pexels

The Two-Part Fix

Solving duplicate events requires two things working together.

1. Return 202 Before You Process Anything

The first change is structural: your endpoint should not process the event synchronously at all. It should validate the incoming request, store the raw payload, and return HTTP 202 immediately. Processing happens in a background worker after the acknowledgment is sent.

This eliminates the window where a processing success can be paired with a failed response. The endpoint stores the event and returns. The provider receives its 202 and stops retrying. A worker handles the actual logic independently.

app.post('/webhooks/orders', async (req, res) => {
  if (!verifySignature(req)) {
    return res.status(401).end();
  }

  await queue.push({
    id: req.body.id,
    type: req.body.type,
    payload: req.body,
    received_at: new Date()
  });

  res.status(202).end(); // Respond before processing
});

Even with this change, the provider might still deliver the same event twice in some edge cases (concurrent retries, network partitions). The 202 pattern reduces the frequency significantly but does not eliminate duplicates entirely. That is where idempotency comes in.

2. Implement Idempotency Using the Event ID

Every webhook provider includes a unique event ID in the payload. Use it. Before your background worker processes any event, check whether that event ID already exists in a processed_events table. If it does, skip it. If it does not, process the event and record the ID.

def process_event(event_id, event_type, payload):
    # Skip if already processed
    existing = db.query(
        "SELECT 1 FROM processed_events WHERE event_id = %s",
        (event_id,)
    ).fetchone()

    if existing:
        return  # Silently skip duplicate

    # Run business logic
    execute_business_logic(event_type, payload)

    # Record completion after success
    db.execute(
        "INSERT INTO processed_events (event_id, processed_at) VALUES (%s, NOW())",
        (event_id,)
    )
    db.commit()

Record the event ID after the business logic succeeds, not before. If you record it first and processing fails, the event is permanently skipped on future retries.

The Most Common Implementation Mistake

Teams that implement idempotency checks often still see occasional duplicates. The most common cause is a race condition in the check-then-insert sequence: two worker processes both query for the event ID, both find nothing, both proceed to process, and both succeed before either inserts the record.

The fix is to make the check and the claim atomic. In PostgreSQL, INSERT ... ON CONFLICT DO NOTHING RETURNING event_id does this in a single operation. If the row already exists, the insert is silently skipped and RETURNING returns nothing, which your code treats as a duplicate signal. Two processes executing this simultaneously will have exactly one succeed and one skip.

This atomic approach is safer than any version of "check, then decide" because the database engine enforces the uniqueness constraint at the storage level, regardless of how many concurrent workers are running.

"Every duplicate event problem I have seen traces back to the same thing: the endpoint was doing too much before it returned a response. Responding fast and processing asynchronously eliminates the window where duplicates happen." - Dennis Traina, 137Foundry

Why This Problem Hides for So Long

Duplicate event processing is easy to miss because the system usually looks correct from the outside. The order was fulfilled - that part worked. The second fulfillment might succeed silently, or it might fail gracefully because the record already exists, or it might produce a visible error that gets swallowed by error handling. None of these outcomes necessarily produce an obvious alert.

The places to look for this problem proactively are your provider's delivery dashboard (do any events show multiple successful deliveries?) and any tables where your webhook logic writes data (are there duplicate records with identical payload IDs?). For payment integrations specifically, reconciling webhook-triggered transactions against payment provider records catches duplicates that application logs miss.

For a complete walkthrough of webhook reliability patterns, including async processing, idempotency, dead letter queues, and monitoring lag, the guide on building webhook integrations that handle failures gracefully covers the full architecture. 137Foundry works with engineering teams on exactly these integration challenges, particularly for systems where duplicates have financial or operational consequences.

Photo by luis gomes on Pexels

Testing Your Idempotency Implementation

Once you have idempotency in place, it is worth verifying it works correctly before you rely on it in production. The test is straightforward: trigger a real event from your provider's dashboard, let your handler process it, then use your provider's replay feature or a tool like Postman to resend the exact same event to your endpoint.

Your handler should return 200 or 202 on the second delivery without running any business logic. Check that no duplicate records were created in your database and that the idempotency table contains exactly one entry for the event ID. If your duplicate check works correctly, the second delivery is a no-op at the business logic level.

Also test the race condition path: send two deliveries of the same event in rapid succession before either has been processed. Both requests should resolve cleanly, with exactly one processed and one skipped. If you are using a read-then-write check rather than an atomic insert, this test will expose the race condition - you may see both requests proceed to processing. An atomic INSERT ... ON CONFLICT eliminates this window entirely.

A Quick Checklist Before Your Next Webhook Goes Live

Before any webhook integration reaches production, verify these three things:

Your endpoint returns 202 (or 200) immediately without waiting for processing to complete
Your processing logic checks the event ID before running any business logic
Your idempotency insert uses an atomic operation (ON CONFLICT or equivalent) rather than a separate read-then-write

These three changes transform a webhook handler from brittle to resilient. They take less than a day to implement correctly, and they prevent a category of production incidents that is genuinely difficult to debug after the fact.

5 Patterns for Building Resilient Event-Driven Integrations

137Foundry — Sun, 05 Apr 2026 05:21:42 +0000

Point-to-point integrations are easy to build and easy to break. You wire up an API call from one system to another, it works in testing, and then a 30-second downstream outage in production causes a cascade of failures, lost state, and a manual cleanup effort that takes longer than the outage itself.

Event-driven integration patterns address this directly. They decouple the systems involved so that no single failure propagates through the entire integration chain. The tradeoff is upfront design work, but the operational stability that results is not comparable to the alternative.

Here are five patterns that appear in most well-built event-driven integrations, with examples of when and why each one matters.

1. Queue-Based Event Processing

What it is: Instead of processing webhook events or API callbacks synchronously in the request handler, your endpoint stores each incoming event in a message queue or database table and returns an acknowledgment immediately. A separate worker process reads from the queue and handles the business logic.

Why it matters: Webhook providers set short timeout windows - typically 5-30 seconds. If your handler does any significant processing before responding, you risk timing out even when nothing is wrong with your application. The provider marks the delivery failed and retries, creating duplicates.

Separating acknowledgment from processing eliminates this window entirely. The endpoint does the minimum work (validate, store, acknowledge), and the worker handles everything else.

Example:

// Endpoint: validates, stores, acknowledges
app.post('/webhooks', async (req, res) => {
  if (!validateSignature(req)) return res.status(401).end();
  await eventStore.push({ id: req.body.id, payload: req.body });
  res.status(202).end();
});

// Worker: processes independently
async function processQueue() {
  const event = await eventStore.dequeue();
  await handleBusinessLogic(event);
  await eventStore.markProcessed(event.id);
}

2. Idempotent Consumers

What it is: Every event handler checks whether the event has already been processed before running any business logic. The event ID from the provider payload is used as the idempotency key, stored in a processed_events table. Processing the same event twice produces the same outcome as processing it once.

Why it matters: No event delivery system guarantees exactly-once delivery. Retries, network partitions, and processing failures all create scenarios where the same event arrives multiple times. Without idempotency at the consumer level, duplicates produce duplicate side effects - fulfilled orders, sent emails, deducted inventory.

Idempotent consumers are the primary defense against duplicate processing at the application layer, and they are necessary regardless of what queue or broker infrastructure you use.

Photo by Brett Sayles on Pexels

When to apply: Every event consumer that writes state or triggers side effects. If the handler is purely read-only and produces no observable changes, idempotency is not necessary but still not harmful.

3. Dead Letter Queues

What it is: Events that fail to process after a defined number of retry attempts are moved to a separate "dead letter" storage location rather than dropped. A dead letter queue (DLQ) holds failed events for manual inspection and eventual reprocessing.

Why it matters: Some events fail not because of transient infrastructure issues but because of application-level problems: a referenced record does not exist, the payload is malformed, or an edge case in the business logic throws an unhandled exception. These events will fail on every retry until the underlying issue is fixed.

Without a DLQ, these events silently disappear. You may not know what data was missed until a customer reports a problem. With a DLQ, failed events are available for inspection, and once the code issue is fixed, they can be reprocessed without requiring the provider to resend them.

Basic implementation:

MAX_RETRIES = 3

def process_with_retry(event):
    for attempt in range(MAX_RETRIES):
        try:
            handle_event(event)
            return  # Success
        except Exception as e:
            log_attempt_failure(event.id, attempt, str(e))
            if attempt == MAX_RETRIES - 1:
                dead_letter_queue.push(event)  # Move to DLQ
                return

4. Circuit Breakers for Downstream Failures

What it is: A circuit breaker wraps calls to downstream services and tracks failure rates. When failures exceed a threshold, the circuit "opens" and subsequent calls fail immediately without attempting the downstream request. After a cooldown period, the circuit enters a "half-open" state and tests whether the downstream service has recovered.

Why it matters: When a downstream service (a payment gateway, a shipping API, a CRM) is experiencing an outage, your event handlers will fail on every attempt. Without a circuit breaker, your workers keep attempting calls to a known-bad service, consuming resources and creating a backlog of failed events.

Martin Fowler's Circuit Breaker pattern is the widely referenced description of this design. In practice, most teams implement it with a library (hystrix, opossum for Node.js, resilience4j for Java) rather than from scratch.

The circuit breaker is particularly valuable in event-driven integrations because it prevents a temporary downstream outage from turning into a permanent data backlog. When the downstream recovers, the circuit closes and events that were queued during the outage process normally.

"The pattern we see most often in integration work is teams building point-to-point connections that are brittle by design. Event-driven patterns are more work upfront, but the operational stability over time is not even close." - Dennis Traina, 137Foundry

5. Event Sourcing for Audit Trails

What it is: Rather than updating application state in-place, every state change is recorded as an immutable event in an event log. The current state of any entity is derived by replaying its event history. This is the core idea behind event sourcing.

Why it matters: For integration systems that handle high-value business events (payments, order state changes, inventory updates), the ability to audit what happened and replay events to rebuild state is genuinely valuable. When something goes wrong - a processing bug, a deployment that corrupted state - you can replay events from the log to restore correct state.

This is a heavier architectural commitment than the other four patterns. It is worth the investment for domains with complex state transitions, audit requirements, or frequent debugging needs. For simpler integrations, a combination of the first four patterns (queue, idempotency, DLQ, circuit breaker) provides most of the reliability benefits without the full event sourcing model.

When to apply: Financial transaction systems, inventory management with external integrations, any domain where "what happened and when" needs to be auditable over time.

Combining the Patterns

These five patterns compose naturally. A typical production integration setup looks like:

Events arrive at an endpoint that stores them in a queue (Pattern 1)
Workers dequeue events, run an idempotency check (Pattern 2), and attempt processing
Failed attempts are retried up to a limit, then moved to a DLQ (Pattern 3)
Calls to downstream services go through a circuit breaker (Pattern 4)
All state changes are written as immutable event records (Pattern 5, for applicable domains)

None of these patterns require specific infrastructure choices. They can be implemented with a PostgreSQL table as a queue, a Redis set for idempotency keys, a separate database table as a DLQ, and a simple failure counter in memory as a circuit breaker.

For teams building integrations that handle high-value business events and where reliability matters, API integration firm 137Foundry designs and implements these architectures as part of their data integration work. For a detailed look at the webhook-specific reliability patterns these designs are built on, the guide to building webhook integrations that handle failures gracefully covers the core decisions.

The foundational reading for event-driven reliability is well-distributed across the industry: the message queue pattern and idempotence articles on Wikipedia provide solid conceptual grounding, and Fowler's circuit breaker article is the canonical implementation reference.

Why Responsive Images Are the Most Overlooked Mobile Performance Fix

137Foundry — Sat, 04 Apr 2026 05:50:18 +0000

A site can have clean HTML, minimal JavaScript, optimized fonts, and efficient CSS - and still load slowly on mobile because someone uploaded a 2400px-wide JPEG for the hero section and left it there. Images are consistently the single largest contributor to page weight, and mobile users pay for that weight in both load time and data usage. The fix is well-documented, the browser support is excellent, and most teams still are not implementing it fully.

The issue is not ignorance of the problem - most developers know that oversized images hurt performance. The issue is that the correct implementation of responsive images involves three separate mechanisms that interact with each other, and partial implementations leave most of the performance benefit unrealized.

The Three-Part Solution

Part 1: srcset for Resolution Switching

The srcset attribute tells the browser what versions of an image are available and at what widths. The browser then chooses the most appropriate version based on the current viewport width and the device's pixel density.

<img
  src="product-800.jpg"
  srcset="product-400.jpg 400w,
          product-800.jpg 800w,
          product-1200.jpg 1200w,
          product-1600.jpg 1600w"
  alt="Product overview showing key features"
  width="800"
  height="600"
>

Without the sizes attribute (covered below), the browser defaults to assuming the image will render at 100% of the viewport width. This is often wrong - a product image in a three-column grid on desktop renders at roughly 33% of the viewport width, not 100%. The browser will still pick a reasonable option from srcset without sizes, but it will not be the optimal one.

The width and height attributes are not optional - they tell the browser how much space to reserve for the image before it loads, preventing layout shift. This directly improves Cumulative Layout Shift (CLS), one of the Core Web Vitals metrics Google uses in ranking calculations.

Photo by Karub ‎ on Pexels

Part 2: sizes for Layout Context

The sizes attribute tells the browser how wide the image will actually render at different viewport widths. Without this information, the browser cannot calculate the optimal source to request because it does not know whether the image occupies the full viewport width, half of it, or a fixed pixel value.

<img
  src="product-800.jpg"
  srcset="product-400.jpg 400w,
          product-800.jpg 800w,
          product-1200.jpg 1200w,
          product-1600.jpg 1600w"
  sizes="(max-width: 480px) 100vw,
         (max-width: 768px) calc(100vw - 2rem),
         (max-width: 1200px) 50vw,
         400px"
  alt="Product overview showing key features"
  width="800"
  height="600"
>

This tells the browser: on screens narrower than 480px, the image takes the full viewport width; on screens up to 768px, it takes the full width minus 2rem of padding; on screens up to 1200px, it takes half the viewport; on larger screens, it renders at a fixed 400px. With this information, the browser can select the minimum file that will look sharp at each size.

The MDN documentation on responsive images covers the srcset and sizes interaction in depth, including the calculation the browser uses to select the appropriate source.

Part 3: Modern Formats with the picture Element

JPEG and PNG have been the default image formats for web use for decades. WebP and AVIF offer significantly better compression at equivalent visual quality - WebP typically reduces file size by 25-35% compared to JPEG, and AVIF reduces it further still. The <picture> element lets you serve these modern formats to browsers that support them while falling back to JPEG for browsers that do not.

<picture>
  <source
    type="image/avif"
    srcset="product-400.avif 400w, product-800.avif 800w, product-1200.avif 1200w"
    sizes="(max-width: 768px) 100vw, 50vw"
  >
  <source
    type="image/webp"
    srcset="product-400.webp 400w, product-800.webp 800w, product-1200.webp 1200w"
    sizes="(max-width: 768px) 100vw, 50vw"
  >
  <img
    src="product-800.jpg"
    srcset="product-400.jpg 400w, product-800.jpg 800w, product-1200.jpg 1200w"
    sizes="(max-width: 768px) 100vw, 50vw"
    alt="Product overview showing key features"
    width="800"
    height="600"
  >
</picture>

The browser reads the source elements from top to bottom and uses the first one it supports. AVIF gets priority, then WebP, then JPEG as the fallback. The caniuse data for WebP shows support above 97% globally, and AVIF support has crossed 90% in modern browsers.

The Automation Problem

Manually generating four format variants at four size variants for every image on a site is not sustainable for content-heavy projects. The right approach is to automate image processing as part of the build pipeline or at the content management layer.

Cloudinary, Imgix, and Cloudflare Images are CDN-based services that handle format conversion, resizing, and delivery automatically. You upload a source image and the service generates appropriate derivatives on-demand based on URL parameters or automatic optimization. The Google developer documentation on image optimization covers the principles behind this approach.

For teams managing image processing at the build layer, Sharp is a Node.js image processing library that generates optimized variants efficiently. ImageMagick provides equivalent functionality in server-side and CLI contexts.

The lazy Attribute: Deferring Off-Screen Images

Beyond serving the right image size, there is a simpler win available for below-the-fold images: native lazy loading. Adding loading="lazy" to an img element tells the browser to defer loading that image until it is near the viewport, rather than loading all images as soon as the HTML is parsed.

<!-- Images below the fold do not need to load immediately -->
<img
  src="article-inline-800.jpg"
  srcset="article-inline-400.jpg 400w, article-inline-800.jpg 800w"
  sizes="(max-width: 768px) 100vw, 50vw"
  alt="Diagram showing responsive image size selection logic"
  width="800"
  height="450"
  loading="lazy"
>

The loading="lazy" attribute has broad browser support and requires no JavaScript or external libraries. For pages with multiple inline images - articles, product listings, portfolio pages - lazy loading significantly reduces the initial page payload and improves LCP for the content above the fold.

One important exception: do not apply loading="lazy" to the largest contentful element or any image above the fold. The browser needs to load those immediately for LCP. Lazy loading is for images the user has not yet scrolled to.

"Image weight is the single biggest performance win most sites leave on the table. We regularly cut 40-60 percent off total page weight just by implementing proper srcset with a CDN in front of it - without touching a single line of application code." - Dennis Traina, 137Foundry

Photo by AS Photography on Pexels

Practical Starting Point

If you are working on a site that does not yet have responsive images, the fastest path to improvement is not a full pipeline implementation - it is auditing the current images with PageSpeed Insights or WebPageTest to identify the largest offenders, then implementing srcset and sizes on those specific images first. The Pareto distribution applies strongly to image weight: typically 20% of images account for 80% of the wasted bytes.

For a complete look at how mobile performance decisions fit into mobile-first design as a whole - including Core Web Vitals targets, fluid typography, and touch-first interaction design - the guide to mobile-first web design connects these technical details to the broader design approach.

137Foundry handles image optimization as a standard part of web development projects, integrating the three-part responsive image system alongside CDN configuration so performance does not degrade as content grows.

The responsive image specification has been supported in all major browsers since 2016. There is no longer a compatibility reason to avoid it. The only remaining barrier is implementation effort - and for most sites, addressing the largest image offenders takes an afternoon and measurably improves both page speed and search rankings.

5 Open Source CSS Frameworks for Mobile-First Web Development

137Foundry — Sat, 04 Apr 2026 05:50:16 +0000

CSS frameworks have evolved significantly from their early origins as grid systems bolted onto fixed-width layouts. The modern options are either built mobile-first from the ground up or have been substantially rearchitected in that direction. Here are the ones worth evaluating for projects where responsive design quality matters from day one.

Here are the ones I keep coming back to, depending on the project.

1. Tailwind CSS

Link: tailwindcss.com

Tailwind takes a utility-first approach - instead of semantic component classes, you compose layouts directly in HTML using low-level utility classes. Mobile-first is baked into the responsive prefix system: md:flex-row means "apply flex-row at the md breakpoint and above," which is a mobile-first media query by definition.

The configuration file gives you full control over breakpoints, spacing scales, color palettes, and typography. Tailwind's JIT (just-in-time) compiler generates only the CSS you actually use, so production builds are typically a few kilobytes rather than the hundreds of kilobytes a legacy framework ships with.

The tradeoff is verbose HTML and a learning curve for the naming conventions. But for teams that have adopted it, the speed advantage for building responsive layouts is substantial - you can see the layout respond across breakpoints as you add classes without switching to a stylesheet.

Photo by Bibek ghosh on Pexels

2. Bootstrap 5

Link: getbootstrap.com

Bootstrap 5 dropped the jQuery dependency and significantly improved its mobile-first implementation compared to earlier versions. The grid system uses Flexbox throughout and the breakpoint system goes from xs (no prefix, mobile default) upward through sm, md, lg, xl, and xxl.

Bootstrap's strength is its component library. If you need a working mobile-friendly navigation, modal, accordion, carousel, or form in minimal time, Bootstrap has production-ready implementations of all of them. The documentation is comprehensive and the browser compatibility is broad.

For projects where design differentiation matters, Bootstrap requires more design work to avoid the "Bootstrap look" - but the underlying grid and component infrastructure is solid. The Bootstrap 5 grid documentation is worth reading even if you use a different framework, as it explains mobile-first grid concepts clearly.

3. Foundation by Zurb

Link: get.foundation

Foundation was mobile-first before most frameworks made it a default. The grid system uses a 12-column flexbox layout with named breakpoints (small, medium, large, xlarge, xxlarge) and a progressive-disclosure approach where small-screen styles are the base and larger viewports add or override them.

Foundation's XY Grid is notably more flexible than Bootstrap's grid for complex layouts - it supports both fixed-count column grids and flexible grid patterns that adapt to content width. The framework also ships with motion UI for accessible animations, which is a useful inclusion for projects where entrance animations matter.

Foundation is used less frequently than Tailwind or Bootstrap in new projects today, but it remains an excellent option for content-heavy sites and applications where its grid flexibility addresses layout problems that simpler grids struggle with.

4. Bulma

Link: bulma.io

Bulma is a pure-CSS framework (no JavaScript) built entirely on Flexbox. The component system is semantic rather than utility-based - you apply class names like columns, column, card, and navbar that describe the component type rather than the specific styles.

Bulma's mobile-first approach means all components default to stacked single-column layouts and expand to multi-column at the tablet and desktop breakpoints. The framework is lightweight (the full build is under 200KB unminified) and has no JavaScript dependencies, making it a good option for projects where you want a CSS layer without JavaScript coupling.

The documentation includes a detailed responsive columns guide that shows how to use the breakpoint classes to control column behavior across device sizes.

5. Pico.css

Link: picocss.com

Pico is minimal by design. It applies sensible, accessible default styles to semantic HTML elements without requiring any class names for basic layouts. A form element automatically gets mobile-friendly input sizing and spacing. A nav element gets responsive behavior. Tables reflow correctly on small screens.

Pico is not the right choice for complex component-heavy applications, but for content sites, landing pages, documentation, and simple web applications, it provides a clean mobile-first baseline in under 10KB. The tradeoff is that customization requires CSS overrides rather than a configuration system, so it scales less well to large design systems.

For teams building sites where mobile performance is critical, Pico's minimal footprint makes it worth considering as a starting foundation over heavier alternatives.

How to Choose Between Them

The frameworks above serve meaningfully different use cases, and the wrong choice adds friction rather than speed. A few questions that help clarify the decision:

How custom does the visual design need to be? Tailwind gives you the most control with the least visual opinion. Bootstrap and Foundation have stronger default aesthetics that require more work to override. Pico and Bulma sit in the middle - sensible defaults that are relatively easy to theme.

How much component coverage do you need out of the box? Bootstrap has the broadest component library: navbars, carousels, modals, accordions, dropdowns. If your project needs these and you want them already built, Bootstrap is worth the overhead. Tailwind requires you to build or import components separately.

What is the team's CSS familiarity? Tailwind has a steeper initial learning curve. Developers new to CSS often find Bootstrap or Bulma's semantic class names more approachable because they map to components they can reason about. Tailwind rewards teams that are comfortable thinking in terms of CSS properties rather than component names.

What are the performance constraints? For sites where page weight directly affects business outcomes - high mobile traffic, performance-sensitive markets - Pico and Tailwind (with PurgeCSS configured) produce the smallest production builds. Bootstrap and Foundation require more careful configuration to avoid shipping unused styles.

137Foundry works across the full range of these frameworks depending on project requirements - the right choice depends on team familiarity, project scale, and the balance between speed-to-ship and design customization needs.

"Most frameworks give you the grid, but they can't give you the layout decisions. We've seen teams spend more time fighting a framework's responsive system than they would have spent writing the CSS themselves. The framework should serve the design - not the other way around." - Dennis Traina, 137Foundry

The choice of CSS framework matters less than the discipline of writing mobile-first CSS within whatever system you choose. The frameworks above all support mobile-first patterns natively - whether you use them depends on your project's specific requirements for component coverage, bundle size, and design flexibility.

For a deeper look at how mobile-first principles apply beyond the framework layer - including design decisions, performance budgets, and SEO implications - the guide to mobile-first web design principles covers what changes when you build from mobile up versus desktop down.

Photo by Negative Space on Pexels

Related Resources

MDN: Responsive Web Design Basics - Foundation concepts before you pick a framework
web.dev: Mobile-First - Google's guidance on responsive design fundamentals
Google Mobile-First Indexing - Why mobile-first design now directly affects search rankings
CSS-Tricks: A Complete Guide to Flexbox - The layout model all modern frameworks are built on

Why Interaction to Next Paint Changed How Developers Think About Responsiveness

137Foundry — Fri, 03 Apr 2026 03:10:49 +0000

For years, First Input Delay was the responsiveness metric in Core Web Vitals. It measured one thing: the delay between a user's first interaction and the browser starting to process it. Most sites passed FID easily because it only captured input delay on the first click, ignoring everything after that. A page could freeze for two seconds when you opened a dropdown menu, and FID would not register it.

In March 2024, Google replaced FID with Interaction to Next Paint. The shift was not cosmetic. INP fundamentally changed what "responsive" means for web applications by measuring every interaction across the entire page visit, not just the first one, and by tracking the complete lifecycle of each interaction through input delay, processing, and paint.

This article explains why the change matters, what INP actually measures, and how to think about responsiveness now that the rules have changed.

What FID Got Wrong

First Input Delay measured the gap between a user's first click (or tap or keypress) and the moment the browser began running the event handler. This was useful but deeply limited.

The biggest problem was that FID only captured the first interaction. If your page loaded cleanly but became sluggish after JavaScript hydration completed, after a state update triggered a heavy re-render, or after a third-party script loaded, FID would still report a good score. Users experiencing a slow, janky interface would not be reflected in the metric.

FID also only measured input delay, the time spent waiting before processing started. It did not count how long the event handler itself took to run, and it did not count how long the browser took to update the screen after the handler finished. A click that had zero input delay but took 800ms to process and paint would score perfectly under FID.

According to Chrome's analysis of real-user data, over 90% of websites passed the FID threshold of 100ms. That number made FID essentially useless as a differentiator. Meanwhile, users continued to report feeling that sites were slow and unresponsive.

Photo by cottonbro studio on Pexels

What INP Measures Differently

Interaction to Next Paint captures the full lifecycle of an interaction in three phases:

Input delay is the time between the user's action (click, tap, keypress) and the browser starting to run your event handler. This is what FID measured, but INP captures it for every interaction, not just the first one.

Processing time is how long your event handler takes to execute. If clicking a button triggers a state update that causes React to re-render a large component tree, that entire rendering time counts as processing time.

Presentation delay is the time between your handler finishing and the browser updating pixels on screen. This includes layout calculation, paint, and compositing. If your handler changes CSS properties that trigger layout (like width, height, or position), the presentation delay can be significant.

The INP value for a page visit is typically the interaction with the worst latency (with some statistical adjustment for pages with many interactions). Google considers 200ms or less "good," 200-500ms "needs improvement," and over 500ms "poor."

The web.dev INP documentation explains the statistical methodology. For most sites, the reported INP value is the 98th percentile interaction, meaning it reflects the worst experience a typical user encounters during their visit.

Why This Changes How You Build

Under FID, responsiveness was mostly about avoiding long tasks during initial page load. If your JavaScript did not block the main thread before the first click, you passed. Developers focused on code splitting, lazy loading, and deferring non-critical scripts, all optimizations for the initial load window.

INP requires responsiveness throughout the entire session. This shifts the focus from "fast to load" to "fast to use." Specific patterns that passed FID but fail INP:

Heavy state updates on interaction. Clicking a filter that triggers a re-render of 500 list items blocks the main thread during processing. Under FID, this was invisible unless it happened to be the first interaction. Under INP, it counts every time.

Synchronous layout calculations in event handlers. Reading layout properties (like offsetHeight or getBoundingClientRect()) inside a click handler forces the browser to calculate layout synchronously, which blocks the main thread. The Google developers documentation on forced layout covers this in detail.

Third-party scripts that run on interaction. Analytics scripts that fire on every click, chat widgets that initialize on first interaction, and consent management platforms that intercept touches all contribute to INP.

"INP changed the conversation from 'how fast does the page load' to 'how fast does the page respond to every single thing the user does.' That is a much harder bar to clear, and it is exactly what users actually care about." - Dennis Traina, 137Foundry

Practical Fixes That Work

The good news is that INP optimizations follow predictable patterns.

Break up long event handlers. If a click handler triggers work that takes more than 50ms, split it. Use scheduler.yield() (available in Chrome and behind a flag in other browsers) or setTimeout(0) to yield back to the browser between chunks of work. This lets the browser process pending user input and paint updates between your work chunks.

async function handleFilterClick(selectedFilter) {
  // Update the UI immediately
  showLoadingIndicator();

  // Yield to let the browser paint the loading state
  await scheduler.yield();

  // Now do the expensive filtering
  const filtered = applyFilter(data, selectedFilter);

  // Yield again before rendering results
  await scheduler.yield();

  renderResults(filtered);
}

Debounce rapid interactions. Scroll handlers, resize listeners, and search-as-you-type inputs can fire dozens of events per second. Debounce them so the expensive work only runs once after the user stops interacting, rather than on every individual event.

Move computation to Web Workers. Data processing, sorting large arrays, and parsing JSON payloads do not need to happen on the main thread. A Web Worker runs JavaScript in a background thread that cannot block user interactions.

Optimize React re-renders. Use React.memo to prevent unnecessary re-renders, useMemo for expensive calculations, and useTransition to mark non-urgent state updates as low priority so they do not block the main thread during user interactions. The React documentation on Transitions explains how startTransition keeps the UI responsive during heavy updates.

For a broader look at all three Core Web Vitals and the diagnostic workflow from field data to fixes, this complete guide to Core Web Vitals covers LCP and CLS alongside INP.

Photo by Daniil Komov on Pexels

Measuring INP in Production

Lab tools like Lighthouse simulate interactions, but they cannot replicate the variety of real user behavior. Some users click rapidly, some use keyboard navigation, some interact with elements that your test script never touches. Real-user monitoring is the only reliable way to track INP.

The web-vitals library reports INP values from actual visitors. Integrate it with your analytics pipeline to see which pages and which interactions have the highest INP values. The attribution build identifies the exact element and event type responsible for the worst interaction.

Teams at 137Foundry typically pair web-vitals monitoring with the Chrome DevTools Interactions track to diagnose specific slow interactions identified in field data. That combination of real-user detection and lab investigation is the fastest path to fixing INP problems.

The Responsiveness Standard Is Higher Now

INP raised the bar for what counts as a responsive web application. Passing FID was easy because it only measured one moment. Passing INP requires that every interaction, on every page, throughout the entire visit, responds within 200ms. That is a higher standard, but it is also a more honest reflection of user experience. Sites that invest in INP optimization are genuinely faster to use, which translates to better engagement, lower bounce rates, and a ranking advantage in competitive search results.

5 Browser DevTools Tricks for Debugging Core Web Vitals

137Foundry — Fri, 03 Apr 2026 03:10:46 +0000

Most developers know Chrome DevTools for setting breakpoints and inspecting CSS. But the Performance and Rendering panels contain specialized features for debugging Core Web Vitals that even experienced developers overlook. These are not experimental flags or hidden menus. They are stable, production-ready features built specifically for diagnosing LCP, CLS, and INP problems.

The difference between guessing at performance issues and knowing exactly what to fix comes down to using the right DevTools features at the right time. Here are five that consistently help me track down the root cause of Core Web Vitals failures.

1. The Performance Panel's Web Vitals Track

The Performance panel records everything that happens during page load and user interaction. But the default view can be overwhelming, with dozens of tracks showing network requests, rendering activity, GPU work, and JavaScript execution simultaneously.

The trick is to focus on the Web Vitals lane in the Experience section. After recording a performance trace (press Ctrl+Shift+E to start recording with a page reload), expand the Experience track. You will see markers for LCP, layout shifts (CLS events), and interactions (INP candidates).

Click on the LCP marker to see exactly which element triggered it and when it rendered. Click on a layout shift marker to see which elements moved and by how much. Click on an interaction marker to see the full breakdown of input delay, processing time, and presentation delay.

This targeted approach turns a wall of data into a focused investigation. Instead of scanning the entire waterfall looking for "slow things," you start from the metric that is failing and trace backward to the cause.

The Chrome DevTools Performance panel reference documents every track and what it measures. Spend 20 minutes reading it once, and your debugging sessions will be significantly faster going forward.

Photo by Daniil Komov on Pexels

2. Layout Shift Regions Overlay

CLS problems are notoriously hard to debug because layout shifts happen fast. By the time you notice the page jumped, the shift is over and you cannot tell which element moved or why.

DevTools has a rendering overlay that highlights layout shift regions in real time. Open the Command Menu (Ctrl+Shift+P), type "Show Rendering," and enable Layout Shift Regions. Now, every time an element shifts position, DevTools draws a blue rectangle around the affected area.

Reload the page and watch. You will see exactly which elements shift and when. Common findings include:

Images loading without reserved dimensions causing text below them to jump
Web fonts swapping in with different metrics than the fallback font
Ads or embedded widgets injecting content above the fold
Cookie consent banners that push page content down instead of overlaying it

Once you see the shifting element, fixing it is usually straightforward. Add explicit width and height attributes to images, use font-display: optional to prevent font swaps, or reserve space for dynamic content with CSS min-height.

"Most CLS fixes are trivially simple once you can see which element is shifting. The hard part is always identification, not the fix itself." - Dennis Traina, 137Foundry

3. Network Throttling With Request Blocking

LCP failures on fast development machines often stem from resources that are perfectly fine on a gigabit connection but catastrophically slow on mobile networks. DevTools network throttling simulates slower connections, but the real trick is combining throttling with request blocking.

Open the Network panel, set throttling to "Slow 3G" or create a custom profile (DevTools lets you define exact download speed, upload speed, and latency). Then right-click any request and select "Block request URL" or "Block request domain." This lets you test what happens when specific resources are slow or unavailable.

Practical uses:

Block your analytics and chat widget scripts to see how much they affect LCP
Block third-party font CDNs to test your font fallback strategy
Block specific JavaScript bundles to find which ones are render-blocking
Throttle to 3G and reload to see what your mobile users actually experience

The Network reference in DevTools covers request blocking and custom throttling profiles. For a complete walkthrough of Core Web Vitals diagnostics, this guide covers the full process from identifying failures in Search Console to applying targeted fixes.

4. The Interactions Track for INP Debugging

Interaction to Next Paint replaced First Input Delay in March 2024, and many developers still debug it using FID-era techniques that miss the point. FID only measured input delay (the gap between a click and the browser starting to process it). INP measures the entire interaction lifecycle: input delay plus processing time plus presentation delay.

The Performance panel's Interactions track shows every user interaction during a recording. Record a trace while clicking buttons, opening dropdowns, typing in form fields, and scrolling. Each interaction appears as a block in the Interactions track, colored by duration:

Green: under 200ms (good)
Yellow: 200-500ms (needs improvement)
Red: over 500ms (poor)

Click on any interaction to see the three phases broken down. If input delay is the problem, look for long tasks running when the user clicked. If processing time is the problem, your event handler is doing too much work. If presentation delay is the problem, the browser is spending too long on layout and paint after your handler finishes.

The web.dev INP guide explains each phase and the common causes. The Long Animation Frames API (available in Chrome 123+) provides even more detail about what scripts are blocking during interactions.

Teams at 137Foundry regularly use this workflow to trace INP problems to specific event handlers, third-party scripts, or framework hydration bottlenecks.

5. Performance Insights Panel

The Performance Insights panel (separate from the standard Performance panel) provides a simplified, guided view of performance data. While the Performance panel gives you raw data and expects you to know what to look for, Performance Insights highlights the specific issues and links them to actionable recommendations.

After recording a trace, Performance Insights shows a timeline with annotated insights:

"Render blocking request" with the specific CSS or JS file identified
"Layout shift" with the culprit element and the shift score
"Long task" with the script responsible and its duration
"LCP" with the element and timing breakdown

Each insight links to documentation explaining why it matters and how to fix it. This panel is especially useful for developers who are new to performance optimization and want guided analysis rather than raw data.

The Performance Insights documentation walks through the panel's features. It does not replace the full Performance panel for deep investigation, but it catches the most common issues faster.

Photo by Tiger Lily on Pexels

Putting It Together

These five features cover different aspects of Core Web Vitals debugging:

Feature	Primary Metric	What It Reveals
Web Vitals Track	All	Which metrics fail and when
Layout Shift Regions	CLS	Which elements shift and why
Network Throttling + Blocking	LCP	Which resources delay rendering
Interactions Track	INP	Which interactions are slow and why
Performance Insights	All	Guided analysis with recommendations

Start with the Web Vitals Track to identify which metric is failing. Then use the specialized tool for that specific metric. The fastest path to fixing Core Web Vitals is always: identify the failing metric, isolate the root cause, fix the specific element, and verify in field data after deploy.

Performance debugging is a skill that improves with practice. These tools make the process systematic rather than based on guesswork, and they are all available right now in your browser without installing anything.