🗺️ MaraMap Frontend
The Next.js web app for MaraMap — a running and travel log that turns years of
Facebook posts into an interactive map, timeline and list.
Pairs with MaraMap-Backend
(NestJS Content API + Supabase + Cloudflare R2).
Tech stack
| |
|---|
| Framework | Next.js 16 (App Router, Turbopack) + React 19 |
| Styling | Tailwind CSS v4 |
| Map | Leaflet + react-leaflet + marker clustering |
| Motion / icons | framer-motion, lucide-react |
| Tests | Jest + Testing Library (unit), Playwright (E2E) |
| Package manager | Bun (what CI uses) |
| Hosting | Vercel |
Getting Started
bun install # also installs the pre-push git hook (see Testing)
bun run dev # http://localhost:3006
The app needs the backend running on port 3016 for anything data-driven.
Environment variables
A single gitignored .env holds everything this machine needs: NEXT_PUBLIC_API_URL
and NEXT_PUBLIC_CARTO_BASEMAP_API_KEY. There's no .env.development /
.env.production split locally — this repo only ever runs one environment
on a dev machine, and the deployed values on Vercel are configured in its own
dashboard rather than from a committed file (these were always gitignored, so
they never reached a Vercel build in the first place).
Leave NEXT_PUBLIC_API_URL empty for local dev. src/utils/apiBase.ts then
derives the backend URL from the page's own hostname, so the app works from
both the laptop (localhost:3016) and a phone on the same LAN
(<machine-LAN-IP>:3016) with no hardcoded address to update when the IP changes.
Project structure
src/
app/
(public)/ # Public site — home, /log/[id], /personal-best
admin/ # Admin area — login, new, edit/[id], import, personal-best
map/ # Full-screen map view
components/ # MapView, ListView, TimelineView, CountryModal, SiteHeader…
admin/ # MediaManager, Combobox
utils/ # apiBase, formatLocation, locationData, postHelpers
Routes
| Route | Purpose |
|---|
/ | Home — map / list / timeline of all posts |
/log/[id] | Single post with photo and video carousels + lightbox |
/personal-best | Personal-best records |
/map | Full-screen map |
/admin | Post management (JWT auth against the backend) |
/admin/new, /admin/edit/[id] | Create / edit a post, with direct-to-R2 media upload |
/admin/import | Facebook export import review flow |
Testing
bun run test # Jest unit tests with coverage
bun run test:watch
bun run test:e2e # Playwright (starts its own dev server on :3006)
bun run test:e2e:ui # Playwright UI mode
bun run lint
A pre-push hook (.githooks/pre-push, installed automatically by the
prepare script) runs eslint --fix, amends any auto-fixes into the last
commit, then runs the unit tests and aborts the push if they fail.
CI
.github/workflows/ci.yml runs on push and PR to develop / master:
lint → unit tests → Playwright E2E → bun run build. Test results are published
as PR checks via dorny/test-reporter.
Decisions worth knowing before you change things
These are non-obvious and each one was learned the hard way.
Images bypass the Vercel image optimizer (next.config.ts,
images.unoptimized: true). On the Hobby plan the optimizer has a monthly
transformation quota; photo-heavy post pages blew past it and every
next/image request started returning 402, breaking every image. R2 media is
already Cloudflare-served (free egress, CDN-cached) and FB-export sized
(~200 KB median). If per-device srcset/AVIF is wanted back, do it in
Cloudflare or pre-generate variants in the ETL — not Vercel.
Fonts are loaded with a plain <link>, not next/font/google
(src/app/layout.tsx). next/font downloads woff2 files at build time, and
when the Vercel builder could not reach fonts.gstatic.com the build hard-failed
with no fallback. Weights must stay in sync with the font-* utilities in use —
serif 900 in particular, which every font-serif font-black heading depends on.
Video preload is deliberate, not accidental (src/app/(public)/log/[id]/page.tsx).
The main carousel keeps preload="metadata" because the first frame is the
visual there. The thumbnail rail renders an icon tile instead of a <video>
(at 56 px the frame is unreadable, and each one costs a metadata fetch), and the
lightbox uses preload="none" because every slide in the strip is rendered at
once. See docs/VIDEO_PLAN.md.
Bun is the only supported package manager. package.json's
packageManager field pins the exact version and a preinstall hook
(npx only-allow bun) blocks npm/pnpm/yarn install attempts, so a
second lockfile can't reappear. A past package-manager switch dropped the
Vercel build cache and contributed to a build failure — that's the incident
this guards against.
