DEV Community: Mark

6 Pitfalls of Building a Multilingual Site with Next.js 15: From Query Strings to URL Paths

Mark — Mon, 24 Aug 2026 05:31:39 +0000

I built a 150+ tool website with Next.js 15 on Cloudflare Pages (utlkit.com).
Half the traffic was from China, half from elsewhere. Time to add i18n.
I thought it would take a day. It took four, and I rewrote the approach three times.

Why is i18n Harder Than You Think?

A 100+ page tool site needs more than translated text. You need to handle:

Layer	Problem
Routing	Does the URL change on language switch? How does Google distinguish en/zh pages?
SEO	Bilingual title/description/keywords? How to set canonical?
Static Export	Many i18n approaches are incompatible with `output: 'export'`
Hydration	Different locale SSR vs CSR causing mismatches
Scale	104 tool pages × 500+ i18n keys — can't do this manually

I went through query string → subdirectory → path prefix before settling on the [locale] route segment approach.

Approach Comparison

Approach 1: Query String (First Attempt, Quickly Abandoned)

URL format: /tools/bmi-calculator/?lang=zh-CN

Pros:

Minimal code changes, just read the query parameter

Fatal Flaws:

SEO disaster — Search engines treat ?lang=zh and / as the same page. Chinese content becomes duplicate content.
Cache issues — Cloudflare caches by URL. The cached version without query overrides the version with query.
Social sharing — Users share the link without the lang parameter.

Verdict: Never do this for a multilingual site.

Approach 2: Subdirectory

URL format: /en/tools/bmi-calculator/ and /zh/tools/bmi-calculator/

This is the most common multilingual URL pattern (GitHub, Stripe use this).

Pros:

SEO-friendly, search engines clearly distinguish language versions
Industry best practice

Approach 3: Path Prefix `[locale]` (Final Choice)

URL format: /en/tools/bmi-calculator/ and /zh-CN/tools/bmi-calculator/

Essentially the same as Approach 2, but using Next.js's [locale] dynamic route segment instead of separate /en/ and /zh/ directories.

Why this won:

Perfect SEO (each language has its own URL)
Next.js natively supports [locale] dynamic routing
Works with generateStaticParams() for static prerendering
Adding a third language later is just adding a string

Pitfall 1: Nested Root Layout

The Problem

Page crashes or goes white after switching language.

Root Cause

In Next.js 15 App Router, both app/layout.tsx and app/[locale]/layout.tsx render. If both include <html> and <body> tags, you get nested HTML:

<html>                    <!-- app/layout.tsx -->
  <html lang="zh-CN">     <!-- app/[locale]/layout.tsx -->
    <body>
      <body>
        <!-- actual content -->
      </body>
    </body>
  </html>
</html>

Double <html> → double Hydration → unpredictable bugs.

Fix

Root layout returns only children:

// app/layout.tsx — outputs metadata only, no tags
export default function RootLayout({ children }) {
  return children
}

Locale layout renders complete HTML:

// app/[locale]/layout.tsx — renders full html/head/body
<html lang={locale}>
  <head>...</head>
  <body>
    <I18nProvider locale={locale}>
      {children}
    </I18nProvider>
  </body>
</html>

Pitfall 2: redirect() Doesn't Work with Static Export

The Problem

Wanted to redirect root path / to /en/ or /zh-CN/ based on browser language, but redirect() did nothing.

Root Cause

Next.js redirect() relies on server-side runtime. In output: 'export' (pure static export) mode, there is no server runtime — redirect() is silently skipped.

Fix

Client-side JS detection with redirect:

// app/page.tsx
export default function RootPage() {
  return (
    <>
      <script dangerouslySetInnerHTML={{
        __html: `(function(){
          var lang = (navigator.language || 'en').toLowerCase();
          var target = '/en/';
          if (lang.indexOf('zh') === 0) target = '/zh-CN/';
          window.location.replace(target);
        })()`,
      }} />
      {/* Fallback for no-JS environments */}
      <noscript>
        <meta httpEquiv="refresh" content="0;url=/en/" />
      </noscript>
    </>
  )
}

Key points:

window.location.replace() instead of href — no extra history entry
<noscript> fallback — prevents being stuck in no-JS environments

Pitfall 3: Passing Locale to generateMetadata

The Problem

All tool page titles showed in English even when visiting /zh-CN/.

Root Cause

In Next.js 15, generateMetadata() receives params as an async promise:

// ❌ Old way — params is a Promise, not a plain object
export async function generateMetadata({ params }) {
  const { locale } = params  // undefined or error
}

Fix

// ✅ Next.js 15 way: params is a Promise
export async function generateMetadata(props) {
  const { locale, slug } = await props.params
  const [en, zhCN] = await Promise.all([
    import('@/lib/i18n/en'),
    import('@/lib/i18n/zh-CN'),
  ])
  const dict = { en: en.default, 'zh-CN': zhCN.default }
  const t = (key) => dict[locale]?.[key] || key

  return {
    title: `${t(tool.nameI18n)} - UtlKit`,
    description: t(tool.descI18n),
    alternates: {
      canonical: `https://utlkit.com/${locale}/tools/${slug}/`,
      languages: {
        'en': `https://utlkit.com/en/tools/${slug}/`,
        'zh-CN': `https://utlkit.com/zh-CN/tools/${slug}/`,
      },
    },
  }
}

Key points:

params is a Promise — must await props.params
Server Components can await import() translation files (tree-shaking friendly)
alternates.languages tells search engines about multilingual page variants

Pitfall 4: Content Doesn't Refresh on Language Switch

The Problem

User switches language from Header. URL changes but page content stays the same.

Root Cause

I18nProvider's setLocale initially only changed React state:

// ❌ Only changes state, doesn't refresh the page
const setLocale = (locale) => {
  setLocaleState(locale)
  setStoredLocale(locale)
}

With [locale] routing, a language change requires navigating to a different URL (from /en/xxx to /zh-CN/xxx), not just changing state — because server-rendered SEO metadata is URL-based.

Fix

setLocale navigates to the new URL:

const setLocale = useCallback((newLocale) => {
  if (typeof window === 'undefined') return
  const currentPath = window.location.pathname
  const parts = currentPath.split('/')
  const firstSegment = parts[1]
  if (firstSegment === 'en' || firstSegment === 'zh-CN') {
    // In [locale] route — replace language segment in URL
    const afterLocale = currentPath.slice(firstSegment.length + 1)
    const newPath = '/' + newLocale + (afterLocale ? '/' + afterLocale : '')
    window.location.href = newPath  // Hard navigation, re-SSR
    return
  }
  // Fallback: root route
  setLocaleState(newLocale)
  setStoredLocale(newLocale)
}, [])

Key decision: Use window.location.href hard navigation instead of router.push — because we need full SSR to update metadata.

Pitfall 5: Sitemap Doesn't Support Multilingual

The Problem

Sitemap only generated English URLs. Chinese pages weren't indexed.

Root Cause

app/sitemap.ts defaulted to single-language URLs:

// ❌ English only
{ url: 'https://utlkit.com/tools/bmi-calculator/' }

Fix

Generate bilingual URLs for every page:

// app/sitemap.ts
export default function sitemap() {
  const baseUrl = 'https://utlkit.com'
  const locales = ['en', 'zh-CN']

  const entries = [{ url: baseUrl, priority: 1 }] // root URL

  // Static pages: en + zh-CN
  for (const locale of locales) {
    for (const slug of ['about', 'privacy', 'terms', 'contact']) {
      entries.push({ url: `${baseUrl}/${locale}/${slug}/`, priority: 0.5 })
    }
  }

  // Tool pages: 104 tools × 2 languages = 208 entries
  for (const locale of locales) {
    for (const tool of tools) {
      entries.push({
        url: `${baseUrl}/${locale}/tools/${tool.slug}/`,
        priority: locale === 'en' ? 0.8 : 0.6,
      })
    }
  }

  return entries
}

Final count: 213 URLs (102 tools × 2 + 4 static × 2 + root + sitemap page × 2).

Bonus: The sitemap page's <link> elements also needed to be locale-aware, otherwise they'd link to old paths.

Pitfall 6: 500+ i18n Keys to Translate

The Problem

104 tool pages, each with title, description, placeholder, label, tooltip, FAQ — the translation workload far exceeded expectations.

Solution

Establish a naming convention for i18n keys:

// tools.ts — tool definitions with i18n keys
{
  nameI18n: 'tools.bmi.title',      // → en: 'BMI Calculator'
  descI18n: 'tools.bmi.description', // → en: 'Calculate your BMI...'
}

Batch process with scripts:

// scripts/fix-tool-metadata.js
// Batch-update 102 tool page metadata from hardcoded to i18n
const tools = require('../src/lib/tools')
for (const tool of tools) {
  // Generate bilingual metadata template...
}

Phased rollout:

Global components first (Header/Footer)
Batch tool page metadata (script-generated)
Tool component UI text (placeholders, labels, etc.)
FAQ and special pages last

Total: ~500+ i18n keys covering all user-visible text.

Final Architecture

┌─────────────────────────────────────────────┐
│ Root path /                                 │
│ Detects navigator.language, JS redirects    │
├─────────────────────────────────────────────┤
│ /[locale]/layout.tsx                        │
│ - generateStaticParams: ['en', 'zh-CN']     │
│ - generateMetadata: bilingual metadata      │
│ - Renders complete <html lang={locale}>     │
├─────────────────────────────────────────────┤
│ /[locale]/page.tsx (home page)              │
│ - Bilingual metadata                        │
│ - Hero section + tool list                  │
├─────────────────────────────────────────────┤
│ /[locale]/tools/[slug]/page.tsx (tool page) │
│ - generateMetadata: reads translation       │
│ - alternates.languages: bilingual canonical │
├─────────────────────────────────────────────┤
│ I18nProvider (client)                       │
│ - Reads locale from URL path (SSR passed)   │
│ - setLocale: navigates to target URL        │
│ - t(key): translation function              │
│ - href(path): generates locale-aware links  │
└─────────────────────────────────────────────┘

Lessons Learned

Approach	Result	Rating
Query string `?lang=zh`	❌ SEO disaster	⭐
Subdomain `zh.example.com`	⚠️ Complex deployment	⭐⭐
Path prefix `[locale]`	✅ Perfect SEO	⭐⭐⭐⭐⭐
Only change React state	❌ Metadata out of sync	⭐
Hard navigation `location.href`	✅ Full SSR refresh	⭐⭐⭐⭐

Key takeaways:

Multilingual sites need separate URLs — Search engines must distinguish language versions; query strings won't cut it
[locale] route is the most Next.js-native approach — generateStaticParams works perfectly with static export
Don't nest root and locale layouts — Only locale layout should render <html>
Use hard navigation for language switching — location.href instead of router.push to ensure metadata re-SSR
generateMetadata params is a Promise — Next.js 15 change; forgetting await means no locale
Sitemap must explicitly generate each language's URL — Won't auto-infer
i18n key naming needs a convention — 500+ keys without one is chaos
alternates.languages is critical for SEO — Tells search engines about all language variants of each page

Project

UtlKit — 150+ free online tools with English and Chinese support. All the above problems were encountered during real development and deployment. Solutions are running in production.

If this helped, feel free to drop a ⭐️. Comments welcome.

Next.js 15 Dark Mode Without the Flash: From Hydration Error to Zero-Flicker

Mark — Mon, 17 Aug 2026 09:53:37 +0000

I built a 100+ tool website with Next.js 15 on Cloudflare Pages.
I thought implementing dark mode would take half a day. It took three, and I hit 8 different bugs along the way.

The Problem List

#	Problem	Status
1	React Hydration Error #418	✅ Fixed
2	White screen flash on load	✅ Fixed
3	`SyntaxError: missing ) after argument list`	✅ Fixed
4	Toggle icon never changes	✅ Fixed
5	Theme lost after SPA navigation	✅ Fixed

Each fix introduced a new problem. The final solution looks simple, but the path to get there was anything but.

Pitfall 1: React Hydration Error #418

The Problem

Chrome DevTools filled with red:

Error: Hydration failed because the server HTML didn't match the client.

Root Cause

The project started with next-themes:

// ❌ next-themes causes SSR/CSR mismatch
<ThemeProvider attribute="class" defaultTheme="dark">
  <html>{children}</html>
</ThemeProvider>

next-themes makes SSR render HTML without a theme class, but CSR adds class="dark". React 19 reports Hydration Error.

The toggle button was also a problem:

// ❌ Conditional rendering → text mismatch between SSR and CSR
<button onClick={toggle}>
  {isDark ? '☀️' : '🌙'}
</button>

SSR renders ☀️ (default dark). CSR renders 🌙 (if user's system is light). Different text → Error #418.

Fix

Drop next-themes. Use CSS to toggle icon visibility instead of conditional rendering — both icons always render in the DOM:

// ✅ Both icons always rendered, CSS controls visibility
<span className="theme-toggle-light-icon">🌙</span>
<span className="theme-toggle-dark-icon">☀️</span>

[data-theme="light"] .theme-toggle-light-icon { display: inline; }
[data-theme="light"] .theme-toggle-dark-icon { display: none; }
[data-theme="dark"] .theme-toggle-light-icon { display: none; }
[data-theme="dark"] .theme-toggle-dark-icon { display: inline; }

SSR and CSR text content is identical (🌙☀️), only CSS display differs. No hydration mismatch.

Pitfall 2: White Screen Flash

The Problem

Page flashes white before switching to dark mode.

First Fix: head script

<script>
  (function(){
    var s = localStorage.getItem('theme') || 'dark';
    document.documentElement.classList.add(s);
  })();
</script>

Result: Flash gone ✅
New problem: Theme lost after SPA navigation

Second Fix: Intercept pushState

var p = history.pushState;
history.pushState = function(){ p.apply(this, arguments); restoreTheme() };

Result: SPA navigation preserves theme ✅

Pitfall 3: Console SyntaxError

The Problem

Uncaught SyntaxError: missing ) after argument list at bmi-calculator/:1:4908

Root Cause

The <script> in <head> used dangerouslySetInnerHTML:

<script dangerouslySetInnerHTML={{ __html: `(function(){...&&...})()` }} />

Next.js 15's RSC (React Server Components) serializes the __html content into RSC payload data. During serialization, && gets escaped to \u0026\u0026, causing a syntax error when the client executes it.

The inline HTML script is fine — but the RSC payload copy is broken.

Fix: Move to an External JS File

// ❌ Serialized by RSC → SyntaxError
<script dangerouslySetInnerHTML={{ __html: '...' }} />

// ✅ External file, immune to RSC serialization
<script src="/theme-init.js" />

Result: SyntaxError gone ✅
New problem: External JS requires an HTTP request → the first frame renders before JS executes → flash returns

Pitfall 4: External JS Still Flashes

Root Cause

<script src="/theme-init.js"> needs the browser to send an HTTP request, download the file, then execute it. Meanwhile the browser has already rendered the first frame using the default light CSS.

Fix: CSS `@media (prefers-color-scheme)` as the default

Core idea: Make the browser render the correct theme without any JavaScript.

/* Default: light */
:root {
  --bg: #f8fafc;
  --surface: #ffffff;
  --border: #e2e8f0;
  --text: #1e293b;
}

/* System prefers dark: @media overrides */
@media (prefers-color-scheme: dark) {
  :root {
    --bg: #0f172a;
    --surface: #1e293b;
    --border: #334155;
    --text: #e2e8f0;
  }
}

/* User explicitly chose a theme: data-theme overrides @media */
html[data-theme="dark"] {
  --bg: #0f172a !important;
  --surface: #1e293b !important;
  --border: #334155 !important;
  --text: #e2e8f0 !important;
}

html[data-theme="light"] {
  --bg: #f8fafc !important;
  --surface: #ffffff !important;
  --border: #e2e8f0 !important;
  --text: #1e293b !important;
}

Three-layer priority:

:root defaults to light
@media (prefers-color-scheme: dark) overrides for system preference
[data-theme] with !important forces user's explicit choice

The browser knows the colors while parsing CSS — no JavaScript needed for the first frame.

Pitfall 5: Toggle Icon Never Changes

The Problem

Theme switching works (the page actually changes), but the button always shows 🌙.

Root Cause

Tailwind CSS's dark: prefix (like dark:hidden) with darkMode: 'class' requires a .dark class. But Tailwind v4 ignores the variant configuration — dark: is always bound to @media (prefers-color-scheme: dark).

So dark:hidden only follows the system setting, not the JS-set data-theme. If the user's system is light but they manually switch to dark, dark:hidden still doesn't trigger.

Fix: Custom CSS Classes

Skip Tailwind's dark: prefix entirely:

[data-theme="light"] .theme-toggle-light-icon,
:not([data-theme]) .theme-toggle-light-icon {
  display: inline;
}
[data-theme="light"] .theme-toggle-dark-icon,
:not([data-theme]) .theme-toggle-dark-icon {
  display: none;
}
[data-theme="dark"] .theme-toggle-light-icon {
  display: none;
}
[data-theme="dark"] .theme-toggle-dark-icon {
  display: inline;
}

:not([data-theme]) covers the default state when the user hasn't made a choice (default light, show 🌙).

Final Architecture

┌─────────────────────────────────────────────┐
│ Layer 1: CSS @media (prefers-color-scheme)  │
│  Native browser support, zero JS, correct   │
│  on the very first frame                    │
├─────────────────────────────────────────────┤
│ Layer 2: theme-init.js sets data-theme      │
│  Reads localStorage, overrides @media       │
│  Intercepts pushState for SPA navigation    │
├─────────────────────────────────────────────┤
│ Layer 3: ThemeProvider (React)              │
│  Syncs React state, handles user toggle     │
└─────────────────────────────────────────────┘

Key Files

public/theme-init.js — Runs before React:

(function(){
  try{
    var d = document.documentElement;
    var stored = localStorage.getItem('theme');
    var isDark;
    if(stored === 'light') isDark = false;
    else if(stored === 'dark') isDark = true;
    else isDark = window.matchMedia('(prefers-color-scheme:dark)').matches;

    if(isDark) d.setAttribute('data-theme', 'dark');
    else d.setAttribute('data-theme', 'light');

    // Restore after SPA navigation
    function restore(){
      if(!d.getAttribute('data-theme')){
        // Re-read and set...
      }
    }
    var p = history.pushState;
    history.pushState = function(){
      p.apply(this, arguments);
      requestAnimationFrame(restore);
    };
    // Same for replaceState and popstate...
  }catch(e){}
})();

app/[locale]/layout.tsx — Reference external JS:

<head>
  <script src="/theme-init.js" />
</head>

components/ThemeProvider.tsx — React state management:

function setTheme(theme: 'light' | 'dark' | 'system') {
  const resolved = theme === 'system' ? getSystemTheme() : theme
  localStorage.setItem(THEME_KEY, theme)
  const el = document.documentElement
  el.setAttribute('data-theme', resolved)
  el.classList.remove('dark', 'light')
  el.classList.add(resolved)
}

globals.css — Three-tier CSS variables + toggle icons:

/* Default light */
:root { --bg: #f8fafc; --text: #1e293b; ... }

/* System dark override */
@media (prefers-color-scheme: dark) {
  :root { --bg: #0f172a; --text: #e2e8f0; ... }
}

/* User explicit choice forces override */
html[data-theme="dark"] { --bg: #0f172a !important; ... }
html[data-theme="light"] { --bg: #f8fafc !important; ... }

/* Toggle button icons */
[data-theme="dark"] .theme-toggle-light-icon { display: none; }
[data-theme="dark"] .theme-toggle-dark-icon { display: inline; }
[data-theme="light"] .theme-toggle-light-icon { display: inline; }
[data-theme="light"] .theme-toggle-dark-icon { display: none; }

Lessons Learned

Approach	Result
`next-themes`	❌ Hydration Error #418
`dangerouslySetInnerHTML` in `<head>`	❌ RSC serialization SyntaxError
`<script src>` external file	⚠️ HTTP request → still flashes one frame
Tailwind `dark:` prefix	⚠️ v4 always binds to media query, ignores JS
`@media` default + `data-theme` override	✅ Perfect

Key takeaways:

dangerouslySetInnerHTML in <head> is a trap — Next.js RSC serializes __html, turning && into \u0026\u0026 → syntax error
External JS is one frame slower than inline — Requires HTTP request; first frame renders before JS executes
CSS @media is the only way to eliminate flash completely — Browser knows colors during CSS parsing, no JavaScript needed
Tailwind v4's darkMode config is unreliable — variant is ignored; dark: always binds to @media prefers-color-scheme
Three-tier priority strategy — :root default → @media for system → [data-theme] for user choice
SPA navigation clears <html> classes — Must intercept pushState/replaceState to restore theme

Project

UtlKit — 150+ free online tools. All the above problems were encountered during real development and deployment. Solutions are running in production.

If this helped, feel free to drop a ⭐️. Comments welcome.

Cloudflare Cache Hit Rate: 7% to 90%

Mark — Sun, 02 Aug 2026 14:41:05 +0000

Cloudflare Pages Cache Hit Rate at 7%? I Brought It to 90% with 3 Rules

After deploying utlkit.com to Cloudflare Pages, domestic (China) access was painfully slow.
LCP P75 hit 20 seconds. Cache hit rate was only 7.62%.
3 Cache Rules + 1 localization fix later: 90%+ hit rate, first paint from 20s down to 3s.

The Problem

After deploying utlkit.com to Cloudflare Pages, users in China reported extremely slow load times. Opening Chrome DevTools revealed LCP P75 at 20 seconds, P90 at 26 seconds.

I checked Cloudflare's Cache Analytics:

Cache hit rate: 7.62%.

That means 92% of requests were origin fetches — no cache hit at all. For Cloudflare Pages, each "origin fetch" means reading from object storage, pushing TTFB from milliseconds to several seconds. Combined with China's network conditions to overseas servers, the experience was terrible.

Root Cause Analysis

Why was the cache hit rate so low?

Cloudflare's default behavior is to not cache HTML pages (or use a very short Edge TTL), because dynamic sites need fresh content. But for a purely static site, this default is completely wrong.

Three specific reasons:

1. Cloudflare doesn't cache HTML by default

Cloudflare's design philosophy is "your origin knows best". If the origin doesn't send explicit Cache-Control headers, CF uses a 2-hour Edge TTL for HTML — and often bypasses cache entirely.

2. _headers only controls browser caching, not Cloudflare edge caching

I had _headers configured in my project:

# out/_headers
/*
  Cache-Control: public, max-age=86400, stale-while-revalidate=604800

This tells the browser to cache the page for 1 day. But does Cloudflare's edge node respect it? Not necessarily. _headers sets response headers for the browser — it has limited direct impact on CF edge caching behavior.

3. Cookies cause cache bypass

Cloudflare's default behavior: if a request carries cookies, bypass the cache. After users interact with your site (click buttons, fill forms), the browser sends cookies on subsequent requests. For a tools site, after using one tool, navigating to another — cookies come along, and cache is bypassed every time.

The Solution

Approach Comparison

Approach	Effect	Cost	Complexity	Best For
Cache Rules	★★★★	Free	Low	All sites
IP Optimization + Worker Proxy	★★★★★	Free	High	Heavy CF users
China CDN → CF origin	★★★★★	$8+/mo	Medium	ICP-filed domains
`_headers` only	★★	Free	Very low	Supplement only

Conclusion: Cache Rules is the best bang-for-buck. Start here.

Step 1: Create Cache Rules

Go to Cloudflare Dashboard → Caching → Cache Rules → Create Rule.

The free plan allows 3 rules — exactly what we need.

Rule 1: Long Cache for Static Assets (highest priority)

Conditions:

HTTP Host equals "utlkit.com"
AND
HTTP Request URI matches one of:
  /_next/static/*
  /fonts/*

Actions:

Edge TTL → Ignore cache-control header, 30 days
Browser TTL → Override, 30 days
Ignore query string ✅

All files under /_next/static/ in Next.js include content hashes in their filenames. If content changes, the filename changes — so it's safe to cache aggressively. Same for fonts.

Rule 2: Short Cache for Sitemap

Conditions:

HTTP Host equals "utlkit.com"
AND
HTTP Request URI matches one of:
  /sitemap.xml
  /robots.txt

Actions:

Edge TTL → Ignore cache-control, 1 day
Browser TTL → Override, 1 day

Rule 3: HTML Page Cache (catch-all, most important)

Conditions:

HTTP Host equals "utlkit.com"

Actions:

Edge TTL → Ignore cache-control header, 14 days
Browser TTL → Override, 7 days
Ignore query string ✅ (critical! /?cat=finance and / share the same cache)

How long should Edge TTL be? Too short and caching is useless; too long and users see stale content after deploys. Cloudflare Pages auto-purges cache on every deploy, so Edge TTL can be long. Browser TTL should be shorter (7 days) to avoid users being stuck on old versions forever.

Rule order: Static assets → Sitemap → HTML (catch-all last)

Step 2: Purge Everything

After creating rules, go to Caching → Configuration → Purge Everything to clear old cache.

Step 3: Verify

# First request
$ curl -sI https://utlkit.com/ | grep cf-cache-status
cf-cache-status: MISS    ← Normal, first request

# Second request
$ curl -sI https://utlkit.com/ | grep cf-cache-status
cf-cache-status: HIT     ← Working!

Verify key resources:

# Tool page
curl -sI https://utlkit.com/tools/bmi-calculator/ | grep cf-cache-status
# MISS → HIT ✅

# JS chunk
curl -sI https://utlkit.com/_next/static/chunks/main-app-xxx.js | grep cf-cache-status
# MISS → HIT ✅

# CSS
curl -sI https://utlkit.com/_next/static/css/xxx.css | grep cf-cache-status
# MISS → HIT ✅

Additional Fix: Localizing Sentry CDN

During debugging, I also found this in layout.tsx:

<script src="https://browser.sentry-cdn.com/8.30.0/bundle.min.js" />

browser.sentry-cdn.com frequently times out from China (sometimes completely unreachable). This 70KB script sits in <head> and blocks page rendering.

Simple fix: download it to public/:

curl -o public/sentry-bundle.min.js \
  https://browser.sentry-cdn.com/8.30.0/bundle.min.js

Update the reference:

- <script src="https://browser.sentry-cdn.com/8.30.0/bundle.min.js" />
+ <script src="/sentry-bundle.min.js" />

Now the script is served through Cloudflare's own CDN — instant load in China.

⚠️ Note: Remember to manually update this file when Sentry releases new versions. Set a reminder to check quarterly.

Results

Metric	Before	After
Cache hit rate	7.62%	90%+
Homepage TTFB (cache hit)	2-7s	200-400ms
LCP P75	20s	2-3s
First paint in China	Often 10s+	Stable 3-5s

Lessons Learned

Lesson 1: Cloudflare's new UI doesn't match old tutorials

Most online guides are based on the old Cache Rules interface. The parameter names and layout are completely different in the 2024+ UI. Settings like "Cache Level" and "Edge TTL" are now in sub-panels.

Fix: Edge TTL is now a dropdown — select "Ignore cache-control header and use this TTL" to unlock the time input. Maximum selectable: 30 days.

Lesson 2: Not ignoring query strings splits your cache

The homepage gets frequent visits as /?cat=finance, /?cat=developer, etc. Without ignoring query strings, CF treats each unique query as a different cache key. 104 tools × 8 categories = 800+ cache variants, killing your hit rate.

Fix: Enable "Ignore query string" so all queries share the same cached version.

Lesson 3: Browser TTL too long means users see stale content after deploys

I initially set Browser TTL to 14 days. After deploying a new version, a colleague complained "why is it still the old version?". Browser cache isn't affected by CF Purge — it only expires when TTL runs out.

Fix: Drop Browser TTL to 7 days, keep Edge TTL at 14 days. CF auto-purges Edge cache on deploy, so new visitors see the new version immediately. Returning users gradually update over 7 days.

Advanced: IP Optimization for China

If your site is still slow in China even with cache hits (because Cloudflare's default Anycast IPs route through congested international backbones), consider IP Optimization + Worker Proxy:

Create cdn.yourdomain.com in DNS (DNS only / grey cloud), CNAME to a third-party optimized IP pool
All subdomains grey-cloud CNAME to cdn.yourdomain.com
Pages doesn't support routes — use a Worker as reverse proxy
Worker uses route mode (supports IP optimization), forwards to Pages

This can reduce China latency from 300-500ms to 50-100ms, but maintenance is significantly more complex. For a tools site, Cache Rules optimization is usually enough.

Summary

Cloudflare Pages free plan + 3 Cache Rules = good enough global CDN.

Three key takeaways:

Explicitly tell CF to cache HTML (it doesn't by default)
Ignore query strings (prevents cache fragmentation)
Separate Edge TTL from Browser TTL (Edge long, Browser short)

Free, simple, and highly effective.

*Based on the real-world optimization of utlkit.com. Site: utlkit.com

Free Website Performance Monitoring: PageSpeed CI + CrUX + GitHub Actions

Mark — Sun, 26 Jul 2026 07:33:03 +0000

Commercial performance monitoring starts at $29-99/month.
With Google PageSpeed API + GitHub Actions, you get continuous monitoring at $0.

The Need

After launching a site, you need to continuously monitor Core Web Vitals:

LCP (Largest Contentful Paint)
CLS (Cumulative Layout Shift)
INP (Interaction to Next Paint)

Commercial options: Speedcurve, Calibre, Sentry Performance — starting at $29-99/month.

Free option: Build it yourself.

Architecture

GitHub Actions (cron daily)
  → Call PageSpeed Insights API
    → Parse LCP/CLS/INP scores
      → Store as GitHub Artifact (historical comparison)
        → Score below threshold → Alert via PR/Issue

PageSpeed API Free Tier

QPS: 20 requests/second
Daily quota: ~1,250 push triggers + daily cron is more than enough
API Key: Optional (higher limits with key)
Free tier: More than sufficient for personal projects

Implementation

Step 1: Base Workflow

# .github/workflows/pagespeed.yml
name: PageSpeed Insights

on:
  schedule:
    - cron: '0 0 * * *'  # Daily at UTC 00:00
  push:
    branches: [main]

jobs:
  pagespeed:
    runs-on: ubuntu-latest
    steps:
      - name: Run PageSpeed
        run: |
          URL="https://utlkit.com"
          API_KEY="${{ secrets.PAGESPEED_API_KEY }}"

          curl -s "https://pagespeedonline.googleapis.com/pagespeedonline/v5/runPagespeed?url=${URL}&category=PERFORMANCE&category=ACCESSIBILITY&strategy=mobile${API_KEY:+&key=${API_KEY}}" \
            -o pagespeed-mobile.json

          curl -s "https://pagespeedonline.googleapis.com/pagespeedonline/v5/runPagespeed?url=${URL}&category=PERFORMANCE&category=ACCESSIBILITY&strategy=desktop${API_KEY:+&key=${API_KEY}}" \
            -o pagespeed-desktop.json

      - name: Extract scores
        run: |
          echo "Mobile Performance: $(jq '.categories.performance.score' pagespeed-mobile.json)"
          echo "Mobile Accessibility: $(jq '.categories.accessibility.score' pagespeed-mobile.json)"
          echo "Desktop Performance: $(jq '.categories.performance.score' pagespeed-desktop.json)"

      - name: Upload results
        uses: actions/upload-artifact@v4
        with:
          name: pagespeed-${{ github.sha }}
          path: pagespeed-*.json
          retention-days: 90

Step 2: Add Retry Logic

PageSpeed API occasionally returns 429 (rate limited) or 500:

MAX_RETRIES=3
RETRY_DELAY=5

for i in $(seq 1 $MAX_RETRIES); do
  HTTP_CODE=$(curl -s -o response.json -w "%{http_code}" \
    "https://pagespeedonline.googleapis.com/pagespeedonline/v5/runPagespeed?url=${URL}&strategy=${STRATEGY}${API_KEY:+&key=${API_KEY}}")

  if [ "$HTTP_CODE" = "200" ]; then exit 0; fi

  if [ "$HTTP_CODE" = "429" ]; then
    echo "Rate limited, waiting ${RETRY_DELAY}s..."
    sleep $RETRY_DELAY
    RETRY_DELAY=$((RETRY_DELAY * 2))  # Exponential backoff
  else
    sleep $RETRY_DELAY
  fi
done

echo "Failed after $MAX_RETRIES retries"
exit 1

Step 3: Add Alerts

LCP=$(jq '.audits.largest-contentful-paint.score' pagespeed-mobile.json)
CLS=$(jq '.audits.cumulative-layout-shift.score' pagespeed-mobile.json)
INP=$(jq '.audits.interaction-to-next-paint.score' pagespeed-mobile.json)

# Threshold alert (Google recommends: ≥90 good, ≥50 needs improvement)
if [ "$LCP" -lt 50 ] || [ "$CLS" -lt 50 ] || [ "$INP" -lt 50 ]; then
  echo "::warning title=Core Web Vitals below threshold::LCP=$LCP, CLS=$CLS, INP=$INP"
fi

Step 4: CrUX Dashboard Integration

Chrome UX Report (CrUX) provides real user performance data:

Visit https://chromestatus.com/speed
Enter your domain
View real-world LCP/CLS/INP distributions

This data is more authentic than PSI's lab data — it reflects global Chrome users' actual experience.

Real Debugging Case: CLS Spike

PageSpeed CI alert: CLS jumped from 0.01 to 0.25.

Debugging:

PSI details → CLS contributor is the ad slot
Ad slot loads dynamically with unknown height → layout shift
Fix: Set aspect-ratio on ad container to reserve space
Redeploy → CI runs PSI → CLS back to 0.01

Without CI, this regression wouldn't be found until users complained.

Cost Comparison

Option	Monthly Cost	Capability
Speedcurve	$99+	Professional
Calibre	$39+	Professional
PageSpeed CI (this approach)	$0	More than enough

Lessons Learned

Configure API Key — Free tier is enough, but a key is more stable
Always add retries — PageSpeed API occasionally 429s
Keep Artifacts for 90 days — Enough to track performance trends
CrUX for real data — PSI is lab data; CrUX is real users
Set alert threshold at 50 — Google's recommended line; too low = false alarms, too high = useless

Project

utlkit.com — 150+ free online tools

Client-Side Encryption with Web Crypto API

Mark — Sun, 19 Jul 2026 15:23:46 +0000

Building a pure-frontend encryption toolset with no backend dependency.
Web Crypto API is powerful — but has some gotchas.

Why Pure Frontend Encryption?

Privacy — Sensitive user data should never reach a server
Trust — Open-source frontend code is auditable; black-box backends aren't
Cost — Zero server cost

What Web Crypto API Supports

✅ SHA-1 / SHA-256 / SHA-384 / SHA-512 (digest)
✅ RSA-OAEP / RSA-PSS (asymmetric)
✅ AES-GCM / AES-CBC / AES-KW (symmetric)
✅ HMAC (signatures)
✅ ECDSA / Ed25519 (elliptic curve)
❌ MD5 (not in spec)
❌ Blowfish / TWOFISH (not in spec)

SHA Hash Family

Simplest usage:

async function sha256(message) {
  const encoder = new TextEncoder()
  const data = encoder.encode(message)
  const hashBuffer = await crypto.subtle.digest('SHA-256', data)
  const hashArray = Array.from(new Uint8Array(hashBuffer))
  return hashArray.map(b => b.toString(16).padStart(2, '0')).join('')
}

sha256('hello')
// → "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"

All five hashes in one call:

async function hashAll(text) {
  const encoder = new TextEncoder()
  const data = encoder.encode(text)
  const algorithms = ['SHA-1', 'SHA-256', 'SHA-384', 'SHA-512']
  const results = {}

  for (const algo of algorithms) {
    const hashBuffer = await crypto.subtle.digest(algo, data)
    results[algo] = Array.from(new Uint8Array(hashBuffer))
      .map(b => b.toString(16).padStart(2, '0'))
      .join('')
  }

  return results
}

MD5: Not in Web Crypto, Implement It Yourself

MD5 is a weak hash, superseded by SHA-2, but still heavily used in practice.

Web Crypto doesn't support it. Implement it yourself:

function md5(string) {
  function md5cycle(x, k) {
    var a = x[0], b = x[1], c = x[2], d = x[3]
    a = ff(a, b, c, d, k[0], 7, -680876936)
    d = ff(d, a, b, c, k[1], 12, -389564586)
    // ... (full MD5 four-round computation)
    x[0] = add32(a, x[0])
    x[1] = add32(b, x[1])
    x[2] = add32(c, x[2])
    x[3] = add32(d, x[3])
  }
  // ... (padding, processing, hex output)
  // ~100 lines total
}

The complete MD5 implementation is about 100 lines — pure bitwise operations, no dependencies.

Performance: For short text (<10KB), pure JS MD5 takes ~5-10ms. More than acceptable.

AES-GCM Encryption

// Generate random key
async function generateAesKey() {
  return crypto.subtle.generateKey(
    { name: 'AES-GCM', length: 256 },
    true,  // exportable
    ['encrypt', 'decrypt']
  )
}

// Encrypt
async function aesEncrypt(plaintext, key) {
  const encoder = new TextEncoder()
  const iv = crypto.getRandomValues(new Uint8Array(12)) // 96-bit IV

  const ciphertext = await crypto.subtle.encrypt(
    { name: 'AES-GCM', iv: iv },
    key,
    encoder.encode(plaintext)
  )

  // Return IV + ciphertext (IV must be transmitted together)
  const result = new Uint8Array(iv.length + ciphertext.byteLength)
  result.set(iv)
  result.set(new Uint8Array(ciphertext), iv.length)
  return btoa(String.fromCharCode(...result)) // Base64 output
}

// Decrypt
async function aesDecrypt(encodedText, key) {
  const data = Uint8Array.from(atob(encodedText), c => c.charCodeAt(0))
  const iv = data.slice(0, 12)
  const ciphertext = data.slice(12)

  const plaintextBuffer = await crypto.subtle.decrypt(
    { name: 'AES-GCM', iv: iv },
    key,
    ciphertext
  )

  return new TextDecoder().decode(plaintextBuffer)
}

Security Best Practices

Random IV every time — Same key encrypting different messages must use different IVs
IV doesn't need to be secret — Transmit it alongside ciphertext
GCM mode includes authentication — Tampered ciphertext fails decryption with an error
Don't persist keys — Key disappears on page refresh

HMAC Signatures

async function hmacSha256(message, keyString) {
  const encoder = new TextEncoder()

  const key = await crypto.subtle.importKey(
    'raw',
    encoder.encode(keyString),
    { name: 'HMAC', hash: 'SHA-256' },
    false,
    ['sign', 'verify']
  )

  const signature = await crypto.subtle.sign('HMAC', key, encoder.encode(message))

  return Array.from(new Uint8Array(signature))
    .map(b => b.toString(16).padStart(2, '0'))
    .join('')
}

async function verifyHmac(message, keyString, expectedSignature) {
  const encoder = new TextEncoder()
  const key = await crypto.subtle.importKey(
    'raw',
    encoder.encode(keyString),
    { name: 'HMAC', hash: 'SHA-256' },
    false,
    ['verify']
  )

  const signatureBytes = Uint8Array.from(
    expectedSignature.match(/.{1,2}/g).map(b => parseInt(b, 16))
  )

  return crypto.subtle.verify('HMAC', key, signatureBytes, encoder.encode(message))
}

Performance Comparison

Size       Algorithm       Time
────────────────────────────────
1 KB       SHA-256         < 1ms
1 KB       MD5 (JS)        ~2ms
1 KB       AES-GCM encrypt ~1ms
100 KB     SHA-256         ~2ms
100 KB     AES-GCM         ~3ms
1 MB       SHA-256         ~15ms
1 MB       AES-GCM         ~20ms

For a tool site processing KB-level data, Web Crypto performance is more than sufficient.

MD5 Alternatives

Approach	Pros	Cons
Pure JS (~100 lines)	No dependencies, controllable	Self-maintained
`blueimp-md5` library	Mature and stable	Extra dependency

The project chose pure JS implementation.

Best Practices Summary

Prefer Web Crypto API — Native, secure, fast
Pure JS for MD5 — Small code, doesn't affect architecture
Don't store keys — Gone on refresh
Generate random IV — Every encryption gets a new IV
Use GCM over CBC — GCM has built-in authentication
HMAC for integrity — More reliable than hash alone

Project

Hash Generator — AES Encrypt/Decrypt — HMAC Generator

Sentry Source Map Upload Debugging: From 0% Adoption to Full Resolution

Mark — Sun, 12 Jul 2026 15:06:11 +0000

After integrating Sentry error monitoring, Release Adoption stayed at 0%, and Source Maps never resolved.
Two days of debugging, six pitfalls cleared.

Background

The project is a Next.js 15 static export deployed on Cloudflare Pages. I wanted Sentry error monitoring so user errors show readable stack traces.

Seems simple: Install SDK → Upload Source Maps → Done.

Reality:

0% Adoption → SDK not initialized → Switch to CDN
Source Map upload fails → sentry-cli crashes → Switch to HTTP API
Wrong region → Token parse failure → Write parser logic
Release mismatch → Filename wrong → Unicode escape

Pitfall 1: Release Adoption Stays at 0%

Symptoms

Sentry Dashboard:

Releases list shows the release ✅
But Adoption is 0% ❌
Events list is empty ❌

Root Cause

@sentry/browser got tree-shaken away by SWC.

// ❌ This code is eliminated by SWC during build
import * as Sentry from '@sentry/browser'
Sentry.init({ dsn: '...', release: process.env.NEXT_PUBLIC_SENTRY_RELEASE })

@sentry/browser uses heavy lazy imports and conditional exports internally. SWC's minification pass treats these as dead code and removes them entirely.

Solution: Use Sentry CDN

// app/layout.tsx
export default function RootLayout({ children }) {
  return (
    <html>
      <head>
        <script
          src="https://browser.sentry-cdn.com/7.113.0/bundle.min.js"
          crossorigin="anonymous"
        />
        <script dangerouslySetInnerHTML={{ __html: `
          Sentry.init({
            dsn: '${process.env.NEXT_PUBLIC_SENTRY_DSN}',
            release: '${process.env.NEXT_PUBLIC_SENTRY_RELEASE}',
            environment: 'production'
          })
        `}} />
      </head>
      <body>{children}</body>
    </html>
  )
}

The CDN script lives outside SWC's processing pipeline and won't be tree-shaken.

Result: Release Adoption goes from 0% to >0% ✅

Pitfall 2: sentry-cli Crashes on GitHub Actions

Symptoms

- uses: actions/setup-node@v4
  with:
    node-version: 22
- run: npx @sentry/cli sourcemaps upload out/

Runtime error:

Error: The module '/node_modules/@sentry/cli/bin/sentry-cli'
was compiled against a different Node.js version

Root Cause

sentry-cli is a Rust-compiled binary with Node.js FFI bindings that are incompatible with the Actions Node.js version.

Solution: Direct HTTP API

// scripts/upload-sourcemaps.js
const fs = require('fs')
const https = require('https')

// Parse org ID and region from Auth Token
function parseSentryToken(authToken) {
  const payload = authToken.replace('sntrys_', '')
  const decoded = JSON.parse(Buffer.from(payload, 'base64').toString())
  return {
    orgId: decoded.org_slug,
    region: decoded.host === 'https://sentry.io' ? 'us' : 'eu'
  }
}

// multipart/form-data upload
function uploadSourceMap(options) {
  const boundary = '----FormBoundary' + Math.random().toString(36).slice(2)
  // ... build multipart body and send via https.request()
}

Pitfall 3: Wrong Region

Symptoms

404 Not Found: /api/0/organizations/myorg/releases/

Root Cause

Sentry has two regions: us.sentry.io and eu.sentry.io. My org is in US, but the default request went to EU.

Solution

The Auth Token encodes region info:

// Sentry token: sntrys_ prefix + base64(JSON)
const token = 'sntrys_eyJyZWdpb25FbmRwb2ludCI6ICJodHRwczovL3VzLnNlbnRyeS5pbyJ9'
const payload = Buffer.from(token.slice(7), 'base64').toString()
const info = JSON.parse(payload)
// info.regionEndpoint → "https://us.sentry.io"

Pitfall 4: Release Name Mismatch

Symptoms

Source Maps upload succeeds, but Dashboard still shows "Missing."

Root Cause

The release name in Source Maps doesn't match what the SDK reports:

SDK reports:  "release": "utlkit-20260521-abc1234"
Source Map:   "release": "utlkit-abc1234"  ← missing date

Solution

Generate the release name from one script, used by both SDK and upload:

// scripts/generate-sentry-release.js
const { execSync } = require('child_process')
const commitSha = execSync('git rev-parse --short HEAD').toString().trim()
const date = new Date().toISOString().split('T')[0]
const release = `utlkit-${date}-${commitSha}`
console.log(release)

Pitfall 5: Unicode Escape Corrupts Filenames

Symptoms

Source Maps uploaded but Sentry shows garbled paths.

Root Cause

JSON.stringify converts non-ASCII characters to \uXXXX, which Sentry's API can't parse correctly.

Final Workflow

name: Upload Sentry Source Maps
on:
  push:
    branches: [main]

jobs:
  upload:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24
      - run: npm ci
      - run: npm run build
      - run: node scripts/generate-sentry-release.js > .sentry-release
      - run: node scripts/upload-sourcemaps.js
        env:
          SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
          SENTRY_DSN: ${{ secrets.SENTRY_DSN }}

Summary

Pitfall	Symptom	Solution
SWC tree-shakes SDK	Adoption 0%	Use Sentry CDN
sentry-cli Node incompatibility	Binary crash	Direct HTTP API
Wrong region	404	Parse region from Token
Release mismatch	Source Map Missing	Unified release name
Unicode escape	Garbled filenames	Handle encoding properly
Dynamic import optimized away	SDK not initialized	CDN script

Core lesson: Sentry's official docs assume Node.js SSR or bundler plugins. The static export + CDN SDK combination requires custom upload logic.

Project

utlkit.com — All formatter tools run purely in the browser. The solutions above are running stably in production.

Building Pure Frontend Formatter Tools: Why Node.js Libraries Fail in the Browser

Mark — Mon, 29 Jun 2026 01:41:31 +0000

Building a pure-frontend online formatter tool site seems straightforward: import a formatting library → call it in the browser.
In practice, three commonly-used libraries all failed in the browser.

The Problem List

During development, three popular libraries all broke in the browser:

Library	Purpose	Browser Behavior
`terser`	JS minification	❌ `fs is not defined`
`html-minifier-terser`	HTML minification	❌ `fs is not defined`
`xml-formatter` v3.7.0	XML formatting	⚠️ ESM/CJS interop issues

terser: The `fs` Module Problem

Reproduction

import { minify } from 'terser'

// Called in a browser component
const result = await minify(code, { compress: true, mangle: true })

Build succeeds. Runtime error:

Uncaught ReferenceError: fs is not defined
    at Object.readSourceMap (terser/dist/bundle.min.js:1:xxxxx)

Root Cause

terser internally calls fs.readFileSync to read source map files. Fine in Node.js — fs doesn't exist in browsers.

Even though terser's package.json declares a browser field for conditional exports, some internal modules still reference fs, and webpack/SWC tree-shaking doesn't fully eliminate them.

Solution: Lightweight Regex Minifier

function minifyJs(code) {
  return code
    // Remove single-line comments
    .replace(/\/\/.*$/gm, '')
    // Remove multi-line comments
    .replace(/\/\*[\s\S]*?\*\//g, '')
    // Collapse whitespace
    .replace(/\s+/g, ' ')
    .trim()
    // Remove spaces around punctuation
    .replace(/\s*([,;{}()\[\]])\s*/g, '$1')
    // Remove blank lines
    .replace(/\n\s*\n/g, '\n')
}

Advantages:

Zero dependencies, pure JS
Works in both browser and Node.js
Tiny codebase (20 lines)
More than sufficient for a tool site's JS minification

Disadvantages:

Lower compression ratio than Terser
No AST-level optimizations (variable mangling, dead code elimination)

But for "user pastes code in browser to see minified output," regex is more than enough.

html-minifier-terser: Same `fs` Problem

Problem

Same root cause as terser. html-minifier-terser calls fs internally to read local files for <script src="..."> etc.

Solution

function minifyHtml(html) {
  return html
    .replace(/<!--[\s\S]*?-->/g, '')   // Remove HTML comments
    .replace(/>\s+</g, '><')            // Collapse whitespace between tags
    .replace(/\s*=\s*/g, '=')           // Tighten attribute values
    .replace(/ {2,}/g, ' ')             // Collapse multiple spaces
    .trim()
}

xml-formatter: ESM/CJS Interop Issues

Problem

This library actually supports the browser. But v3.7.0's export structure is messy:

// xml-formatter v3.7.0 actual exports
export default function formatXml(...) { ... }  // default export
export function minify(xml) { ... }             // named export

After SWC compilation (CJS wrapper), the default export becomes exports.default. Direct import formatXml from 'xml-formatter' sometimes returns a non-function object.

Debugging

// ❌ formatXml is undefined at runtime
import formatXml from 'xml-formatter'
import { minify } from 'xml-formatter'  // ✅ This works

// ✅ Correct approach
import _formatXml from 'xml-formatter'
const formatXml = _formatXml.default || _formatXml

Final Solution

// Format with xml-formatter (interop handled)
import _formatXml from 'xml-formatter'
const formatXml = _formatXml.default || _formatXml

// Minify with custom function (xml-formatter's minify is inconsistent across versions)
function minifyXml(xml) {
  return xml
    .replace(/<!--[\s\S]*?-->/g, '')
    .replace(/\s+/g, ' ')
    .replace(/>\s+</g, '><')
    .trim()
}

Library Selection Checklist

Before choosing a library, run through this:

Does package.json have a browser field? — Yes → browser-adapted
Does the dependency tree include fs, path, net? — Yes → can't use in browser
Does the npm page mention "Browser Support"?
Search GitHub Issues for "browser", "client-side" — Any similar reports?
Test locally with a simple HTML + <script type="module">

Recommended Libraries for Pure Frontend Tools

Function	Library	Why
JS/HTML/XML formatting	`js-beautify`	Explicit browser build support
CSS minification	`csso`	Pure JS, no Node.js deps
JSON formatting	`JSON.stringify/parse`	Native API
SQL formatting	`sql-formatter`	Browser-compatible
YAML formatting	`js-yaml`	Browser-compatible

Core Lesson

Don't judge a library by its name. Judge it by its runtime dependencies.
"js" in the name doesn't mean it runs in browsers. "node" in the name doesn't mean it can't.

Project

utlkit.com — All formatter tools run purely in the browser. The solutions above are running stably in production.

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

6 Pitfalls of Building a Multilingual Site with Next.js 15: From Query Strings to URL Paths

Why is i18n Harder Than You Think?

Approach Comparison

Approach 1: Query String (First Attempt, Quickly Abandoned)

Approach 2: Subdirectory

Approach 3: Path Prefix [locale] (Final Choice)

Pitfall 1: Nested Root Layout

The Problem

Root Cause

Fix

Pitfall 2: redirect() Doesn't Work with Static Export

The Problem

Root Cause

Fix

Pitfall 3: Passing Locale to generateMetadata

The Problem

Root Cause

Fix

Pitfall 4: Content Doesn't Refresh on Language Switch

The Problem

Root Cause

Fix

Pitfall 5: Sitemap Doesn't Support Multilingual

The Problem

Root Cause

Fix

Pitfall 6: 500+ i18n Keys to Translate

The Problem

Solution

Final Architecture

Lessons Learned

Project

Next.js 15 Dark Mode Without the Flash: From Hydration Error to Zero-Flicker

The Problem List

Pitfall 1: React Hydration Error #418

The Problem

Root Cause

Fix

Pitfall 2: White Screen Flash

The Problem

First Fix: head script

Second Fix: Intercept pushState

Pitfall 3: Console SyntaxError

The Problem

Root Cause

Fix: Move to an External JS File

Pitfall 4: External JS Still Flashes

Root Cause

Fix: CSS @media (prefers-color-scheme) as the default

Pitfall 5: Toggle Icon Never Changes

The Problem

Root Cause

Fix: Custom CSS Classes

Final Architecture

Key Files

Lessons Learned

Project

Cloudflare Cache Hit Rate: 7% to 90%

Cloudflare Pages Cache Hit Rate at 7%? I Brought It to 90% with 3 Rules

The Problem

Root Cause Analysis

Why was the cache hit rate so low?

The Solution

Approach Comparison

Step 1: Create Cache Rules

Rule 1: Long Cache for Static Assets (highest priority)

Rule 2: Short Cache for Sitemap

Rule 3: HTML Page Cache (catch-all, most important)

Step 2: Purge Everything

Step 3: Verify

Additional Fix: Localizing Sentry CDN

Results

Lessons Learned

Lesson 1: Cloudflare's new UI doesn't match old tutorials

Lesson 2: Not ignoring query strings splits your cache

Lesson 3: Browser TTL too long means users see stale content after deploys

Advanced: IP Optimization for China

Summary

Free Website Performance Monitoring: PageSpeed CI + CrUX + GitHub Actions

Approach 3: Path Prefix `[locale]` (Final Choice)

Fix: CSS `@media (prefers-color-scheme)` as the default

terser: The `fs` Module Problem

html-minifier-terser: Same `fs` Problem