# WeatherStar 4000+ (ws4kp): a browser weather forecast with 90s Weather Channel graphics

> ws4kp rebuilds the look of the WeatherStar 4000 local forecast on top of NOAA's weather API. It is a small Node and browser app, not an emulator, and it only works for United States locations.

**netbymatt/ws4kp** — A web-based WeatherStar 4000. Instead, this project intends to create a simple to use interface with minimal configuration fuss.

- Repository: https://github.com/netbymatt/ws4kp
- Website: https://weatherstar.netbymatt.com
- Stars: 2,011 · Forks: 264
- Language: JavaScript
- License: MIT
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/netbymatt-ws4kp

## What ws4kp actually solves, and who it is for

The README is explicit that this is not a faithful reconstruction of the WeatherStar 4000, the box that generated the blue and orange local forecast segments on The Weather Channel in the 1990s. The author points anyone wanting accuracy to the WS4000 Simulator at taiganet.com. ws4kp takes the opposite trade: a simple interface with minimal configuration fuss. The stated motivation is nostalgia and an interest in following weather, particularly severe storms.

The practical audience is narrower than the visual style suggests. Anyone who wants a weather dashboard for a US address can run it, but the value is in the presentation layer: the retro screens, the travel cities style, the radar with an image timestamp. If you only want numbers, a plain weather API call is less work. If you want the look and you live outside the United States, this project is the wrong tool, and the README says so directly: it is tightly coupled to NOAA's weather API, which covers the US only, and it recommends the ws4kp-international fork by @mwood77 for international locations.

## How the forecast pipeline is put together

The architecture separates API code from user interface code, and that separation is the most interesting design decision in the repository. The forecast data comes from the api.weather.gov REST API. The README lists the techniques in use: ES6 arrow functions, promises, async/await with parallel loading of forecast resources, classes and extensions, and JavaScript modules. Date handling goes through luxon rather than hand-rolled parsing. Static assets and API responses are cached at practical rates.

Two deployment modes change where the requests originate. In server deployment, a Node.js process runs a caching proxy with server-side request deduplication and logging, which matters when several browsers sit behind one host. In static deployment, nginx serves pre-built files and every browser calls the weather services directly, relying on browser caching. The build pipeline is Gulp and Webpack for bundling, SASS for the hand-written CSS, and ESLint for style. The README notes the codebase was kept as library-free as possible so that people learning to program can read it, which is a reasonable reason to accept some of the hand-rolled structure.

## Install ws4kp with npm and open the first forecast

The Quick Start assumes Node is already installed. Clone the repository, install dependencies, and start the dev server:

```bash
git clone https://github.com/netbymatt/ws4kp.git
cd ws4kp
npm install
npm start
```

Then open the browser at the address the README gives, https://localhost:8080. That mode serves individual JavaScript modules with readable code and source maps, so the initial load issues many HTTP requests. If you want the minified bundles that load faster, build first and start with the DIST variable set:

```bash
npm run build
DIST=1 npm start
```

For a container instead of a local Node install, the default image is the static nginx build, with no server-side proxy:

```bash
docker run -p 8080:8080 ghcr.io/netbymatt/ws4kp
```

The server variant is built from Dockerfile.server and adds the caching proxy:

```bash
docker build -f Dockerfile.server -t ws4kp-server .
docker run -p 8080:8080 ws4kp-server
```

Configuration in the Docker Compose path is done by turning permalink URL arguments into environment variables prefixed with WSQS_. The README's compose example sets the location, hides hazards, and enables the current weather screen:

```yaml
services:
  ws4kp:
    image: ghcr.io/netbymatt/ws4kp
    environment:
      - WSQS_latLonQuery=Orlando International Airport Orlando FL USA
      - WSQS_hazards=false
      - WSQS_current_weather=true
    ports:
      - 8080:8080
```

One repository detail worth knowing before you script a deployment: the Dockerfile deletes dist/playlist.json from the build output before copying it into the image.

## United States only, and other limits worth knowing first

The geographic restriction is the hard boundary. NOAA's API is exclusive to the United States, and the README calls it a requirement for the experience the project is trying to deliver. There is no configuration flag that lifts this; the documented answer is to use a different fork.

A second limitation is upstream dependency. Every screen is a rendering of data fetched from api.weather.gov. If that service is slow or returns nothing for a location, ws4kp has no fallback provider, and the caching layer in server mode only helps with repeat requests, not with a failing upstream. The choice between deployment modes is therefore a real operational decision rather than a preference: static deployment pushes every client's requests straight to the weather service, while the server proxy deduplicates and caches them. On a shared network with several viewers, the static image is the more fragile option.

Finally, the README itself frames the emulation as approximate. Screen changes were made because more or less forecast information exists today than in the 1990s, and those differences are documented in sections of the README rather than presented as bugs. If pixel-accurate hardware reproduction is the goal, this is not that project.

## How ws4kp differs from the WS4000 Simulator

The WS4000 Simulator at taiganet.com is the alternative the README names, and the difference is one of intent rather than features. That project targets accuracy as a WeatherStar 4000 emulation. ws4kp targets a modern, low-configuration web app that borrows the visual language. In practice that means ws4kp is easier to stand up (npm start, or one docker run) and easier to modify, since the README describes the code as well commented and deliberately library-light. The simulator is the better answer if the point is fidelity to the original hardware.

The other alternative is the ws4kp-international fork, which exists for the same reason ws4kp cannot serve non-US users: the data source. Choosing between them is not a matter of taste. If your location is outside the United States, the fork is the only option the README offers.

## Maintenance, licence and upgrade cost

The repository is not archived, but the available record does not include a last push date, so there is no basis for describing the cadence of updates. Treat the release history as something to check on the repository page before you commit to running it, rather than something this article can vouch for.

The licence is MIT, which permits commercial and private use and modification, with the usual requirement to keep the licence and copyright notice. That is a permissive position, and for a self-hosted weather display it removes most distribution concerns. It is not legal advice; read LICENSE in the repository for the binding text.

Upgrade cost is mostly environmental. The project pins Node 24 in its build stage, and the dependency list includes gulp 5, eslint 10, luxon 3, metar-taf-parser 9 and p-limit 7, all of which move independently. Because the build produces a dist directory that the container copies into nginx, upgrading means rebuilding rather than pulling new source into a running server. The package.json test script is a stub that exits with an error, so there is no test suite to tell you whether an upgrade broke a screen. Plan on checking the rendered forecast after each bump.

## Conclusion

Adopt ws4kp if you want a self-hosted, retro-styled weather display for a US location and you are comfortable running Node or a container. Skip it if you need international coverage, since the README states the project is tightly coupled to NOAA's API and points to the ws4kp-international fork instead. Before deploying, verify two things: that your chosen location resolves through the WSQS_latLonQuery parameter, and that the deployment mode you pick (server proxy versus static nginx) matches how many clients will hit the upstream API.

## FAQ

### How did the WeatherStar 4000 work?

The README describes it as the hardware that produced the blue and orange graphics during The Weather Channel's local forecast in the 1990s. ws4kp is not a precise reproduction of that hardware; the README points to the WS4000 Simulator for a more accurate one.

### Is there a vintage weather app available?

ws4kp is one: a web app that renders a forecast in the style of The Weather Channel's 1990s local forecast. It can be run locally with npm start or as a Docker container, and a live version is hosted at weatherstar.netbymatt.com.

### Who made the WeatherStar 4000?

The README does not cover the history of the original hardware beyond describing it as the device behind The Weather Channel's local forecast graphics. It only credits the author of this project, Matt Walsh, in package.json.

### Is there any open source weather station software available?

ws4kp is open source under the MIT licence and displays forecasts from NOAA's weather API, but it is a forecast display rather than weather station software. The README does not describe collecting data from local sensors.

## Sources

- [Official documentation](https://weatherstar.netbymatt.com)
- [Official README](https://github.com/netbymatt/ws4kp#readme)
- [Project repository](https://github.com/netbymatt/ws4kp)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/netbymatt-ws4kp