From 7fa1cdf5e1a329ce7415f098c09c1e9b027f1c65 Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Fri, 14 Jul 2023 13:26:26 +0100 Subject: [PATCH 1/9] Adds docs for notRestoredReasons --- files/en-us/web/api/performance_api/index.md | 1 + .../index.md | 156 ++++++++++++++++++ .../api/performancenavigationtiming/index.md | 2 + .../notrestoredreasons/index.md | 76 +++++++++ files/jsondata/GroupData.json | 3 +- 5 files changed, 237 insertions(+), 1 deletion(-) create mode 100644 files/en-us/web/api/performance_api/reporting_backforward_cache_not_restored_reasons/index.md create mode 100644 files/en-us/web/api/performancenavigationtiming/notrestoredreasons/index.md diff --git a/files/en-us/web/api/performance_api/index.md b/files/en-us/web/api/performance_api/index.md index 933da2692142eda..ba78dedb57b5fa8 100644 --- a/files/en-us/web/api/performance_api/index.md +++ b/files/en-us/web/api/performance_api/index.md @@ -90,6 +90,7 @@ The following guides help you to understand key concepts of the Performance API - [Navigation timing](/en-US/docs/Web/API/Performance_API/Navigation_timing): Measuring navigation timing of a document. - [User timing](/en-US/docs/Web/API/Performance_API/User_timing): Measuring and recording performance data custom to your application. - [Server timing](/en-US/docs/Web/API/Performance_API/Server_timing): Collecting server-side metrics. +- [Reporting back/forward cache not restored reasons](/en-US/docs/Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons): Reporting on whether frames present in the document were blocked from using the [back/forward cache](https://web.dev/bfcache/) (bfcache), and why. - Paint timing - Long task timing - Largest contentful paint diff --git a/files/en-us/web/api/performance_api/reporting_backforward_cache_not_restored_reasons/index.md b/files/en-us/web/api/performance_api/reporting_backforward_cache_not_restored_reasons/index.md new file mode 100644 index 000000000000000..20f20bef8b0635a --- /dev/null +++ b/files/en-us/web/api/performance_api/reporting_backforward_cache_not_restored_reasons/index.md @@ -0,0 +1,156 @@ +--- +title: Reporting back/forward cache not restored reasons +slug: Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons +page-type: web-api-overview +status: + - experimental +browser-compat: api.PerformanceNavigationTiming.notRestoredReasons +--- + +{{DefaultAPISidebar("Performance API")}}{{SeeCompatTable}} + +The {{domxref("PerformanceNavigationTiming.notRestoredReasons")}} property reports information on whether frames present in the document were blocked from using the [back/forward cache](https://web.dev/bfcache/) (bfcache) on navigation, and why. Developers can use this information to identify pages that need updates to make them bfcache-compatible, thereby improving site performance. + +## Concepts and usage + +Modern browsers provide an optimization feature for history navigation called the [back/forward cache](https://web.dev/bfcache/) (bfcache). This enables an instant loading experience when users go back to a page they have already visited. Pages can be blocked from entering the bfcache or get evicted while in the bfcache for different reasons, some required by a specification and some specific to browser implementations. + +Previously, there was no way for developers to find out why their pages were blocked from using the bfcache in the wild, though there is a [test in Chrome dev tools](https://web.dev/bfcache/#test-to-ensure-your-pages-are-cacheable). To enable monitoring in the field, the [`PerformanceNavigationTiming`](/en-US/docs/Web/API/PerformanceNavigationTiming) class has been extended to include a `notRestoredReasons` property. This returns an object containing related information on all frames present in the document: + +- Details such as frame `id` and `name`, to help identify them in the HTML. +- Whether they were blocked from using the bfcache. +- Reasons why they were blocked from using the bfcache. + +This allows developers to take action to make those pages bfcache-compatible, thereby improving site performance. + +## Examples + +A [`PerformanceNavigationTiming`](/en-US/docs/Web/API/PerformanceNavigationTiming) instance can be obtained from features such as [`Performance.getEntriesByType()`](/en-US/docs/Web/API/Performance/getEntriesByType) and [`PerformanceObserver`](/en-US/docs/Web/API/PerformanceObserver). + +For example, you could invoke the following function to return all `PerformanceNavigationTiming` objects currently present in the performance timeline and log their `notRestoredReasons`: + +```js +function returnNRR() { + const navEntries = performance.getEntriesByType("navigation"); + for (let i = 0; i < navEntries.length; i++) { + console.log(`Navigation entry ${i}`); + let navEntry = navEntries[i]; + console.log(navEntry.notRestoredReasons); + } +} +``` + +The `PerformanceNavigationTiming.notRestoredReasons` property returns an object with the following structure, which represents the blocked state of the top-level frame: + +```js +{ + blocked: true, + children: [], + id: "", + name: "", + reasons: [ "Internal Error", "Unload handler" ], + src: "", + url: "a.com" +} +``` + +The properties are as follows: + +- `blocked` + - : A boolean value specifying whether the navigated page is blocked from using the bfcache (`true`) or not (`false`). +- `childen` + - : An array of objects representing the blocked state of any frames embedded in the top-level frame. Each object has the same structure as the parent object — this way, any number of levels of embedded frames can be represented inside the object recursively. If the frame has no children, the array will be empty. +- `id` + - : A string representing the `id` attribute value of the frame (for example `