Skip to content

Routing

Francisca Portugal edited this page Oct 27, 2026 · 1 revision

How the SPA maps URLs to pages, where paths come from, and what guards exist (almost none). Status: current.

The router is React Router v6 with BrowserRouter. Routes are declared in App.tsx; page components live in pages/. There is no file-based routing and no route-level code splitting.

Router setup

<BrowserRouter>
  <CombinedProvider>
    <SentryRoutes>            {/* Sentry.withSentryReactRouterV6Routing(Routes) */}
      …routes…
    </SentryRoutes>
    <Toaster />
  </CombinedProvider>
</BrowserRouter>
  • BrowserRouter uses the History API, so URLs are clean (/planner, not /#/planner).
  • SentryRoutes wraps Routes to attach the current route to Sentry events; it does not change matching.
  • CombinedProvider wraps the router's routes, so every page can read the root contexts.
  • The router is not lazy: all pages are static imports and ship in the initial bundle.

Routes

Path Page Layout Notes
/planner TimeTableSelectorPage ✅ The product; login prompt when anonymous
/about AboutPage ✅
/faqs FaqsPage ✅
/exchange ExchangePage ✅ Legacy exchange UI
/privacy-policy PrivacyPolicyPage ✅
/exchange/verify/:token ExchangeVerifyPage ✅ Declared separately from the page list
/ → /planner — Redirect
/home → /about — Redirect
* NotFoundPage ✅ Catch-all
/admin AdminPage page="pedidos" ❌ Own shell; client-side guard
/admin/vacancies AdminPage page="vacancies" ❌
/admin/settings AdminPage page="settings" ❌
/admin/statistics AdminPage page="statistics" ❌

The first six come from the pages array in App.tsx; admin routes are declared by hand and are not wrapped in Layout.

Where paths come from

src/config/local.json and src/config/prod.json define:

{
  "pathPrefix": "/",
  "paths": {
    "about": "about",
    "planner": "planner",
    "exchange": "exchange",
    "faqs": "faqs",
    "notfound": "*",
    "home": "home",
    "admin": "admin",
    "privacypolicy": "privacy-policy"
  }
}

getPath(simplePath) concatenates config.pathPrefix + simplePath. configToUse selects config when VITE_APP_PROD is true, otherwise dev_config.

Two quirks:

  • Exchange and privacy routes use config, not configToUse. If the dev and prod path maps ever diverge, those two routes will still use production paths.
  • Admin routes are hardcoded (admin, admin/vacancies, …) rather than read from config.paths.admin. The header still links to getPath(config.paths.admin).

Redirects

From To
/ /planner
config.pathPrefix (/) /planner
config.pathPrefix without its trailing slash ("") /planner
/home /about

They use <Navigate replace …>, so the redirect does not add a history entry. React Router ranks static paths above the * catch-all, so these win over NotFoundPage for their exact paths.

Layout and SEO

Layout wraps the public pages and the verify page:

  • renders Header, Footer, the feedback button and the page content;
  • sets document.title to <page title> | <site title>;
  • renders SEO (Helmet) with title, description, canonical, Open Graph and JSON-LD breadcrumbs.

Each pages entry carries its own location, description, canonical and breadcrumbs. The canonical URLs are hardcoded to https://tts.niaefeup.pt/..., including in dev and preview builds.

Admin routes opt out: AdminPage renders AdminSidebar + its own main area, and each page picks the view from the hardcoded route.

Navigation

  • Header builds its links from config.paths (Horários, Turmas, Sobre, FAQs, Admin).
    • Admin is filtered out unless signedIn && user.is_admin.
    • A wip flag can hide a link in production (all are currently false).
    • The active item is matched by the location string passed to Layout, not by useLocation().
  • Logo links to /, which redirects to /planner.
  • Footer contains external social links only.
  • Programmatic navigation uses useNavigate() (admin, exchange verify, request forms) or window.location for full-page flows such as OIDC login and reloads.
  • Query params are read with useSearchParams: ?session= joins a collaborative session on the planner. Exchange verification uses the /exchange/verify/:token path param instead.

Guards

There is no router-level guard. Authentication and authorization are handled inside pages:

Page Behaviour
Planner Anonymous users see the schedule shell plus a login prompt; the planner UI is not usable
Exchange Page renders, but actions require a session
Admin Redirects anonymous users to the OIDC login and non-admins to /exchange
Others Public

This is UX only. The backend must enforce auth on every route — the catalog returns 401 without a session, and admin endpoints are still 🚧. Never rely on a hidden link or a redirect for security.

Deep links and the SPA fallback

Because routing is client-side, a refresh on /planner or /exchange/verify/abc must return index.html:

  • Production: nginx uses try_files $uri $uri/ /index.html.
  • Dev: Vite's dev server does the same fallback.
  • Static hosts: the same rewrite is required. Netlify is configured via netlify.toml.

Hashed assets (/assets/*.js) are served as files; only unknown paths fall back to the SPA.

Adding a route

  1. Create the component in src/pages/, export it from src/pages/index.ts.
  2. Add its path to config/local.json and config/prod.json if it is a normal page.
  3. Add an entry to the pages array in App.tsx:
    • path: getPath(configToUse.paths.<key>);
    • location (header label), description, canonical, breadcrumbs;
    • element.
  4. Decide whether it belongs inside Layout (normal page) or outside (admin-style shell).
  5. Add a header link in components/layout/Header.tsx if it should be discoverable.
  6. If it needs a param, declare a separate <Route> (as /exchange/verify/:token does).
  7. Guard inside the page if it needs auth; the router will not do it for you.
  8. Update this page and the Frontend directory tour.

No server change is needed for a new client route, provided the SPA fallback already exists.

Pitfalls

  • No route-level code splitting. Every page is in the initial bundle.
  • No global error boundary. A render error is not caught by the router.
  • No scroll restoration. Navigating does not reset scroll; the planner scrolls the layout into view itself.
  • Canonicals are production URLs even in dev/preview.
  • Admin protection is client-side only. A hidden header link is not authorization.
  • configToUse is not used everywhere. Exchange and privacy read config directly.
  • Active nav matching is by label. Renaming a location without changing the header breaks the highlight.
  • The * route is a page, not a redirect. It renders NotFoundPage with a 200 response; the server does not send a 404 status.

See also


Last verified: 2026-10-27

Clone this wiki locally