Skip to content

📝 Scribe: Add docs for reportWebVitals #330

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
daggerstuff wants to merge 8 commits into
base: staging
Choose a base branch
from
+17 −2
Open

📝 Scribe: Add docs for reportWebVitals #330

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
398cca9
📝 Scribe: Add docs for reportWebVitals
google-labs-jules[bot] Mar 31, 2026
7ccaa2a
📝 Scribe: Add docs for reportWebVitals
google-labs-jules[bot] Apr 1, 2026
0c7d8f2
📝 Scribe: Add docs for reportWebVitals
google-labs-jules[bot] Apr 1, 2026
7ab5e07
📝 Scribe: Add docs for reportWebVitals
google-labs-jules[bot] Apr 1, 2026
5323e78
📝 Scribe: Add docs for reportWebVitals
google-labs-jules[bot] Apr 1, 2026
abf7f20
📝 Scribe: Add docs for reportWebVitals
google-labs-jules[bot] Apr 1, 2026
7cc057f
📝 Scribe: Add docs for reportWebVitals
google-labs-jules[bot] Apr 1, 2026
ab9642d
📝 Scribe: Add docs for reportWebVitals
google-labs-jules[bot] Apr 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 17 additions & 2 deletions src/utils/performance-optimization.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,23 @@
*/

/**
* Reports Core Web Vitals and other metrics to the console
* Helps with debugging performance issues during development
* Instruments the application to collect and report Core Web Vitals and other key performance metrics.
*
* This function initializes `PerformanceObserver`s for Largest Contentful Paint (LCP), Cumulative Layout Shift (CLS),
* First Input Delay (FID), First Contentful Paint (FCP), and Time to First Byte (TTFB). These metrics are crucial
Copy link
Copy Markdown

@cubic-dev-ai cubic-dev-ai bot Mar 31, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: The JSDoc incorrectly says TTFB is captured via PerformanceObserver, but the code reads it from navigation timing entries.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At src/utils/performance-optimization.ts, line 11:

<comment>The JSDoc incorrectly says TTFB is captured via `PerformanceObserver`, but the code reads it from navigation timing entries.</comment>

<file context>
@@ -5,8 +5,23 @@
+ * Instruments the application to collect and report Core Web Vitals and other key performance metrics.
+ *
+ * This function initializes `PerformanceObserver`s for Largest Contentful Paint (LCP), Cumulative Layout Shift (CLS),
+ * First Input Delay (FID), First Contentful Paint (FCP), and Time to First Byte (TTFB). These metrics are crucial
+ * for monitoring the real-world user experience and identifying performance bottlenecks.
+ *
</file context>
Suggested change
* First Input Delay (FID), First Contentful Paint (FCP), and Time to First Byte (TTFB). These metrics are crucial
* First Input Delay (FID), First Contentful Paint (FCP), and also reads navigation timing for Time to First Byte (TTFB). These metrics are crucial
Fix with Cubic

* for monitoring the real-world user experience and identifying performance bottlenecks.
Comment on lines +10 to +12
Copy link
Copy Markdown

@charliecreates charliecreates bot Mar 31, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The docs explicitly call out FID, which is deprecated in favor of INP in modern Core Web Vitals guidance. If the implementation already measures INP (or plans to), this comment will become misleading; if it truly measures FID, it’s worth noting that it’s legacy/deprecated to set expectations for readers.

Suggestion

Update the JSDoc to either (a) mention INP instead of FID (if applicable), or (b) explicitly mark FID as legacy.

For example:

  • ... PerformanceObservers for ... Interaction to Next Paint (INP) ...`

or

  • ... First Input Delay (FID) (legacy; INP is the recommended replacement) ...

Reply with "@CharlieHelps yes please" if you'd like me to add a commit with this change.

Comment on lines +10 to +12
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Apr 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Fix inaccurate TTFB instrumentation wording.

Line 10-Line 12 says TTFB is collected via PerformanceObserver, but reportTTFB() uses performance.getEntriesByType('navigation'). Please adjust the doc so it doesn’t imply observer-based collection for TTFB.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@src/utils/performance-optimization.ts` around lines 10 - 12, The docstring
incorrectly states TTFB is collected via PerformanceObserver; update the comment
so it accurately describes that reportTTFB() reads TTFB using
performance.getEntriesByType('navigation') rather than via a PerformanceObserver
— mention reportTTFB() by name and clarify that LCP/CLS/FID/FCP use
PerformanceObserver while TTFB is gathered from the navigation entry.

*
* @remarks
* Reporting is conditionally enabled. It will only log metrics to the console if the `NODE_ENV` environment
* variable is set to `"development"`, or if the `ENABLE_METRICS` environment variable is set to `"true"`.
*
Comment on lines +8 to +17
Copy link
Copy Markdown

@charliecreates charliecreates bot Mar 31, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The JSDoc is now tightly coupled to specific implementation details (e.g., claiming it "initializes PerformanceObservers" and listing FID). This can drift over time and become misleading:

  • FID is no longer a Core Web Vital (replaced by INP), so the doc may be outdated even if the code still reports it.
  • If the implementation changes (e.g., using web-vitals helpers rather than directly creating observers), the doc will read as incorrect.

Consider describing what is collected/reported (and under what conditions) without asserting how it is implemented, and update the metric list to reflect modern CWV (INP vs FID) or explicitly label FID as legacy if still applicable.

Suggestion

Reword the JSDoc to avoid hard-coding implementation details and update the metrics list to reflect current Core Web Vitals. For example:

  • Replace "initializes PerformanceObservers" with "collects and reports".
  • Replace FID with INP, or note FID is legacy if the code still captures it.
/**
 * Instruments the application to collect and report key performance metrics.
 *
 * Collects metrics such as LCP, CLS, INP (replaces FID), FCP, and TTFB.
 *
 * @remarks
 * Reporting is enabled in development (`NODE_ENV === "development"`) or when explicitly enabled (`ENABLE_METRICS === "true"`).
 */

Reply with "@CharlieHelps yes please" if you'd like me to add a commit with this tweak.

* @example
* ```typescript
* // In a top-level application entry point:
* import { reportWebVitals } from "./utils/performance-optimization";
*
* reportWebVitals();
* ```
*/
export function reportWebVitals() {
if (typeof window !== 'undefined') {
Expand Down
Loading