try-works/role-model / .agents/skills/cloudflare
cloudflare
UnverifiedComprehensive Cloudflare platform skill covering Workers, Pages, storage (KV, D1, R2), AI (Workers AI, Vectorize, Agents SDK), feature flags (Flagship), networking (Tunnel, Spectrum), security (WAF, DDoS), and infrastructure-as-code (Terraform, Pulumi). Use for any Cloudflare development task. Biases towards retrieval from Cloudflare docs over pre-trained knowledge.
references/miniflare/gotchas.md
View on GitHub# Gotchas & Troubleshooting
## Miniflare Limitations
**Not supported:**
- Analytics Engine (use mocks)
- Cloudflare Images/Stream
- Browser Rendering API
- Tail Workers
- Workers for Platforms (partial support)
**Behavior differences from production:**
- Runs workerd locally, not Cloudflare edge
- Storage is local (filesystem/memory), not distributed
- `Request.cf` is cached/mocked, not real edge data
- Performance differs from edge
- Caching implementation may vary slightly
## Common Errors
### "Cannot find module"
**Cause:** Module path wrong or `modulesRules` not configured
**Solution:**
```js
new Miniflare({
modules: true,
modulesRules: [{ type: "ESModule", include: ["**/*.js"] }],
});
```
### "Data not persisting"
**Cause:** Persist paths are files, not directories
**Solution:**
```js
kvPersist: "./data/kv", // Directory, not file
```
### "Cannot run TypeScript"
**Cause:** Miniflare doesn't transpile TypeScript
**Solution:** Build first with esbuild/tsc, then run compiled JS
### "`request.cf` is undefined"
**Cause:** CF data not configured
**Solution:**
```js
new Miniflare({ cf: true }); // Or cf: "./cf.json"
```
### "EADDRINUSE" port conflict
**Cause:** Multiple instances using same port
**Solution:** Use `dispatchFetch()` (no HTTP server) or `port: 0` for auto-assign
### "Durable Object not found"
**Cause:** Class export doesn't match config name
**Solution:**
```js
export class Counter {} // Must match
new Miniflare({ durableObjects: { COUNTER: "Counter" } });
```
## Debugging
**Enable verbose logging:**
```js
import { Log, LogLevel } from "miniflare";
new Miniflare({ log: new Log(LogLevel.DEBUG) });
```
**Chrome DevTools:**
```js
const url = await mf.getInspectorURL();
console.log(`DevTools: ${url}`); // Open in Chrome
```
**Inspect bindings:**
```js
const env = await mf.getBindings();
console.log(Object.keys(env));
```
**Verify storage:**
```js
const ns = await mf.getKVNamespace("TEST");
const { keys } = await ns.list();
```
## Best Practices
**✓ Do:**
- Use `dispatchFetch()` for tests (no HTTP server)
- In-memory storage for CI (omit persist options)
- New instances per test for isolation
- Type-safe bindings with interfaces
- `await mf.dispose()` in cleanup
**✗ Avoid:**
- HTTP server in tests
- Shared instances without cleanup
- Old compatibility dates (use 2026+)
## Migration Guides
### From Miniflare 2.x to 3+
Breaking changes in v3+:
| v2 | v3+ |
|----|-----|
| `getBindings()` sync | `getBindings()` returns Promise |
| `ready` is void | `ready` returns `Promise<URL>` |
| service-worker-mock | Built on workerd |
| Different options | Restructured constructor |
**Example migration:**
```js
// v2
const bindings = mf.getBindings();
mf.ready; // void
// v3+
const bindings = await mf.getBindings();
const url = await mf.ready; // Promise<URL>
```
### From unstable_dev to Miniflare
```js
// Old (deprecated)
import { unstable_dev } from "wrangler";
const worker = await unstable_dev("src/index.ts");
// New
import { Miniflare } from "miniflare";
const mf = new Miniflare({ scriptPath: "src/index.ts" });
```
### From Wrangler Dev
Miniflare doesn't auto-read `wrangler.toml`:
```js
// Translate manually:
new Miniflare({
scriptPath: "dist/worker.js",
compatibilityDate: "2026-01-01",
kvNamespaces: ["KV"],
bindings: { API_KEY: process.env.API_KEY },
});
```
## Resource Limits
| Limit | Value | Notes |
|-------|-------|-------|
| CPU time | 30s default | Configurable via `scriptTimeout` |
| Storage | Filesystem | Performance varies by disk |
| Memory | System dependent | No artificial limits |
| Request.cf | Cached/mocked | Not live edge data |
See [patterns.md](./patterns.md) for testing examples.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |