Nuxt HMR CSS Fix – How I Solved Hot Reload & Styling Issues with a Single-Port Setup

If you’re struggling with Nuxt 3 hot reload disconnects and broken styles, this Nuxt HMR CSS fix shows exactly how I solved it by using a single-port IPv4 setup.

WebSocket connection to 'ws://localhost:24678/_nuxt/?token=…' failed: net::ERR_CONNECTION_REFUSED
[vite] server connection lost. Polling for restart...

You clean .nuxt, reinstall packages, restart the dev server—and 10 minutes later, it’s back. Your CSS doesn’t hot reload properly, icons blow up to full-page size, and your browser console looks like a crime scene.

That was my life with the Afitpilot Nuxt application—until I finally cracked it.

---

The Symptoms

My setup:

• Nuxt: 3.10.3
• Tailwind CSS: 3.4.17
• Node: 20.11.1
• Design system: 30+ components, custom global CSS

The issues:

• Random Vite HMR ports (24678, 50410, 3001) kept dying.
• IPv6/IPv4 mismatch meant sometimes localhost worked, sometimes it didn’t.
• CSS updates often required a full reload.
• Global svg resets from the design system blew icons up like parade balloons.

---

Root Causes

1. Random port allocation — Vite’s default HMR chooses a random port each run. If a firewall/VPN doesn’t like it, the socket dies.
2. IPv6 vs IPv4 — macOS localhost often resolves to ::1 (IPv6), but Vite was binding to 127.0.0.1 (IPv4).
3. Global CSS collisions — Tailwind + design-system styles were loading in the wrong order, sometimes wiping out each other’s rules.

---

The Fix

After hours of trial, error, and coffee, this Nuxt HMR CSS fix worked instantly solution was simple:

1. My Nuxt HMR CSS Fix: The Single-Port Solution

No more random ports—everything (server + HMR) runs on 127.0.0.1:3000:

export default defineNuxtConfig({
  devServer: { host: '127.0.0.1', port: 3000 },
  vite: {
    server: {
      host: '127.0.0.1',
      strictPort: true,
      hmr: { protocol: 'ws', host: '127.0.0.1', port: 3000, clientPort: 3000 },
      watch: { usePolling: true, interval: 100 }
    }
  }
})

This removed all connection-refused spam instantly.

---

2. CSS Structure & Load Order

• assets/css/tailwind.css for Tailwind directives (@tailwind base; @components; @utilities).
• assets/css/globals.css for global styles, loaded after Tailwind.
• Design system CSS loaded last to keep its intended overrides.

---

3. Tailwind Content Paths

Ensured Tailwind scanned all design-system components:

content: [
  './app.vue',
  './components/**/*.{vue,js,ts}',
  './pages/**/*.{vue,js,ts}',
  './packages/**/*.{vue,js,ts}',
  '../packages/**/*.{vue,js,ts}',
]

---

4. Icon Sanity

Prevented full-page blue SVGs:

.nuxt-icon svg, .icon svg, [data-icon] svg {
  width: 1em;
  height: 1em;
  flex: none;
}

Related reading: Tailwind’s SVG best practices.

5. Clean Scripts

Added repeatable dev scripts for cache/process cleanup:

"dev:clean": "rimraf .nuxt .output node_modules/.vite && nuxi cleanup || true",
"dev": "NUXT_HOST=127.0.0.1 NUXT_PORT=3000 nuxi dev"

If you’re new to Nuxt CLI, check the Nuxt CLI documentation.

---

Results After Applying the Nuxt HMR CSS Fix

This Nuxt HMR CSS fix not only removed the connection errors but also restored instant hot reload and fixed my CSS updates in real time.

✅ No more HMR errors — Console is clean.
✅ Instant CSS updates — Tailwind and globals reload smoothly.
✅ Stable icons — No unintentional SVG supersizing.
✅ Predictable dev environment — One port, one protocol, always IPv4.

Startup now looks like:

Nuxt 3.10.3 with Nitro 2.12.4
➜ Local: http://127.0.0.1:3000/
✔ Vite server hmr 82 files in 2287ms

---

Lessons Learned

1. Kill the random port habit — Pin HMR to your main dev server port.
2. Control CSS order — Decide what wins when Tailwind meets your design system.
3. IPv4 > IPv6 (for dev) — At least on macOS with Vite/Nuxt.
4. Always have a “clean” script — Saves hours when caches misbehave.

---

Final Word

If you’re tired of chasing random dev server issues, I highly recommend trying this Nuxt HMR CSS fix before looking for more complex workarounds.

Nuxt + Vite is powerful, but small configuration mismatches can create endless frustration.
If your HMR keeps disconnecting and your styles refuse to behave, lock it down to a single IPv4 port, fix your CSS order, and own your build pipeline.

Your sanity will thank you.

For more of my dev fixes, see:

• Cursor Conversation Too Long — The Simple Prompt That Solves It
• Cursor Claude 3.7 Sonnet One-File Focus Issue: Why It Happens and How to Fix It