| name | typo3-favicon-manifest |
| description | Integrate and configure favicon, app icon, and web manifest support in TYPO3 v14 projects, including Fluid `f:page.headerData`, TypoScript head tags, `page.shortcutIcon`, site-level route enhancer mapping for `/site.webmanifest` and `/browserconfig.xml`, and practical verification steps. Use when creating or fixing favicon/app icon setup, wiring web manifest delivery, or migrating icon configuration in a TYPO3 v14 project. |
TYPO3 Favicon + Web Manifest Workflow
Follow this workflow to add or repair favicon and app icon integration in a reusable, project-agnostic way.
1. Collect Required Context
Ask for missing context before editing:
- Identify which extension or site package owns frontend output.
- Ask where the favicon/app icon files are stored (exact folder path).
- Ask whether
site.webmanifest and browserconfig.xml already exist.
- Ask which site configuration identifier is active (for
config/sites/<site-id>/config.yaml).
If icon files do not exist yet, suggest generating a full icon set with RealFaviconGenerator and then continue once the files are available.
2. Verify or Define Expected Icon Files
Expect at least these common files (names can vary by project):
apple-touch-icon.pngfavicon-32x32.pngfavicon-16x16.pngandroid-chrome-192x192.pngsafari-pinned-tab.svgfavicon.icosite.webmanifestbrowserconfig.xml
If project naming differs, keep generated markup consistent with actual filenames.
3. Add Head Integration
Prefer Fluid f:page.headerData in the PAGEVIEW layout when the site package owns the page shell:
<f:page.headerData>
<link rel="apple-touch-icon" sizes="180x180" href="{f:uri.resource(path: 'Icons/Favicon/apple-touch-icon.png', extensionName: 'Sitepackage')}">
<link rel="icon" type="image/png" sizes="32x32" href="{f:uri.resource(path: 'Icons/Favicon/favicon-32x32.png', extensionName: 'Sitepackage')}">
<link rel="icon" type="image/png" sizes="16x16" href="{f:uri.resource(path: 'Icons/Favicon/favicon-16x16.png', extensionName: 'Sitepackage')}">
<link rel="icon" type="image/png" sizes="192x192" href="{f:uri.resource(path: 'Icons/Favicon/android-chrome-192x192.png', extensionName: 'Sitepackage')}">
<link rel="manifest" href="/site.webmanifest">
<link rel="mask-icon" href="{f:uri.resource(path: 'Icons/Favicon/safari-pinned-tab.svg', extensionName: 'Sitepackage')}" color="#5bbad5">
<meta name="msapplication-config" content="/browserconfig.xml">
<meta name="theme-color" content="#ffffff">
</f:page.headerData>
Use TypoScript page.headerData when the head tags are configured outside Fluid templates. Keep {path:EXT:...} + insertData = 1 so Composer/public-path setups resolve correctly.
page {
headerData {
10 = TEXT
10 {
value (
<link rel="apple-touch-icon" sizes="180x180" href="{path:EXT:sitepackage/Resources/Public/Icons/Favicon/apple-touch-icon.png}">
<link rel="icon" type="image/png" sizes="32x32" href="{path:EXT:sitepackage/Resources/Public/Icons/Favicon/favicon-32x32.png}">
<link rel="icon" type="image/png" sizes="16x16" href="{path:EXT:sitepackage/Resources/Public/Icons/Favicon/favicon-16x16.png}">
<link rel="icon" type="image/png" sizes="192x192" href="{path:EXT:sitepackage/Resources/Public/Icons/Favicon/android-chrome-192x192.png}">
<link rel="manifest" href="/site.webmanifest">
<link rel="mask-icon" href="{path:EXT:sitepackage/Resources/Public/Icons/Favicon/safari-pinned-tab.svg}" color="#5bbad5">
<meta name="msapplication-config" content="/browserconfig.xml">
<meta name="theme-color" content="#ffffff">
)
insertData = 1
}
}
shortcutIcon = EXT:sitepackage/Resources/Public/Icons/Favicon/favicon.ico
}
Implementation notes:
- Replace
EXT:sitepackage/... with the real extension path.
- Avoid hardcoding
/_assets/... hashes.
- If
headerData.10 is already occupied, use the next free index (20, 30, ...).
- Escape or hardcode only trusted values in
f:page.headerData; it outputs raw head content.
4. Create or Update site.webmanifest
Create the manifest file in the same public icon folder used by the project (or adapt to existing conventions).
Use this minimal template and replace placeholders:
{
"name": "Project Name",
"short_name": "Project",
"icons": [
{
"src": "/path-or-public-url/android-chrome-192x192.png",
"sizes": "192x192",
"type": "image/png"
},
{
"src": "/path-or-public-url/android-chrome-512x512.png",
"sizes": "512x512",
"type": "image/png"
}
],
"theme_color": "#ffffff",
"background_color": "#ffffff",
"display": "standalone"
}
Keep icon URLs consistent with the deployed public paths used by TYPO3.
5. Expose Manifest and Browser Config at Root URL
Ensure /site.webmanifest and /browserconfig.xml are resolvable via site routing.
Add entries to the PageTypeSuffix map in config/sites/<site-id>/config.yaml:
routeEnhancers:
PageTypeSuffix:
type: PageType
default: '/'
index: ''
map:
site.webmanifest: 3478304621
browserconfig.xml: 2943879438
Use stable, unused numeric type IDs and document them with the site configuration.
6. Confirm Delivery and HTML Output
Verify end-to-end after changes:
- Open frontend HTML source and confirm all
<link>/<meta> tags render.
- Check direct responses for
/site.webmanifest and /browserconfig.xml.
- Confirm favicon appears in browser tabs and mobile install prompts.
- Clear TYPO3 caches if assets/routes do not appear immediately.
7. Project-Agnostic Guardrails
- Preserve existing site package conventions instead of forcing a fixed icon folder.
- Keep semantic and routing behavior unchanged except for favicon-related additions.
- Prefer minimal diffs when retrofitting existing TYPO3 projects.
- Document assumptions explicitly when file names, site IDs, or route enhancer names are inferred.
Load References As Needed
References
Use these external sources when needed:
