Prevents critical routing conflicts (API routes returning index.html ), export syntax errors, HMR race conditions, and Vite 8+ compatibility issues through tested configuration patterns
Includes auto-provisioning for R2, D1, and KV resources (Wrangler 4.45+), Workers RPC for service-to-service calls, and gradual rollout asset mismatch handling
Fetches cloudflare-worker-base from jezweb/claude-skills and configures it for Cursor.
3
Select Cursor when prompted
The CLI shows a list of agents. Use arrow keys and space to select Cursor:
◆ Which agents do you want to install to?
│
│ ── Universal (.agents/skills) ────────────────
│ · Cline · Codex · Goose · Windsurf
│ ●Cursor(selected)
│ · Cursor · Aider · Continue
4
Verify installation
Confirm successful installation by checking the skill directory location:
.cursor/skills/cloudflare-worker-base
Restart Cursor to activate cloudflare-worker-base. Access via /cloudflare-worker-base in your agent's command palette.
⚠
Security Notice
We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.
Skills execute code in your environment. Always review source, verify the publisher, and test in isolation before production.
Error: "A hanging Promise was canceled" during development
Source: workers-sdk #9518Prevention: Use @cloudflare/[email protected] or later
Issue #5: Static Assets Upload Race
Error: Non-deterministic deployment failures in CI/CD
Source: workers-sdk #7555Prevention: Use Wrangler 4.x+ with retry logic (fixed in recent versions)
Issue #6: Service Worker Format Confusion
Error: Using deprecated Service Worker format
Source: Cloudflare migration guide
Prevention: Always use ES Module format
Issue #7: Gradual Rollouts Asset Mismatch (2025)
Error: 404 errors for fingerprinted assets during gradual deployments
Source: Cloudflare Static Assets DocsWhy It Happens: Modern frameworks (React/Vue/Angular with Vite) generate fingerprinted filenames (e.g., index-a1b2c3d4.js). During gradual rollouts between versions, a user's initial request may go to Version A (HTML references index-a1b2c3d4.js), but subsequent asset requests route to Version B (only has index-m3n4o5p6.js), causing 404s
Prevention:
Avoid gradual deployments with fingerprinted assets
Use instant cutover deployments for static sites
Or implement version-aware routing with custom logic
Issue #8: Free Tier 429 Errors with run_worker_first (2025)
Error: 429 (Too Many Requests) responses on asset requests when exceeding free tier limits
Source: Cloudflare Static Assets Billing DocsWhy It Happens: When using run_worker_first, requests matching specified patterns ALWAYS invoke your Worker script (counted toward free tier limits). After exceeding limits, these requests receive 429 instead of falling back to free static asset serving
Prevention:
Upgrade to Workers Paid plan ($5/month) for unlimited requests
Use negative patterns (!/pattern) to exclude paths from Worker invocation
Minimize run_worker_first patterns to only essential API routes
Issue #9: Vite 8 Breaks nodejs_compat with require()
Error: Calling require for "buffer" in an environment that doesn't expose the require functionSource: workers-sdk #11948Affected Versions: Vite 8.x with @cloudflare/vite-plugin 1.21.0+
Why It Happens: Vite 8 uses Rolldown bundler which doesn't convert require() to import for external modules. Workers don't expose require() function, causing Node built-in module imports to fail at runtime.
Prevention:
Status: Workaround available. Vite team working on fix (vitejs/vite#21452).
Issue #10: Vite base Option Breaks SPA Routing (1.13.8+)
Error: curl http://localhost:5173/prefix returns 404 instead of index.html
Source: workers-sdk #11857Affected Versions: @cloudflare/vite-plugin 1.13.8+
Why It Happens: Plugin now passes full URL with base path to Asset Worker (matching prod behavior). Platform support for assets.base not yet available.
Prevention (dev-mode workaround):
// worker.ts - Strip base path in developmentif(import.meta.env.DEV){ url.pathname = url.pathname.replace(import.meta.env.BASE_URL,'');if(url.pathname ==='/'){returnthis.env.ASSETS.fetch(request);} request =newRequest(url, request);}
Status: Intentional change to align dev with prod. Platform feature assets.base planned for Q1 2026 (workers-sdk #9885).
Route Priority with run_worker_first
Critical Understanding: "not_found_handling": "single-page-application" returns index.html for unknown routes (enables React Router, Vue Router). Without run_worker_first, this intercepts API routes!
Request Routing with run_worker_first: ["/api/*"]:
Free Tier Warning (2025): run_worker_first patterns count toward free tier limits. After exceeding, requests get 429 instead of falling back to free static assets. Use negative patterns (!/pattern) or upgrade to Paid plan.
Auto-Provisioning (Wrangler 4.45+)
Default Behavior: Wrangler automatically provisions R2 buckets, D1 databases, and KV namespaces when deploying. This eliminates manual resource creation steps.
Critical: Always Specify Resource Names
⚠️ Edge Case (workers-sdk #11870): If you provide only binding without database_name/bucket_name, Wrangler uses the binding name as the resource name. This causes confusing behavior with wrangler dev and subcommands, which prefer database_id → database_name → binding.
›Claude Desktop or compatible AI client with skill support
›Clear understanding of task or problem to solve
›Willingness to iterate and refine outputs
Time Estimate
15-45 minutes depending on use case complexity
Steps
1Install skill using provided installation command
2Test with simple use case relevant to your work
3Evaluate output quality and relevance
4Iterate on prompts to improve results
5Integrate into regular workflow if valuable
Common Pitfalls
⚠Expecting perfect results without iteration
⚠Not providing enough context in prompts
⚠Using skill for tasks outside its intended scope
⚠Accepting outputs without review and validation
Best Practices
✓ Do
+Start with clear, specific prompts
+Provide relevant context and constraints
+Review and refine all outputs before using
+Iterate to improve output quality
+Document successful prompt patterns
✗ Don't
−Don't use without understanding skill limitations
−Don't skip validation of outputs
−Don't share sensitive information in prompts
−Don't expect skill to replace human judgment
💡 Pro Tips
★Be specific about desired format and style
★Ask for multiple options to choose from
★Request explanations to understand reasoning
★Combine AI efficiency with human expertise
When to Use This
✓ Use when
Use when skill capabilities match your task, clear ROI on time saved, and you can validate outputs. Best for repetitive tasks, learning, and quality improvement.
✗ Avoid when
Avoid when task requires deep expertise you can't validate, involves sensitive decisions, or when learning process is more valuable than speed of completion.
Learning Path
1Familiarize yourself with skill capabilities and limitations
2Start with low-risk, non-critical tasks
3Progress to more complex and valuable use cases
4Build expertise through regular use and experimentation
