Local Development

Run the Worker and CLI from a clone of the repository so you can test routing changes before deploying them.

Why Use This Setup?

Runs the Worker from source so routing changes are testable without touching your live domain.
Simulates inbound mail locally so you can check how an alias, sender rule, or expiry behaves.
Runs the CLI from source so menu and command changes can be tried immediately.

Getting Started

bash

npm install
npm run dev

npm run dev starts the documentation site and runs wrangler dev for the Worker in parallel. The Worker listens on http://localhost:8787 unless that port is taken.

Config Resolution

The dev script looks for wrangler.toml in the project root and then in your platform config directory. If you have both, it asks which one to use.

When neither exists, it generates a wrangler.toml in the project root from the first config.json it finds there or in the config directory. The generated file points at the TypeScript source, so code changes reload without a build.

warning

A wrangler.toml left over from mm deploy points at the built package instead of the source. Delete it before running npm run dev if you want your source changes picked up.

Simulating Inbound Mail

Wrangler accepts test messages for email Workers at a local endpoint:

bash

curl --request POST 'http://localhost:8787/cdn-cgi/handler/email' \
  --url-query '[email protected]' \
  --url-query '[email protected]' \
  --header 'Content-Type: application/json' \
  --data-raw 'From: [email protected]
To: [email protected]
Subject: Local test

Hello from local development.'

The terminal running wrangler dev shows whether the message was forwarded or rejected, along with the reason.

Running the CLI From Source

bash

# Interactive menu
npm run manage

# Direct commands
npm run manage -- alias list

Checks Before a Pull Request

bash

npm run check
npm run build

npm run check runs linting, type checks, and tests across every workspace, including the routing tests in src/tests/worker/.