docs: ADR and migration guidance for per-page document titles#252
docs: ADR and migration guidance for per-page document titles#252arbrandes merged 2 commits intoopenedx:mainfrom
Conversation
Add ADR 0015 establishing that route-level page components own the document title via <Helmet>, and a corresponding section in the migration how-to so apps being ported don't ship without titles. Co-Authored-By: Claude <noreply@anthropic.com>
Show the example as src/Main.jsx (the component the route lazy-loads), not a generic content component, since that's where the apps actually add Helmet. Note the nested-routes case and the don't-reuse-an-h1 gotcha that came up in both learner-dashboard and instructor-dashboard. Co-Authored-By: Claude <noreply@anthropic.com>
|
Overall I think this makes sense, my only concern is that helmet always "wins," so authenticated apps must use a helmet title even if they just want the basic fallback because the authn title already "won." I know you mentioned
but you followed that with (emphasis mine)
the current ADR means that every app "needs to set a title." I think it's worth looking into having |
|
Not worth it. Every app needs to set a title, period. |
|
(Every app with a top-level route, I mean.) |
brian-smith-tcril
left a comment
brian-smith-tcril
left a comment
There was a problem hiding this comment.
With
Every app needs to set a title, period.
in mind, this LGTM.
I do think it's worth digging into
If many more apps adopt the pattern and a
wrapper proves valuable, we can revisit.
and possibly a way to enforce the every app with a top level route needs a title rule, but those are far into follow-up territory.
|
Should we consider the React 19 upgrade? You can still use react-helmet with React 19, but it now supports just including |
Well, I'll be damned. That'll be awesome. Let's totally do that once we upgrade to React 19. 👍🏼 |
|
🎉 This PR is included in version 1.0.0-alpha.43 🎉 The release is available on: Your semantic-release bot 📦🚀 |
4 participants
Description
Refs #250.
Adds ADR 0015 establishing that each route-level page component in a frontend-base app owns the document title via
<Helmet>fromreact-helmet, with the i18n message pattern{page}.page.titledefaulting to{Page Name} | {siteName}. This is the same patternfrontend-app-authnalready follows.The motivation is straightforward. A frontend-base site renders all of its apps under a single
index.html, so the document title only changes if a page sets it. Authn does; learner-dashboard and instructor-dashboard don't. After signing in, the browser tab keeps reading "Login | " while the user sits on a different app, which is a UX regression.The migration how-to gains a corresponding section so apps being ported don't ship without titles. Follow-up PRs will add the pattern to the apps that are missing it.
LLM usage notice
Built with assistance from Claude.