Here's what happened.

what i tried first (wrong)​

The obvious thing: create src/pages/404.js. It's a pages directory, 404 is a page, right?

// src/pages/404.js
export default function NotFound() {
  return <div>my custom 404</div>;
}

In dev: it flashed briefly, then the default "Page Not Found" page took over. In prod (Cloudflare Pages): same thing. Default page. My file completely ignored.

Why it doesn't work:

src/pages/404.js creates a route at /404. It doesn't replace Docusaurus's internal 404 handler. When you navigate to an unknown URL, Docusaurus's React Router says "no route found" and renders @theme/NotFound — the built-in component. Your pages/404.js is a different route entirely, never triggered for actual 404s.

The host (Cloudflare) might also serve 404.html from the build output, but client-side navigation within the app always goes through Docusaurus's router, not the file system.

what actually works — swizzling​

Docusaurus has a concept called swizzling: you can override theme components by creating them in src/theme/.

The component that handles 404s is @theme/NotFound. So:

npm run swizzle @docusaurus/theme-classic NotFound

In Docusaurus v2 this created a single file: src/theme/NotFound.js. Simple.

In Docusaurus v3 it creates two files:

src/theme/NotFound/index.js         # page wrapper (provides Layout)
src/theme/NotFound/Content/index.js # the actual content ("Page Not Found" text)

what i actually did (also wrong)​

I read that v3 split the component, so I deleted NotFound/index.js and only created NotFound/Content/index.js thinking I just needed the content part.

✖ Module not found: Can't resolve '@theme/NotFound'

Right. By deleting index.js, I deleted the component entirely. Docusaurus needs NotFound/index.js to exist to resolve @theme/NotFound. The Content subcomponent can't exist without the parent.

the fix that works​

You need both files. index.js is a passthrough wrapper:

// src/theme/NotFound/index.js
import React from "react";
import NotFound from "@theme-original/NotFound";

export default function NotFoundWrapper(props) {
  return <NotFound {...props} />;
}

And Content/index.js is where you put your actual custom content:

// src/theme/NotFound/Content/index.js
import React from "react";
import Link from "@docusaurus/Link";

export default function NotFoundContent() {
  return (
    <main style={{ textAlign: "center", padding: "4rem 1rem" }}>
      <img
        src="https://cdn3.emoji.gg/emojis/29604-peepolost.png"
        width="80px"
        alt="peepoLost"
      />
      <h1>404 — genuinely no idea where you are</h1>
      <p>this page doesn't exist. you might be more lost than me.</p>
      <Link to="/">-&gt; take me home</Link>
    </main>
  );
}

one more thing: swizzle doesn't hot reload​

After getting the file structure right, changes still weren't showing in dev. This is a known Docusaurus issue (#10238) — swizzled components don't support hot reload. You have to fully restart the dev server every time you change them. Ctrl+C, npm start, wait.

And if the Docusaurus cache (.docusaurus/) is stale, even a restart isn't enough. Full clean required:

npx docusaurus clear && npm start

RCA summary​

The correct structure is both files. The parent index.js as a wrapper, the Content/index.js with your actual UI. The GitHub discussion (#6030) has the right answer — just note that it was written for v2, and the file structure changed in v3.

Anyway. peepoLost is on the 404 page now. thirty minutes well spent.

-- Bala

I used Terraform.

The requirements​

Like any good engineer, I started by writing requirements for a website that would hold maybe three blog posts and a resume PDF:

• Must be fast
• Must cost $0/month
• Must be "production grade" (this one is my fault)
• Must have infrastructure-as-code because apparently I have something to prove

Normal people: git push → GitHub Pages → done.

Me: opens a new Terraform file

The architecture​

Here's the full system design. Yes, I drew this out. Yes, it's for a personal blog.

[ Browser ]
    |
    v
[ Cloudflare CDN ] <-- ~300 edge locations globally
    |                   because my 3 readers deserve low latency
    v
[ Cloudflare Pages ] <-- static site, auto-deploys on git push
    |
    v
[ Docusaurus build ] <-- React + Markdown = blog + docs site
    |
[ Cloudflare R2 ] <-- resume PDF, because S3 costs money
    |
[ Terraform ] <-- manages all of the above
    |
[ GitHub Actions ] <-- runs npm audit weekly (security theater, but mine)

Total monthly cost: $0.

The domain (bevani.dev) costs ~$10/year. That's it. Everything else is free tier.

Why Cloudflare Pages over GitHub Pages?​

Honestly? I wanted a CDN and GitHub Pages uses Fastly which has fewer edge locations. The real reason is that I wanted to learn Cloudflare's stack and this was a good excuse.

But the performance argument is real — if someone in Singapore opens my resume link, Cloudflare serves it from an edge node nearby instead of a US datacenter. Whether anyone in Singapore will ever read my blog is a separate question.

The $0 stack breakdown​

Grand total: 83 cents a month.

Things that went wrong (a partial list)​

1. Webpack and webpackbar had a domestic dispute

Docusaurus ships with webpackbar for build progress. webpackbar needs webpack. But webpack 5.97+ changed its options schema and webpackbar passed invalid options. The fix: pin webpack to 5.96.1 and override all nested instances. Problem solved. Time spent: longer than I'd like to admit.

2. Terraform's R2 backend needs 6 "skip" flags

Cloudflare R2 is S3-compatible but not exactly S3. When you use it as a Terraform backend, you have to tell Terraform to skip every AWS-specific validation:

skip_credentials_validation = true
skip_metadata_api_check     = true
skip_region_validation      = true
skip_requesting_account_id  = true
use_path_style              = true

Five skip flags and one rename. That's how you know you're in compatibility layer territory.

3. My .npmrc was poisoning the lockfile

My global ~/.npmrc had legacy-peer-deps=true set from some project years ago. npm on my Mac: uses relaxed peer dep resolution, generates lockfile npm on Cloudflare: strict mode, tries to install from lockfile, explodes

The fix was a one-line .npmrc in the project. The real fix was asking why I had that global setting in the first place. I did not investigate further.

4. Cloudflare Pages GitHub App wasn't installed

Terraform kept getting a 401 with error code 8000011 — "internal issue with your Cloudflare Pages Git installation." The fix was going to the Cloudflare dashboard, clicking through the project creation wizard just enough to install the GitHub App, then backing out and letting Terraform do the actual work.

Clicking to authorize an OAuth app so that your IaC tool can do things: very normal.

Was this overkill?​

Obviously.

But the infrastructure is reproducible from scratch with three commands:

make install
make tf-init
make deploy

And every content change is just a Markdown file edit + git push. Cloudflare handles the build and deploy automatically. The whole thing costs less than a coffee per month.

Would I do it again? Yes. Will I blog consistently now that I have this? Ask me in a year.

-- Bala

Why a blog?​

There's something satisfying about having a place on the internet that is definitively mine — no algorithmic timeline, no engagement metrics, no sponsored posts.

Just text. Mine.

What to expect​

Whatever comes to mind. No theme, no schedule, no promises.

The stack​

This site is built with Docusaurus, deployed to Cloudflare Pages, with infrastructure managed by Terraform. Simpler than it sounds.

$ make dev
# http://localhost:3000 -- and we're live

See you around.

-- Bala