We Switched Our Site from HTML to Nuxt 3 and Hit 5 Walls in One Day (With Checklist)

Preface: What Does a One-Day Architecture Migration Really Cost?

On March 21st, SFD Lab migrated our website from a static HTML site to Nuxt 3 SSR.

Sounds pretty cool, right? Architecture upgrade done in a day—modern framework, server-side rendering, SEO-friendly. Another bullet point for the resume.

But here's what actually happened: the boss opened the homepage, and every illustration was broken. Clicked into an article—"Article not found." The hamburger menu on mobile was invisible. curl the source code—"not-found" everywhere.

In one day, we hit 5 walls. Each one is a blind spot that's easy to miss during an architecture switch. Today I'm laying them all out so you don't have to walk the same path.

Wall 1: Nginx proxy_pass Killed All the Images

💥 What Happened

Right after the switch went live, the boss opened the homepage first thing. Every single illustration—broken. Console full of 404s, nothing under /uploads/ or /images/ would load.

🔍 Investigation

The old site was plain HTML—Nginx served that directory directly, so paths like /uploads/logo.png just worked naturally. But once we switched to proxy_pass pointing at Nuxt's Node process, all requests got forwarded to port 3000. The Node process had no idea those static files existed—it only knows how to render Vue components, not find your images on disk.

🎯 Root Cause

During the architecture switch, we only changed the main route forwarding and completely forgot that static assets were still sitting in the old directory. proxy_pass is an "intercept everything" operation—any path you haven't explicitly exempted gets forwarded to Node.

🔧 Fix

Added 3 location blocks to the Nginx config:

location /uploads/ {
    alias /var/www/old-site/uploads/;
}

location /images/ {
    alias /var/www/old-site/images/;
}

location /api/ {
    proxy_pass http://127.0.0.1:8370;
}

Just a few lines, but skip them and everything breaks.

📝 Lesson

Before switching to proxy_pass, list out every static asset path from the old site. Use grep or find to scan all HTML/CSS/JS files for referenced paths, and make sure each one has someone "catching" it in the new architecture. Don't assume "Nuxt will handle it automatically"—it won't.

Wall 2: Every Article Detail Page Said "Article Not Found"

💥 What Happened

Homepage looked fine. Article list had data. But click into any article's detail page—"Article not found." Every single article, no exceptions.

🔍 Investigation

Dug into the frontend code—oh boy. Our Chameleon dev had written a bunch of mock data: mockSciencePosts, mockTechArticles… The list pages used this fake data, so the homepage and listing pages looked normal. But the detail page needed to query a specific article by slug, the mock data had no matching content, and it returned empty.

And during QA? Only the homepage and list pages were checked. Nobody clicked into an article detail page.

🎯 Root Cause

Two problems stacked: first, using mock data for prototyping is fine, but it wasn't swapped out for real API calls before going live. Second, QA wasn't deep enough—only checked the "first layer."

While fixing it, we hit a bonus trap: the lang parameter didn't match. The frontend was sending "zh-CN," but the CMS API only accepts "zh." Two characters of difference, took us a while to track down.

🔧 Fix

Deleted 300+ lines of mock data code, replaced everything with useAsyncData + $fetch calling the CMS REST API directly. Added a lang parameter mapping: "zh-CN" → "zh", "en-US" → "en".

📝 Lesson

Before going live, grep the entire project for "mock." This isn't a suggestion—it's a rule. Mock data is like scaffolding: you need it while building, but you absolutely must tear it down before move-in. Otherwise what tenants (users) see is an unfinished shell.

Same goes for QA: don't just check the homepage. Click into at least 3 articles and verify the detail pages render correctly.

Wall 3: "not-found" Hiding in the SSR Source Code

💥 What Happened

This one was sneaky. Open the page in a browser—everything looks fine. But curl the page source—

$ curl -s https://v2.smallfiredragon.com/science/xxx | grep not-found
<div class="not-found">...

"not-found" markers in the source code. Search engine crawlers see this source code, which means SEO is toast.

🔍 Investigation

Here's how Nuxt 3 SSR works: the Node server renders HTML first and sends it to the browser, then the client receives the HTML and "hydrates" (activates), re-fetching data on the client side.

The problem was in the server-side rendering step. When the Node process fetched the CMS API from inside the server, it used the domain v2.smallfiredragon.com—but the server couldn't resolve that domain internally (no internal DNS configured). So the server-side fetch failed, and it rendered the not-found state.

Why did the browser work fine? Because after client-side hydration, it re-fetched using public DNS, which resolved correctly, got the data, and overwrote the server's error state. Users couldn't tell, but crawlers saw the server's broken HTML.

🎯 Root Cause

Network requests in an SSR environment are completely different from the client side. The server is on the internal network—DNS resolution, firewall rules, and hosts files can all differ. This discrepancy is impossible to catch in dev because your dev machine can resolve everything.

🔧 Fix

Two approaches: added a domain resolution entry in the server's /etc/hosts, and also changed the SSR API address in Nuxt's runtimeConfig to the local loopback address (127.0.0.1:8370). We did both—belt and suspenders.

📝 Lesson

When deploying an SSR app, always use curl to check the server-rendered HTML. What the browser sees ≠ what search engines see. curl is the crawler's perspective. Running a curl check after every deployment is mandatory coursework for SSR projects.

Wall 4: The Hamburger Menu "Went Invisible"

💥 What Happened

Open the site on mobile, there should be a hamburger menu icon in the top right—but nothing's visible. It's not that it wasn't rendered; it rendered but was invisible.

🔍 Investigation

Opened DevTools—the element was there, had width and height, position was correct. Checked Computed styles for color: #94A3B8, a cool medium gray. Background color? #111318, deep blue-black.

Numerically the contrast barely passes the threshold, but in practice on a small mobile screen, fine-lined icons in that gray—really hard to spot. Especially outdoors in bright light or with lower screen brightness, it's practically invisible.

🎯 Root Cause

Interactive element colors in dark theme weren't specifically reviewed. Might be barely visible on a large desktop screen, but on a small mobile screen it just "disappears."

🔧 Fix

Changed the icon color to brand orange #F97316. Orange on a dark background maxes out contrast, and it aligns with the brand color—two birds with one stone.

📝 Lesson

Dark theme isn't just "make the background black and call it done." Every interactive element needs its color contrast re-evaluated. Before launch, run all interactive elements through WebAIM's Contrast Checker—especially icons, button borders, and secondary text that are easy to overlook.

Wall 5: The Boss's Warning Got Treated as Background Noise

💥 What Happened

At 5:53 PM, the boss posted in the group: "Check if the article paths are the same."

The team's response: checked the HTTP status code, 200, no problem! Moved on to other things.

Then Walls 2 and 3 happened.

🔍 Investigation

Looking back, when the boss said "check the article paths," there were several layers implied: Can the paths be accessed? What do they return? Is the content correct? Did the SEO paths change? Do old links still redirect?

But the team only understood the most surface-level interpretation: "path is accessible" → HTTP 200 → no problem.

🎯 Root Cause

HTTP 200 only means "the server responded normally"—not "the page content is correct." A page showing "Article not found" will still return 200 just fine.

🔧 Fix

No code fix—this is a process issue. The team established a new rule: the boss's warnings = risk signals that require deep investigation down to the content layer. Not just checking status codes and calling it done, but opening the page, reading the content, viewing the source code, testing interactions.

📝 Lesson

200 OK is the least reliable "everything's fine" signal. QA must look at actual content, not status codes. This applies not just to architecture migrations—it's true for any post-deployment check.

---

SFD Editor's Note

Each of these 5 walls, taken individually, isn't hard to fix. But stack them together, add the time pressure of "get it done in one day," and you've got an accident relay race.

Our lab's biggest takeaway from this migration wasn't technical—Nginx config, mock data cleanup, DNS resolution, you can Google all of that. The biggest takeaway was redefining what "QA" actually means:

You think QA is opening the homepage and glancing at it. Real QA means simulating the user's complete journey, including pages you think "definitely work fine."

Especially for something like an architecture migration where you're changing the foundation. When the foundation changes, every floor, every window, every pipe above it could be affected. You can't just check if the front door opens—you need to walk through every room.

📋 Architecture Migration Checklist

Here's the checklist we put together and use internally. Sharing it here:

I. Before Migration

• □ List all static asset paths from the old site (/uploads/, /images/, /fonts/, /assets/, etc.)
• □ List all API endpoint addresses from the old site
• □ List all article/page URLs from the old site; export a complete URL inventory
• □ grep the entire project for "mock," "fake," "dummy," "test"—flag all placeholder data for replacement
• □ Confirm the new architecture's server can resolve all required domains (test with curl, not a browser)
• □ Confirm CMS API parameter formats (field names and values for lang, slug, etc.)
• □ Back up old site configuration (Nginx conf, DNS records, SSL certificate paths)

II. Nginx Configuration Switch

• □ Add separate location blocks for each static asset path
• □ Configure API forwarding in its own location (don't mix it into the main proxy_pass)
• □ Test each location block works (curl every path)
• □ Verify SSL certificates are correctly bound to the new config
• □ Set up 301 redirects from old URLs to new URLs (if the path structure changed)

III. SSR-Specific Checks

• □ curl the homepage source and confirm it has real content (not an empty shell or not-found)
• □ curl at least 3 article detail pages and check the source
• □ Confirm server-side DNS can resolve all API domains (test with nslookup/dig on the server)
• □ Verify SSR environment variables are correctly set (API addresses, language parameters, etc.)
• □ Compare server-rendered output with client-rendered output—there should be no content differences

IV. Content & UI QA

• □ Open the homepage; verify all images load
• □ Click into at least 3 article detail pages; confirm content displays correctly
• □ Test all language versions (zh/en/ja, etc.); confirm switching works
• □ Mobile test: hamburger menu, navigation, article pages, images
• □ Check visibility of all interactive elements in both dark and light themes
• □ Check page title, meta description, and OG tags are correct

V. Post-Launch Monitoring

• □ Full test of old URLs (run through the exported URL inventory; check for 301/200)
• □ Google Search Console indexing status check (1-3 days after launch)
• □ Monitor server error logs (Nginx error log + Node process logs)
• □ Have someone outside the team (or the boss) browse freely to catch things you missed

This checklist isn't long, but every item on it was earned through real crashes. Save it and open it up before your next architecture migration.

After all, hitting a wall isn't scary—hitting the same wall twice is.