--- agent: agent description: Optimize Largest Contentful Paint (LCP) with framework-specific implementation for Next.js 16 --- # Optimize LCP Optimize the Largest Contentful Paint element to achieve < 2.5 seconds. ## Prerequisites - Run `analyze-performance` first to identify the LCP element - Access to the codebase - Reference: `.github/prompts/_partials-performance/performance-patterns.md` ## Next.js 16 Considerations > **Image optimization defaults changed in Next.js 16:** > - `minimumCacheTTL` is now 4 hours (was 60 seconds) > - Default quality is 75 > - `images.domains` is deprecated, use `remotePatterns` > - `params` and `searchParams` must be awaited ## Context Required Before starting, gather: 1. LCP element type (image, text, video, background-image) 2. Current LCP timing breakdown (TTFB, load delay, render delay) 3. Framework being used (Next.js, React, Vue, etc.) 4. Current loading mechanism (eager, lazy, priority) ## Steps ### 1. Locate LCP Element in Code **Step: Find the component** 1. Use the selector from the analysis to find the element 2. Identify the component/page where it's rendered 3. **Critical: Check if it's a Server or Client Component** 4. Note any dynamic loading or conditional rendering > ⚠️ **Critical Next.js Learning**: When using `priority` on `` in a **Client Component**, > the preload link gets added to `` instead of `` due to streaming. This defeats the > purpose of preloading. See section 2A for the correct approach. ### 2. Implement Priority Loading #### 2A. Next.js App Router - CORRECT Approach (Server Components) > **Why this matters**: In Next.js App Router with streaming, child components render AFTER > `` closes. Any `preload()` call or `priority` prop in a child component will place > the preload tag in ``, not ``. **Step 1: Preload in layout.tsx (CRITICAL)** ```typescript // app/[...slug]/layout.tsx - CORRECT PLACEMENT import { getImageProps } from "next/image"; import { preload } from "react-dom"; export default async function Layout({ children, params }) { // Next.js 16: params must be awaited const resolvedParams = await params; const data = await getData(resolvedParams); const lcpImageUrl = data.heroImage; if (lcpImageUrl) { // Use getImageProps to get the EXACT optimized srcSet URLs // This ensures the preloaded URL matches the rendered image URL const lcpImageProps = getImageProps({ src: lcpImageUrl, width: 1200, height: 600, alt: "Hero", }); if (lcpImageProps?.props.srcSet) { preload(lcpImageProps.props.src as string, { as: "image", fetchPriority: "high", imageSrcSet: lcpImageProps.props.srcSet, imageSizes: lcpImageProps.props.sizes, }); } } return <>{children}; } ``` **Step 2: Image component WITHOUT priority** ```typescript // components/Hero.tsx - NO priority prop import Image from "next/image"; export function Hero({ imageUrl }: { imageUrl: string }) { return ( Hero

); } ``` **Step 3: Verify preload placement** ```bash # Check that preload is in , not # Use browser headers to avoid WAF/CDN blocks (CloudFront, Cloudflare, etc.) curl -s "https://your-site.com/page" \ -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36" \ -H "Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8" \ -H "Accept-Language: en-US,en;q=0.5" \ | tr '>' '\n' | grep -n 'as="image"\| ``` #### 2C. Convert Client Component Parent to Server Component If your LCP image is inside a Client Component tree, consider refactoring: ```typescript // BEFORE: Parent is Client Component - ALL children become client // "use client" export function Header({ data }) { return (

{/* Client - loses Server benefits */}

); } // AFTER: Parent is Server Component with isolated Client boundaries export function Header({ data }) { return (

{/* Client - own "use client" */} {/* Server Component ✅ */} {/* Client - own "use client" */}

); } ``` #### 2D. Standard HTML Images ```html

``` #### 2E. Background Images ```html ``` ### 3. Add Resource Preloading > **Note**: For Next.js App Router, do NOT use `metadata.other` for preload links. > It generates `` tags, NOT `` tags. Use `ReactDOM.preload()` instead. **Step: Add preload hints** For Next.js - Use ReactDOM.preload() in layout (see section 2A above). For standard HTML: ```html For standard HTML: ```html ``` ### 4. Optimize TTFB (If > 600ms) **Step: Implement caching strategies** For Next.js 16 with Cache Components: ```typescript // app/page.tsx import { cacheLife, cacheTag } from 'next/cache'; export default async function Page() { 'use cache' cacheLife('hours') cacheTag('hero-page') const data = await fetch('https://api.example.com/hero'); return ; } ``` > **Note**: Route segment configs like `export const revalidate` are deprecated > with `cacheComponents: true`. Use the `"use cache"` directive instead. For Edge caching: ```typescript // next.config.js module.exports = { async headers() { return [ { source: '/:path*', headers: [ { key: 'Cache-Control', value: 'public, max-age=3600, stale-while-revalidate=86400', }, ], }, ]; }, }; ``` ### 5. Reduce Render Blocking **Step: Inline critical CSS** 1. Identify CSS needed for LCP element 2. Inline it in the document head 3. Defer non-critical CSS ```typescript // For Next.js, critical CSS is automatic with CSS Modules // For custom solutions: import styles from './hero.module.css'; // CSS Modules automatically scope and can be critical-path extracted ``` **Step: Defer non-critical JavaScript** ```typescript // Next.js - use dynamic imports import dynamic from 'next/dynamic'; const HeavyAnalytics = dynamic(() => import('./Analytics'), { ssr: false, loading: () => null, }); // Standard - use defer/async