The App Router can produce icon elements from conventional files or from the metadata object. Both approaches are valid, but mixing them without a clear rule can easily create competing declarations.
Choose file conventions
Place favicon.ico at the root of app. Supported icon files can live in a route segment, while apple-icon describes the icon intended for Apple devices.
Next.js detects these files, determines useful attributes and adds the corresponding link elements to head. An icon placed in a segment applies to routes in that segment.
| File | Location | Purpose |
|---|---|---|
| favicon.ico | app/ | Site fallback |
| icon.svg | app segment | Browser icon |
| apple-icon.png | app segment | Apple icon |
| manifest.webmanifest | app segment | Installable manifest |
Use metadata for explicit paths
If assets live in public or on an image host, declare metadata.icons in a layout or page. Specify icon, apple and, when needed, shortcut using consistent URLs.
Metadata from a child segment can replace composed fields inherited from its parent. Inspect the final head on several routes instead of assuming that every parent entry was merged.
For an icon generated on demand, Next.js also supports icon.tsx or icon.js. The function returns image data with an explicit size and content type. Keep this approach for genuinely dynamic compositions: a static file is simpler to cache, inspect and serve consistently across deployments.
Connect the manifest and its icons
A static manifest file or manifest.ts function can describe the application name, colors and installable icons. Manifest icon URLs must be public and point to files with the declared dimensions.
Keep the manifest role separate from the tab favicon: a 512×512 installation icon does not automatically replace icon.svg or favicon.ico.
Test in production
Run a production build, open one route from every affected segment and inspect the link elements. Then open every asset URL directly and confirm that middleware does not intercept it.
If you use basePath or a CDN, test the produced URLs in the deployed environment. Local behavior does not always reveal an incorrect public base or rewrite rule.
Primary sources
Frequently asked questions
Do you need to write link elements by hand?
No. File conventions or metadata.icons can generate them. Choose one clear source of truth.
Where should favicon.ico go?
With App Router, the favicon.ico convention is supported at the root of the app directory.
Does manifest.ts replace icon.svg?
No. The manifest describes installable icons among other data, while icon.svg directly serves the browser icon.