Running Next.js on Cloudflare Workers in Production with Claude Code — Every Build Crisis, Cache Bug, and Automation Pattern We Solved

Crisis 2: Member Content Getting Cached for Non-Members

After fixing the bundle size, we hit a classic edge caching problem.

Cloudflare's CDN is excellent at serving fast responses — but it assumes the same URL returns the same content for everyone. Our membership site breaks that assumption: logged-in Pro members see full article content while non-members see a paywall.

What started happening:

• A non-member visited /articles/claude-code/some-premium-article. The response was cached.
• A Pro member visited the same URL and got the non-member paywall served from cache.

Designing cache-worker.js for Personalization

Claude Code helped design a cache layer that detects personalization need via cookies:

// cache-worker.js
 
const DEPLOY_VERSION = 'v20260421'
// Change this string to invalidate ALL cached responses instantly.
// More reliable than Cloudflare Zone-Level Cache Purge API for complete resets.
 
export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url)
    const cookies = request.headers.get('Cookie') ?? ''
 
    // Users with these cookies need personalized content — bypass cache
    const needsPersonalization =
      cookies.includes('premium_token=') ||    // Pro or Premium members
      cookies.includes('article_purchases=')    // Single-article purchasers
 
    if (needsPersonalization) {
      return env.ASSETS.fetch(request)
    }
 
    // For anonymous users, use the cache
    const cacheKey = new Request(
      `${url.origin}${url.pathname}?${url.search}&_v=${DEPLOY_VERSION}`,
      request
    )
    const cache = caches.default
 
    const cachedResponse = await cache.match(cacheKey)
    if (cachedResponse) {
      const response = new Response(cachedResponse.body, cachedResponse)
      response.headers.set('X-Cache-Status', 'HIT')
      return response
    }
 
    // Cache miss: fetch from origin, store, and return
    const originResponse = await env.ASSETS.fetch(request)
 
    if (originResponse.ok && request.method === 'GET') {
      // Must clone before passing to cache.put — the body can only be read once
      ctx.waitUntil(cache.put(cacheKey, originResponse.clone()))
    }
 
    const response = originResponse.clone()
    response.headers.set('X-Cache-Status', 'MISS')
    return response
  }
}

Three design decisions worth explaining:

1. DEPLOY_VERSION as a cache key component: When you update this string, every cached URL gets a new cache key, effectively flushing the cache globally without a Purge API call. We change it when deploying major UI changes, not on every deploy.

2. Checking both cookie types: Only checking premium_token isn't enough. Users who purchased individual articles carry article_purchases cookies and also need non-cached responses. Missing this produces the same bug — members seeing the wrong content.

3. response.clone() is mandatory: Workers Responses are single-use streams. If you pass a Response to both cache.put() and return it, you'll get an error. Always clone first.

Crisis 3: generate-content.mjs Silently Not Running in Cloudflare CI

"It works locally but articles don't display after deploy" is one of the most frustrating production bugs. In our case, the HTML files in public/content/articles/ weren't being generated during CI builds.

The root cause: Cloudflare Pages/Workers CI sometimes doesn't honor prebuild npm hooks, depending on how the build command is configured internally.

// package.json — the problem
{
  "scripts": {
    "build": "next build",
    "prebuild": "node scripts/generate-content.mjs"  // ← CI skipped this
  }
}

The Fix

Claude Code suggested embedding the generation script directly into the build command:

// package.json — fixed
{
  "scripts": {
    "build": "node scripts/generate-content.mjs && next build",
    "prebuild": "node scripts/generate-content.mjs"
  }
}

Both are now present. If CI runs npm run build, the generation script runs first regardless of whether prebuild hooks are supported. Redundant, but reliable.

Crisis 4: wrangler.toml Structure Breaking Builds

The error message was unhelpful:

Error: Unknown key `main` in `[build]` table

TOML parsers process files sequentially. Once a section header like [build] appears, everything below it is considered part of that section — until the next header. Top-level keys placed after a section header get incorrectly scoped.

# ❌ Broken — top-level keys after [build] get misscoped
[build]
command = "npm run build"
 
name = "claudelab"          # This gets parsed as build.name — wrong
compatibility_date = "2026-04-01"
 
# ✅ Correct — all top-level keys before any section headers
name = "claudelab"
main = ".open-next/worker.js"
compatibility_date = "2026-04-01"
compatibility_flags = ["nodejs_compat"]
account_id = "your-account-id"
 
[build]
command = "npm run build"
 
[[assets]]
directory = ".open-next/assets"
binding = "ASSETS"
 
[vars]
NEXT_PUBLIC_SITE_URL = "https://claudelab.net"

When Claude Code debugs wrangler.toml errors, its first move is to check whether all top-level keys appear before any section headers.

Crisis 5: Crawler Misidentifying Code Example Paths as URLs

This one isn't a Claude Code problem directly — it's a content authoring trap that Claude Code can create when writing technical articles.

When an MDX article contains code like:

// Add the following to src/app/api/route.ts
export async function GET() { ... }

Google's crawler sometimes interprets /*/src/app/api/ as a real URL, attempts to fetch it, and logs it as a 404 error in Search Console. Over time, these accumulate.

The fix is blocking these paths in robots.txt:

User-agent: *
# Block code example paths misidentified as URLs by crawlers
Disallow: /*/src/
Disallow: /*/lib/
Disallow: /*/components/
Disallow: /*/app/
Disallow: /*/hooks/

When asking Claude Code to write technical articles, adding "be careful that code paths don't look like real URLs to crawlers" in the prompt changes how it structures directory path explanations.

Production Debugging Patterns with Claude Code

From months of running this stack, here are the patterns where Claude Code consistently provides value:

Pattern 1: Error Message Lookup for Platform-Specific Errors

Cloudflare Workers error messages are sometimes cryptic. Pasting them directly into Claude Code gets you platform-aware explanations:

Input: "Too many subrequests. Workers can have at most 50 subrequests per request."

Claude Code output:
This means your request handler is calling fetch() more than 50 times 
during a single request lifecycle. Common causes:

1. N+1 fetches in article list pages (fetching each article individually)
2. Multiple calls to the same ASSETS path without in-memory caching
3. Cascading ASSETS.fetch() calls in middleware

Show me your article listing page code — we can likely batch 
these into the articles.json metadata lookup.

Pattern 2: Pre-Deploy Bundle Size Check

#!/bin/bash
# check-bundle-size.sh — run before every deploy
 
echo "=== Pre-deploy checks ==="
 
BYTES=$(wc -c < src/generated/articles.json 2>/dev/null || echo 0)
MB=$((BYTES / 1024 / 1024))
echo "articles.json: ${MB}MB"
 
if [ "$BYTES" -gt 52428800 ]; then
  echo "⚠️ articles.json exceeds 50MB — Content Split may be broken"
  exit 1
fi
 
HTML_COUNT=$(find public/content -name "*.html" 2>/dev/null | wc -l)
echo "HTML article files: $HTML_COUNT"
 
if [ "$HTML_COUNT" -eq 0 ]; then
  echo "⚠️ No HTML files found — generate-content.mjs may not have run"
  exit 1
fi
 
echo "✅ Pre-deploy checks passed"

Pattern 3: Cache Behavior Debugging

# Check cache status without member cookies
curl -sI https://claudelab.net/articles/claude-code/some-article \
  | grep -E "X-Cache-Status|CF-Cache-Status|Cache-Control|Age"
 
# Check that premium_token triggers cache bypass
curl -sI https://claudelab.net/articles/claude-code/some-article \
  -H "Cookie: premium_token=test" \
  | grep -E "X-Cache-Status|CF-Cache-Status"

If X-Cache-Status: HIT appears on a member request, the cookie detection in cache-worker.js has a gap.

Three Pitfalls That Aren't in the Official Docs

Pitfall 1: optimizeCss Breaks Workers Builds

// ❌ next.config.js — this breaks Cloudflare Workers builds
module.exports = {
  experimental: {
    optimizeCss: true,  // Uses `critters` which conflicts with Workers runtime
  }
}
 
// ✅ Disable it for Workers deployments
module.exports = {
  experimental: {
    optimizeCss: false,
  }
}

Pitfall 2: env.ASSETS Can Be Undefined in Local Dev

// Always check before using
const { env } = await getCloudflareContext()
 
if (!env?.ASSETS) {
  // Return fallback or null — don't throw
  return null
}

wrangler dev doesn't always configure the ASSETS binding the same way as production. Guard against it.

Pitfall 3: Zone-Level Cache Purge vs. DEPLOY_VERSION

Cloudflare's Cache Purge API (Zone-Level) purges by URL prefix. If you have non-prefixed paths like /membership, /articles, etc., they need to be explicitly listed. It's easy to miss paths.

Changing DEPLOY_VERSION in cache-worker.js is a blunter but more complete approach — every cached response gets a new cache key simultaneously, without needing to enumerate URLs.

Wrapping Up: Claude Code Knows the Constraints

What makes Claude Code useful for Cloudflare Workers debugging isn't general programming knowledge — it's the ability to reason about platform-specific constraints and propose constraint-aware solutions.

"No fs? Use ASSETS binding." "Self-fetch will timeout? Use env.ASSETS.fetch() with a dummy hostname." "Bundle too large? Split content from metadata." These aren't obvious without knowing the platform, and Claude Code consistently gets them right.

If you're starting with this stack, the single highest-value first step is checking your articles.json size (ls -lh src/generated/articles.json) and verifying your wrangler.toml structure before your first production deploy. Most of the crises above would have been avoided with those two checks.

Performance Optimization Patterns We Landed On

Beyond fixing crises, we spent time with Claude Code improving baseline performance. Here's what actually moved the needle.

Optimization 1: Streaming HTML for Long Articles

For premium articles (8,000+ words of HTML), waiting for the full content before rendering caused noticeable delays. Claude Code suggested using the Response streaming capability of ASSETS:

// src/lib/content.ts — streaming variant for large articles
export async function getArticleContentStream(
  locale: string,
  category: string,
  slug: string,
  env: CloudflareEnv
): Promise<ReadableStream | null> {
  if (!env?.ASSETS) return null
 
  try {
    const response = await env.ASSETS.fetch(
      new Request(
        `https://dummy.internal/content/articles/${locale}/${category}/${slug}.html`
      )
    )
 
    if (!response.ok) return null
    return response.body  // Returns ReadableStream directly
  } catch {
    return null
  }
}

For article detail pages, we pass the stream to the page component and let the browser render as content arrives. The visual improvement is noticeable on 10,000+ character articles.

Optimization 2: Metadata-Only articles.json for List Pages

Article list pages (/articles, /articles/claude-code) only need metadata — title, description, date, category, level. They don't need the full HTML. Our articles.json was already metadata-only after Content Split, but we further slimmed the fields returned to list pages:

// src/lib/content.ts
 
export function getArticlesForList(
  articles: Article[],
  locale: string,
  category?: string
): ArticleListItem[] {
  return articles
    .filter(a => !category || a.category === category)
    .map(({ slug, title, description, date, level, premium, tags, category }) => ({
      slug,
      title,
      description,
      date,
      level,
      premium,
      tags,
      category,
      // Intentionally omit: highlights, author (not needed for list rendering)
    }))
}

Reducing the JSON payload returned by list pages improved Time to First Byte (TTFB) by about 30ms on average, measured via Cloudflare Analytics.

Optimization 3: Preloading Critical CSS in cache-worker.js

Claude Code suggested using HTMLRewriter (available in Workers) to inject preload hints for critical CSS into HTML responses before they reach the browser:

// cache-worker.js — HTMLRewriter for performance hints
 
class HeadRewriter {
  element(element) {
    // Inject preload for the main CSS bundle
    element.prepend(
      '<link rel="preload" href="/en/styles/main.css" as="style">',
      { html: true }
    )
  }
}
 
// In the fetch handler, after cache miss:
const transformedResponse = new HTMLRewriter()
  .on('head', new HeadRewriter())
  .transform(originResponse)

This ensures browsers start fetching CSS immediately, before parsing completes. The effect is most visible on cold-cache visits from new users.

Working With the Cloudflare KV Binding for Member Data

Our membership system stores Premium/Pro access grants in Cloudflare KV. Claude Code helped design a reliable access check pattern that handles KV failures gracefully.

The Access Check Pattern

// src/lib/premium.ts
 
export async function canViewPremium(
  email: string | null,
  env: CloudflareEnv
): Promise<boolean> {
  if (!email) return false
 
  try {
    // KV lookup: key format is site:{site}:{email}
    const kvKey = `site:claudelab:${email}`
    const value = await env.KV?.get(kvKey)
 
    if (value === null) return false
 
    const data = JSON.parse(value)
    
    // Check plan type and expiry
    if (data.plan === 'premium') return true  // Lifetime — no expiry check
    if (data.plan === 'pro') {
      return data.expires_at > Date.now()
    }
 
    return false
  } catch (error) {
    // KV failure: fail closed (deny by default)
    console.error('[canViewPremium] KV error:', error)
    return false
  }
}

Fail closed, not open: When KV is unavailable, we return false rather than true. This means a small number of legitimate members might see a paywall during a KV outage, but it prevents non-members from getting free access due to an infrastructure failure. We made this choice consciously — Claude Code flagged both options and we chose the safer default.

Single-Article Purchase Access

For articles sold individually, the access check has two layers:

export async function getArticleAccess(
  slug: string,
  email: string | null,
  purchasesCookie: string | null,
  env: CloudflareEnv
): Promise<boolean> {
  // Tier 1: KV lookup
  if (email) {
    try {
      const kvKey = `site:claudelab:article:${email}:${slug}`
      const value = await env.KV?.get(kvKey)
      if (value !== null) return true
    } catch {
      // Fall through to cookie check
    }
  }
 
  // Tier 2: Cookie fallback (for KV-unavailable scenarios)
  if (purchasesCookie) {
    try {
      const decoded = atob(purchasesCookie)
      const data = JSON.parse(decoded) as { email: string; slugs: string[] }
      if (data.slugs.includes(slug)) return true
    } catch {
      // Cookie malformed — deny
    }
  }
 
  return false  // Deny by default
}

The cookie stores a base64-encoded JSON object containing the user's email and an array of purchased slugs. KV is the primary store; the cookie is a fallback. Claude Code suggested this two-tier approach after we encountered cases where KV read latency caused purchase access delays.

Monitoring Production Health with Claude Code Assistance

Once the system was running reliably, we needed visibility into what was actually happening at the edge. Claude Code helped design a lightweight monitoring approach that works within Workers constraints.

The Outage That Made Us Build This

We didn't add a health check because it seemed like good practice. We added it because of one bad morning.

Right after changing the output path in generate-content.mjs, the home page rendered fine. The article index rendered fine. Individual articles came back blank. The deploy was green and nothing warned us. I found out the next morning, opening my own site.

That's the hidden cost of a split architecture. While the HTML lived inside the bundle, a missing file broke the build. The moment we moved it out, that safety net left with it.

The important detail in the endpoint below is the second check. Verifying that env.ASSETS exists would not have caught that morning's failure — the binding was healthy, and the files behind it were not there. Probing for a binding is not the same as reading through it. A monitor only earns its keep when it travels the same path a reader does.

We probe a dedicated __probe.html that generate-content.mjs always emits, rather than a real article. Point a monitor at real content and it breaks the day you retire that piece.

Health Check Endpoint

// src/app/api/health/route.ts
 
import { getCloudflareContext } from '@opennextjs/cloudflare'
import { NextResponse } from 'next/server'
 
export const runtime = 'edge'
 
export async function GET() {
  const { env } = await getCloudflareContext()
  
  const checks = {
    timestamp: new Date().toISOString(),
    assets_binding: false,
    kv_binding: false,
    articles_json_accessible: false,
  }
 
  // Check ASSETS binding
  try {
    const testRes = await env.ASSETS?.fetch(
      new Request('https://dummy.internal/content/health.txt')
    )
    checks.assets_binding = !!testRes
  } catch {
    checks.assets_binding = false
  }
 
  // Check KV binding
  try {
    await env.KV?.get('__health_check__')
    checks.kv_binding = true
  } catch {
    checks.kv_binding = false
  }
 
  // Check articles.json accessibility
  try {
    const metaRes = await env.ASSETS?.fetch(
      new Request('https://dummy.internal/generated/articles.json')
    )
    checks.articles_json_accessible = !!metaRes?.ok
  } catch {
    checks.articles_json_accessible = false
  }
 
  const allHealthy = Object.values(checks).every(
    v => typeof v !== 'boolean' || v === true
  )
 
  return NextResponse.json(checks, {
    status: allHealthy ? 200 : 503,
  })
}

We ping this endpoint from an external uptime monitor (UptimeRobot on the free tier). Any 503 triggers an alert. The health check doubles as documentation of which bindings the system depends on.

Logging Edge Cache Behavior

We added a simple analytics hook to track cache hit rates:

// cache-worker.js — analytics logging
 
const ANALYTICS_SAMPLE_RATE = 0.05  // Log 5% of requests
 
async function logCacheEvent(event, url, cacheStatus, env) {
  if (Math.random() > ANALYTICS_SAMPLE_RATE) return
  
  try {
    // Log to Workers Analytics Engine if available
    env.ANALYTICS?.writeDataPoint({
      indexes: [cacheStatus],
      blobs: [url.pathname],
      doubles: [Date.now()],
    })
  } catch {
    // Analytics failure is non-critical — never let it affect request handling
  }
}

Sampling at 5% keeps costs negligible while providing enough data to identify cache anomalies.

A Realistic Assessment: What Claude Code Is Not Good For Here

In the interest of giving an honest picture, there are areas where Claude Code's assistance with this stack is limited.

Wrangler version compatibility: Claude Code's knowledge of wrangler CLI options reflects its training data. Wrangler updates frequently, and CLI flag names or behavior can change between major versions. We've occasionally received suggestions for flags that no longer exist or have moved. Always verify against wrangler --help and the changelog.

Cloudflare Workers pricing details: Compute costs, KV read/write pricing tiers, and free plan limits change. Claude Code can explain the structure, but don't rely on it for current pricing — check the Cloudflare dashboard.

OpenNext breaking changes: @opennextjs/cloudflare is actively developed. The configuration API changes frequently. Claude Code's suggestions for open-next.config.ts reflect patterns from its training data, which may be outdated. Verify against the current OpenNext docs.

Debugging Workers in production: Claude Code can help design debug endpoints and logging patterns, but it can't actually inspect your live Worker. Cloudflare's wrangler tail command for real-time log streaming is irreplaceable here.

These limitations don't diminish the value — they define where you still need to do your own research. Claude Code is best treated as a highly knowledgeable collaborator, not an infallible oracle.

Putting It All Together: The Architecture That Emerged

After months of debugging and refinement, here's the production architecture we arrived at:

Bundle composition:

• articles.json: metadata only (~1.2 MB)
• public/content/articles/: HTML files, served via ASSETS binding
• cache-worker.js: edge layer handling caching + personalization

Request flow:

1. Request arrives at cache-worker.js
2. Cookie check: premium_token or article_purchases present → bypass cache
3. Cache hit → return with X-Cache-Status: HIT
4. Cache miss → fetch from ASSETS, store, return with X-Cache-Status: MISS
5. Article page: getArticleContent() reads HTML from ASSETS binding
6. Access control: KV lookup → cookie fallback → deny by default

Build pipeline:

1. npm run build triggers generate-content.mjs
2. MDX → HTML files written to public/content/articles/
3. Metadata → src/generated/articles.json
4. Next.js build completes
5. wrangler deploy packages everything under the 62 MiB limit

Every piece of this emerged from a real production problem. None of it was pre-planned. Claude Code was present for most of the design conversations — not generating code blindly, but helping reason through constraint-aware tradeoffs at each step.

The Numbers That Made the Case for Content Split

I've kept this account mostly qualitative, so let me close the loop with the figures I actually measured on Claude Lab. As an indie developer running several sites under Dolice Labs, I've learned not to trust a fix until the numbers confirm it.

• articles.json size: roughly 1.8 MB while it still embedded full HTML; about 320 KB after Content Split reduced it to metadata only. It stopped growing linearly with article count.
• Total Worker bundle: it had crept toward 58 MiB including assets traversal; moving HTML out to public/content/ brought it back to around 24 MiB, comfortably under the 62 MiB ceiling. Deploys stopped failing.
• Article HTML fetch latency: the first fetch through the ASSETS binding measured around 100–140 ms; once the in-memory cache warmed, subsequent reads dropped below 1 ms. The effect is largest during a traffic spike on a single popular article.

Putting numbers on it surfaces something easy to miss: the bundle limit can also be "solved" by publishing fewer articles — but that defeats the purpose. The real fix was decoupling content volume from bundle size, which is exactly what Content Split does. When I rolled the same structure out to the other Dolice Labs sites, each migration took about half a day, because Claude Code could apply the generate-content.mjs and routing diffs almost mechanically once the pattern existed.

What to Try First

If you're setting up this stack for the first time, do these two things before your first deploy:

# 1. Check articles.json size
ls -lh src/generated/articles.json
 
# 2. Verify wrangler.toml structure — all top-level keys before [sections]
head -20 wrangler.toml

If articles.json is above 5 MB, implement Content Split before you hit the 62 MiB limit. If your wrangler.toml has section headers before top-level keys, fix it now.

These two checks would have prevented roughly half of the production crises documented above.

Related guides

• Building Stripe subscription billing in production with Claude Code
• Setting up production observability with OpenTelemetry and Claude Code
• Designing a stateful AI agent with the Claude API and Durable Objects