Local Development

Run the proxy locally for testing and development using npm run dev.

Starting the Dev Server

bash

npm run dev

This spawns wrangler dev with --local-upstream localhost. The worker is available at http://localhost:8787 (the port may vary if 8787 is in use).

From the repository root, npm run dev also starts the documentation site. To start only the worker, run npm run dev --workspace ntfy-reverse-proxy.

Config File Resolution

The dev script looks for config.json in this order and uses the first one it finds:

Project root.
XDG config directory (~/.config/ntfy-reverse-proxy/config.json on Linux/macOS).

If neither location has a config.json, the script stops with an error. Copy config.sample.json to config.json in the project root, configure it, and run the script again.

Wrangler.toml Generation

On every run, the dev script regenerates wrangler.toml next to the selected config.json and refreshes the bundled config and source-based Worker entry in .wrangler/ntfy-reverse-proxy/. Existing generated files are replaced, so both config and code changes are picked up without manual cleanup.

The local wrangler.toml has no KV namespace binding, so the Statuspage interpreter skips its duplicate check and component list in local tests.

Local Testing

Deployed requests pick their context by hostname: the first label is matched against context IDs. Locally, wrangler dev serves every request as localhost, so a local request names its context in the X-NRP-Context header instead.

HTTPS enforcement is skipped for localhost, so plain HTTP works:

bash

curl -X POST http://localhost:8787 \
  -H "X-NRP-Context: mycontext" \
  -H "Content-Type: text/plain" \
  -d "Test notification from local dev"

The header is only read for requests to localhost. Deployed requests ignore it and are always routed by hostname.

Environment Variables

CLOUDFLARE_API_TOKEN — Not required for local development.
.env — Not needed either, because the worker takes its settings from the bundled config.json, not from environment variables.