Unlocking Performance Insights: Measuring Soft Navigations in Single Page Applications

The web is constantly evolving, and with it, the way we measure website performance. Google's Core Web Vitals initiative emphasizes user experience, prompting a shift from traditional technical metrics to user-centric ones. However, Single Page Applications (SPAs), with their unique "soft navigation" architecture, have presented a challenge to accurately measure performance using existing tools. This article dives deep into the experimental efforts to measure soft navigations and how you can leverage them to gain valuable insights into your SPA's performance.

The Challenge of Soft Navigations

Traditional website architecture involves loading distinct web pages upon navigation. SPAs, however, employ "soft navigations," where JavaScript dynamically updates the page content without fully reloading. This creates a smoother user experience but disrupts traditional performance measurement methods.

The core issue is defining what constitutes a "soft navigation" and how to measure it consistently. Is it simply an interaction on the page, or a genuine navigation event warranting separate performance metrics?

Defining Soft Navigations

To address this challenge, the Chrome team has proposed the following definition of a soft navigation:

• User-Initiated: The navigation begins with a user action (e.g., a button click).
• Visible URL Change: The user perceives a change in the URL, and the browser's history is updated.
• DOM Change: The navigation leads to a modification of the Document Object Model (DOM), reflecting the new content.

Keep in mind that these heuristics might generate false positives or negatives. Provide Feedback at the soft navigation specification repository if you see otherwise.

Chrome's Implementation of Soft Navigations

When soft navigation heuristics are enabled, Chrome alters how it reports certain performance metrics:

• PerformanceTiming Event: A soft-navigation event is emitted after each detected soft navigation, providing detailed timing information.
• Performance API Access: The Performance API grants access to soft-navigation timing entries.
• Metric Resets: First Paint (FP), First Contentful Paint (FCP), and Largest Contentful Paint (LCP) metrics are reset and re-emitted upon the next appropriate occurrences.
• navigationId Attribute: A navigationId attribute is added to relevant performance timings (first-paint, first-contentful-paint, largest-contentful-paint, first-input-delay, event, and layout-shift), enabling accurate Cumulative Layout Shift (CLS) and Interaction to Next Paint (INP) calculations. These metrics can also be found in our articles about optimizing CLS and improving INP.

These changes allow you to measure Core Web Vitals for each page navigation, offering a more granular understanding of user experience within SPAs.

Implications of Enabling Soft Navigations

Before enabling soft navigations in Chrome, be aware of these implications:

• Additional Metric Events: FP, FCP, and LCP events might be re-emitted. While the Chrome User Experience Report (CrUX) ignores these extra values, Real User Measurement (RUM) monitoring could be affected. Contact your RUM provider if you have any concerns.
• navigationID Attribute: If you're using performance entries in your application code, you might need to consider the new navigationID attribute.
• Browser Support: This feature is currently exclusive to Chromium-based browsers. Ensure you account for users on other browsers or older Chromium versions who might not report soft-navigation metrics.

As enabling this feature is experimental, it's crucial to meticulously test it to identify unforeseen side effects.

Enabling Soft Navigations in Chrome

Soft navigations are not enabled by default. Here's how to enable this feature for testing:

• For Developers: Turn on the "Experimental Web Platform features" flag in Chrome at chrome://flags/#enable-experimental-web-platform-features or use the --enable-experimental-web-platform-features command-line argument.
• For Websites (Origin Trial): Enroll in the origin trial running from Chrome 117. Include a meta element with the origin trial token in either the HTML or HTTP header. See the Get started with origin trials post for complete instructions.

You can selectively enable the origin trial for a portion of your users to control the impact. Please be mindful of the implications mentioned earlier, particularly when enabling for a large user percentage. Keep in mind that Origin trials are limited to enabling experimental features on 0.5% of Chrome page loads as a median over 14 days.

Measuring Soft Navigations: A Practical Guide

Once Soft navigation experimentation has been enabled, the metrics will be reported to you using the standard PerformanceObserver API as usual.

Reporting Basics

You can subscribe to soft navigation notifications like this:

const observer = new PerformanceObserver(console.log);
observer.observe({ type: "soft-navigation", buffered: true });

Aligning Metrics with the Correct URL

Soft navigations are only visible after they complete. The best way to report metrics under the correct URL is to finalize these metrics on navigation and ensure they report as the previous URL of the page.

const softNavEntry =
 performance.getEntriesByType('soft-navigation').filter(
 (entry) => entry.navigationId === navigationId
 )[0];
const hardNavEntry = performance.getEntriesByType('navigation')[0];
const navEntry = softNavEntry || hardNavEntry;
const pageUrl = navEntry?.name;

Report the metrics against the pageUrl variable, rather than the updated URL.

Getting the Navigation Start Time

The navigation start time can be obtained in this way:

const softNavEntry =
 performance.getEntriesByType('soft-navigation').filter(
 (entry) => entry.navigationId === navigationId
 )[0];
const hardNavEntry = performance.getEntriesByType('navigation')[0];
const navEntry = softNavEntry || hardNavEntry;
const startTime = navEntry?.startTime;

The startTime is the time of the initial interaction (for example, a button click) which initiated the soft navigation.

Measuring Core Web Vitals

A flag must be set to include soft navigation entry metrics. Add includeSoftNavigationObservations: true to your performance observer's function call.

new PerformanceObserver((entryList) => {
 for (const entry of entryList.getEntries()) {
 console.log('Layout Shift time:', entry);
 }
}).observe({type: 'layout-shift', buffered: true, includeSoftNavigationObservations: true});

To calculate LCP for a soft navigation, you'll need to offset the LCP timing to get a timing relative to the soft navigation. For example:

new PerformanceObserver((entryList) => {
 for (const entry of entryList.getEntries()) {
 const softNavEntry =
 performance.getEntriesByType('soft-navigation').filter(
 (navEntry) => navEntry.navigationId === entry.navigationId
 )[0];
 const hardNavEntry = performance.getEntriesByType('navigation')[0];
 const navEntry = softNavEntry || hardNavEntry;
 const startTime = navEntry?.startTime;
 console.log('LCP time:', entry.startTime - startTime);
 }
}).observe({type: 'largest-contentful-paint', buffered: true, includeSoftNavigationObservations: true});

With long-lived metrics, you might need to "reset" or "reinitialize" them to treat them as new metrics, without regard for the memory values set for previous pages. Metrics will have to finalized upon each new soft navigation or hard navigation event.

Considerations for Content Consistency

FP, FCP, and LCP for soft navigations will only measure new paints. This can result in a different LCP from a cold load versus a soft load.

Measuring TTFB for Soft Navigations

For soft navigations, the "true" TTFB might be elusive. For now, consider reporting a TTFB of 0. In the future, more precise methods of identifying the "navigation request" might emerge. This is a similar recommendation to the handling of back/forward cache restores. The web-vitals library recommends using 0.

Conclusion

Measuring soft navigations is a crucial step towards accurately assessing the user experience of SPAs. By understanding the definition of soft navigations, enabling the experimental features in Chrome, and implementing the appropriate measurement techniques, you can gain valuable insights into your SPA's performance. As this technology evolves, your feedback and experimentation will play a vital role in shaping the future of web performance measurement.