DEV Community: Mark

Cloudflare Pages Blank Page? The index.txt Trap with Next.js Static Export

Mark — Sun, 21 Jun 2026 14:27:31 +0000

After deployment, the site occasionally showed a blank screen on the homepage — refreshing fixed it.
Debugging this took half a day. The culprit was a subtle interaction between Next.js and Cloudflare.

The Problem

After deploying to Cloudflare Pages, most visits work fine. But occasionally — especially when navigating to the homepage from another page — a blank screen appears. Refresh and it's fine.

Sentry reports no errors. The Network tab looks fine — at first glance.

Debugging Process

Step 1: Check Cloudflare Cache

First instinct: Cloudflare cached an intermediate state. Cleared cache. Problem persisted.

Step 2: Browser DevTools

Opened Network tab, enabled "Preserve log", reproduced the issue.

When the blank screen appeared, the / request had Content-Type: text/plain in the response headers, with an empty body.

Normally it should be Content-Type: text/html with index.html content.

Step 3: Content Negotiation

Why does the same URL sometimes return HTML and sometimes text/plain?

Key clue: Before navigating to /, the browser sends a prefetch request:

GET / HTTP/1.1
Accept: text/plain
Accept-Encoding: gzip, deflate, br

This prefetch with Accept: text/plain is from Next.js 15's content negotiation prefetch mechanism.

Root Cause Analysis

Next.js 15 Prefetch Behavior

Before client-side navigation, Next.js 15 prefetches the target resource. For efficiency, it sometimes requests with Accept: text/plain — expecting lightweight metadata instead of full HTML.

Next.js Static Export Creates index.txt

During output: 'export' build, Next.js creates out/index.html for the / route. But internal processes (content negotiation support) also generate out/index.txt.

Cloudflare Pages File Matching

Cloudflare Pages static hosting routing rules:

GET / + Accept: text/html → matches index.html ✅
GET / + Accept: text/plain → matches index.txt ✅ (if it exists)

When index.txt exists, Cloudflare Pages does content negotiation based on the Accept header and returns index.txt.

If index.txt is empty, users see a blank page.

The Complete Bug Chain

App Router Link prefetch
  → browser sends GET / Accept: text/plain
    → Cloudflare Pages finds index.txt
      → returns empty text/plain response
        → browser uses this as page content
          → Blank screen!

Evolution: From Blank Screen to 404 Flood

The delete approach fixed the blank screen, but introduced a new problem.

The Problem

With 150+ tool pages, each page triggers an Accept: text/plain prefetch request during client-side navigation. With index.txt deleted, every request returns 404.

F12 Network panel is filled with 404s:

/              404 (text/plain)
/tools/json-formatter/  404 (text/plain)
/tools/base64/          404 (text/plain)
/tools/uuid-generator/  404 (text/plain)
...                  (100+)

Impact

Visual noise: Network panel full of red 404s during debugging
Wasted bandwidth: Each 404 costs a Cloudflare request and response
Connection contention: HTTP/1.1 has 6 concurrent connections per domain; 404s steal slots from real resources
Cloudflare doesn't cache 404s: Every visit hits the origin

Better Approach: Create Empty index.txt

Instead of deleting, create them — let the prefetch hit a valid 200 response:

// scripts/create-index-txt.js
const fs = require('fs')
const path = require('path')

function createIndexTxtFiles(dir) {
  let count = 0
  function walk(currentDir) {
    const indexPath = path.join(currentDir, 'index.html')
    if (fs.existsSync(indexPath)) {
      const txtPath = path.join(currentDir, 'index.txt')
      if (!fs.existsSync(txtPath)) {
        fs.writeFileSync(txtPath, '')
        count++
      }
    }
    try {
      const entries = fs.readdirSync(currentDir, { withFileTypes: true })
      for (const entry of entries) {
        if (entry.isDirectory()) {
          walk(path.join(currentDir, entry.name))
        }
      }
    } catch (e) {}
  }
  walk(dir)
  console.log(`Created ${count} index.txt files`)
}

createIndexTxtFiles(path.join(__dirname, '..', 'out'))

Update build script:

{
  "scripts": {
    "build": "next build && node scripts/create-index-txt.js"
  }
}

Why Creating Is Better Than Deleting

Aspect	Delete index.txt	Create empty index.txt
Prefetch result	404	200 OK (0 bytes)
Cloudflare cache	❌ Doesn't cache 404	✅ Caches 200
Connection contention	Every request hits origin	Cache HIT, instant return
Network panel	Full of red	All green
Blank screen risk	None	None (empty file won't override HTML)
File size	0	0 bytes × page count

Key insight: empty index.txt won't cause a blank screen. When Next.js client receives empty content, it knows this isn't valid HTML and automatically falls back to requesting the full index.html with Accept: text/html. Once Cloudflare caches this 200 response, subsequent prefetches are cache HITs — no wasted connections.

Lessons Learned

Read your hosting platform's file matching docs — Cloudflare Pages' content negotiation differs from standard static servers
Browser prefetches are a double-edged sword — They optimize load time but add edge cases
Inspect the build output directory — ls -la out/ to check for unexpected files
Blank page → check Network first — Wrong Content-Type is often the root cause
Don't fight the platform — Instead of deleting files and flooding with 404s, work with the mechanism

Project

Full build config and deployment flow at UtlKit — 150+ free online tools, Next.js 15 static export + Cloudflare Pages zero-cost deployment.

If this helped, leave a ❤️.

React 19 Hydration Mismatch in Static Export

Mark — Sun, 14 Jun 2026 14:18:22 +0000

📚 This is Part 3 of the UtlKit Tech Series —
Part 2 covers the architecture & trade-offs → Read Part 2

React 19 Static Export Hydration Mismatch? Pitfalls in Next.js 15

I built a 150+-tool online site with Next.js 15, deployed on Cloudflare Pages.
Everything looked great until the console started flooding with Hydration Error #418.

The Problem

Open DevTools Console — a wall of red:

Error: Hydration failed because the server rendered HTML didn't match the client.
Expected server HTML: <html class="dark">
Client-rendered HTML: <html>

The site works fine functionally, but this error hurts SEO scores and floods Sentry.

Weirder still: npm run dev works fine. npm run build && npm start breaks.

Root Cause Analysis

Layer 1: React 19 RSC and Static Export Compatibility

Next.js 15 defaults to React 19 with React Server Components (RSC). But in output: 'export' mode, every page is statically rendered to HTML.

The problem:

SSR phase: Server-side render tries to read localStorage (theme value) → can't read it (no localStorage on server)
CSR phase: Client-side hydration reads localStorage → has a value, dynamically adds class="dark"
Result: SSR HTML ≠ CSR HTML → Hydration Mismatch

Layer 2: Dynamic className on `<html>` and `<body>`

The layout.tsx had code like this:

// ❌ Causes Hydration Mismatch
export default function RootLayout({ children }) {
  const theme = useTheme() // Client hook reading localStorage
  return (
    <html lang="zh" className={theme}>
      <body>{children}</body>
    </html>
  )
}

useTheme() returns the default value (light) during SSR, but returns the localStorage value (possibly dark) during CSR. Different class on <html> → Hydration Error.

Layer 3: Terser Made Things Worse

To reduce bundle size, I added Terser minification to the build:

// next.config.js
compress: true,

After Terser compression, code execution timing changed subtly, making hydration behave inconsistently across browsers (especially Chrome). Sometimes it hydrates fine, sometimes it errors — non-deterministic bugs are the worst.

Solutions (Progressive)

Solution 1: suppressHydrationWarning (Quick Fix)

// ✅ Tells React to ignore differences on <html>
<html lang="zh" className={theme} suppressHydrationWarning>

Result: Errors gone ✅
Problem: This masks the issue. Dark mode still flashes on first paint — white then black.

Solution 2: Head Script to Pre-read Theme (Eliminates Flash)

Add a <script> in <head> that executes before React renders:

<script>
  (function() {
    const theme = localStorage.getItem('theme') || 'light';
    document.documentElement.classList.add(theme);
    document.documentElement.style.colorScheme = theme;
  })();
</script>

Result: No first-paint flash ✅, suppressHydrationWarning clears errors ✅
Problem: Good enough, but I wanted to try React 19...

Solution 3: Downgrade React 19 → 18 (Root Fix)

After testing, React 19's RSC has several known issues with output: 'export':

Different hydration timing than React 18
Some Server Component features behave unexpectedly during static export
Many community reports (GitHub Issues)

Downgraded decisively:

// package.json
{
  "dependencies": {
    "react": "^18.3.1",
    "react-dom": "^18.3.1"
  }
}

Result: All Hydration issues completely resolved ✅
Problem: Lost RSC, but static sites don't need it anyway.

Final Solution (What's in Production)

// app/layout.tsx
export default function RootLayout({ children }) {
  return (
    <html lang="zh" suppressHydrationWarning>
      <head>
        <script dangerouslySetInnerHTML={{ __html: `
          (function() {
            try {
              var t = localStorage.getItem('theme') || 'light';
              document.documentElement.classList.add(t);
              document.documentElement.style.colorScheme = t;
            } catch(e) {}
          })();
        `}} />
      </head>
      <body>{children}</body>
    </html>
  )
}

Key points:

<script> in <head> executes before React → eliminates flash
suppressHydrationWarning → eliminates errors
try/catch → prevents localStorage errors in restricted environments (iframes, etc.)
React 18 → stable hydration timing

Lessons Learned

Approach	Effect	Recommendation
`suppressHydrationWarning` only	Clears errors, but flash remains	⭐⭐
Head script + `suppressHydrationWarning`	No errors, no flash	⭐⭐⭐⭐
React 19→18 downgrade + head script	Most stable	⭐⭐⭐⭐⭐
`useLayoutEffect` delayed DOM	Works but complex	⭐⭐⭐

Core takeaways:

Static sites don't need RSC — RSC brings 10x more problems than benefits in output: 'export' mode
localStorage is the #1 cause of Hydration mismatches — SSR can't read it, CSR can, guaranteed inconsistency
Head script is the best pattern for theme/locale flash — Zero dependencies, zero overhead
Don't over-optimize builds — Terser saved a few KB but introduced non-deterministic bugs

Project

This site is UtlKit — 150+ free online developer tools. All the issues above were encountered during real development and deployment, and the solutions are running stably in production.

If this helped, feel free to leave a ❤️. Questions welcome in the comments.

150+ Tools with Only 2 Layout Components: UtlKit Architecture Design

Mark — Sat, 06 Jun 2026 06:56:26 +0000

150+ Tools with Only 2 Layout Components: UtlKit Architecture Design

UtlKit Series Part 2/2: Architecture and Trade-offs
Part 1 covers the story and tech choices → Read Part 1

150+ tools, but only 2 core layouts. Good architecture doubles development speed.

Overall Architecture

Directory Structure

src/
├── app/
│   ├── layout.tsx          # Root layout: Sentry, fonts, theme
│   ├── page.tsx            # Homepage: category tabs + tool grid
│   ├── page.client.tsx     # Homepage client-side logic
│   ├── tools/
│   │   ├── json-formatter/
│   │   │   ├── page.tsx    # Page + SEO metadata
│   │   │   └── formatter.tsx # Tool core logic
│   │   ├── hash-generator/
│   │   ├── base64/
│   │   └── ... (150+ tools total)
│   ├── about/page.tsx
│   ├── contact/page.tsx
│   ├── privacy/page.tsx
│   └── terms/page.tsx
├── components/
│   ├── ConverterLayout.tsx  # Shared layout for converter tools
│   ├── ToolSection.tsx      # Shared layout for calculator tools
│   ├── Header.tsx           # Nav + search + language + theme toggle
│   ├── Footer.tsx
│   ├── Breadcrumbs.tsx
│   ├── ThemeProvider.tsx
│   └── AdSlot.tsx
├── lib/
│   ├── tools.ts             # Tool metadata (150+ tools: name/icon/category)
│   ├── i18n/
│   │   ├── en.ts            # English ~2200 lines
│   │   └── zh-CN.ts         # Chinese ~2200 lines
│   ├── md5.ts               # Pure JS MD5 implementation
│   ├── sentry-release.ts
│   └── tool-seo.ts
└── styles/
    └── globals.css          # Tailwind + CSS custom properties

Component Abstraction: 80% of Tools Share Layouts

150+ tools distilled into two core layouts:

1. ConverterLayout — Input → Process → Output

JSON formatter, Base64, Hash, and similar tools all use this:

┌─────────────────────────────────┐
│  Input          │  Output       │
│  textarea       │  textarea     │
│                 │               │
│  [Convert]      │  [Copy]       │
└─────────────────────────────────┘

2. ToolSection — Form → Calculate → Result

BMI, Compound Interest, Loan calculator and similar:

┌────────────────────────┐
│  [Input 1]             │
│  [Input 2]             │
│  [Input 3]             │
│                        │
│  [Calculate]           │
│                        │
│  ─── Result ───        │
│  Result display area   │
└────────────────────────┘

These two shared layouts + minimal custom logic per tool dramatically improved development efficiency. Each tool only needs to implement its core conversion logic — the UI is handled uniformly by the layout components.

Browser-Only Trade-offs

The Biggest Trade-off: No Node.js Ecosystem

Node.js has mature formatting/minification libraries, but the browser doesn't have fs, net, or child_process.

Library	Node.js Dependency	Alternative
`terser` (JS minification)	✅ `fs`	Custom regex minifier
`html-minifier-terser`	✅ `fs`	Custom regex minifier
`xml-formatter` minify	⚠️ ESM/CJS issues	Custom regex minifier
`js-beautify` (formatting)	❌ Browser-compatible	✅ Use directly
`csso` (CSS minification)	❌ Pure JS	✅ Use directly

Conclusion: Use existing libraries for formatting, write custom regex for minification.

Full analysis in Part 3 → Why Node.js Libraries Don't Work in the Browser

Encryption: Web Crypto API Limitations

The browser natively supports SHA-256/384/512, AES-GCM, and HMAC — but not MD5.

MD5 is proven insecure, but it's still widely used in practice (file checksums, legacy system compatibility, etc.).

Solution: Implement MD5 yourself (~100 lines of pure JS, bitwise operations).

Full analysis in Part 5 → Client-Side Encryption with Web Crypto API

i18n: Bilingual Design

src/lib/i18n/
├── en.ts       (2208 lines)
└── zh-CN.ts    (2207 lines)

Usage:

const { t } = useI18n()
<button>{t('btn.copy')}</button>  // "Copy" / "复制"

Key decisions:

Not using next-intl — SSR safety issues in static export mode
localStorage + Context — Simple and controllable
All page titles bilingual — SEO-friendly for both languages
Tool names also bilingual — Search, breadcrumbs, sitemap

From 0 to 1 to 100

These two articles cover the "0 to 1" — design decisions and architecture. The following articles cover the "1 to 100" — real-world pitfalls:

Part	Title	Core Problem
1	React 19 Hydration Mismatch in Static Export	SSR/CSR inconsistency
2	Cloudflare Pages Blank Page: the index.txt Bug	Content negotiation mechanism
3	Why Node.js Libraries Fail in the Browser	`fs` dependencies, ESM/CJS interop
4	Sentry Source Maps: From 0% to Full Resolution	Tree-shaking, HTTP API, region detection
5	Client-Side Encryption with Web Crypto API	MD5 gap, AES-GCM, HMAC
6	Free Performance Monitoring: PageSpeed CI	Zero-cost Core Web Vitals monitoring
7	Cloudflare Cache Hit Rate: 7% → 90%	3 Cache Rules + localization optimization
8	Perfect Dark Mode: From Hydration Error to Zero Flicker	Troubleshooting 8 pitfalls
9	6 Pitfalls of Multilingual Sites	query string → path prefix, 3 rounds of redesign

Project Info

Website: utlkit.com
Stack: Next.js 15 + React 18 + TypeScript + Tailwind CSS
Hosting: Cloudflare Pages
Tools: 150+ tools, 8 categories
Cost: $0/month

If you find this helpful, follow along for the rest of the series. Constructive feedback welcome in the comments.

I Spent 2 Months Building a 150+ Tool Website with $0 Server Cost

Mark — Mon, 01 Jun 2026 12:57:55 +0000

📚 This is Part 1 (Opening) of the UtlKit Tech Series —

Next: Architecture & Trade-offs →

As a frontend developer, I've used countless online tools. And almost all of them suck:

Sign-up required — just to format a JSON string?
Ad overload — the actual tool gets squeezed into a corner
Privacy concerns — your JSON might contain API keys, and the tool sends it to a server
Fragmented — formatters on one site, Base64 on another, hashing on a third

So I decided to build one that doesn't: no sign-up, no ads, pure client-side computation, data never leaves the browser.

The goal was simple — if I need this tool, someone else does too.

The result is utlkit.com: 150+ tools, 8 categories, zero server costs.

Requirements

Requirement	Meaning
Pure client-side	All logic runs in the browser
Zero server cost	Static hosting, no Node.js backend
150+ pages	One page per tool, SEO-friendly
Bilingual (EN/ZH)	i18n support
Dark/Light mode	User preference
Mobile responsive	Works on all devices

Why Not Other Frameworks?

Option	Pros	Cons	Verdict
Vanilla HTML/JS	Simple	Managing 150+ pages is painful	Too slow
VuePress / VitePress	Fast	Docs-oriented, not for interactive tools	Not flexible enough
Nuxt SSR	Powerful	Needs a server	Violates zero-cost principle
Next.js 15 + `output: 'export'`	SSR SEO + client interactivity + static hosting	Has pitfalls (covered later)	✅ Best balance

The Key Decision: `output: 'export'`

// next.config.js
const nextConfig = {
  output: 'export',       // Static export
  trailingSlash: true,    // Required for static files
  images: { unoptimized: true }, // No image optimization server
}

This means:

✅ Build output is plain HTML/CSS/JS files
✅ Deployable to any static host (Cloudflare Pages, Vercel, GitHub Pages)
✅ Zero server cost
❌ No API Routes, no Server Components, limited dynamic routing

Deployment: Zero Cost on Cloudflare Pages

Build output: out/ directory, ~14 MB
Hosting: Cloudflare Pages
Domain: utlkit.com
Monthly cost: $0

Build Pipeline

npm run build
  → next build (output: 'export')
  → Generates out/ directory
  → clean-index-txt.js (removes index.txt)
  → Outputs 150+ static HTML files

Cloudflare Pages CI/CD: git push → auto build → auto deploy, ~3 minutes to production.

What's Coming Next in This Series

Above is the story and the tech choices. The following articles cover real-world pitfalls:

Part	Title	Core Problem
1	Architecture and Trade-offs	Structure, reusability & trade-offs
2	React 19 Hydration Mismatch in Static Export	SSR/CSR inconsistency
3	Cloudflare Pages Blank Page: the index.txt Bug	Content negotiation mechanism
4	Why Node.js Libraries Fail in the Browser	`fs` dependencies, ESM/CJS interop
5	Sentry Source Maps: From 0% to Full Resolution	Tree-shaking, HTTP API, region detection
6	Client-Side Encryption with Web Crypto API	MD5 gap, AES-GCM, HMAC
7	Free Performance Monitoring: PageSpeed CI	Zero-cost Core Web Vitals monitoring
8	Cloudflare Cache Hit Rate: 7% → 90%	3 Cache Rules + localization optimization
9	Perfect Dark Mode: From Hydration Error to Zero Flicker	Troubleshooting 8 pitfalls
10	6 Pitfalls of Multilingual Sites	query string → path prefix, 3 rounds of redesign

Each article includes full debugging process, code examples, and lessons learned.

📚 This is Part 1 (Opening) of the UtlKit Tech Series — > - Next: Architecture & Trade-offs →

Project Info

Website: utlkit.com
Stack: Next.js 15 + React 18 + TypeScript + Tailwind CSS
Hosting: Cloudflare Pages
Tools: 150+ tools, 8 categories
Cost: $0/month

Part 2 will cover architecture design: directory structure, component abstraction, browser-only trade-offs, and i18n approach. Follow along for the full series.

DEV Community: Mark

Cloudflare Pages Blank Page? The index.txt Trap with Next.js Static Export

The Problem

Debugging Process

Step 1: Check Cloudflare Cache

Step 2: Browser DevTools

Step 3: Content Negotiation

Root Cause Analysis

Next.js 15 Prefetch Behavior

Next.js Static Export Creates index.txt

Cloudflare Pages File Matching

The Complete Bug Chain

Evolution: From Blank Screen to 404 Flood

The Problem

Impact

Better Approach: Create Empty index.txt

Why Creating Is Better Than Deleting

Lessons Learned

Project

React 19 Hydration Mismatch in Static Export

React 19 Static Export Hydration Mismatch? Pitfalls in Next.js 15

The Problem

Root Cause Analysis

Layer 1: React 19 RSC and Static Export Compatibility

Layer 2: Dynamic className on <html> and <body>

Layer 3: Terser Made Things Worse

Solutions (Progressive)

Solution 1: suppressHydrationWarning (Quick Fix)

Solution 2: Head Script to Pre-read Theme (Eliminates Flash)

Solution 3: Downgrade React 19 → 18 (Root Fix)

Final Solution (What's in Production)

Lessons Learned

Project

150+ Tools with Only 2 Layout Components: UtlKit Architecture Design

150+ Tools with Only 2 Layout Components: UtlKit Architecture Design

Overall Architecture

Directory Structure

Component Abstraction: 80% of Tools Share Layouts

1. ConverterLayout — Input → Process → Output

2. ToolSection — Form → Calculate → Result

Browser-Only Trade-offs

The Biggest Trade-off: No Node.js Ecosystem

Encryption: Web Crypto API Limitations

i18n: Bilingual Design

From 0 to 1 to 100

Project Info

I Spent 2 Months Building a 150+ Tool Website with $0 Server Cost

Requirements

Why Not Other Frameworks?

The Key Decision: output: 'export'

Deployment: Zero Cost on Cloudflare Pages

Build Pipeline

What's Coming Next in This Series

Project Info

Layer 2: Dynamic className on `<html>` and `<body>`

The Key Decision: `output: 'export'`