Skip to content

Docs: Documentation for useReportWebVitals in Pages Router causes duplicated CWV reporting #79940

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

Jump to bottom
Closed
DiegoDev2 opened this issue May 29, 2025 · 3 comments · Fixed by #79963
Closed

Docs: Documentation for useReportWebVitals in Pages Router causes duplicated CWV reporting #79940

DiegoDev2 opened this issue May 29, 2025 · 3 comments · Fixed by #79963
Assignees
@icyJoseph

Comments

@DiegoDev2
Copy link

DiegoDev2 commented May 29, 2025 •
edited
Loading

What is the documentation issue?

Following the official documentation for useReportWebVitals in the Pages Router leads to unexpected duplicate metrics on client-side navigations.

The docs recommend using the hook like this:

import { useReportWebVitals } from 'next/web-vitals'
 
function MyApp({ Component, pageProps }) {
  useReportWebVitals((metric) => {
    console.log(metric)
  })
 
  return <Component {...pageProps} />
}

But this causes duplicated CWV entries (e.g. LCP, TTFB, etc.) on soft navigations (next/link), likely because the hook re-runs.

Why this matters:

  • The current guidance works in the App Router, but misleads users in the Pages Router.
  • It leads to noisy or incorrect analytics data.

Let me know if you'd like me to submit a PR request to help you with this solution. Thanks!

Is there any context that might help us understand?

#79800

Does the docs page already exist? Please link to it.

https://nextjs.org/docs/pages/api-reference/functions/use-report-web-vitals
@icyJoseph
Copy link
Contributor

Hi, yeah, I'll fix this. This happens because the function reference changes.

@icyJoseph icyJoseph mentioned this issue May 30, 2025
Merged
@DiegoDev2
Copy link
Author

Hi, yeah, I'll fix this. This happens because the function reference changes.

Hi! I checked your PR — looks good. I had helped clarify the issue earlier, so glad to see it fixed this way. I’ll keep following other issues to keep contributing.

@Ebube54
Copy link

Ebube54 commented May 31, 2025

I'm highly motivated to address this issue #79940, "Docs: Documentation for useReportWebVitals in Pages Router causes duplicated CWV reporting," as accurate web performance metrics are crucial for optimization, and misleading documentation directly hinders developers. As an experienced React and TypeScript developer with practical knowledge of Next.js (both Pages and App Routers), I understand the nuances of how hooks behave across different routing paradigms and the importance of precise Web Vitals reporting. My approach would involve thoroughly reproducing the duplicated reporting in a Pages Router environment, deeply debugging the useReportWebVitals hook's lifecycle on soft navigations to pinpoint the exact cause of the re-runs, and then proposing a clear, well-tested fix both in code and documentation to ensure correct CWV reporting for Pages Router users.

leerob added a commit that referenced this issue Jun 2, 2025
@icyJoseph @leerob
chore: Use same function references in useReportWebVitals examples (#…
7a57ca7 
…79963)

Closes: https://linear.app/vercel/issue/DOC-4726/docs-usereportwebvitals
FIxes: #79940

---------

Co-authored-by: Lee Robinson <[email protected]>
@icyJoseph icyJoseph self-assigned this Jun 3, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@icyJoseph icyJoseph

Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

chore: Use same function references in useReportWebVitals examples vercel/next.js
3 participants
@icyJoseph @Ebube54 @DiegoDev2