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
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:
curl --request POST 'http://localhost:8787/cdn-cgi/handler/email' \
--url-query 'from=sender@shop.com' \
--url-query 'to=velvet-harbor-42@mail.example.com' \
--header 'Content-Type: application/json' \
--data-raw 'From: sender@shop.com
To: velvet-harbor-42@mail.example.com
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
# Interactive menu
npm run manage
# Direct commands
npm run manage -- alias list
Checks Before a Pull Request
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/.