Wat is het weer?

Nederlandstalige weerapp voor watishetweer.nl. De applicatie combineert actuele en verwachte weerdata met een centrale interpretatielaag, neerslag, luchtkwaliteit, pollen, waarschuwingen en Nachtzicht.

Productie en build

Cloudflare Pages is het enige productieplatform. De productieflow draait vanuit GitHub Actions en bouwt met:

npm run build:cloudflare

De build assembleert de canonieke bronbestanden en gecontroleerde buildlagen tot public/. Daarna voegt scripts/cloudflare-output.js de Cloudflare Pages-configuratie toe en deployt .github/workflows/cloudflare-production.yml exact de main-SHA: eerst als releasekandidaat (Pages-preview op branch release-candidate) met readiness en volledige smoke, en pas daarna hetzelfde artifact naar production. Een rode kandidaat laat de live site ongemoeid. Wijzig daarom niet handmatig bestanden in public/; die map wordt opnieuw opgebouwd.

Belangrijke ingangen:

• index.html — hoofdtemplate en primaire browserlogica.
• interpretatie-engine.js — centrale interpretatielogica.
• build-weather.js — assembleert het productie-artifact en bindt de serviceworker-cache aan de app-shell.
• scripts/ — afgebakende build-, verificatie- en regressielagen.
• api/ — gedeelde serverroute-logica die door Cloudflare Pages Functions wordt aangeroepen.
• functions/api/ — dunne Cloudflare Pages Functions-wrappers.
• functions/_middleware.js — securityheaders voor dynamische Cloudflare-responses.
• cloudflare/_headers — securityheaders voor statische Cloudflare-responses.
• cloudflare/_routes.json — expliciete Pages Functions-routing.
• wrangler.jsonc — Cloudflare Pages-projectconfiguratie.

API-routes

De huidige publieke serverroutes zijn:

• api/forecast.mjs — beschermde server-side forecastfallback (Visual Crossing, met WeatherAPI als noodfallback) voor actuele, uur- en zevendaagse forecastdata.
• api/plaatsnaam.mjs — reverse geocoding voor Mijn locatie wanneer de directe BigDataCloud-resolutie niet genoeg oplevert.
• api/neerslag.mjs — actuele en korte-termijnneerslag via de beschikbare providerlaag.
• api/waarschuwingen.mjs — officiële weerwaarschuwingen op basis van de gekozen locatie.
• functions/api/admin/seo.js — privé SEO-dashboard-API achter Cloudflare Access; zie .github/SEO_DASHBOARD_SETUP.md.

Serverlogica staat in lib/. De functions/api/*.js-bestanden zijn alleen de Cloudflare-ingangen en horen geen tweede implementatie van de route te bevatten.

Forecastfallback (Visual Crossing en WeatherAPI)

Open-Meteo blijft de primaire forecastbron. Alleen bij een fout of wanneer de volledige Open-Meteo-request na tweeënhalve seconde nog niet gereed is, starten de lichte Open-Meteo-fallback en de same-origin route /api/forecast binnen hetzelfde begrensde fallbackvenster. Die route probeert eerst Visual Crossing en valt daarna terug op WeatherAPI; geldige volledige antwoorden van beide providers worden tien minuten in de Cloudflare edge-cache bewaard. De eerste volledige, gevalideerde zevendaagse dataset wint; verliezende requests worden afgebroken.

De providersleutels mogen uitsluitend als versleutelde Cloudflare Pages-secrets VISUAL_CROSSING_API_KEY en WEATHERAPI_KEY in zowel preview als production worden ingesteld. Zet een sleutel nooit in browsercode, GitHub Actions-output of een repositorybestand. Omdat de app zeven dagen toont, is een WeatherAPI Starter-abonnement of hoger vereist; een driedaagse Free-response faalt bewust gesloten.

Reverse geocoding

De standaardfallback is de publieke Nominatim-dienst van OpenStreetMap. De serverroute rondt coördinaten af, gebruikt een herkenbare product-User-Agent en geeft cache-instructies mee.

De basis-URL kan optioneel zonder codewijziging worden omgezet naar een andere Nominatim-compatible dienst:

NOMINATIM_BASE_URL=https://geo.example.nl/nominatim

Zonder deze variabele blijft https://nominatim.openstreetmap.org de standaard. Een expliciet ingestelde maar ongeldige URL faalt gesloten; de applicatie schakelt dan niet stil terug naar de publieke dienst.

Waarschuwingen

• Verenigde Staten en ondersteunde gebieden: National Weather Service, op coördinaat.
• Europa: MeteoAlarm, waarbij bruikbare CAP-gebiedsinformatie tegen het gekozen punt wordt gecontroleerd.
• Elders: geen bron als er geen betrouwbare ondersteunde waarschuwingbron is.

Een waarschuwing wordt alleen als plaatsgebonden kaart doorgegeven wanneer de server expliciet bewijs voor die plaatsdekking heeft. Landbrede of onbekende scope wordt niet als lokale waarschuwing gepresenteerd.

Amerikaanse meldingen (NWS) tonen altijd hun specifieke gebeurtenis; er is geen algemene kop meer. De server (lib/nws-gebeurtenissen.cjs) kent alle gebeurtenistypen van api.weather.gov/alerts/types (fixture: scripts/fixtures/nws-gebeurtenistypen.json) en geeft per melding titelNl (alleen bij een zekere vertaling), klasse (waarschuwing, waakzaamheid, advies of melding), ernstNl en prioriteit mee. Is de vertaling onzeker, of is het type nieuw, dan staat de officiële Engelse naam in de kop (lang="en"). ernstNl is de ernst die de Amerikaanse weerdienst zelf opgeeft (CAP severity: gering, matig, ernstig, extreem of niet opgegeven) en wordt altijd met die bronvermelding getoond; het is geen KNMI- of MeteoAlarm-kleurcode. Berichten met een andere status dan Actual (testberichten) worden niet getoond. Engelstalige bezoekers zien de officiële Engelse naam. De oudere tabellen in scripts/final-audit-20260901.js (kaarten) en scripts/staff-audit-20260826.js (briefing) zijn alleen nog de terugval voor een antwoord zonder titelNl; een nieuwe vertaling hoort in lib/nws-gebeurtenissen.cjs en een nieuwe officiële naam ook in de namenlijst van taal/en.js (scripts/nws-gebeurtenissen.test.js bewaakt beide). De lijst staat op prioriteit (ernst van de bron, daarna soort melding, daarna begin); de dringendste drie staan direct zichtbaar en elke andere actieve waarschuwing staat in de uitklap "+ N andere waarschuwingen". Verschillende meldingen worden nooit samengevoegd: ook als de bron er één gedeelde tekst bij geeft (Miami: Rip Current Statement en Coastal Flood Advisory), blijft elke kaart met haar volledige officiële tekst staan. Alleen een identiek object (zelfde titel, einde en gebied) wordt één kaart.

De MeteoAlarm-feed per land kan groot zijn (Spanje: 3,5 MB, ruim 7 seconden). De route wacht hooguit 4 seconden en geeft anders het landbrede Atom-antwoord; de download loopt dan via waitUntil door. In caches.default komt een compacte kopie (alleen lopende waarschuwingen en de gebruikte velden; Spanje ongeveer 0,2 MB) die vijf minuten vers is en tot een kwartier bruikbaar blijft terwijl op de achtergrond een nieuwe wordt opgehaald. Die cache is per Cloudflare-datacenter.

Seizoenspagina's

Seizoenspagina's zoals /witte-kerst/ en /oud-en-nieuw/ hebben een vaste URL die ieder jaar terugkomt. Iedere pagina is alleen configuratie in scripts/seizoenspagina.config.js (datums, plaatsen, teksten); het sjabloon (scripts/generate-seizoenspaginas.js) en de browserlogica (scripts/seizoenspagina-runtime.js) zijn gedeeld. Buiten de 7-daagse verwachting toont de pagina alleen wanneer de verwachting verschijnt; daarbinnen haalt hij de echte Open-Meteo-verwachting op. Er is geen lange-termijnverwachting en geen klimaatstatistiek. De pagina's staan in de sitemap en als footerlink op iedere weerpagina.

Nachtzicht-pagina's

/nachtzicht/ zet de Nationale Parken op een rij (donkerste eerst), /nachtzicht/<park>/ toont per park de komende nachten en /maan/ de maanfase en de komende hoofdfasen. De parken en hun coördinaten staan in scripts/nachtzicht.config.js (Wikidata); een park doet alleen mee als de RIVM-lichtkaart (lichtvervuiling-nl.json) rond het park volledig is, waardoor parken aan de landsgrens ontbreken. De pagina's tonen exact de nachtscore, het oordeel en het kijkvenster van het blok Nachtzicht: scripts/nachtzicht-bron.js neemt bij de build de rekenfuncties en teksten letterlijk over uit de app (index.html, senior-correctness-v2.js, scripts/mobile-screenshot-polish.js, scripts/final-global-correctness-20260901.js, nederlandse-weergrammatica.js) en faalt als een anker verdwijnt. scripts/nachtzicht-pariteit-browser.test.js legt de pagina's naast de echte app; verander je Nachtzicht in de app, dan faalt die test tot de pagina's meegaan. De maanfasen op /maan/ volgen Meeus (Astronomical Algorithms). Een geopende pagina blijft kloppen: de uitkomst wordt per uur lokaal opnieuw berekend en de verwachting wordt hoogstens een uur oud gehouden (één gewone aanvraag, zonder betaalde reserve; bij een storing blijft het getoonde staan en meldt de regel "Verwachting van HH:MM" hoe oud het is); de uurwaarden van de parkgrafiek staan ook als uitklapbare tabel (zie scripts/nachtzicht-runtime.js). Seizoenspagina's verversen op dezelfde manier stil binnen dezelfde toestand.

Belangrijkste externe bronnen

Onderdeel	Bron
actuele, uur- en dagverwachting	Open-Meteo primair; Visual Crossing en WeatherAPI als server-side fallback
locatie zoeken	Open-Meteo Geocoding
luchtkwaliteit en pollen	Open-Meteo Air Quality (CAMS)
reverse geocoding	BigDataCloud, met Nominatim-compatible serverfallback
waarschuwingen VS	National Weather Service
waarschuwingen Europa	MeteoAlarm
kaartondergrond	CARTO / OpenStreetMap-attributie

Zon- en maanstanden worden lokaal berekend. Bronvermeldingen die leveranciers vereisen staan in de interface en mogen niet zonder inhoudelijke controle worden verwijderd.

Testen

De minimale lokale kwaliteitsketen is:

npm test

De Cloudflare-productiebuild is:

npm run build:cloudflare

De repository bevat daarnaast echte browsercontroles voor Chromium en WebKit, mobiele en desktopbreedtes, performance, neerslagrandgevallen, internationale locaties en serviceworker/offlinegedrag. Na iedere productiedeploy vergelijkt de wereldmonitor zes klimaatzones op mobiel en desktop met de Open-Meteo-respons waarmee de pagina werkelijk rendert. Een aparte live monitor meet in Chromium en WebKit de tijd tot zichtbare data en een bruikbare grafiek, het aantal externe verzoeken, dubbele forecastaanvragen, scroll/rendering en onverwachte Cloudflare Analytics-injectie. GitHub Actions is de uiteindelijke merge-eis; een wijziging hoort niet gemerged te worden op basis van alleen een lokale groene subset.

Belangrijke contracten die expliciet worden getest:

• ontbrekende waarden mogen niet stil 0 worden;
• neerslagkans en neerslaghoeveelheid blijven semantisch gescheiden;
• plaats- en tijdlogica gebruikt de tijdzone van de gekozen locatie;
• geocodingduplicaten worden generiek verwijderd zonder gelijknamige echte plaatsen samen te voegen;
• waarschuwingen zijn fail-closed wanneer plaatsdekking niet bewezen is;
• lange plaatsnamen mogen geen horizontale overflow veroorzaken;
• het definitieve artifact en de serviceworker-cacheversie moeten bij elkaar horen;
• statische en dynamische productie-responses houden hetzelfde securitycontract;
• API-cachegedrag gebruikt expliciet Cloudflare-CDN-Cache-Control;
• dezelfde kernfunctionaliteit wordt in Chromium en WebKit gecontroleerd.

Serviceworker en cache

De serviceworker-versie wordt tijdens de build afgeleid van de definitieve app-shell. Verhoog of wijzig daarom niet handmatig een cacheversie om een wijziging zichtbaar te krijgen. De gedeelde build- en postbuildhelpers vernieuwen en verifiëren de cachehash nadat het artifact is gewijzigd.

Werkwijze voor wijzigingen

Werk via een aparte branch en pull request. Houd wijzigingen klein en bewijsbaar:

1. oorzaak vaststellen;
2. plan bepalen;
3. broncode aanpassen;
4. relevante unit- en contracttests toevoegen of bijwerken;
5. volledige regressie- en browserketen draaien;
6. Cloudflare-preview controleren waar van toepassing;
7. pas na merge de Cloudflare-production-run en de publieke production-smoke controleren.

Weerformules, interpretatiebeleid, waarschuwing-scope en andere productregels horen niet als screenshotpatch of plaats-specifieke uitzondering te worden aangepast. Nieuwe oplossingen moeten generiek blijven voor huidige en toekomstige locaties.

Productie terugdraaien

Gebruik een rollback alleen bij een bewezen productiestoring of ernstige regressie. Productie hoort altijd herleidbaar te blijven tot een GitHub-SHA.

1. Leg de fout, het tijdstip en de actieve build-SHA vast. De productie-HTML bevat hiervoor weather-build-sha.
2. Bepaal de laatste bekende goede commit op main.
3. Maak een kleine revert-PR die de foutieve wijziging terugdraait. Omzeil de verplichte CI niet.
4. Na merge deployt Cloudflare production exact de nieuwe main-SHA naar Pages.
5. Verifieer daarna de WeatherNow production smoke: homepage, www-redirect, securityheaders, sitemap, kernroutes, API-contracten en de wereldwijde mobiel/desktopmatrix moeten groen zijn.

Verwijder oude Cloudflare Pages-deployments niet routinematig; immutable deployments blijven nuttig voor vergelijking en incidentanalyse.

Overdracht

Voor architectuur, accountgrenzen, secrets zonder geheime waarden, databronnen, deploy, monitoring, kostencontrole, incidentherstel en veelvoorkomende wijzigingen:

• Overdracht en beheer
• Sale-readiness audit van 31 augustus 2026