How to implement LCP end to end

Your performance dashboard has an LCP chart, and it's blank. Nothing errors, nothing warns — the metric simply never arrives. In a Next.js app the cause is almost always missing web‑vitals instrumentation: the browser measures Largest Contentful Paint on every load, but unless a listener forwards it to your backend, the number dies inside the browser. This post wires up the full path — observer, transport, API receiver — and then verifies each hop.

A blank LCP chart and a silent console

When the instrumentation is missing, the console stays quiet and your analytics endpoint receives nothing. A typical “broken” run looks like this:

> npm run dev

> my-next-app@0.1.0 dev
> next dev

ready - started server on http://localhost:3000

You open the page, interact with it, and never see a line such as LCP: 1.23s in the terminal or network tab. The problem surfaces after you deploy to Vercel because the production build also lacks the listener, so your performance dashboard shows a blank LCP chart.

It happens when you:

• launch the app with npm run dev or next start,
• navigate to any route that renders above‑the‑fold content,
• expect the metric to appear in your custom analytics dashboard.

The behavior is identical on local development, staging, and production because the missing code lives in the shared pages/_app.js file.

Where the observer has to run

Next.js ships a tiny helper called next/web-vitals that abstracts the browser’s PerformanceObserver API. If you never import or call this helper, the browser never sends the LCP value to your JavaScript. The result is a silent metric that never reaches your backend.

Two things compound the issue:

1. Server‑side rendering hides the client‑side observer. When the page is rendered on the server, there is no window object, so the observer can only be attached in the client bundle. If you place the observer in a file that never runs on the client (e.g., a server‑only API route), it never fires.
2. Turbopack’s aggressive tree‑shaking can drop unused code. If you import next/web-vitals but never reference the exported function, Turbopack removes it from the final bundle, leaving the observer absent in production. See the Next.js Turbopack stuck / disable guide for more details.

The relevant code path in Next.js looks like this (simplified):

// node_modules/next/dist/compiled/web-vitals/index.js
export function getCLS(onReport) { /* registers CLS observer */ }
export function getLCP(onReport) { /* registers LCP observer */ }

If getLCP is never called, the browser never records the metric.

There is a timing constraint on top of that: the browser only emits LCP once per page load. If your code registers the observer after the paint has already happened, the metric is lost. Placing the getLCP call inside a useEffect that runs on the first client render guarantees the observer is attached early enough.

Wiring getLCP into pages/_app.js

Add a small reportWebVitals function to pages/_app.js. The function receives a metric object, extracts the name and value, and forwards it to an API route you control. The API route can then forward the data to Google Analytics, Segment, or any custom endpoint.

// pages/_app.js
import '../styles/globals.css';
import { useEffect } from 'react';
import { getLCP } from 'web-vitals';

function reportWebVitals(metric) {
  // Convert the metric value to milliseconds for consistency
  const payload = {
    name: metric.name,
    value: Math.round(metric.value),
    id: metric.id,
    page: window.location.pathname,
  };

  // Send the metric to our analytics endpoint
  fetch('/api/analytics', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(payload),
  }).catch(console.error);
}

// Attach the observer once the component mounts
export default function MyApp({ Component, pageProps }) {
  useEffect(() => {
    // getLCP registers a PerformanceObserver for LCP
    getLCP(reportWebVitals);
  }, []);

  return <Component {...pageProps} />;
}

That single change addresses the cause because it guarantees that the LCP observer runs in the client bundle, survives Turbopack optimisation, and always posts the metric to your backend.

To apply it in your project:

1. Open pages/_app.js. If the file does not exist, create it at the project root under pages/.
2. Add the import { getLCP } from 'web-vitals'; line at the top. (getLCP comes from the Google web-vitals npm package — next/web-vitals only exports the App Router useReportWebVitals hook, not getLCP.)
3. Paste the reportWebVitals function shown above, adjusting the endpoint URL if you use a different path.
4. Inside the MyApp component, add a useEffect that calls getLCP(reportWebVitals).
5. Save the file and restart the dev server (npm run dev). The observer will now fire on the first paint of any page.

Receiving the metric: pages/api/analytics.js

You also need a tiny API route to accept the POST request:

// pages/api/analytics.js
export default async function handler(req, res) {
  if (req.method !== 'POST') {
    res.setHeader('Allow', ['POST']);
    return res.status(405).end('Method Not Allowed');
  }

  const metric = req.body;
  // Forward to your analytics provider – here we just log it
  console.log('Received web vital:', metric);

  // Example: send to an external service
  // await fetch('https://example.com/collect', {
  //   method: 'POST',
  //   headers: { 'Content-Type': 'application/json' },
  //   body: JSON.stringify(metric),
  // });

  res.status(200).json({ status: 'ok' });
}

The API route is optional if you already have a logging solution, but keeping it explicit makes the end‑to‑end flow clear.

Watching the metric arrive

Run the development server:

npm run dev

Open the site in Chrome, open DevTools → Network, and filter for analytics. Reload the page. You should see a POST request similar to:

POST /api/analytics HTTP/1.1
Content-Type: application/json

{"name":"LCP","value":1234,"id":"v2-1623456789-0","page":"/"}

At the same time, the server console will output:

Received web vital: { name: 'LCP', value: 1234, id: 'v2-1623456789-0', page: '/' }

If you see both the network request and the console log, the instrumentation works. Open the page a few times and watch the value change; it should reflect the time (in milliseconds) it took for the largest contentful element to appear.

If you still don’t see any request, double‑check that:

• The useEffect runs only on the client (no SSR errors in the console).
• The fetch URL matches the API route (/api/analytics).
• Turbopack isn’t stripping getLCP. If you suspect that, try disabling Turbopack temporarily as described in the Next.js Turbopack disable guide.

Slow connections: the observer that never fires

On a very slow network the LCP observer may fire after the page has already been unmounted, causing the fetch to be aborted. To guard against this, add a timeout fallback:

useEffect(() => {
  const timeout = setTimeout(() => {
    // Send a placeholder if the observer never fires
    reportWebVitals({ name: 'LCP', value: 0, id: 'timeout' });
  }, 15000); // 15 seconds

  getLCP(metric => {
    clearTimeout(timeout);
    reportWebVitals(metric);
  });
}, []);

Client-side navigations and duplicate LCP events

If you navigate client‑side (using next/link) the observer may emit a new LCP for each navigation. To avoid double‑counting, filter out metrics that arrive after the first one per page:

let reported = false;
function reportWebVitals(metric) {
  if (reported) return;
  reported = true;
  // send as before
}

Keeping the instrumentation from disappearing again

There is no built-in ESLint rule that enforces a reportWebVitals export, so guard it with a tiny CI script instead:

// scripts/check-web-vitals.js — run in CI before deploy
const fs = require('fs')

if (fs.existsSync('pages/_app.js')) {
  const src = fs.readFileSync('pages/_app.js', 'utf8')
  if (!/export\s+function\s+reportWebVitals/.test(src)) {
    console.error('pages/_app.js is missing `export function reportWebVitals`')
    process.exit(1)
  }
}
console.log('reportWebVitals present')

You can also write a simple Jest test that renders the app with @testing-library/react and asserts that a network request to /api/analytics occurs within 5 seconds. Automated testing catches the omission before it lands in production.

Related

• Fix "lcp" not working in production
• Next.js Turbopack stuck / disable guide
• Fix Next.js revalidatePath Not Working in Server Actions (6 Production Causes + Cheat Sheet 2026)

---

Originally published at https://www.iloveblogs.blog

Comments

[Tarun Sharma]

Couple of things worth flagging on the edge cases. The timeout fallback that sends value 0 will wreck your percentiles, a batch of fake zeros drags p75 down and hides real regressions. Better to send nothing if the observer never fired.

The "only report the first one" bit is also backwards for LCP. web-vitals already calls your callback once, at the point LCP is final (page hidden or bfcache), not on every candidate paint. If you dedupe to the first value you can end up keeping an early candidate instead of the real largest element, so let the library decide when to fire.

And the reason a late useEffect still catches it is that PerformanceObserver is created with buffered: true inside web-vitals, so it replays entries from before it attached. Worth mentioning since the post frames observer timing as the main risk.