AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

cloudflare-deploy

Deploy 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.

Original source
openai
License
Apache-2.0
Pinned revision
49f948faa9258a0c61caceaf225e179651397431

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read openai--cloudflare-deploy at revision 49f948faa9258a0c61caceaf225e179651397431, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 309

references/static-assets/gotchas.md

Best Practices

1. Use Selective Worker-First Routing

Instead of run_worker_first = true, use array patterns:

{
  "assets": {
    "run_worker_first": [
      "/api/*",           // API routes
      "/admin/*",         // Admin area
      "!/admin/assets/*"  // Except admin assets
    ]
  }
}

Benefits:

  • Reduces Worker invocations
  • Lowers costs
  • Improves asset delivery performance

2. Leverage Navigation Request Optimization

For SPAs, use compatibility_date = "2025-04-01" or later:

{
  "compatibility_date": "2025-04-01",
  "assets": {
    "not_found_handling": "single-page-application"
  }
}

Navigation requests skip Worker invocation, reducing costs.

3. Type Safety with Bindings

Always type your environment:

interface Env {
  ASSETS: Fetcher;
}

Common Errors

"Asset not found"

Cause: Asset not in assets directory, wrong path, or assets not deployed
Solution: Verify asset exists, check path case-sensitivity, redeploy if needed

"Worker not invoked for asset"

Cause: Asset served directly, run_worker_first not configured
Solution: Configure run_worker_first patterns to include asset routes (see configuration.md:66-106)

"429 Too Many Requests on free tier"

Cause: run_worker_first patterns invoke Worker for many requests, hitting free tier limits (100k req/day)
Solution: Use more selective patterns with negative exclusions, or upgrade to paid plan

"Smart Placement increases latency"

Cause: run_worker_first=true + Smart Placement routes all requests through single smart-placed location
Solution: Use selective patterns (array syntax) or disable Smart Placement for asset-heavy apps

"CF-Cache-Status header unreliable"

Cause: Header is probabilistically added for privacy reasons
Solution: Don't rely on CF-Cache-Status for critical routing logic. Use other signals (ETag, age).

"JWT expired during deployment"

Cause: Large asset deployments exceed JWT token lifetime
Solution: Update to Wrangler 4.34.0+ (automatic token refresh), or reduce asset count

"Cannot use 'assets' with 'site'"

Cause: Legacy site config conflicts with new assets config
Solution: Migrate from site to assets (see configuration.md). Remove site key from wrangler.jsonc.

"Assets not updating after deployment"

Cause: Browser or CDN cache serving old assets
Solution:

  • Hard refresh browser (Cmd+Shift+R / Ctrl+F5)
  • Use cache-busting (hashed filenames)
  • Verify deployment completed: wrangler tail

Limits

| Resource/Limit | Free | Paid | Notes | |----------------|------|------|-------| | Max asset size | 25 MiB | 25 MiB | Per file | | Total assets | 20,000 | 100,000 | Requires Wrangler 4.34.0+ (Sep 2025) | | Worker invocations | 100k/day | 10M/month | Optimize with run_worker_first patterns | | Asset storage | Unlimited | Unlimited | Included |

Version Requirements

| Feature | Minimum Wrangler Version | |---------|--------------------------| | 100k file limit (paid) | 4.34.0 | | Vite plugin | 4.0.0 + @cloudflare/vite-plugin 1.0.0 | | Navigation optimization | 4.0.0 + compatibility_date: "2025-04-01" |

Performance Tips

1. Use Hashed Filenames

Enable long-term caching with content-hashed filenames:

app.a3b2c1d4.js
styles.e5f6g7h8.css

Most bundlers (Vite, Webpack, Parcel) do this automatically.

2. Minimize Worker Invocations

Serve assets directly when possible:

{
  "assets": {
    // Only invoke Worker for dynamic routes
    "run_worker_first": ["/api/*", "/auth/*"]
  }
}

3. Leverage Browser Cache

Set appropriate Cache-Control headers:

// Versioned assets
'Cache-Control': 'public, max-age=31536000, immutable'

// HTML (revalidate often)
'Cache-Control': 'public, max-age=0, must-revalidate'

See patterns.md:169-189 for implementation.

4. Use .assetsignore

Reduce upload time by excluding unnecessary files:

*.map
*.md
.DS_Store
node_modules/

See configuration.md:107-126 for details.