Skip to content

fcakyon/claude-codex-settings / plugins/cloudflare-skills/skills/cloudflare-deploy

cloudflare-deploy

Verified

Discover and choose Cloudflare products for apps, APIs, AI agents, storage, networking, and security. Use for architecture and product selection, including when the user describes a need without naming a Cloudflare product; then find the relevant skill or documentation.

FileKindSize
SKILL.mdskill md26.7 KB
references/ai-gateway/README.mdmarkdown1.9 KB
references/ai-gateway/configuration.mdmarkdown2.2 KB
references/ai-gateway/dynamic-routing.mdmarkdown1.9 KB
references/ai-gateway/features.mdmarkdown2.6 KB
references/ai-gateway/sdk-integration.mdmarkdown2.2 KB
references/ai-gateway/troubleshooting.mdmarkdown2.5 KB
references/ai-search/README.mdmarkdown1.8 KB
references/ai-search/api.mdmarkdown1.3 KB
references/ai-search/configuration.mdmarkdown1.8 KB
references/ai-search/gotchas.mdmarkdown1.6 KB
references/ai-search/patterns.mdmarkdown1.7 KB
references/bindings/README.mdmarkdown1.3 KB
references/bindings/api.mdmarkdown2.4 KB
references/bindings/configuration.mdmarkdown2.5 KB
references/bindings/gotchas.mdmarkdown3.0 KB
references/bindings/patterns.mdmarkdown2.4 KB
references/browser-rendering/README.mdmarkdown1.2 KB
references/browser-rendering/api.mdmarkdown1.2 KB
references/browser-rendering/configuration.mdmarkdown1.3 KB
references/browser-rendering/gotchas.mdmarkdown1.9 KB
references/browser-rendering/patterns.mdmarkdown1.5 KB
references/c3/README.mdmarkdown3.6 KB
references/c3/api.mdmarkdown2.2 KB
references/c3/configuration.mdmarkdown1.6 KB
references/c3/gotchas.mdmarkdown2.3 KB
references/c3/patterns.mdmarkdown2.1 KB
references/containers/README.mdmarkdown1.9 KB
references/containers/api.mdmarkdown1.6 KB
references/containers/configuration.mdmarkdown1.8 KB
references/containers/gotchas.mdmarkdown2.4 KB
references/containers/patterns.mdmarkdown2.5 KB
references/cron-triggers/README.mdmarkdown1.5 KB
references/cron-triggers/api.mdmarkdown1.7 KB
references/cron-triggers/configuration.mdmarkdown1.7 KB
references/cron-triggers/gotchas.mdmarkdown2.3 KB
references/cron-triggers/patterns.mdmarkdown2.0 KB
references/d1/README.mdmarkdown1.4 KB
references/d1/api.mdmarkdown1.9 KB
references/d1/configuration.mdmarkdown1.9 KB
references/d1/gotchas.mdmarkdown2.2 KB
references/d1/patterns.mdmarkdown2.2 KB
references/hyperdrive/README.mdmarkdown2.1 KB
references/hyperdrive/api.mdmarkdown3.1 KB
references/hyperdrive/configuration.mdmarkdown3.2 KB
references/hyperdrive/gotchas.mdmarkdown3.4 KB
references/hyperdrive/patterns.mdmarkdown2.7 KB
references/images/README.mdmarkdown983 B
references/images/api.mdmarkdown1.6 KB
references/images/configuration.mdmarkdown2.1 KB
references/images/gotchas.mdmarkdown2.2 KB
references/images/patterns.mdmarkdown1.8 KB
references/kv/README.mdmarkdown1.5 KB
references/kv/api.mdmarkdown1.8 KB
references/kv/configuration.mdmarkdown1.7 KB
references/kv/gotchas.mdmarkdown2.4 KB
references/kv/patterns.mdmarkdown2.9 KB
references/miniflare/README.mdmarkdown1.6 KB
references/miniflare/api.mdmarkdown1.8 KB
references/miniflare/configuration.mdmarkdown2.1 KB
references/miniflare/gotchas.mdmarkdown2.3 KB
references/miniflare/patterns.mdmarkdown2.2 KB
references/observability/README.mdmarkdown2.5 KB
references/observability/api.mdmarkdown2.2 KB
references/observability/configuration.mdmarkdown2.5 KB
references/observability/gotchas.mdmarkdown3.7 KB
references/observability/patterns.mdmarkdown3.0 KB
references/pages-functions/README.mdmarkdown1.3 KB
references/pages-functions/api.mdmarkdown1.1 KB
references/pages-functions/configuration.mdmarkdown1.3 KB
references/pages-functions/gotchas.mdmarkdown1.6 KB
references/pages-functions/patterns.mdmarkdown1.4 KB
references/pages/README.mdmarkdown1.5 KB
references/pages/api.mdmarkdown1.1 KB
references/pages/configuration.mdmarkdown1.5 KB
references/pages/gotchas.mdmarkdown1.7 KB
references/pages/patterns.mdmarkdown1.2 KB
references/queues/README.mdmarkdown1.8 KB
references/queues/api.mdmarkdown1.8 KB
references/queues/configuration.mdmarkdown2.3 KB
references/queues/gotchas.mdmarkdown2.8 KB
references/queues/patterns.mdmarkdown2.6 KB
references/r2/README.mdmarkdown1.7 KB
references/r2/api.mdmarkdown1.7 KB
references/r2/configuration.mdmarkdown2.2 KB
references/r2/gotchas.mdmarkdown3.3 KB
references/r2/patterns.mdmarkdown2.2 KB
references/secrets-store/README.mdmarkdown1.8 KB
references/secrets-store/api.mdmarkdown1.9 KB
references/secrets-store/configuration.mdmarkdown2.4 KB
references/secrets-store/gotchas.mdmarkdown2.8 KB
references/secrets-store/patterns.mdmarkdown3.0 KB
references/skill-feedback.mdmarkdown2.7 KB
references/smart-placement/README.mdmarkdown5.0 KB
references/smart-placement/api.mdmarkdown5.4 KB
references/smart-placement/configuration.mdmarkdown6.0 KB
references/smart-placement/gotchas.mdmarkdown5.5 KB
references/smart-placement/patterns.mdmarkdown5.6 KB
references/static-assets/README.mdmarkdown1.7 KB
references/static-assets/api.mdmarkdown1.7 KB
references/static-assets/configuration.mdmarkdown2.1 KB
references/static-assets/gotchas.mdmarkdown2.7 KB
references/static-assets/patterns.mdmarkdown2.2 KB
references/stream/README.mdmarkdown1.8 KB
references/stream/api-live.mdmarkdown2.1 KB
references/stream/api.mdmarkdown2.4 KB
references/stream/configuration.mdmarkdown2.0 KB
references/stream/gotchas.mdmarkdown2.3 KB
references/stream/patterns.mdmarkdown2.3 KB
references/tail-workers/README.mdmarkdown1.4 KB
references/tail-workers/api.mdmarkdown1.4 KB
references/tail-workers/configuration.mdmarkdown1.4 KB
references/tail-workers/gotchas.mdmarkdown1.6 KB
references/tail-workers/patterns.mdmarkdown1.5 KB
references/tunnel/README.mdmarkdown1.5 KB
references/tunnel/api.mdmarkdown1.3 KB
references/tunnel/configuration.mdmarkdown1.3 KB
references/tunnel/gotchas.mdmarkdown1.5 KB
references/tunnel/networking.mdmarkdown1.5 KB
references/tunnel/patterns.mdmarkdown1.5 KB
references/vectorize/README.mdmarkdown2.1 KB
references/vectorize/api.mdmarkdown2.1 KB
references/vectorize/configuration.mdmarkdown2.1 KB
references/vectorize/gotchas.mdmarkdown2.4 KB
references/vectorize/patterns.mdmarkdown2.6 KB
references/waf/README.mdmarkdown1.6 KB
references/waf/api.mdmarkdown2.0 KB
references/waf/configuration.mdmarkdown1.9 KB
references/waf/gotchas.mdmarkdown2.3 KB
references/waf/patterns.mdmarkdown1.9 KB
references/workers-ai/README.mdmarkdown1.8 KB
references/workers-ai/api.mdmarkdown1.3 KB
references/workers-ai/configuration.mdmarkdown1.6 KB
references/workers-ai/gotchas.mdmarkdown1.9 KB
references/workers-ai/patterns.mdmarkdown1.7 KB
references/workflows/README.mdmarkdown1.8 KB
references/workflows/api.mdmarkdown1.8 KB
references/workflows/configuration.mdmarkdown2.0 KB
references/workflows/gotchas.mdmarkdown2.8 KB
references/workflows/patterns.mdmarkdown2.7 KB

references/smart-placement/gotchas.md

View on GitHub
# Smart Placement Gotchas

## Common Errors

### "INSUFFICIENT_INVOCATIONS"

**Cause:** Not enough traffic for Smart Placement to analyze
**Solution:**
- Ensure Worker receives consistent global traffic
- Wait longer (analysis takes up to 15 minutes)
- Send test traffic from multiple global locations
- Check Worker has fetch event handler

### "UNSUPPORTED_APPLICATION"

**Cause:** Smart Placement made Worker slower rather than faster
**Reasons:**
- Worker doesn't make backend calls (runs faster at edge)
- Backend calls are cached (network latency to user more important)
- Backend service has good global distribution
- Worker serves static assets or Pages content

**Solutions:**
- Disable Smart Placement: `{ "placement": { "mode": "off" } }`
- Review whether Worker actually benefits from Smart Placement
- Consider caching strategy to reduce backend calls
- For Pages/Assets Workers, use separate backend Worker with Smart Placement

### "No request duration metrics"

**Cause:** Smart Placement not enabled, insufficient time passed, insufficient traffic, or analysis incomplete
**Solution:**
- Ensure Smart Placement enabled in config
- Wait 15+ minutes after deployment
- Verify Worker has sufficient traffic
- Check `placement_status` is `SUCCESS`

### "cf-placement header missing"

**Cause:** Smart Placement not enabled, beta feature removed, or Worker not analyzed yet
**Solution:** Verify Smart Placement enabled, wait for analysis (15min), check if beta feature still available

## Pages/Assets + Smart Placement Performance Degradation

**Problem:** Static assets load 2-5x slower when Smart Placement enabled with `run_worker_first = true`.

**Cause:** Smart Placement routes ALL requests (including static assets like HTML, CSS, JS, images) to remote locations. Static content should ALWAYS be served from edge closest to user.

**Solution:** Split into separate Workers OR disable Smart Placement:
```jsonc
// ❌ BAD - Assets routed away from user
{
  "name": "pages-app",
  "placement": { "mode": "smart" },
  "assets": { "run_worker_first": true }
}

// ✅ GOOD - Assets at edge, API optimized
// frontend/wrangler.jsonc
{
  "name": "frontend",
  "assets": { "run_worker_first": true }
  // No placement field - stays at edge
}

// backend/wrangler.jsonc
{
  "name": "backend-api",
  "placement": { "mode": "smart" }
}
```

This is one of the most common and impactful Smart Placement misconfigurations.

## Monolithic Full-Stack Worker

**Problem:** Frontend and backend logic in single Worker with Smart Placement enabled.

**Cause:** Smart Placement optimizes for backend latency but increases user-facing response time.

**Solution:** Split into two Workers:
```jsonc
// frontend/wrangler.jsonc
{
  "name": "frontend",
  "placement": { "mode": "off" },  // Explicit: stay at edge
  "services": [{ "binding": "BACKEND", "service": "backend-api" }]
}

// backend/wrangler.jsonc
{
  "name": "backend-api",
  "placement": { "mode": "smart" },
  "d1_databases": [{ "binding": "DB", "database_id": "xxx" }]
}
```

## Local Development Confusion

**Issue:** Smart Placement doesn't work in `wrangler dev`.

**Explanation:** Smart Placement only activates in production deployments, not local development.

**Solution:** Test Smart Placement in staging environment: `wrangler deploy --env staging`

## Baseline Traffic & Analysis Time

**Note:** Smart Placement routes 1% of requests WITHOUT optimization for comparison (expected).

**Analysis time:** Up to 15 minutes. During analysis, Worker runs at edge. Monitor `placement_status`.

## RPC Methods Not Affected (Critical Limitation)

**Problem:** Enabled Smart Placement on backend but RPC calls still slow.

**Cause:** Smart Placement ONLY affects `fetch` handlers. RPC methods (Service Bindings with `WorkerEntrypoint`) are NEVER affected.

**Why:** RPC bypasses `fetch` handler - Smart Placement can only route `fetch` requests.

**Solution:** Convert to fetch-based Service Bindings:

```typescript
// ❌ RPC - Smart Placement has NO EFFECT
export class BackendRPC extends WorkerEntrypoint {
  async getData() {
    // ALWAYS runs at edge
    return await this.env.DATABASE.prepare('SELECT * FROM table').all();
  }
}

// ✅ Fetch - Smart Placement WORKS
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    // Runs close to DATABASE when Smart Placement enabled
    const data = await env.DATABASE.prepare('SELECT * FROM table').all();
    return Response.json(data);
  }
}
```

## Requirements

- **Wrangler 2.20.0+** required
- **Consistent multi-region traffic** needed for analysis
- **Only affects fetch handlers** - RPC methods and named entrypoints not affected

## Limits

| Resource/Limit | Value | Notes |
|----------------|-------|-------|
| Analysis time | Up to 15 minutes | After enabling |
| Baseline traffic | 1% | Routed without optimization |
| Min Wrangler version | 2.20.0+ | Required |
| Traffic requirement | Multi-region | Consistent needed |

## Disabling Smart Placement

```jsonc
{ "placement": { "mode": "off" } }  // Explicit disable
// OR remove "placement" field entirely (same effect)
```

Both behaviors identical - Worker runs at edge closest to user.

## When NOT to Use Smart Placement

- Workers serving only static content or cached responses
- Workers without significant backend communication
- Pure edge logic (auth checks, redirects, simple transformations)
- Workers without fetch event handlers
- Pages/Assets Workers with `run_worker_first = true`
- Workers using RPC methods instead of fetch handlers

These scenarios won't benefit and may perform worse with Smart Placement.
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: 471kUpdated Claude CodeCodexVerifiedInstall
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: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall