About freemap-v3-react

Freemap Slovakia web application (www.freemap.sk)

f

Published by

freemapslovakia

Visit View Profile

README.md

View on GitHub

Freemap Slovakia Web Application

Source of www.freemap.sk, the web map portal maintained by OZ Freemap Slovakia.

Freemap is a free, non-commercial web map application built on OpenStreetMap data. Its focus is a detailed outdoor map for hiking, cycling, cross-country skiing and horse riding across Europe, complemented by many additional base and overlay layers and by tools for search, route planning, drawing and measurement, GPX viewing, live tracking, personal maps, map embedding, and export.

This repository is the frontend — a React single-page application. It talks to:

the Freemap API server (freemap-v3-api) for accounts, photos, tracking, saved maps and purchases, and
external tile, routing (GraphHopper) and geocoding (Nominatim / Overpass) services.

Tech stack

React 19 + Redux Toolkit (application state is reflected in the URL hash)
Leaflet / react-leaflet with MapLibre GL for vector layers
TypeScript, type-checked with tsgo
rspack bundler, Biome for linting/formatting, pnpm as the package manager
Zod schemas for validation (see CLAUDE.md for conventions)

Requirements

Node.js 22+
pnpm
A running Freemap API server for features that depend on the backend (login, photos, tracking, saved maps, export); the map itself renders without it.

Compiling and running in development mode

Map local.freemap.sk to 127.0.0.1 in your system hosts file (on Linux and macOS this is /etc/hosts):
```
127.0.0.1 local.freemap.sk
```
Install dependencies:
```
pnpm install
```
Start the dev server (it compiles protobufs, syncs language files, and rebuilds on change):
```
pnpm start
```
Trust the development CA certificate in your browser (the dev server is served over HTTPS).
Open the application at https://local.freemap.sk:9000/.

Building for production

The build target is selected with the DEPLOYMENT environment variable:

unset or dev — development build for local.freemap.sk (uses local backend / base URLs).
www — production build for www.freemap.sk (wires up the production backend, GraphHopper, Matomo, Sentry and Facebook app IDs).
any other value (e.g. next) — a production-optimized build that still uses the local / default URLs.

pnpm install
DEPLOYMENT=www pnpm build

The static web resources are emitted into the dist/ directory.

Deploying www.freemap.sk is done with the dep script, which runs a www production build, injects and uploads Sentry source maps, and rsyncs dist/ to the server:

pnpm dep

Server (nginx) configuration

The production nginx site configs are checked into this repo under etc/nginx/sites-available/ as a reference for what is actually deployed:

www.freemap.sk — the main site.
www.freemap.eu — the .eu mirror (additionally allows CORS for the GlitchTip/Sentry origin).

Both serve the static build from /home/freemap/www and share the same cache-header policy, which is critical to get right — mismatched headers pin users to stale hashed asset names and break the layout after a deploy:

Entry HTML (index*.html, the / redirect), service workers (sw.js, upload-sw.js) and assets-manifest.json are served Cache-Control: no-store, max-age=0 — they are unhashed and must never go stale.
Content-addressed assets (rspack emits 16-char [contenthash]/[chunkhash] names) are max-age=31536000, immutable.
*.png / *.jpg get a one-year max-age (without immutable).

The configs also handle: HSTS / Referrer-Policy headers, HTTP→HTTPS redirect and HTTP/3 (QUIC) via Certbot-managed TLS, per-user directory listings under /~<user>/, search-engine sitemap rewrites for bots on /, /mbtiles offline-map downloads, and a reverse proxy for /tiles/parametric-shading.

When changing build-output naming, the service worker, or the asset manifest, update these configs in the same change set.

Environment variables

Most deployment-specific values are derived from DEPLOYMENT (see above). The remaining overrides:

FM_MAPSERVER_URL — base URL of the Mapnik tile server, without a trailing slash (default https://outdoor.tiles.freemap.sk; e.g. http://localhost:4000 for local rendering).
PREVENT_ADS — if set (to any value), disables the ad banner.

Documentation

Deeper reference docs live in doc/:

Drawing feature export/import format mapping — how points, lines and polygons round-trip through GPX and GeoJSON, including the curated icon mappings for Garmin / OsmAnd / Locus.

src/static/llms.txt is a hand-maintained, user-facing description of the application (its functions, modals and map layers) for AI assistants, served at www.freemap.sk/llms.txt per the llmstxt.org convention. Keep it in sync when changing user-visible behavior — see CLAUDE.md.

Contributor notes for Claude Code (workflow, conventions): CLAUDE.md.

Translation (i18n)

The English master is src/translations/en.tsx; other locales are edited via their *.template.tsx files (the plain *.tsx files are generated — see CLAUDE.md).

Files holding translatable text:

rspack.config.ts — texts in htmlPluginProps
src/translations/en-shared.json
src/translations/en.tsx
src/components/supportUsModal/translations/en.tsx
src/globalErrorHandler.ts — bottom error message
src/osm/osmTagToNameMapping-en.ts
https://github.com/FreemapSlovakia/freemap-mapnik/blob/develop/legend.js

License

Apache-2.0

freemap-v3-react