NetWatch is an MIT-licensed JavaScript single-page application by @sneak that provides real-time network latency monitoring to common internet hosts, displayed with color-coded figures and sparkline graphs, served from a static bucket or Docker container.

Getting Started

# Install dependencies
yarn install

# Development server
yarn dev

# Production build
yarn build

# Preview production build
yarn preview

# Docker
docker build -t netwatch .
docker run -p 8080:8080 netwatch

Entrypoints

This repository adheres to the Scripts to Rule Them All standard: normalized scripts in script/ are the entrypoints for the development workflow, and the Makefile targets are thin shims that call them.

The repo holds two projects: the frontend at the repo root and the Go backend in backend/, which has its own script/ directory and its own shim Makefile. The root scripts cover both, so make check at the root fails if either half is broken. We provide:

• script/bootstrap — install all dependencies, assuming nothing is present: pinned node via nvm if needed, yarn via corepack, yarn install --frozen-lockfile, and the backend's toolchain — Go (an already-installed Go is reused only when its version falls inside the window the pinned golangci-lint can analyse; a newer Go is ignored, not preferred) and golangci-lint at the version Dockerfile.backend pins. Everything not installed by the system package manager comes from a hash-verified release archive and is symlinked into ~/.local/bin, so make check works in a plain shell afterwards
• script/setup — make a fresh clone ready for development: bootstrap plus the git pre-commit hook
• script/projectname — print the project name (used for the Docker image tags)
• script/test — run the whole repo's tests: script/frontend-test, then backend/script/test
• script/lint — lint the whole repo: script/frontend-lint, then backend/script/lint
• script/fmt — format the whole repo (writes): script/frontend-fmt, then backend/script/fmt
• script/fmt-check — check formatting across the whole repo (read-only)
• script/check — run test, lint, and fmt-check; this is the repo-wide gate
• script/frontend-test — the frontend's test: the production build (no unit tests yet)
• script/frontend-lint — run prettier in check mode
• script/frontend-fmt — format everything prettier understands (writes)
• script/frontend-fmt-check — check prettier formatting (read-only)
• script/frontend-check — the frontend half of script/check, shimmed by make frontend-check and used by Dockerfile, whose build stage is a node image with no Go toolchain. Its mirror make backend-check shims to backend/script/check
• script/docker — build both images, tagged via script/projectname: netwatch from Dockerfile and netwatch-server from Dockerfile.backend
• script/cibuild — CI entrypoint: builds both images; the only build step in the Gitea workflow
• script/precommit — run by the git pre-commit hook; runs script/check, so a commit is gated on both halves of the repo
• script/install-precommit — install the git pre-commit hook; this is the repo's only pre-commit hook installer

The backend's scripts are shimmed by backend/Makefile and are also called by the root scripts above:

• backend/script/build — compile netwatch-server with version and architecture stamped in
• backend/script/test — run the Go tests under a 30-second timeout
• backend/script/lint — assert .golangci.yml still matches its pinned sha256, then run golangci-lint
• backend/script/fmt — format the Go sources (writes)
• backend/script/fmt-check — check Go formatting (read-only)
• backend/script/check — run the backend's test, lint, and fmt-check
• backend/script/run — build and run the server locally
• backend/script/clean — remove build artifacts

Rationale

When debugging network issues, it's useful to have a persistent at-a-glance view of latency and reachability to multiple well-known internet endpoints. NetWatch provides this as a zero-dependency SPA that can be deployed anywhere static files are served, with no backend required.

Design

The application is a single-page app built with Vite and Tailwind CSS v4. All code lives in src/main.js with a class-based architecture:

• CONFIG: Frozen configuration object (update interval, timeouts, axis ticks, etc.)
• HostState: Per-host state management — history buffer, latency tracking, status transitions
• AppState: Top-level state container — WAN hosts, local hosts, pause state, aggregate stats
• SparklineRenderer: Canvas 2D sparkline drawing with fixed axes, color-coded line segments, error regions, and DPR-aware scaling
• UI functions: buildUI() constructs the DOM, updateHostRow() / updateSummary() / updateHealthBox() handle incremental updates
• tick(): Main loop — measures all hosts in parallel via Promise.all, pushes samples, redraws UI. When paused, pushes blank markers (no probes, no false outage)

Monitoring targets

• 22 WAN hosts: datavi.be, Anthropic API, OpenAI API, AWS Console, GCP Console, Azure, Cloudflare, Fastly, Akamai, GitHub, B2, 7 S3 regional endpoints (Cape Town, London, Bahrain, Tokyo, Sydney, Oregon, São Paulo), 4 GCS locational endpoints (Iowa, Belgium, Singapore, Sydney)
• Local CPE: Cable modem at 192.168.100.1 (always monitored)
• Local Gateway: Auto-detected on startup by probing common default gateway addresses (192.168.1.1, 192.168.0.1, 192.168.8.1, 10.0.0.1); first responder wins. Note: modern browsers enforce Private Network Access restrictions that block public-origin pages from reaching RFC1918 addresses, so local targets only work when NetWatch is served from localhost or a private address.

Local hosts are tracked separately from WAN stats.

Latency measurement

HEAD requests with mode: 'no-cors' and cache: 'no-store', timed with performance.now(). 1-second timeout; anything over 1000ms is clamped to unreachable. IPv4 only.

Color coding

Latency	Color
< 50ms	Green
< 100ms	Lime
< 200ms	Yellow
< 500ms	Orange
>= 500ms	Red
Unreachable	Gray

Output structure

dist/
├── index.html
└── assets/
    ├── index-*.css
    └── index-*.js

Features

• Real-time monitoring with 2s update interval and 300s history sparklines
• Health indicator: green (HEALTHY) or red (DEGRADED) based on WAN reachability
• Summary stats: reachable count, min/max/avg latency across WAN hosts only
• Fixed chart axes: Y-axis 0–1000ms, X-axis 0–300s
• Color-coded latency figures and sparkline line segments
• Play/pause: pause stops probes but history keeps scrolling (blank gaps, no false outage)
• Clickable service URLs
• Canvas-based sparkline rendering with devicePixelRatio scaling
• Zero runtime dependencies: all resources bundled into build artifacts

Deployment

After running yarn build, deploy the contents of the dist/ directory to any static file host (S3, GCS, Cloudflare Pages, Vercel, Netlify, GitHub Pages) or use the Docker image behind a reverse proxy.

The Docker image:

• Listens on port 8080 by default (override with PORT env var)
• Trusts X-Forwarded-For from RFC1918 reverse proxies (10/8, 172.16/12, 192.168/16)
• Sends access logs to stdout
• Caches static assets with immutable headers

Browser Compatibility

Requires a modern browser with ES modules, Fetch API, Canvas API, and CSS custom properties.

Limitations

• CORS: Some hosts may block cross-origin HEAD requests. The app uses no-cors mode which allows the request but provides opaque responses. Latency is still measurable based on request timing.
• Local gateway: The 192.168.100.1 endpoint requires the host to be accessible from your network.
• Network conditions: Measurements reflect browser-to-endpoint latency, which includes your local network, ISP, and internet routing.

TODO

• Add unit tests
• Add eslint for JS linting (currently lint target runs prettier only)
• Add configurable host list (environment variable or config file)
• Add latency history export (CSV/JSON)
• Add notification/alert when status changes to DEGRADED

License

MIT. See LICENSE.

Author

@sneak