README.md

Frontend Documentation

The frontend is the React/TypeScript public Geoportal interface for this repository. It runs locally as the frontend Docker Compose service on port 3000, or directly with npm from frontend/.

Available Documentation

Testing:

• Testing Guide - test suite, coverage, accessibility checks, and test-writing patterns.
• Testing Quick Reference - common testing commands and snippets.

Code quality:

• Linting and Formatting - ESLint, Prettier, and local workflow.
• Linting Quick Reference - short command and troubleshooting reference.

Features:

• Homepage Map Visualization - H3 hex map, featured carousel, preview layers, and Allmaps behavior.

Configuration:

• Google Tag Manager is injected by the SSR root only when VITE_KAMAL_DEST=prd and VITE_GTM_ID is present and matches a GTM container ID. Kamal leaves this blank by default and sets VITE_GTM_ID only for the prd destination.

Project Overview

The frontend stack currently uses:

• React 19 and React DOM 19.
• React Router 7 for routing, loaders, SSR, build, and production serving.
• TypeScript, Vite 7, and React Router dev tooling.
• Vitest 3, Testing Library, happy-dom, axe, and pa11y for tests and accessibility checks.
• Material UI 7, Tailwind, Leaflet, GeoBlacklight frontend components, Allmaps, H3, Recharts, and Lucide icons.

Quick Commands

Run from frontend/:

# Development and production build checks
npm run dev
npm run build
npm run start

# Testing
npm test
npm run test:watch
npm run test:coverage
npm run test:a11y

# Code quality
npm run lint
npm run lint:fix
npm run format
npm run format:check

Run from the repository root after frontend dependency or Vite config changes:

make frontend-reset

Then hard-refresh the browser or use a private/incognito window to avoid stale chunk URLs.

Maintenance Checklist

• Update this file when frontend/package.json scripts or major dependencies change.
• Update testing docs when Vitest, Testing Library, axe, pa11y, or test setup changes.
• Update feature docs when homepage map, featured resource, preview-layer, or Allmaps behavior changes.
• Run npm run lint, npm run format:check, and npm test before merging frontend behavior changes.