nitrix
751201617d
Replace PathResourceResolver SPA fallback with SpaController that injects OG/Twitter meta-tags into cached index.html template. Event pages get event-specific tags (title, date, location), all other pages get generic fete branding. Includes og-image.png brand asset and forward-headers-strategy for proxy support. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
58 lines
2.7 KiB
Markdown
58 lines
2.7 KiB
Markdown
# 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
|
|
|
|
1. **All HTML page requests** go through a new `SpaController` (replaces the current `PathResourceResolver` SPA fallback).
|
|
2. The controller reads the compiled `index.html` template once at startup and caches it.
|
|
3. For event pages (`/events/{token}`): fetches event data, generates event-specific meta-tags, injects them into the HTML.
|
|
4. For non-event pages: injects generic fete branding meta-tags.
|
|
5. 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.
|