91 lines
4.0 KiB
Markdown
91 lines
4.0 KiB
Markdown
# wtr.
|
|
|
|
**Pogoda z danych IMGW. Prosto. Pięknie. Aktualnie.**
|
|
|
|
`wtr.` to nowoczesna pogodowa PWA dla Polski oparta o publiczne dane IMGW. Aplikacja prezentuje bieżące odczyty synoptyczne, stacje hydrologiczne oraz ostrzeżenia w spokojnym, mobilnym interfejsie z gradientami, kartami glassmorphism i subtelnymi animacjami.
|
|
|
|
Interfejs jest dostępny po polsku i angielsku. Wybrany język jest zapisywany lokalnie w przeglądarce. Oryginalne treści ostrzeżeń oraz nazwy stacji pochodzą bezpośrednio z API IMGW i nie są automatycznie tłumaczone.
|
|
|
|
## Stack
|
|
|
|
- Next.js z App Router i TypeScript
|
|
- Tailwind CSS oraz komponenty w stylu shadcn/ui
|
|
- Framer Motion
|
|
- Recharts
|
|
- Lucide React
|
|
- TanStack Query
|
|
- Zustand z trwałym stanem `localStorage`
|
|
- własny service worker, manifest i offline fallback
|
|
|
|
## Uruchomienie
|
|
|
|
Wymagany jest Node.js 20.9 lub nowszy.
|
|
|
|
```bash
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
Aplikacja będzie dostępna pod adresem `http://localhost:3000`.
|
|
|
|
Sprawdzenie jakości i build produkcyjny:
|
|
|
|
```bash
|
|
npm run lint
|
|
npm run build
|
|
npm run start
|
|
```
|
|
|
|
## Dane IMGW
|
|
|
|
Aplikacja korzysta wyłącznie z rzeczywistych publicznych danych IMGW:
|
|
|
|
- dane synoptyczne: `https://danepubliczne.imgw.pl/api/data/synop`
|
|
- pojedyncza stacja synoptyczna: `https://danepubliczne.imgw.pl/api/data/synop/id/{id}`
|
|
- dane hydrologiczne: `https://danepubliczne.imgw.pl/api/data/hydro/`
|
|
- ostrzeżenia meteorologiczne: `https://danepubliczne.imgw.pl/api/data/warningsmeteo`
|
|
- ostrzeżenia hydrologiczne: `https://danepubliczne.imgw.pl/api/data/warningshydro`
|
|
- dane meteorologiczne: `https://danepubliczne.imgw.pl/api/data/meteo/`
|
|
- lista produktów: `https://danepubliczne.imgw.pl/api/data/product`
|
|
|
|
Przeglądarka pobiera dane przez whitelistowane proxy w `app/api/imgw/[...path]/route.ts`. Pozwala to ujednolicić cache, błędy API i bezpiecznie obsłużyć hydro bez mixed content.
|
|
|
|
## Ograniczenia API
|
|
|
|
Publiczny endpoint synoptyczny IMGW udostępnia najnowszy pomiar, a nie pełną prognozę godzinową lub wielodniową i nie historię odczytów. `wtr.` nie generuje fikcyjnych prognoz. Widok stacji prezentuje aktualne parametry i jawnie opisany snapshot pomiarowy. Brakujące wartości są oznaczane jako `Brak danych`.
|
|
|
|
Czas aktualizacji parametrów hydrologicznych może się różnić. Interfejs pokazuje czas pomiaru, aby starsze odczyty nie wyglądały na bieżące.
|
|
|
|
## Struktura projektu
|
|
|
|
```text
|
|
app/ routing, layout, proxy IMGW, offline fallback
|
|
components/dashboard dashboard aplikacji
|
|
components/weather/ hero, stacje, metryki i szczegóły
|
|
components/warnings/ alerty meteo i hydro
|
|
components/hydro/ lista stacji hydrologicznych
|
|
components/ui/ bazowe komponenty interfejsu
|
|
components/states/ loading, empty i error states
|
|
hooks/ zapytania TanStack Query
|
|
lib/ API, normalizacja, helpery i stan
|
|
types/ typy danych IMGW
|
|
public/ manifest, ikony i service worker
|
|
```
|
|
|
|
## PWA i offline
|
|
|
|
Manifest znajduje się w `public/manifest.json`, a service worker w `public/sw.js`. Rejestracja service workera działa w buildzie produkcyjnym. Powłoka aplikacji ma podstawowy offline fallback. Odpowiedzi API mogą być dostępne z pamięci urządzenia przy braku sieci, ale UI nadal prezentuje czas pomiaru i status świeżości.
|
|
|
|
## Wdrożenie na Vercel
|
|
|
|
1. Umieść repozytorium w serwisie Git.
|
|
2. Importuj projekt do Vercel jako aplikację Next.js.
|
|
3. Nie dodawaj kluczy API: publiczne endpointy IMGW ich nie wymagają.
|
|
4. Wdróż standardowym poleceniem builda `npm run build`.
|
|
|
|
Proxy IMGW działa jako route handler Next.js i jest zgodne z hostingiem Vercel.
|
|
|
|
## Bezpieczeństwo zależności
|
|
|
|
Projekt używa stabilnego Next.js `16.2.6`. `npm audit --omit=dev` raportuje obecnie umiarkowane zgłoszenie `GHSA-qx2v-qp2m-jg93` dla PostCSS `8.4.31` bundlowanego bezpośrednio przez najnowszy Next.js. Główna konfiguracja projektu korzysta z poprawionego PostCSS `8.5.x`, ale wewnętrznej kopii Next.js nie należy ręcznie podmieniać. Po publikacji poprawki upstream należy zaktualizować Next.js i ponownie uruchomić audyt.
|