Next.js Metadata Files API Reference
Search engines, social media crawlers, and browsers all expect a handful of specific files and head-tag conventions before they'll represent your site correctly — a favicon for the tab bar, a manifest for "add to home screen," an Open Graph image for a rich link preview, a robots file for crawler instructions, a sitemap for discovery. Next.js turns every one of these into a first-class file convention: drop a correctly-named file in the right place in your app directory, and Next.js generates the matching HTML <head> output and serves the asset automatically — no manual <meta> tag wrangling required.
This is the short index page for that whole family of conventions; the five individual file types each have their own dedicated, deeper reference elsewhere in this blog. What's worth understanding here is the shared behavior across all five, since it's genuinely consistent and easy to overlook until it surprises you.
Two Ways to Define Any Metadata File
Every convention in this family supports two forms:
- A static file —
opengraph-image.jpg,icon.png, a literal image or text file sitting in yourappdirectory, served as-is. - A dynamic variant using code —
opengraph-image.tsx,icon.tsx, a file that default-exports a function generating the content programmatically, giving you per-route, per-locale, or per-data variation that a single static file structurally can't provide.
Both forms are recognized by the same filename convention (same base name, different extension), and Next.js handles the "serve this correctly with the right head tags" part identically regardless of which form you chose.
Automatic Caching, Automatic Head Tags
Once you define one of these files, two things happen automatically, without any configuration on your part:
Next.js serves the file with content hashes in production, specifically for caching purposes — the same class of cache-busting you'd otherwise have to implement by hand for any asset you wanted browsers and CDNs to cache aggressively and safely across deploys.
Next.js updates the relevant <head> elements with the correct metadata automatically — the asset's URL, its file type, its dimensions where applicable. You never hand-write the <link rel="icon"> or <meta property="og:image"> tag yourself; the framework derives it from the file you provided.
This caching applies specifically to the special Route Handlers these conventions generate under the hood — sitemap.ts, opengraph-image.tsx, icon.tsx, and the rest of the family are all, mechanically, Route Handlers that happen to have a metadata-specific contract. That's worth knowing because it directly affects how they interact with one other piece of App Router infrastructure.
The Proxy Interaction Worth Knowing About Upfront
Since these metadata files are implemented as Route Handlers, they're subject to the same request-interception behavior any other route is — including running through your proxy.ts if its matcher doesn't explicitly exclude them. If you have authentication or logging logic in Proxy that isn't scoped carefully, it can end up intercepting requests for your favicon or your sitemap in ways you didn't intend — anything from adding unwanted latency to those requests, to outright breaking them if your Proxy logic assumes every request is an HTML page navigation.
The fix is explicit: configure your Proxy matcher to exclude the metadata file paths, the same way you'd already exclude _next/static and _next/image to avoid unintentionally gating your own static assets.
The Five Conventions This Index Covers
| Convention | Purpose |
|---|---|
favicon, icon, apple-icon | Browser tab icons, home-screen icons, and touch icons |
manifest.json | The Web App Manifest, powering "add to home screen" and other PWA behavior |
opengraph-image, twitter-image | Rich preview images when a link is shared on social platforms |
robots.txt | Crawler access rules — what search engines are and aren't allowed to index |
sitemap.xml | A structured list of your site's URLs, aiding search engine discovery |
Each of these has its own dedicated reference covering its specific file-naming rules, supported dynamic generation options, and the exact head-tag output it produces — this page is intentionally just the map, not the territory.
Key Takeaways
| Behavior | Detail |
|---|---|
| Two forms per convention | A static file, or a dynamically-generated one via a default-exported function |
| Caching | Automatic, with content hashes applied in production |
| Head tags | Generated automatically — no manual <meta>/<link> authoring needed |
| Implementation | These files are specialized Route Handlers under the hood |
| Proxy interaction | Explicitly exclude metadata file paths in your Proxy matcher, or risk unintended interception |
The unifying idea across every metadata file convention is the same one that runs through most of the App Router's design: name a file correctly, put it in the right place, and let the framework handle the tedious, error-prone parts (head tag correctness, caching, format negotiation) that you'd otherwise be maintaining by hand across every page of your site.
