Quickstart: Link Preview (Open Graph Meta-Tags)
Feature: 012-link-preview | Date: 2026-03-09
What This Feature Does
Injects Open Graph and Twitter Card meta-tags into the HTML response so that shared links display rich preview cards in messengers (WhatsApp, Telegram, Signal, etc.) and on social media (Twitter/X).
How It Works
- All HTML page requests go through a new
SpaController (replaces the current PathResourceResolver SPA fallback).
- The controller reads the compiled
index.html template once at startup and caches it.
- For event pages (
/events/{token}): fetches event data, generates event-specific meta-tags, injects them into the HTML.
- For non-event pages: injects generic fete branding meta-tags.
- Static files (
/assets/*, /favicon.svg, /og-image.png) continue to be served directly by Spring Boot's default static resource handler.
Key Files to Create/Modify
Backend (New)
| File |
Purpose |
SpaController.java |
Controller handling all non-API/non-static HTML requests, injecting meta-tags |
OpenGraphService.java |
Service composing meta-tag values from event data |
MetaTagRenderer.java |
Utility rendering meta-tag value objects into HTML <meta> strings |
Backend (Modified)
| File |
Change |
WebConfig.java |
Remove PathResourceResolver SPA fallback (replaced by SpaController) |
application.properties |
Add server.forward-headers-strategy=framework for correct URL construction behind proxies |
Frontend (Modified)
| File |
Change |
index.html |
Add <!-- OG_META_TAGS --> placeholder comment in <head> |
Static Assets (New)
| File |
Purpose |
frontend/public/og-image.png |
Brand image for og:image (1200x630 PNG) |
Testing Strategy
- Unit tests:
OpenGraphService — verify meta-tag values for various event states (full data, no location, no description, long title, special characters).
- Unit tests:
MetaTagRenderer — verify HTML escaping, correct meta-tag format.
- Integration tests:
SpaController — verify correct HTML response with meta-tags for event URLs, generic URLs, and 404 events.
- E2E tests: Fetch event page HTML without JavaScript, parse meta-tags, verify values match event data.
Local Development Notes
- In dev mode (Vite dev server), meta-tags won't be injected since Vite serves its own
index.html. This is expected — meta-tag injection only works when the backend serves the frontend.
- To test locally: build the frontend (
npm run build), copy dist/ contents to backend/src/main/resources/static/, then run the backend.
- Alternatively, test via the Docker build which assembles everything automatically.
nitrix
751201617d