Kovács — Modern Poetry Portfolio
Bilingual (Hungarian/English) poetry portfolio. Every route is prerendered to static HTML, so
the poems are indexable without JavaScript, and an admin portal edits the content live.
Live: https://artoriun.github.io/kov-cs-poetry/
Lighthouse
Measured against the live deploy. CI runs the same audit on every push and gates
accessibility, best practices and SEO at 100.
Mobile — LCP 2.7s · CLS 0 · TBT 0ms
Desktop — LCP 0.6s · CLS 0.004 · TBT 0ms
Stack
| |
|---|
| Front end | React, TypeScript, Vite, Motion |
| Back end | Express, Firestore |
| Media | Cloudinary |
| Tooling | TurboRepo, Biome, Playwright |
| Hosting | GitHub Pages (site) · Render (API) |
Three workspaces: packages/web, packages/api, packages/shared.
Quick start
npm install
npm run dev # web + API, with /api proxied in development
Copy .env.example to packages/api/.env and set at least:
ADMIN_PASSWORD= # or ADMIN_PASSWORD_HASH from `npm run hash-password`
JWT_SECRET=
FIREBASE_PROJECT_ID= # plus CLIENT_EMAIL, PRIVATE_KEY, STORAGE_BUCKET
CLOUDINARY_URL=
Contact email (RESEND_API_KEY or SMTP) is optional — without it the form returns 503 rather
than dropping messages. Firestore is optional too: leave the FIREBASE_* lines commented and
the API still starts and serves the bundled poems, so a fresh clone runs before you have signed
up for anything. The site runs with no API at all in the same way — the poems are in the bundle,
and the portal is simply unreachable.
Scripts
npm run build # production build
npm run prerender # static HTML per route, sitemap and robots
npm run ci # everything CI runs, in order
npm run test # API and unit tests
npm run test:e2e # Playwright, four viewport and touch profiles
npm run check:lighthouse # accessibility / SEO / best-practices gate
npm run hash-password # prints an ADMIN_PASSWORD_HASH
npm run backup-poems # writes the live poems to backups/
Features
- Reader — full-screen poem pages, vertical swipe between pages, staggered line reveals,
and a dedicated landscape layout
- Prerendered — one HTML file per route with its own title, description, canonical and
structured data; the poem text is in the markup before any script runs
- Bilingual — Hungarian and English, switchable, portal included
- Light and dark themes, WCAG AA contrast,
prefers-reduced-motion respected
- Contact form with validation, a honeypot and per-IP rate limiting
- Images sized per device through Cloudinary; the body font is self-hosted
Admin portal
Password login with JWT auth at /admin. Create, edit, hide and drag-to-reorder poems,
feature them on the home carousel, and upload images.
Hiding takes a poem off the site without destroying it: the card stays in the portal, marked
and in its place in the order, with a button that puts it back. Nothing in the portal deletes
anything permanently, which matters most for poems written there — their text exists nowhere
else.
Sign-in is throttled three ways: three wrong passwords in a row pause it for thirty seconds,
which the form counts down rather than calling a lockout an incorrect password, and two
fifteen-minute limits sit behind that as the real ceiling — one in memory, one in Firestore so
it survives a restart.
List is where a poem is written: the image preview sits beside the fields that produce it,
because the text is laid over the image rather than beside it. Order is the same poems as
cards, dragged into the sequence readers meet them in, beside a contents sidebar that mirrors
the public one. Dragging either the cards or the sidebar reorders both, and the change is live
for visitors straight away.
On a touch screen each sidebar entry is dragged by its grip. Reordering and scrolling are both
vertical in a list like that, so the grip is what tells the browser which one a touch means —
everywhere else on the row still scrolls.
Edits are live for visitors immediately. The prerendered HTML that crawlers read is a
build-time snapshot and catches up on the next deploy — weekly by cron, or on demand.
Page breaks
Pages are filled with whole stanzas, so most poems need no markers at all: the reader breaks
between stanzas and only splits one when that stanza alone is taller than the viewport.
Typing \n in a poem's text marks where it continues on a new page over the same background.
It is part of the poem text, so it needs no schema change, and a poem without one is a single
page. The reader never merges across a break, and still subdivides one further if it is too
tall for the viewport.
Testing
npm run ci runs the pipeline in CI's order: Biome, tsc, API and unit tests, Playwright
layout tests across four viewport and touch profiles, an axe accessibility sweep in both
themes, a gzipped bundle budget, a first-paint-versus-hydrated check, and Lighthouse against
the built output.
Deployment
- Site → GitHub Pages on push to
main; the deploy job needs every check to pass first.
- API → Render (free tier). Set
CORS_ORIGIN there, and add the API URL as the
VITE_API_URL GitHub Actions secret.
- Prerendered HTML is a snapshot, so a weekly cron rebuild keeps crawlers current.
- Node 22 is required (
.nvmrc).
Poems live in packages/shared/src/index.ts as a fallback; portal edits are stored in
Firestore and take precedence at runtime.
Licence
All rights reserved — see LICENSE. The source is published to be read, not reused:
this is client work, and the poems and photographs belong to their author.
