docs: add design spec for SEO fixes and prerendering migration
Covers server-side redirects/404, compression/cache headers, dynamic sitemap, vite-react-ssg prerendering with react-helmet-async, and 30 curated conversion-pair landing pages.
This commit is contained in:
@@ -0,0 +1,224 @@
|
|||||||
|
# SEO fixes and prerendering — design
|
||||||
|
|
||||||
|
## Context
|
||||||
|
|
||||||
|
A code-based SEO review of the Convert app (`frontend/` React+Vite SPA served
|
||||||
|
by `src/app.js` Express, catch-all to a single `index.html`) found:
|
||||||
|
|
||||||
|
- Pure client-side rendering: no SSR/prerendering plugin in `vite.config.js`.
|
||||||
|
- Only two indexable URLs exist (`/fr/`, `/en/`); all SEO tags (title, meta
|
||||||
|
description, OG, Twitter, hreflang, JSON-LD) are set client-side in a
|
||||||
|
`useEffect` inside `frontend/src/components/SeoHead.jsx`, so a crawler that
|
||||||
|
doesn't execute JS sees only the static, generic tags baked into
|
||||||
|
`frontend/index.html`.
|
||||||
|
- `/` redirects to `/fr/` or `/en/` via client-side `<Navigate>`
|
||||||
|
(`navigator.language`), not a server redirect.
|
||||||
|
- The Express catch-all (`src/app.js:251-255`) returns `index.html` with an
|
||||||
|
implicit 200 for every unmatched route, including typos — a soft-404.
|
||||||
|
- No `canonical` tag, incomplete OG/Twitter tags, no compression middleware,
|
||||||
|
no explicit `Cache-Control` on static assets.
|
||||||
|
- `frontend/public/sitemap.xml` is static, listing only the two shell URLs.
|
||||||
|
- The app supports 150+ registered conversion pairs
|
||||||
|
(`src/converters/*.js` → `registry.js`) but has zero landing pages
|
||||||
|
targeting specific "convert X to Y" search intent.
|
||||||
|
|
||||||
|
This spec covers the full scope the user approved: targeted technical fixes,
|
||||||
|
a build-time prerendering migration, and a curated set of programmatic
|
||||||
|
conversion-pair landing pages.
|
||||||
|
|
||||||
|
## Goals
|
||||||
|
|
||||||
|
- Every route the app exposes returns fully-formed SEO tags (title,
|
||||||
|
description, canonical, OG, Twitter, hreflang, JSON-LD) in the raw HTML
|
||||||
|
response, with no dependency on JS execution.
|
||||||
|
- `/` redirects server-side (301) by language.
|
||||||
|
- Unknown routes return a real HTTP 404.
|
||||||
|
- Static assets are compressed and cached; HTML is revalidated on each
|
||||||
|
request.
|
||||||
|
- `sitemap.xml` reflects the real, current set of prerendered URLs.
|
||||||
|
- ~30 curated conversion-pair landing pages (×2 languages = 60 URLs) exist,
|
||||||
|
each with genuinely differentiated content, driving long-tail organic
|
||||||
|
traffic to the existing conversion tool.
|
||||||
|
|
||||||
|
## Non-goals
|
||||||
|
|
||||||
|
- Full request-time SSR (rejected in favor of build-time prerendering — no
|
||||||
|
per-request render cost, no framework rewrite, works with the existing
|
||||||
|
static-file hosting model on o2switch).
|
||||||
|
- Generating landing pages for all 150+ registered pairs (would cross the
|
||||||
|
quality-gate hard-stop for thin content; only pairs with real content get a
|
||||||
|
page).
|
||||||
|
- Any change to conversion logic itself (`src/converters/*`, `src/worker.js`).
|
||||||
|
- Adding new conversion pairs — this spec only targets already-registered
|
||||||
|
ones.
|
||||||
|
|
||||||
|
## Architecture: build-time prerendering with `vite-react-ssg`
|
||||||
|
|
||||||
|
`vite-react-ssg` renders each configured route once at build time
|
||||||
|
(`ReactDOMServer`) to a static `frontend/dist/<route>/index.html`, then the
|
||||||
|
same bundle hydrates normally in the browser. Runtime behavior for users is
|
||||||
|
unchanged; what changes is what a non-JS client (crawler, social-media
|
||||||
|
unfurler, `curl`) receives.
|
||||||
|
|
||||||
|
**Why not `useEffect` for SEO tags with this approach:** `useEffect` never
|
||||||
|
runs during `renderToString`/`renderToStaticMarkup` — only after hydration in
|
||||||
|
a real browser. If `SeoHead.jsx` stays as-is, prerendering would still ship
|
||||||
|
HTML with no SEO tags, defeating the migration. `SeoHead.jsx` must be
|
||||||
|
rewritten to use **`react-helmet-async`** (new dependency, pure JS, no native
|
||||||
|
bindings — safe for o2switch), which collects head tags synchronously during
|
||||||
|
render via `HelmetProvider` context, on both the server pass and the client.
|
||||||
|
|
||||||
|
### Changes
|
||||||
|
|
||||||
|
- `frontend/package.json` / root `package.json`: add `react-helmet-async` and
|
||||||
|
`vite-react-ssg` (frontend needs both for local dev; root needs
|
||||||
|
`vite-react-ssg` too, per the existing o2switch single-`node_modules`
|
||||||
|
constraint documented in `CLAUDE.md`).
|
||||||
|
- `frontend/src/main.jsx`: replaced with a `ViteReactSSG` entry (exports an
|
||||||
|
app-creation function instead of calling `createRoot().render()` directly).
|
||||||
|
Routes declared as a single config array consumed by both the prerender
|
||||||
|
pass and client hydration.
|
||||||
|
- `frontend/vite.config.js`: add `vite-react-ssg` build config, listing every
|
||||||
|
route to prerender (see route list below).
|
||||||
|
- `frontend/src/components/SeoHead.jsx`: rewritten on top of
|
||||||
|
`react-helmet-async`'s `<Helmet>`; adds `canonical` (currently missing) and
|
||||||
|
makes `hreflang` alternates and JSON-LD render synchronously instead of via
|
||||||
|
`useEffect`. Also rendered from `NotFound.jsx` (currently not called there),
|
||||||
|
with a `noindex` meta tag for the 404 page specifically.
|
||||||
|
- `frontend/src/pages/HomePage.jsx` and the new conversion-pair pages
|
||||||
|
(below) consume the rewritten `SeoHead`.
|
||||||
|
|
||||||
|
## Express changes (`src/app.js`)
|
||||||
|
|
||||||
|
- **Server-side language redirect**: a route on `/` reads `Accept-Language`,
|
||||||
|
picks `fr` or `en` (default `fr` if absent/unrecognized), and responds
|
||||||
|
`res.redirect(301, '/fr/')` or `/en/'`. Placed before the static/catch-all
|
||||||
|
middleware. Replaces the client-side `<Navigate>` in `RootRedirect`.
|
||||||
|
- **Real 404s**: the catch-all is given the list of routes that were actually
|
||||||
|
prerendered (generated at build time — see "Route manifest" below). A
|
||||||
|
request path not in that list gets `res.status(404).sendFile(<prerendered
|
||||||
|
404 page>)` instead of an implicit 200.
|
||||||
|
- **Compression**: add the `compression` npm package (pure JS, standard
|
||||||
|
Express middleware), mounted early in `src/app.js`, before
|
||||||
|
`express.static`.
|
||||||
|
- **Cache-Control**: `express.static(frontendDist, { setHeaders })` sets
|
||||||
|
`Cache-Control: public, max-age=31536000, immutable` for hashed asset paths
|
||||||
|
(Vite's `/assets/*.js`, `/assets/*.css`) and `Cache-Control: no-cache` for
|
||||||
|
any `index.html` response, so redeploys are picked up immediately while
|
||||||
|
assets cache aggressively.
|
||||||
|
|
||||||
|
### Route manifest
|
||||||
|
|
||||||
|
`vite-react-ssg`'s build produces a known, fixed list of output directories.
|
||||||
|
A small script (`frontend/scripts/generateRouteManifest.js`, run as part of
|
||||||
|
`npm run build`) writes `frontend/dist/route-manifest.json` — a flat array of
|
||||||
|
every valid path — consumed by both the sitemap generator and
|
||||||
|
`src/app.js`'s 404 check.
|
||||||
|
|
||||||
|
## Sitemap generation
|
||||||
|
|
||||||
|
`frontend/public/sitemap.xml` (static, 2 URLs) is replaced by a build step
|
||||||
|
(`frontend/scripts/generateSitemap.js`, runs after the SSG build, reads
|
||||||
|
`route-manifest.json`) that writes `frontend/dist/sitemap.xml` with one
|
||||||
|
`<url>` entry per prerendered route and `<lastmod>` set to the build
|
||||||
|
timestamp. `express.static` serves it from `dist` like any other static
|
||||||
|
file. `robots.txt` is unchanged (already correct).
|
||||||
|
|
||||||
|
## Programmatic conversion-pair landing pages
|
||||||
|
|
||||||
|
### Scope: 30 curated pairs, verified against the registry
|
||||||
|
|
||||||
|
Selected for realistic search intent and confirmed present in
|
||||||
|
`src/converters/*.js` (no page is created for an unregistered pair):
|
||||||
|
|
||||||
|
**Image (8)**: jpg→png, png→jpg, png→webp, webp→jpg, jpg→webp, gif→png,
|
||||||
|
png→pdf, jpg→pdf
|
||||||
|
|
||||||
|
**HEIC (2)**: heic→jpg, heic→png
|
||||||
|
|
||||||
|
**Favicon/ICO (2)**: png→ico, ico→png
|
||||||
|
|
||||||
|
**Document (8)**: pdf→docx, docx→pdf, pdf→txt, pdf→html, csv→xlsx, xlsx→csv,
|
||||||
|
csv→pdf, xlsx→pdf
|
||||||
|
|
||||||
|
**Video (5)**: mov→mp4, mkv→mp4, avi→mp4, webm→mp4, mp4→webm
|
||||||
|
|
||||||
|
**Audio (5)**: wav→mp3, mp3→wav, m4a→mp3, flac→mp3, ogg→mp3
|
||||||
|
|
||||||
|
This is exactly at the quality-gate warning threshold (30 pages) — each page
|
||||||
|
needs genuinely differentiated (60%+ unique) content, not templated text with
|
||||||
|
only format names swapped in.
|
||||||
|
|
||||||
|
### Data model
|
||||||
|
|
||||||
|
`frontend/src/data/conversionPages.js` — one entry per pair:
|
||||||
|
|
||||||
|
```js
|
||||||
|
{
|
||||||
|
pairId: 'pdf-to-docx',
|
||||||
|
sourceFormat: 'pdf',
|
||||||
|
targetFormat: 'docx',
|
||||||
|
family: 'document',
|
||||||
|
slugs: { fr: 'convertir-pdf-en-word', en: 'convert-pdf-to-word' },
|
||||||
|
content: {
|
||||||
|
fr: { title, description, intro, benefits: [...], steps: [...] },
|
||||||
|
en: { title, description, intro, benefits: [...], steps: [...] },
|
||||||
|
},
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
This single table drives: the prerendered route list, hreflang alternates
|
||||||
|
(each language entry links to the other via `slugs`), the sitemap, and the
|
||||||
|
page component itself.
|
||||||
|
|
||||||
|
### Routing
|
||||||
|
|
||||||
|
`/:lang/:slug` pages are added alongside the existing `/:lang/` home route,
|
||||||
|
resolved against `conversionPages.js` by matching `slugs[lang]`. Localized
|
||||||
|
slugs are used (e.g. `/fr/convertir-pdf-en-word` vs.
|
||||||
|
`/en/convert-pdf-to-word`) rather than a shared slug across languages, since
|
||||||
|
localized slugs read naturally and match local-language query patterns; the
|
||||||
|
data model's `slugs` map keeps hreflang correct despite the differing paths.
|
||||||
|
|
||||||
|
### Content
|
||||||
|
|
||||||
|
Each page reuses the existing conversion tool UI with source/target format
|
||||||
|
pre-selected from the route, plus a real intro paragraph, a benefits list,
|
||||||
|
and a short step-by-step guide. This copy is authored (fr + en) as part of
|
||||||
|
implementation — it is not templated or auto-generated from format names,
|
||||||
|
per the quality-gate uniqueness requirement.
|
||||||
|
|
||||||
|
## Testing plan
|
||||||
|
|
||||||
|
- **Prerender output check**: a script/test reads each expected
|
||||||
|
`dist/<route>/index.html` and asserts (via string/regex checks) the
|
||||||
|
presence and correctness of `<title>`, meta description, `canonical`,
|
||||||
|
OG tags, `hreflang` alternates, and JSON-LD — this is what actually proves
|
||||||
|
the SSR-vs-`useEffect` problem is fixed, not merely assumed fixed.
|
||||||
|
- **Express tests** (Vitest, using `.env.local` per `CLAUDE.md`):
|
||||||
|
- `/` → 301 to `/fr/` or `/en/` depending on `Accept-Language`.
|
||||||
|
- Unknown path → 404 (not the current implicit 200).
|
||||||
|
- Known route → 200, `Cache-Control: no-cache` on HTML,
|
||||||
|
`public, max-age=31536000, immutable` on hashed assets.
|
||||||
|
- Response is compressed when the client advertises support.
|
||||||
|
- **Sitemap test**: generated `sitemap.xml` contains exactly one `<url>` per
|
||||||
|
manifest entry, each with a valid `<lastmod>`.
|
||||||
|
- **Functional non-regression**: the full existing Vitest suite, plus a
|
||||||
|
manual browser pass (upload → convert → download) for one pair per family
|
||||||
|
(image, document, audio, video), since the SSG migration changes the
|
||||||
|
routing/render entry point (`main.jsx`).
|
||||||
|
- **Raw-HTML crawler simulation**: `curl` (no JS execution) against `/fr/`,
|
||||||
|
`/en/`, and one conversion-pair page, confirming SEO tags are present in
|
||||||
|
the response body as received — distinct from a browser check, which
|
||||||
|
always executes JS regardless of whether prerendering worked.
|
||||||
|
|
||||||
|
## Risks / open questions
|
||||||
|
|
||||||
|
- `vite-react-ssg` compatibility with `react-router-dom` v7 and React 19
|
||||||
|
(both current dependencies) needs to be confirmed against the installed
|
||||||
|
versions during implementation — not assumed from documentation alone.
|
||||||
|
- Adding `vite-react-ssg` and `react-helmet-async` to **both** `package.json`
|
||||||
|
files, per the existing o2switch constraint that only root's
|
||||||
|
`node_modules` is available at runtime on the server.
|
||||||
|
- Content authoring for 60 pages (30 pairs × 2 languages) is a real writing
|
||||||
|
task, not a mechanical one — likely the largest time cost in this project.
|
||||||
Reference in New Issue
Block a user