Cloudflare Worker Base Stack

Production-tested: cloudflare-worker-base-test (https://cloudflare-worker-base-test.webfonts.workers.dev) Last Updated: 2026-01-20 Status: Production Ready ✅ Latest Versions: [email protected], @cloudflare/[email protected], [email protected], [email protected] Skill Version: 3.1.0

Recent Updates (2025-2026):

• Wrangler 4.55+: Auto-config for frameworks (wrangler deploy --x-autoconfig)
• Wrangler 4.45+: Auto-provisioning for R2, D1, KV bindings (enabled by default)
• Workers RPC: JavaScript-native RPC via WorkerEntrypoint class for service bindings
• March 2025: Wrangler v4 release (minimal breaking changes, v3 supported until Q1 2027)
• June 2025: Native Integrations removed from dashboard (CLI-based approach with wrangler secrets)
• 2025 Platform: Workers VPC Services, Durable Objects Data Studio, 64 env vars (5KB each), unlimited Cron Triggers per Worker, WebSocket 32 MiB messages, node:fs/Web File System APIs
• 2025 Static Assets: Gradual rollout asset mismatch issue, free tier 429 errors with run_worker_first, Vite plugin auto-detection
• Hono 4.11.x: Enhanced TypeScript RPC type inference, cloneRawRequest utility, JWT aud validation, auth middleware improvements

Quick Start (5 Minutes)

# 1. Scaffold project
npm create cloudflare@latest my-worker -- --type hello-world --ts --git --deploy false --framework none

# 2. Install dependencies
cd my-worker
npm install [email protected]
npm install -D @cloudflare/[email protected] [email protected]

# 3. Create wrangler.jsonc
{
  "name": "my-worker",
  "main": "src/index.ts",
  "account_id": "YOUR_ACCOUNT_ID",
  "compatibility_date": "2025-11-11",
  "assets": {
    "directory": "./public/",
    "binding": "ASSETS",
    "not_found_handling": "single-page-application",
    "run_worker_first": ["/api/*"]  // CRITICAL: Prevents SPA fallback from intercepting API routes
  }
}

# 4. Create vite.config.ts
import { defineConfig } from 'vite'
import { cloudflare } from '@cloudflare/vite-plugin'
export default defineConfig({ plugins: [cloudflare()] })

# 5. Create src/index.ts
import { Hono } from 'hono'
type Bindings = { ASSETS: Fetcher }
const app = new Hono<{ Bindings: Bindings }>()
app.get('/api/hello', (c) => c.json({ message: 'Hello!' }))
app.all('*', (c) => c.env.ASSETS.fetch(c.req.raw))
export default app  // CRITICAL: Use this pattern (NOT { fetch: app.fetch })

# 6. Deploy
npm run dev              # Local: http://localhost:8787
wrangler deploy          # Production

Critical Configuration:

• run_worker_first: ["/api/*"] - Without this, SPA fallback intercepts API routes returning index.html instead of JSON (workers-sdk #8879)
• export default app - Using { fetch: app.fetch } causes "Cannot read properties of undefined" (honojs/hono #3955)

Known Issues Prevention

This skill prevents 10 documented issues:

Issue #1: Export Syntax Error

Error: "Cannot read properties of undefined (reading 'map')" Source: honojs/hono #3955 Prevention: Use export default app (NOT { fetch: app.fetch })

Issue #2: Static Assets Routing Conflicts

Error: API routes return index.html instead of JSON Source: workers-sdk #8879 Prevention: Add "run_worker_first": ["/api/*"] to wrangler.jsonc

Issue #3: Scheduled/Cron Not Exported

Error: "Handler does not export a scheduled() function" Source: honojs/vite-plugins #275 Prevention: Use Module Worker format when needed:

export default {
  fetch: app.fetch,
  scheduled: async (event, env, ctx) => { /* ... */ }
}

Issue #4: HMR Race Condition

Error: "A hanging Promise was canceled" during development Source: workers-sdk #9518 Prevention: Use @cloudflare/[email protected] or later

Issue #5: Static Assets Upload Race

Error: Non-deterministic deployment failures in CI/CD Source: workers-sdk #7555 Prevention: 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 Docs Why 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 Docs Why 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 function Source: workers-sdk #11948 Affected 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:

// vite.config.ts - Add esmExternalRequirePlugin
import { defineConfig } from 'vite'
import { cloudflare } from '@cloudflare/vite-plugin'
import { esmExternalRequirePlugin } from 'vite'
import { builtinModules } from 'node:module'

export default defineConfig({
  plugins: [
    cloudflare(),
    esmExternalRequirePlugin({
      external: [/^node:/, ...builtinModules],
    }),
  ],
})

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 #11857 Affected 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 development
if (import.meta.env.DEV) {
  url.pathname = url.pathname.replace(import.meta.env.BASE_URL, '');
  if (url.pathname === '/') {
    return this.env.ASSETS.fetch(request);
  }
  request = new Request(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/*"]:

1. /api/hello → Worker handles (returns JSON)
2. / → Static Assets serve index.html
3. /styles.css → Static Assets serve styles.css
4. /unknown → Static Assets serve index.html (SPA fallback)

Static Assets Caching: Automatic edge caching. Cache bust with query strings: <link href="/styles.css?v=1.0.0">

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.

// ❌ DON'T: Binding-only creates database named "DB"
{
  "d1_databases": [{ "binding": "DB" }]
}

// ✅ DO: Explicit names prevent confusion
{
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "my-app-db"  // Always specify!
how to use cloudflare-worker-base
CursorClaude CodeClineCodexWindsurfGooseGitHub CopilotVS CodeGemini CLIKiloOpencodeKimi CLIRoo ClineAiderContinueZedBolt.newLovablev0Replit AgentSweepSmol DeveloperDevinCavemanAmpAntigravity
How to use cloudflare-worker-base on Cursor
AI-first code editor with Composer
1
Prerequisites
Before installing skills in Cursor, ensure your development environment meets these requirements:
›Cursor installed and configured on your development machine
›Node.js version 16.0+ with npm package manager (verify with node --version)
›Active project directory or workspace where you want to add cloudflare-worker-base
2
Execute installation command
Execute the skills CLI command in your project's root directory to begin installation:
$npx skills add https://github.com/jezweb/claude-skills --skill cloudflare-worker-basecopy
The skills CLI fetches cloudflare-worker-base from GitHub repository jezweb/claude-skills and configures it for Cursor.
3
Select Cursor when prompted
The CLI will show a list of available agents. Use arrow keys to navigate and space to select Cursor:
◆ Which agents do you want to install to?
│
│ ── Universal (.agents/skills) ── always included ────
│   • Amp
│   • Antigravity
│   • Cline
│   • Codex
│ ●Cursor(selected)
│   • Cursor
│   • Windsurf
4
Verify installation
Confirm successful installation by checking the skill directory location:
.cursor/skills/cloudflare-worker-base
Reload or restart Cursor to activate cloudflare-worker-base. Access the skill through slash commands (e.g., /cloudflare-worker-base) or your agent's skill management interface.
⚠
Security & Verification 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 development environment. Always verify the publisher's identity, review recent commits, and test in isolated environments before production deployment.
Additional Resources
›View source code on GitHub›Skills CLI documentation›Learn more about Cursor›What are agent skills?