Aplikacja pokazuje bieżącą analizę IMGW Hybrid dla Polski, modelowe warunki bieżące Open-Meteo poza Polską, prognozę godzinową i 7-dniową, ostrzeżenia IMGW dla Polski, dane hydro oraz deterministyczne briefy pogodowe bez użycia zewnętrznego modelu AI.

Najważniejsze funkcje

Bieżące warunki: IMGW Hybrid w Polsce, Open-Meteo jako modelowe warunki bieżące poza Polską.
Prognoza modelowa 7 dni: IMGW ALARO dla Polski oraz Open-Meteo jako globalny provider i fallback.
Globalne wyszukiwanie miejscowości oraz opcjonalny wybór lokalizacji GPS.
Ostrzeżenia IMGW dla Polski z filtrowaniem meteo po powiecie TERYT, gdy lokalizacja go dostarcza.
Powiadomienia Web Push o nowych ostrzeżeniach, porannym briefie dnia i wieczornym briefie na jutro.
Widoki dashboardu, prognozy szczegółowej dnia, ostrzeżeń, hydro, stacji i ustawień.
PWA z manifestem, własnym service workerem i podstawowym fallbackiem offline.
Interfejs po polsku i angielsku.

Stack

Next.js App Router, React, TypeScript
Tailwind CSS
TanStack Query
Zustand
Framer Motion
Recharts
Lucide React
web-push
SQLite przez better-sqlite3 dla trwałego magazynu subskrypcji Web Push
własny service worker i manifest PWA

Szybki Start

Wymagany jest Node.js 20.9 lub nowszy.

npm install
npm run dev

Aplikacja będzie dostępna pod adresem http://localhost:3000.

Konfiguracja

Do podstawowego uruchomienia aplikacji pogodowej nie są potrzebne klucze API. Publiczne dane IMGW, Open-Meteo i Nominatim są pobierane przez route handlery Next.js.

Powiadomienia Web Push wymagają zmiennych środowiskowych:

WEB_PUSH_VAPID_PUBLIC_KEY=
WEB_PUSH_VAPID_PRIVATE_KEY=
WEB_PUSH_VAPID_SUBJECT=mailto:admin@example.com
NOTIFICATIONS_CRON_SECRET=
WTR_APP_URL=http://127.0.0.1:3000
WTR_DATABASE_PATH=./data/wtr.sqlite
NOTIFICATIONS_WARNING_INTERVAL_MINUTES=5
NOTIFICATIONS_BRIEF_INTERVAL_MINUTES=5
NOTIFICATIONS_MORNING_BRIEF_TIME=07:00
NOTIFICATIONS_TOMORROW_BRIEF_TIME=18:00

Przykład znajduje się w .env.example.

Komendy

Komenda	Opis
`npm run dev`	Uruchamia serwer deweloperski Next.js.
`npm run lint`	Uruchamia ESLint.
`npm run format`	Formatuje obsługiwane pliki przez Prettier.
`npm run format:check`	Sprawdza formatowanie Prettier bez zapisywania zmian.
`npm run test`	Uruchamia testy jednostkowe logiki pogodowej przez Vitest.
`npm run test:watch`	Uruchamia Vitest w trybie obserwowania zmian.
`npm run typecheck`	Uruchamia `tsc --noEmit`.
`npm run build`	Buduje aplikację produkcyjnie i uruchamia kontrolę TypeScript wykonywaną przez Next.js.
`npm run start`	Uruchamia zbudowaną aplikację.
`npm run notifications:worker`	Uruchamia self-hostowany worker powiadomień. Wymaga działającej aplikacji Next.js.

Testy jednostkowe korzystają z Vitest i obejmują kluczową logikę pogodową, m.in. briefy, jednostki, ikony prognozy oraz dopasowanie ostrzeżeń do regionu. Formatowanie jest obsługiwane przez Prettier.

CI

Repozytorium używa Gitea Actions. Workflow znajduje się w .gitea/workflows/ci.yml i uruchamia się przy pushu do main oraz przy pull requestach.

Pipeline działa na ubuntu-latest, instaluje zależności przez npm ci, a następnie uruchamia:

npm run lint,
npm run format:check,
npm run typecheck,
npm run test,
npm run build.

Na instancji Gitea musi być włączony Actions runner kompatybilny z etykietą ubuntu-latest.

CI jest ostateczną bramką jakości po pushu. Lokalnie dobieraj komendy proporcjonalnie do ryzyka zmiany: dokumentacja zwykle wymaga tylko przeglądu diffu, drobne zmiany UI nie wymagają rutynowego builda, a pełny zestaw lint, typecheck i build zostaw dla zmian wysokiego ryzyka.

Struktura Projektu

app/          routing, layout, route handlery i strony
components/   komponenty widoków, UI, stanów, prognozy, hydro i ostrzeżeń
hooks/        hooki TanStack Query
lib/          fetchery, normalizacja danych, Web Push, i18n, store i helpery
types/        typy danych IMGW, prognozy, lokalizacji i powiadomień
public/       manifest, service worker i ikony PWA
scripts/      worker powiadomień dla self-hostingu
docs/         szczegółowa dokumentacja techniczna

Dokumentacja

Status i Ograniczenia

lib/push-store.ts przechowuje subskrypcje Web Push i historię wysyłek w lokalnym SQLite. Na self-hostingu zadbaj o trwały katalog dla WTR_DATABASE_PATH i backup pliku bazy.
Oficjalne ostrzeżenia pogodowe i dane hydrologiczne są obsługiwane tylko dla Polski przez IMGW. Poza Polską aplikacja pokazuje prognozę modelową Open-Meteo i briefy bez oficjalnych alertów.
Endpoint IMGW Hybrid używany przez dashboard pochodzi z publicznego frontendu meteo.imgw.pl, a nie ze stabilnie opisanej dokumentacji danepubliczne.imgw.pl.
Publiczne API IMGW potrafi zwrócić 404 z komunikatem No products were found dla pustych list ostrzeżeń; aplikacja traktuje to jako brak ostrzeżeń.
Prognoza jest prognozą modelową, nie pomiarem IMGW. Bieżące pomiary, modelowe warunki bieżące i prognozy są w UI rozdzielane.