Description
Existing documentation URL(s)
https://developers.cloudflare.com/queues/configuration/local-development/
What changes are you suggesting?
What changes are you suggesting?
The documentation currently states:
Wrangler does not yet support running separate producer and consumer Workers bound to the same Queue locally. To develop locally with Queues, you can temporarily put your consumer's queue() handler in the same Worker as your producer, so the same Worker acts as both a producer and consumer.
However, this may give the impression that separate Workers cannot be used locally at all. In practice, it is possible to run both producer and consumer Workers locally by specifying multiple configuration files when using wrangler dev. That said, since this relies on an experimental feature, I understand if it's not a good fit for the official docs — feel free to include or disregard as you see fit.
If the section were to be rewritten, it might look like this:
While Wrangler does not officially support running separate producer and consumer Workers bound to the same Queue locally, this setup can still be achieved by specifying multiple configuration files when using wrangler dev.
Note: Multiple configuration files are currently supported as an experimental feature.
For example, given the following directory structure:
project/
├── producer/
│ └── wrangler.jsonc
└── consumer/
└── wrangler.jsonc
From within the producer/ directory, the following command starts both Workers in a single wrangler dev session, allowing you to test Queue behavior without merging logic:
wrangler dev -c ./wrangler.jsonc -c ../consumer/wrangler.jsonc --persist-to .wrangler/stateThis clarification would help developers understand that local testing with separate Workers is possible, and avoid unnecessary merging of logic during development.
Why should the docs be changed?
The current documentation may give the false impression that local development with separate producer and consumer Workers is entirely unsupported. In practice, the method above provides a working solution, which can be useful for testing queue behavior without modifying deployment structure.
Without this clarification, developers may assume they have no choice but to merge producer and consumer logic into a single Worker for local testing — even if their production setup keeps them separate. While the workaround described above relies on an experimental feature, it can still help avoid unnecessary restructuring during development.
What is the expected outcome?
By updating the documentation to mention this workaround, developers can:
- Avoid the unnecessary effort of merging producer and consumer logic into a single Worker just for local testing.
- Test production-like architectures locally without deviation from production code.
Additional information
As discussed in this GitHub discussion, this approach is considered a workaround, and the ability to run multiple Workers in a single instance of wrangler dev may be an experimental feature.(Reference comment)
I wasn’t able to find any official documentation that clearly states when this behavior was introduced or whether it’s officially supported.