A compact Homepage header widget backed by the official US National Weather Service API.
It shows the current temperature, the next high/low pair, current forecast conditions, humidity, precipitation probability, wind, and whichever comes next: sunrise or sunset. It requires no account or API key and serves its artwork locally.
The glance/ directory contains a server-rendered Glance custom-api port with the same forecast data and artwork. It includes responsive installation instructions and an optional equal-height, tunable-width layout for placing server uptime, weather, and clock widgets in one row.
- Official NWS forecast data from
api.weather.gov - No API key, proxy service, or third-party weather account
- Automatic latitude/longitude to NWS grid discovery
- Cached grid metadata and forecast data for quick reloads
- One self-hosted PNG sprite with day, night, cloud, precipitation, and metric artwork
- Flat, responsive styling designed for Homepage's header
- Configurable placement, colors, units, refresh timing, and DOM target
- Graceful cached fallback when the NWS endpoint is temporarily slow or unavailable
- A recent Homepage release with
custom.jssupport - A location covered by the US National Weather Service
- Latitude and longitude for that location
- Browser access to
https://api.weather.gov
Copy these files into your Homepage config directory:
nws-weather.js
weather-icons.png
For example:
cp nws-weather.js weather-icons.png /path/to/homepage/config/Homepage only exposes designated files from /app/config, so add two read-only mounts to the Homepage service:
services:
homepage:
volumes:
- /path/to/homepage/config:/app/config
- /path/to/homepage/config/nws-weather.js:/app/public/nws-weather.js:ro
- /path/to/homepage/config/weather-icons.png:/app/public/weather-icons.png:roA complete example is in examples/compose.yaml.
Add this after any existing code in your Homepage custom.js, replacing the example coordinates:
window.HOMEPAGE_NWS_WEATHER = {
latitude: 39.7456,
longitude: -97.0892,
locationLabel: "Home",
};
(() => {
if (document.querySelector('script[data-homepage-nws-weather]')) return;
const script = document.createElement("script");
script.src = "/nws-weather.js?v=0.1.4";
script.defer = true;
script.dataset.homepageNwsWeather = "true";
document.head.appendChild(script);
})();See examples/custom.js for the same loader as a standalone file.
docker compose up -d --force-recreate homepageRefresh Homepage. The widget is inserted before the right-aligned date/time widget and centered in the available space by default.
Set window.HOMEPAGE_NWS_WEATHER before loading nws-weather.js.
| Option | Default | Description |
|---|---|---|
latitude |
required | Latitude from -90 to 90 |
longitude |
required | Longitude from -180 to 180 |
locationLabel |
NWS city/state | Accessible location label and loading text |
timeZone |
NWS location | IANA time zone used to display sunrise and sunset; normally discovered automatically |
units |
"us" |
NWS unit system: "us" or "si" |
position |
"center" |
Placement inside the target: "start", "center", or "end" |
targetSelector |
"#information-widgets-right" |
Element that receives the widget |
linkTarget |
"_blank" |
Target used when opening the detailed NWS forecast |
background |
"#eaf7fb" |
Widget background color |
border |
"#367b98" |
Widget border and focus color |
text |
"#173652" |
Widget text color |
refreshMinutes |
30 |
Successful forecast refresh interval; minimum 5 minutes |
retryMinutes |
5 |
Retry interval after a failed request; minimum 1 minute |
requestTimeoutSeconds |
75 |
Per-request timeout; minimum 5 seconds |
endpointCacheDays |
7 |
NWS grid metadata lifetime; minimum 1 day |
weatherCacheMinutes |
360 |
Maximum forecast cache age; minimum 15 minutes |
spriteUrl |
next to the script | Alternate icon sprite URL |
detailsUrl |
generated from coordinates | Alternate click-through URL |
forecastUrl |
discovered from NWS | Advanced override for testing or a fixed grid |
hourlyUrl |
discovered from NWS | Advanced override for testing or a fixed grid |
Example with custom colors:
window.HOMEPAGE_NWS_WEATHER = {
latitude: 39.7456,
longitude: -97.0892,
locationLabel: "Home",
position: "center",
background: "#edf8fb",
border: "#2f7896",
text: "#173652",
};The browser stores two small JSON entries in localStorage:
- The NWS grid endpoints are refreshed weekly. NWS recommends periodically refreshing them because an office or grid assignment can occasionally change.
- A successful forecast is cached for up to six hours by default and appears immediately on reload while fresh data is requested.
If a refresh fails, the last valid cached forecast remains visible and the widget retries quietly.
The repository has a dependency-free demo using local forecast fixtures:
python3 -m http.server 8088Then open http://localhost:8088/demo/.
The icon sheet is a 4-by-3 grid. If its artwork changes, normalize every icon's visible vertical bounds with the dependency-free maintenance script:
python3 tools/normalize_sprite.py weather-icons.png weather-icons.pngThe operation is idempotent, so a second pass reports zero movement for every cell.
Nothing appears
- Confirm both files return HTTP 200 at
/nws-weather.jsand/weather-icons.png. - Check that the configuration is defined before the loader runs.
- Recreate the Homepage container after adding new bind mounts.
- Look for messages prefixed with
homepage-nws-weatherin the browser console.
The widget says “Forecast unavailable”
- Confirm the coordinates are inside NWS coverage.
- Confirm the browser—not only the Homepage container—can reach
api.weather.govover HTTPS. - NWS responses can occasionally be slow; the default request timeout is intentionally 75 seconds.
Changes do not appear
- Increment the query string on
/nws-weather.js?v=...to bypass browser cache.
This is an unofficial community add-on and is not affiliated with Homepage, NOAA, or the National Weather Service. Forecast data comes from the NWS API. The included weather sprite is original artwork created for this project.



