Optimisations and Metadata

HTTP/1.1 200 OK
Vary: Accept
Cache-Control: public, max-age=14400, must-revalidate
ETag: Rtm4wo8b43_9_XATXMEiuiz15KvS8w9gduR8tRRj390
Content-Type: image/webp
Content-Disposition: attachment; filename="hills.webp"
Content-Security-Policy: script-src 'none'; frame-src 'none'; sandbox;
X-Nextjs-Cache: MISS
Content-Length: 44934
time_total=0.093s

HTTP/1.1 200 OK
(the same headers)
X-Nextjs-Cache: HIT
Content-Length: 44934
time_total=0.0017s

$ file out.webp
RIFF (little-endian) data, Web/P image, VP8 encoding, 1080x720

url=%2Fhills.jpg&w=1000&q=75     400  "w" parameter (width) of 1000 is not allowed
url=%2Fhills.jpg&w=640&q=80      400  "q" parameter (quality) of 80 is not allowed
url=https%3A%2F%2Fexample.com%2Fcat.jpg&w=640&q=75
                                 400  "url" parameter is not allowed
url=%2Fmissing.jpg&w=640&q=75    404  "url" parameter is valid but internal response is invalid
url=%2Fhills.jpg&w=3840&q=75     200  image/webp, 2400x1600, 885,270 bytes (never upscaled)

import Image from "next/image";
import hills from "./hills.jpg"; // a 2400 × 1600 JPEG next to this file

export default function Home() {
  return (
    <main>
      <Image
        src={hills}
        alt="Green hills under an orange sky at sunset"
        placeholder="blur"
        sizes="100vw"
        preload
        style={{ width: "100%", height: "auto" }}
      />
    </main>
  );
}

.next/static/media/hills.0m9f-qzn0u6z1.jpg      1,812,040 bytes (the original, with a content hash)

<img … width="2400" height="1600" … style="color:transparent;width:100%;height:auto;background-size:cover;
     background-position:50% 50%;background-repeat:no-repeat;
     background-image:url(&quot;data:image/svg+xml;charset=utf-8,%3Csvg … feGaussianBlur stdDeviation='20' …
     href='data:image/jpeg;base64,/9j/4AAQSkZJRgABAgAAAQABAAD/wAARCAAFAAgDAREA…'/%3E%3C/svg%3E&quot;)"
     src="/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fhills.0m9f-qzn0u6z1.jpg&amp;w=3840&amp;q=75"/>

curl -sI /_next/static/media/hills.0m9f-qzn0u6z1.jpg            Cache-Control: public, max-age=31536000, immutable
curl -sD - /_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fhills…   Cache-Control: public, max-age=315360000, immutable

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  cacheComponents: true,
  partialPrefetching: true,
  images: {
    // AVIF first, WebP as the fallback, the original format if the browser takes neither
    formats: ["image/avif", "image/webp"],
    // Only this host, port and folder may be optimised; everything else gets a 400
    remotePatterns: [new URL("http://127.0.0.1:4611/photos/**")],
    // Only because the stand-in CDN runs on 127.0.0.1: private IPs are blocked by default (SSRF)
    dangerouslyAllowLocalIP: true,
  },
};

export default nextConfig;

import Image from "next/image";

export default function Gallery() {
  return (
    <main style={{ display: "grid", gridTemplateColumns: "1fr 1fr", gap: 8 }}>
      {/* fill: the image takes the size of this positioned box */}
      <div style={{ position: "relative", aspectRatio: "3 / 2" }}>
        <Image
          src="http://127.0.0.1:4611/photos/hills.jpg"
          alt="Green hills under an orange sky at sunset"
          fill
          sizes="50vw"
          style={{ objectFit: "cover" }}
        />
      </div>
    </main>
  );
}

Accept: image/avif,image/webp,*/*   w=640    200  image/avif   3,898 bytes   68 ms (MISS)
Accept: image/webp,*/*              w=640    200  image/webp   5,278 bytes   29 ms (MISS)
Accept: image/png,*/*               w=640    200  image/jpeg   9,863 bytes   25 ms (MISS)
Accept: image/avif,*/*              w=1920   200  image/avif 149,030 bytes  241 ms (MISS), then 1.2 ms (HIT)
Accept: image/webp,*/*              w=1920   200  image/webp 397,082 bytes  169 ms (MISS), then 1.5 ms (HIT)
url=…%2Fprivate%2Fhills.jpg (outside /photos/**)   400  "url" parameter is not allowed

The same app built without dangerouslyAllowLocalIP:
url=…%2Fphotos%2Fhills.jpg          400  "url" parameter is not allowed
next start logged:  ⨯ upstream image http://127.0.0.1:4611/photos/hills.jpg hostname resolved to private IP ["127.0.0.1"]
                    If this is expected and you understand SSRF risk, use images.dangerouslyAllowLocalIP = true to continue.

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  cacheComponents: true,
  partialPrefetching: true,
  images: {
    loader: "custom",
    // relative to the project root; this project keeps its code in src/
    loaderFile: "./src/lib/image-loader.ts",
  },
};

export default nextConfig;

"use client";

import type { ImageLoaderProps } from "next/image";

// Builds an imgix-style URL: the CDN resizes and re-encodes, Next.js never sees the bytes
export default function cdnLoader({ src, width, quality }: ImageLoaderProps) {
  return `https://img.example-cdn.com${src}?w=${width}&q=${quality ?? 75}&auto=format`;
}

import Image from "next/image";

export default function Home() {
  return <Image src="/hills.jpg" alt="Green hills at sunset" width={240} height={160} />;
}

<img alt="Green hills at sunset" loading="lazy" width="240" height="160" decoding="async" data-nimg="1"
     style="color:transparent"
     srcSet="https://img.example-cdn.com/hills.jpg?w=256&amp;q=75&amp;auto=format 1x,
             https://img.example-cdn.com/hills.jpg?w=640&amp;q=75&amp;auto=format 2x"
     src="https://img.example-cdn.com/hills.jpg?w=640&amp;q=75&amp;auto=format"/>

export default function Home() {
  return <h1>Hello from Inter</h1>;
}

import { Roboto_Mono } from "next/font/google";

// Called in a page, so it is preloaded on /docs only
const mono = Roboto_Mono({ subsets: ["latin"], weight: ["400", "700"] });

export default function Docs() {
  return <pre className={mono.className}>npm run build</pre>;
}

Route (app)
┌ ○ /
├ ○ /_not-found
└ ○ /docs


○  (Static)  prerendered as static content

/       link: <…/07c7676b89ed2778-s.p.2bn3s6zvc0dyp.woff2>; rel=preload …            (Inter)
        stylesheets: 1c0bag5adhl11.css
/docs   link: <…/07c7676b89ed2778-s.p.2bn3s6zvc0dyp.woff2>; rel=preload …,
              <…/af77a86cf1e51fa0-s.p.22iyan98j1_2e.woff2>; rel=preload …             (Inter + Roboto Mono)
        stylesheets: 1c0bag5adhl11.css, 2cztr3xv7br7m.css
        font requests: both files; font faces actually used on the page: Roboto Mono 400 only

Roboto Mono CSS: @font-face … font-weight:400 … src:url(../media/af77a86cf1e51fa0-s.p.22iyan98j1_2e.woff2) …
                 @font-face … font-weight:700 … src:url(../media/af77a86cf1e51fa0-s.p.22iyan98j1_2e.woff2) …
                 @font-face{font-family:Roboto Mono Fallback;src:local(Arial);…;size-adjust:134.61%}

import localFont from "next/font/local";

// The file sits next to this layout: app/fonts/Brand.woff2
const brand = localFont({
  src: "./fonts/Brand.woff2",
  weight: "100 900", // it is a variable font: one file, every weight
  variable: "--font-brand",
  display: "swap",
});

export default function RootLayout({ children }: LayoutProps<"/">) {
  return (
    <html lang="en" className={brand.variable}>
      <body className={brand.className}>{children}</body>
    </html>
  );
}

.next/static/media/Brand-s.p.3rd3ws2mg35i0.woff2   28,356 bytes
@font-face{font-family:brand;src:url(../media/Brand-s.p.3rd3ws2mg35i0.woff2)format("woff2");font-display:swap;font-weight:100 900}
@font-face{font-family:brand Fallback;src:local(Arial);ascent-override:94.47%;descent-override:27.73%;line-gap-override:0.0%;size-adjust:106.39%}
.veGYVa_className{font-family:brand,brand Fallback}
link header: </_next/static/media/Brand-s.p.3rd3ws2mg35i0.woff2>; rel=preload; as="font"; crossorigin=""; type="font/woff2"

import Link from "next/link";

export default function Home() {
  return (
    <main>
      <h1>Scripts</h1>
      <Link href="/store-finder">Store finder</Link>
    </main>
  );
}

import Script from "next/script";

export default function StoreFinder() {
  return (
    <main>
      <h1>Store finder</h1>
      {/* Already loaded by the layout: not loaded again */}
      <Script src="/analytics.js" />
      {/* Only this page needs it: loaded when the page is first shown */}
      <Script src="/maps.js" />
    </main>
  );
}

consent.js @ 10ms
hydrated @ 12ms
inline @ 13ms
analytics.js @ 13ms
chat-widget.js @ 15ms
maps.js @ 4514ms

import { GoogleAnalytics, GoogleTagManager } from "@next/third-parties/google";

export default function RootLayout({ children }: LayoutProps<"/">) {
  return (
    <html lang="en">
      <GoogleTagManager gtmId="GTM-XYZ" />
      <body>{children}</body>
      <GoogleAnalytics gaId="G-XYZ" />
    </html>
  );
}

(window.__log ??= []).push(`consent.js @ ${Math.round(performance.now())}ms`);

(window.__log ??= []).push(`analytics.js @ ${Math.round(performance.now())}ms`);

(window.__log ??= []).push(`chat-widget.js @ ${Math.round(performance.now())}ms`);

(window.__log ??= []).push(`maps.js @ ${Math.round(performance.now())}ms`);

"use client";

import { useEffect } from "react";

declare global {
  interface Window {
    __log?: string[];
  }
}

// Logs the moment React has hydrated the page
export function HydrationMarker() {
  useEffect(() => {
    (window.__log ??= []).push(`hydrated @ ${Math.round(performance.now())}ms`);
  }, []);
  return null;
}

import "server-only";
import { cacheLife } from "next/cache";

const posts = {
  "image-optimisation": { title: "How next/image picks a width", summary: "srcset, sizes and the optimiser.", published: "2026-10-01" },
  "font-loading": { title: "Fonts without layout shift", summary: "What next/font generates at build time.", published: "2026-10-12" },
};

export type Slug = keyof typeof posts;

export async function getPost(slug: string) {
  "use cache";
  cacheLife("hours");
  return posts[slug as Slug] ?? null; // in a real app: a CMS or database query
}

export async function listSlugs() {
  return Object.keys(posts);
}

import type { Metadata } from "next";
import { notFound } from "next/navigation";
import { getPost, listSlugs } from "@/lib/posts";

export async function generateStaticParams() {
  return (await listSlugs()).map((slug) => ({ slug }));
}

export async function generateMetadata({ params }: PageProps<"/blog/[slug]">): Promise<Metadata> {
  const { slug } = await params;
  const post = await getPost(slug); // same cached call as the page: one lookup
  if (!post) return {};
  return {
    title: post.title, // becomes "… | Acme Blog" through the layout's template
    description: post.summary,
    alternates: { canonical: `/blog/${slug}` },
    openGraph: { type: "article", title: post.title, publishedTime: post.published },
  };
}

export default async function PostPage({ params }: PageProps<"/blog/[slug]">) {
  const { slug } = await params;
  const post = await getPost(slug);
  if (!post) notFound();
  return (
    <article>
      <h1>{post.title}</h1>
      <p>{post.summary}</p>
    </article>
  );
}

export default function Home() {
  return <h1>Acme Blog</h1>;
}

Route (app)
┌ ○ /
├ ○ /_not-found
├   /blog/[slug]
│ ├ ◐ /blog/[slug]
│ ├ ○ /blog/image-optimisation
│ └ ○ /blog/font-loading
├ ○ /robots.txt
├ ◐ /search
└ ○ /sitemap.xml


○  (Static)             prerendered as static content
◐  (Partial Prerender)  prerendered as static HTML with dynamic server-streamed content

<title>How next/image picks a width | Acme Blog</title>
<meta name="description" content="srcset, sizes and the optimiser."/>
<link rel="canonical" href="https://acme.dev/blog/image-optimisation"/>
<meta property="og:title" content="How next/image picks a width"/>
<meta property="og:description" content="srcset, sizes and the optimiser."/>
<meta property="og:type" content="article"/>
<meta property="article:published_time" content="2026-10-01"/>
<meta name="twitter:card" content="summary"/>
<meta name="twitter:title" content="How next/image picks a width"/>
<meta name="twitter:description" content="srcset, sizes and the optimiser."/>

x-nextjs-cache: HIT
x-nextjs-prerender: 1
Cache-Control: s-maxage=3600, stale-while-revalidate=82800

import type { MetadataRoute } from "next";

export default function robots(): MetadataRoute.Robots {
  return {
    rules: { userAgent: "*", allow: "/", disallow: "/drafts/" },
    sitemap: "https://acme.dev/sitemap.xml",
  };
}

import type { MetadataRoute } from "next";
import { listSlugs } from "@/lib/posts";

export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
  const slugs = await listSlugs();
  return [
    { url: "https://acme.dev", changeFrequency: "weekly", priority: 1 },
    ...slugs.map((slug) => ({ url: `https://acme.dev/blog/${slug}`, changeFrequency: "monthly" as const })),
  ];
}

User-Agent: *
Allow: /
Disallow: /drafts/

Sitemap: https://acme.dev/sitemap.xml

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
<url>
<loc>https://acme.dev</loc>
<changefreq>weekly</changefreq>
<priority>1</priority>
</url>
<url>
<loc>https://acme.dev/blog/image-optimisation</loc>
<changefreq>monthly</changefreq>
</url>
<url>
<loc>https://acme.dev/blog/font-loading</loc>
<changefreq>monthly</changefreq>
</url>
</urlset>

sitemap.xml headers: content-type: application/xml · x-nextjs-cache: HIT · cache-control: public, max-age=0, must-revalidate

import type { Metadata } from "next";
import { Suspense } from "react";

// Reads searchParams (runtime data), so it can only run at request time
export async function generateMetadata({ searchParams }: PageProps<"/search">): Promise<Metadata> {
  const { q } = await searchParams;
  await new Promise((r) => setTimeout(r, 500)); // stands in for a slow lookup
  return { title: `Results for "${q ?? ""}"`, robots: { index: false } };
}

async function Results({ searchParams }: { searchParams: PageProps<"/search">["searchParams"] }) {
  const { q } = await searchParams;
  return <p>No posts match “{q}”.</p>;
}

export default function SearchPage({ searchParams }: PageProps<"/search">) {
  return (
    <main>
      <h1>Search</h1>
      <Suspense fallback={<p>Searching…</p>}>
        <Results searchParams={searchParams} />
      </Suspense>
    </main>
  );
}

Chrome 155 user agent                           Twitterbot/1.0
time to first byte   0.024 s                    time to first byte   0.507 s
590    </head>                                  517    <title>Results for &quot;fonts&quot; | Acme Blog</title>
694    <h1>Search</h1>                          640    <meta name="robots" content="noindex"/>
751    Searching…                               1298   </head>
1385   No posts match “fonts”                   1371   <h1>Search</h1>
10611  <title>Results for &quot;fonts&quot; …    1397   No posts match “fonts”
10734  <meta name="robots" content="noindex"/>

import type { Metadata } from "next";

export const metadata: Metadata = {
  metadataBase: new URL("https://acme.dev"),
  title: { template: "%s | Acme Blog", default: "Acme Blog" },
};

export default function RootLayout({ children }: LayoutProps<"/">) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

import "server-only";

const posts: Record<string, { title: string; author: string }> = {
  "image-optimisation": { title: "How next/image picks a width", author: "Rohit" },
  "font-loading": { title: "Fonts without layout shift", author: "Rohit" },
};

export async function getPost(slug: string) {
  "use cache";
  return posts[slug] ?? null;
}

export async function listSlugs() {
  return Object.keys(posts);
}

import type { Metadata } from "next";
import { notFound } from "next/navigation";
import { getPost, listSlugs } from "@/lib/posts";

export async function generateStaticParams() {
  return (await listSlugs()).map((slug) => ({ slug }));
}

export async function generateMetadata({ params }: PageProps<"/blog/[slug]">): Promise<Metadata> {
  const post = await getPost((await params).slug);
  return post ? { title: post.title } : {};
}

export default async function PostPage({ params }: PageProps<"/blog/[slug]">) {
  const post = await getPost((await params).slug);
  if (!post) notFound();
  return <h1>{post.title}</h1>;
}

Route (app)
┌ ○ /_not-found
├   /blog/[slug]
│ ├ ◐ /blog/[slug]
│ ├ ○ /blog/image-optimisation
│ └ ○ /blog/font-loading
└   /blog/[slug]/opengraph-image
  ├ ● /blog/image-optimisation/opengraph-image
  └ ● /blog/font-loading/opengraph-image


○  (Static)             prerendered as static content
●  (SSG)                prerendered as static HTML (uses generateStaticParams)
◐  (Partial Prerender)  prerendered as static HTML with dynamic server-streamed content

"use client";

import { useState } from "react";
import { load } from "js-yaml"; // the heavy part: a full YAML parser

export default function YamlPreview() {
  const [text, setText] = useState("theme: dark\nfontSize: 14");
  let result: string;
  try {
    result = JSON.stringify(load(text), null, 2);
  } catch (e) {
    result = (e as Error).message;
  }
  return (
    <div>
      <textarea value={text} onChange={(e) => setText(e.target.value)} rows={4} />
      <pre>{result}</pre>
    </div>
  );
}

// js-yaml ships no types; a real project would install @types/js-yaml instead
declare module "js-yaml" {
  export function load(text: string): unknown;
}

import { ImportPanel } from "@/components/import-panel";

export default function SettingsPage() {
  return (
    <main>
      <h1>Settings</h1>
      <ImportPanel />
    </main>
  );
}

"use client";

import { useState } from "react";
import YamlPreview from "./yaml-preview"; // a normal import: in the page's bundle

export function ImportPanelEager() {
  const [open, setOpen] = useState(false);
  return (
    <section>
      <button onClick={() => setOpen(true)}>Import settings from YAML</button>
      {open && <YamlPreview />}
    </section>
  );
}

import { ImportPanelEager } from "@/components/import-panel-eager";

export default function SettingsEagerPage() {
  return (
    <main>
      <h1>Settings (eager)</h1>
      <ImportPanelEager />
    </main>
  );
}

Route (app)
┌ ○ /_not-found
├ ○ /editor
├ ○ /settings
└ ○ /settings-eager


○  (Static)  prerendered as static content

"use client";

// Reads localStorage while rendering: there is no localStorage on the server
export default function SavedDraft() {
  const draft = localStorage.getItem("draft") ?? "(no saved draft)";
  return <p>Saved draft: {draft}</p>;
}

"use client";

import dynamic from "next/dynamic";

// ssr: false is only allowed here, inside a Client Component
const SavedDraft = dynamic(() => import("./saved-draft"), {
  ssr: false,
  loading: () => <p>Loading draft…</p>,
});

export function DraftSlot() {
  return <SavedDraft />;
}

import { DraftSlot } from "@/components/draft-slot";

export default function EditorPage() {
  return (
    <main>
      <h1>Editor</h1>
      <DraftSlot />
    </main>
  );
}

curl -s localhost:4510/editor   (the <main> of the HTML)
<main><h1>Editor</h1><template data-dgst=""></template><p>Loading draft…</p></main>

headless Chrome, after localStorage.setItem("draft", "Hello from last week") and a reload:
main.innerText = "Editor\n\nSaved draft: Hello from last week"

The same component imported normally (import SavedDraft from "@/components/saved-draft") in the page:
Error occurred prerendering page "/editor".
TypeError: Cannot read properties of undefined (reading 'getItem')
    at <unknown> (src/components/saved-draft.tsx:5:30)

dynamic(..., { ssr: false }) written in the Server Component page instead:
Error: `ssr: false` is not allowed with `next/dynamic` in Server Components. Please move it into a Client Component.

✓ Analyze completed in 1032ms. Results written to …/lazy-yaml/.next/diagnostics/analyze.

1,792 records for /settings: meta 1, route 1, group 16, output 153, module 1,010, part 611. Two of the groups:
{"type":"group","route":"/settings","id":1,"kind":"async",
 "trigger_module_ident":"[project]/…/src/components/yaml-preview.tsx [app-client] (ecmascript, next/dynamic entry)",
 "outputs":["[client-fs]/_next/static/chunks/3met7rq6m2lln.js","[client-fs]/_next/static/chunks/1ftuc-lhfg1e0.js"]}
{"type":"group","route":"/settings","id":12,"kind":"render_dependent",
 "trigger_module_ident":"[project]/…/src/components/import-panel.tsx [app-client] (ecmascript)",
 "outputs":["…/04pk29n8pf9g2.css","…/3ekqz7uysnhqr.js","…/2-5jtj5-qt7nv.js"]}
{"type":"module","ident":"[project]/…/node_modules/js-yaml/dist/js-yaml.mjs [app-client] (ecmascript)", …}

import { WebVitals } from "./web-vitals";

export default function RootLayout({ children }: LayoutProps<"/">) {
  return (
    <html lang="en">
      <body>
        <WebVitals />
        {children}
      </body>
    </html>
  );
}

// Enough text to fill the screen while the image is still downloading
export function Article() {
  return Array.from({ length: 8 }, (_, i) => (
    <p key={i} style={{ fontSize: 20, lineHeight: 1.6 }}>
      Paragraph {i + 1}. The article text the reader has already started reading when the image arrives.
    </p>
  ));
}

import { Article } from "@/components/article";

export default function PlainImg() {
  return (
    <main>
      <h1>Plain img</h1>
      {/* No width or height: the browser can't reserve space until the file arrives */}
      {/* eslint-disable-next-line @next/next/no-img-element */}
      <img src="/hills.jpg" alt="Green hills at sunset" style={{ width: "100%", height: "auto" }} />
      <Article />
    </main>
  );
}

import Image from "next/image";
import { Article } from "@/components/article";

export default function NextImg() {
  return (
    <main>
      <h1>next/image</h1>
      <Image src="/hills.jpg" alt="Green hills at sunset" width={2400} height={1600} sizes="100vw" preload style={{ width: "100%", height: "auto" }} />
      <Article />
    </main>
  );
}

"use client";

import { useState } from "react";

export default function SlowButton() {
  const [count, setCount] = useState(0);
  return (
    <main>
      <h1>INP</h1>
      <button
        onClick={() => {
          const end = performance.now() + 300;
          while (performance.now() < end) {} // 300 ms of main-thread work in the handler
          setCount(count + 1);
        }}
      >
        Clicked {count} times
      </button>
    </main>
  );
}