davila7/claude-code-templates / cli-tool/components/skills/development/cloudflare-deploy
cloudflare-deploy
FlaggedDeploy applications and infrastructure to Cloudflare using Workers, Pages, and related platform services. Use when the user asks to deploy, host, publish, or set up a project on Cloudflare.
references/smart-placement/api.md
View on GitHub# Smart Placement API
## Placement Status API
Query Worker placement status via Cloudflare API:
```bash
curl -X GET "https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/workers/services/{WORKER_NAME}" \
-H "Authorization: Bearer <TOKEN>" \
-H "Content-Type: application/json"
```
Response includes `placement_status` field:
```typescript
type PlacementStatus =
| undefined // Not yet analyzed
| 'SUCCESS' // Successfully optimized
| 'INSUFFICIENT_INVOCATIONS' // Not enough traffic
| 'UNSUPPORTED_APPLICATION'; // Made Worker slower (reverted)
```
## Status Meanings
**`undefined` (not present)**
- Worker not yet analyzed
- Always runs at default edge location closest to user
**`SUCCESS`**
- Analysis complete, Smart Placement active
- Worker runs in optimal location (may be edge or remote)
**`INSUFFICIENT_INVOCATIONS`**
- Not enough requests to make placement decision
- Requires consistent multi-region traffic
- Always runs at default edge location
**`UNSUPPORTED_APPLICATION`** (rare, <1% of Workers)
- Smart Placement made Worker slower
- Placement decision reverted
- Always runs at edge location
- Won't be re-analyzed until redeployed
## cf-placement Header (Beta)
Smart Placement adds response header indicating routing decision:
```typescript
// Remote placement (Smart Placement routed request)
"cf-placement: remote-LHR" // Routed to London
// Local placement (default edge routing)
"cf-placement: local-EWR" // Stayed at Newark edge
```
Format: `{placement-type}-{IATA-code}`
- `remote-*` = Smart Placement routed to remote location
- `local-*` = Stayed at default edge location
- IATA code = nearest airport to data center
**Warning:** Beta feature, may be removed before GA.
## Detecting Smart Placement in Code
**Note:** `cf-placement` header is a beta feature and may change or be removed.
```typescript
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const placementHeader = request.headers.get('cf-placement');
if (placementHeader?.startsWith('remote-')) {
const location = placementHeader.split('-')[1];
console.log(`Smart Placement routed to ${location}`);
} else if (placementHeader?.startsWith('local-')) {
const location = placementHeader.split('-')[1];
console.log(`Running at edge location ${location}`);
}
return new Response('OK');
}
} satisfies ExportedHandler<Env>;
```
## Request Duration Metrics
Available in Cloudflare dashboard when Smart Placement enabled:
**Workers & Pages → [Your Worker] → Metrics → Request Duration**
Shows histogram comparing:
- Request duration WITH Smart Placement (99% of traffic)
- Request duration WITHOUT Smart Placement (1% baseline)
**Request Duration vs Execution Duration:**
- **Request duration:** Total time from request arrival to response delivery (includes network latency)
- **Execution duration:** Time Worker code actively executing (excludes network waits)
Use request duration to measure Smart Placement impact.
### Interpreting Metrics
| Metric Comparison | Interpretation | Action |
|-------------------|----------------|--------|
| WITH < WITHOUT | Smart Placement helping | Keep enabled |
| WITH ≈ WITHOUT | Neutral impact | Consider disabling to free resources |
| WITH > WITHOUT | Smart Placement hurting | Disable with `mode: "off"` |
**Why Smart Placement might hurt performance:**
- Worker primarily serves static assets or cached content
- Backend services are globally distributed (no single optimal location)
- Worker has minimal backend communication
- Using Pages with `assets.run_worker_first = true`
**Typical improvements when Smart Placement helps:**
- 20-50% reduction in request duration for database-heavy Workers
- 30-60% reduction for Workers making multiple backend API calls
- Larger improvements when backend is geographically concentrated
## Monitoring Commands
```bash
# Tail Worker logs
wrangler tail your-worker-name
# Tail with filters
wrangler tail your-worker-name --status error
wrangler tail your-worker-name --header cf-placement
# Check placement status via API
curl -H "Authorization: Bearer $TOKEN" \
https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/services/$WORKER_NAME \
| jq .result.placement_status
```
## TypeScript Types
```typescript
// Placement status returned by API (field may be absent)
type PlacementStatus =
| 'SUCCESS'
| 'INSUFFICIENT_INVOCATIONS'
| 'UNSUPPORTED_APPLICATION'
| undefined;
// Placement configuration in wrangler.jsonc
type PlacementMode = 'smart' | 'off';
interface PlacementConfig {
mode: PlacementMode;
// Legacy fields (deprecated/removed):
// hint?: string; // REMOVED - no longer supported
}
// Explicit placement (separate feature from Smart Placement)
interface ExplicitPlacementConfig {
region?: string;
host?: string;
hostname?: string;
// Cannot combine with mode field
}
// Worker metadata from API response
interface WorkerMetadata {
placement?: PlacementConfig | ExplicitPlacementConfig;
placement_status?: PlacementStatus;
}
// Service Binding for backend Worker
interface Env {
BACKEND_SERVICE: Fetcher; // Service Binding to backend Worker
DATABASE: D1Database;
}
// Example Worker with Service Binding
export default {
async fetch(request: Request, env: Env): Promise<Response> {
// Forward to backend Worker with Smart Placement enabled
const response = await env.BACKEND_SERVICE.fetch(request);
return response;
}
} satisfies ExportedHandler<Env>;
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |