Wayfarer

A black-and-gold weather station: pixel-art skies, a heart-based comfort meter, hourly and 14-day forecasts you can switch between, an animated radar map, official alerts and air quality, and a switchable data source. Built with Next.js 16 (App Router), TypeScript, Tailwind CSS v4 and Leaflet.

Run it

npm install
cp .env.example .env.local   # add whichever keys you have
npm run dev                  # http://localhost:3000

With no keys at all, everything except the OpenWeather map layers still works, on Open-Meteo.

What it shows

Section	What's in it
Alerts	Official NWS watches and warnings for US places; provider alerts elsewhere (WeatherAPI only). Each opens to show the full text.
Hero	Temperature, conditions, today's high/low, a precipitation outlook for the next 24 h, comfort hearts.
Conditions	Feels like, dew point, humidity, wind with direction and gusts, UV index, air quality (US AQI + PM2.5), pressure, visibility, cloud cover, precipitation, sun times, moon phase.
Hourly	24 h / 48 h / 7-day chart (temperature, feels like, chance of precipitation) with a crosshair readout of any hour, or a full table.
Daily	Up to 14 days with a range bar per day. Tap a day for precipitation, wind, UV, humidity, sunrise, sunset and daylight.
Radar and maps	Animated radar (worldwide or high-detail US), plus OpenWeather precipitation, cloud, temperature, wind and pressure maps.

A reading a provider doesn't offer is simply hidden. Nothing shows a fake zero.

Providers and what each delivers

Provider	Env vars	Hourly	Daily	Notes
Open-Meteo	none	7 days, 1 h steps	14 days	Free, no key. The deepest data here.
OpenWeather	`OPENWEATHER_API_KEY`, `OPENWEATHER_PLAN`	5 days, 3 h steps	5 days	`free` plan. No dew point or UV.
		48 h, 1 h steps	8+ days	`onecall` plan (One Call 4.0). Separate subscription, 1,000 calls/day free.
WeatherAPI	`WEATHERAPI_API_KEY`, `WEATHERAPI_PLAN`	up to 3 days	3 days (14 paid)	Includes its own alerts.
Tomorrow.io	`TOMORROW_API_KEY`	5 days	6 days	Free plan: 25 calls/hour. Responses are cached for 10 minutes.

Every provider also gets these, from free sources:

Air quality and time zone: Open-Meteo's air-quality API (CAMS data), so the AQI scale is the same whichever provider you pick.
US alerts: the National Weather Service. Set NWS_CONTACT to an email or URL, because NWS asks apps to identify themselves.
Moon phase: calculated locally.

Radar sources

Layer	Source	Coverage	Frames	Limits
Radar	RainViewer	Worldwide	Last hour, 10-min steps	Max zoom 7, past frames only, personal/educational use only (since Jan 2026)
US radar	NWS NEXRAD via Iowa State IEM	US only	Last 50 min, 5-min steps	Shared academic service: fine for personal use, not for thousands of users
OpenWeather × 5	OpenWeather map tiles	Worldwide	Current only	Needs `OPENWEATHER_API_KEY`; tiles are proxied by `/api/tiles` so the key stays secret

US places open on the US radar layer automatically. The basemap is CARTO's dark style; set CARTO_API_KEY (free at carto.com/basemaps/apikey) so /api/tiles can strip CARTO's watermark while keeping the key server-side.

How it fits together

Browser                          Server (Next.js route handlers)               Outside
───────                          ───────────────────────────────               ───────
WeatherApp ── /api/providers ──▶ which keys exist + each plan's limits
           ── /api/geocode   ──▶ lib/weather/geocode.ts ─────────────────────▶ OpenWeather / Open-Meteo
           ── /api/weather   ──▶ in parallel:
                                   providers/<name>     (required)  ──────────▶ chosen provider
                                   extras/air-quality   (optional)  ──────────▶ Open-Meteo AQ
                                   extras/nws-alerts    (optional)  ──────────▶ api.weather.gov
RadarPanel ── /api/radar     ──▶ RainViewer frame index ─────────────────────▶ RainViewer
           ── /api/tiles/…   ──▶ OpenWeather + CARTO tile proxy ─────────────▶ OpenWeather / CARTO CDN
           ── NEXRAD + RainViewer tiles load straight from their servers (no keys involved)

If an optional source fails, its section just disappears; only a failed forecast shows an error.

lib/weather/types.ts: the one normalized shape. Units are metric, times are UTC, and missing readings are null.
lib/weather/providers/: one adapter per provider. OpenWeather has a folder with free.ts and onecall.ts.
lib/weather/extras/: air quality and NWS alerts.
lib/radar/layers.ts: every map layer and how to load its frames.
lib/display.ts: unit conversion, time-zone-aware formatting, UV/AQI labels, moon phase, precipitation outlook.
components/forecast/: ForecastPanel (the switch), HourlyView + HourlyChart, DailyView.
components/radar/: RadarPanel (controls) and RadarMap (Leaflet, browser-only).
components/ui/ChoiceChips.tsx: the chip group used for providers, views, ranges and map layers.

Adding a provider

Write lib/weather/providers/foo.ts exporting a WeatherProvider, with getForecast() and limits().
Add "foo" to ProviderId in types.ts.
Register it in providers/index.ts, then add its key to .env.example.

Styling (Tailwind v4)

There is no tailwind.config.js; v4 is configured in CSS.

app/globals.css holds the theme tokens in @theme. Colors like --color-gold become bg-gold, text-gold and so on, and the fonts become font-display, font-pixel and font-sans. It also holds one custom utility, chamfer (the cut corners), Leaflet control overrides, and a few base rules.
Every other style is a utility class in the component that uses it. Layout is mobile-first, with sm: (640px and up) for the desktop arrangement.
lib/styles.ts holds the class strings used by more than one component.
To resize a frame's corners, add [--cut:22px] to that Slot's className. Put fixed heights on the Slot itself, not its inner element, which is already h-full.
The Leaflet overrides sit outside any @layer and are prefixed with .leaflet-container. Leaflet's own CSS is unlayered and loads later, so anything weaker loses.
The hourly chart is hand-written SVG with no chart library. Temperature and chance of precipitation sit in separate bands on one time axis rather than sharing two y-axes.

Mobile

Uses viewport-fit=cover with safe-area insets, 44px tap targets and 16px inputs (so iOS doesn't zoom on focus).
Chips, the hourly chart and the forecast strip scroll sideways; the page itself never does.
The map ignores the scroll wheel, so scrolling the page doesn't zoom it; use pinch or the +/− buttons.
"Use my location" requires HTTPS on phones. To test on your Android over LAN, use a Vercel preview deploy.
Radar autoplay and the floating icon stop when the OS asks for reduced motion.

Deploy & Legal Compliance

Vercel: import the repo and add your environment variables (OPENWEATHER_API_KEY, CARTO_API_KEY, NWS_CONTACT, plus any optional provider keys) in Project Settings.
PM2: npm run build && pm2 start npm --name wayfarer -- start.
CARTO domain lock: once deployed, restrict CARTO_API_KEY to your production domain at dashboard.basemaps.carto.com. All /api/* routes also reject cross-site Sec-Fetch-Site: cross-site hotlinking automatically.
Built-in attributions: SiteFooter, PlaceSearch, AlertsBanner, and RadarMap render the required live backlinks and license credits for OpenWeather (CC BY-SA 4.0 / ODbL), Open-Meteo (CC BY 4.0), Copernicus Atmosphere Monitoring Service (CAMS), GeoNames (CC BY 4.0), WeatherAPI.com, Tomorrow.io, OpenStreetMap, CARTO, RainViewer, Iowa State IEM, and NOAA/NWS.
Non-commercial vs. commercial publishing:
- Free, ad-free personal / portfolio site: compliant across every source out of the box.
- Commercial site (ads, paid tiers, or business use): OpenWeather, WeatherAPI.com, NWS, and CARTO (CARTO_API_KEY includes 1M commercial tiles/month) permit commercial use within plan quotas, whereas Open-Meteo (forecast, geocoding, air quality), RainViewer, and Tomorrow.io free tiers are non-commercial only and require paid commercial plans or disabling before monetizing.

10 KiB Raw Blame History Unescape Escape