references/miniflare/gotchas.md
Miniflare Troubleshooting and Migrations
| Symptom or task | Check | |-----------------|-------| | TypeScript, bundled code, or imports fail to load | Custom builds and module rules | | Bindings from Wrangler configuration are missing | Interacting with bindings — direct Miniflare needs explicit configuration | | Tests disagree with Worker runtime behavior | Test runtime differences and compatibility dates | | Instances keep running, ports conflict, or request metadata is unexpected | Instance lifecycle and HTTP server — dispatching a request without HTTP does not mean the instance has no HTTP server | | Storage disappears or leaks across tests | Check the relevant storage configuration and the chosen test tool's persistence settings | | Breakpoints are needed with direct Miniflare | Attaching a debugger | | Upgrade a Miniflare 2 application | Migrate from version 2 | | Upgrade an existing Workers Vitest package | Migrate to Vitest plugin | | Replace unstable_dev tests | Migration guide and integration test harness |
For a migration, choose the target using the testing-tool decision before translating old options. A historical migration page describes that version transition; use current setup documentation for new test suites.