How to Implement Lightweight Front-End White‑Screen Monitoring and Troubleshooting

Preface

In front‑end development, page white‑screen time is a key metric; long white‑screen periods degrade user experience, and unexpected white screens indicate stability risks.

This article introduces a lightweight implementation for white‑screen monitoring in front‑end projects and discusses governance strategies.

By monitoring and reporting white‑screen events before user feedback, teams can proactively improve experience, resolve hidden issues, and add an extra dimension of system stability.

Common White‑Screen Scenarios

Scenario 1

A JavaScript error during rendering causes a white screen, common in React projects.

Scenario 2

Front‑end routing fails to match and no 404 fallback component is configured, often when an H5 URL is set incorrectly.

Scenario 3

No JavaScript error occurs, but the rendering path is incorrect; typical code patterns include returning null while loading or rendering an empty container.

if (loading) {
  return null;
}
return <div>...business content...</div>;
// or
// <div style="height: 100vh">
//   <template v-if="!loading; ">...business content</template>
// </div>

How to Detect?

Detection Timing

When a user enters a page (including initial load and SPA route changes), debounce 3 seconds and use document.elementsFromPoint to sample points along the horizontal and vertical mid‑lines.

If the elements returned from both mid‑lines are the same, a white screen is assumed.

Overall, document.elementsFromPoint works well on mobile; for special compatibility needs, document.elementFromPoint can be used.

Core Detection Process

// Determine if all sampled elements are the same
const isSameElement = (nodeList) => {
  // implementation omitted
};

// Sampling and reporting
const sampling = (reportWhiteScreen) => {
  const sampledElements = [];
  const innerWidth = window.innerWidth;
  const innerHeight = window.innerHeight;
  for (let i = 1; i <= 19; i++) {
    const xElements = document.elementsFromPoint((innerWidth * i) / 20, innerHeight / 2);
    const yElements = document.elementsFromPoint(innerWidth / 2, (innerHeight * i) / 20);
    sampledElements.push(xElements[0]);
    if (i !== 10) {
      sampledElements.push(yElements[0]);
    }
  }
  if (isSameElement(sampledElements)) {
    reportWhiteScreen(sampledElements[0]);
  }
};

// Debounced check after pageview
export const debounceCheckWhiteScreen = () => {
  // placeholder for reporting logic
  sampling(() => {});
};

Handling Edge Cases

Real‑world scenarios are more complex; pages run in various containers and business requirements differ.

Replaced Elements

Replaced elements (e.g., <iframe> ) render independently of CSS and are not affected by parent styles. In white‑screen detection, these elements do not need to be checked for content.

Thus, detection focuses on common container tags such as HTML, BODY, DIV, NAV, MAIN, SECTION, FOOTER, HEADER.

const COMMON_CONTAINER_TAG_NAMES = [
  'HTML',
  'BODY',
  'DIV',
  'NAV',
  'MAIN',
  'SECTION',
  'FOOTER',
  'HEADER',
];
if (COMMON_CONTAINER_TAG_NAMES.indexOf(whiteElementTagName) > -1) {
  reportWhiteScreen();
}

Page Not Visible

When a webview is hidden (e.g., multiple pages open in a mobile app), white‑screen detection is unnecessary; add a visibleState check.

Toast Followed by White Screen

After a normal error toast disappears, the page may still be white; a secondary confirmation step is required.

White Screens That Are Normal

Not all reported white screens indicate bugs; they can result from slow network loading or intentionally empty transition pages.

Slow Page Load

If FCP 75th percentile exceeds 2 seconds, white‑screen reports may rise above 0.8 %.

Solution: optimize code, e.g., add skeleton screens.

Deliberate Empty Design

These pages are defined as empty and should be excluded from alerts.

White‑Screen Detection Workflow

After handling various edge cases, the detection flow is as follows:

Some false positives are expected, but the goal is to observe white‑screen metrics and enable targeted troubleshooting; false alerts can be filtered by route.

Solution Trade‑offs

We compared several mainstream white‑screen detection solutions and chose the one best suited to our business needs.

Troubleshooting Approach

With detection in place, we can discover and resolve H5 page white‑screen issues.

Leveraging our logging system and monitoring platform, we configure dashboards and alert rules for white‑screen logs.

Dashboard Monitoring

Set up route‑level white‑screen dashboards to observe trends during routine checks or after alerts.

Alert Notifications

Compare the current white‑screen ratio with the same time on the previous day; trigger alerts when exceeding thresholds.

The image below shows an alert during a production incident drill.

Investigating Existing Issues

Beyond new cases, historical abnormal white screens often stem from data anomalies in a few scenarios or unhandled user actions.

Data anomalies in limited scenarios.

Special user operations or unhandled states causing missing page content.

Investigate by correlating other logs, checking for API errors or JavaScript errors.

Reflection and Planning

This article presented a lightweight front‑end white‑screen monitoring solution now covering all domestic H5 pages at Huolala, with generic and customized alert rules.

By reviewing reported white‑screen logs, we identified both code defects and business‑side misconfigurations, confirming the solution’s effectiveness.

Future steps include:

Page‑by‑page investigation of reported cases to resolve issues.

Adjust false‑positive handling and whitelist routes in alerts.

After fixing, refine alert thresholds per page.

Continuously monitor related metrics to prevent regression.

With these measures, white‑screen monitoring will further improve user experience and system stability.