Coder Legion - Recent posts tagged vite

Project LifeOps (Part 2): React Frontend with Glassmorphism, 360° Dashboard, and Dark Mode Design Sy

Sun, 13 Sep 2026 12:12:17 +0000

In Part 1 of this series, we established the foundational cloud infrastructure: a zero-cost ($0/month) deployment topology, a polymorphic PostgreSQL schema hosted on Supabase, and a modular, high-performance REST API built with FastAPI.

Having a robust database and resilient backend is critical, but a Personal Operating System (LifeOps) only succeeds if using it every single day is an engaging, friction-free, and visually stimulating experience. If an interface feels clunky, sluggish, or resembles an uninspired, boilerplate admin template, the habit of tracking workouts, reading milestones, and professional tasks dissolves within days.

To solve this, I set out to engineer a Single Page Application (SPA) pairing a modern Glassmorphism Dark Mode aesthetic, instantaneous sub-millisecond interaction speeds, 360° data telemetry, and seamless device responsiveness.

[!TIP]
Test the live app: You can explore the production build of LifeOps directly at https://datalaria.com/apps/lifeops/.

🗺️ LifeOps Series Roadmap

To understand how every architectural layer fits together, this series spans 5 structured installments:

🟢 Part 1: Personal Operating System Architecture and FastAPI + Supabase Backend
🟢 Part 2 (This article): React Frontend with Glassmorphism, 360° Dashboard, and Design System
⚪ Part 3: Core Interactive Modules: Fitness, Library, Cinema, and Professional Kanban Board
⚪ Part 4: In-Memory Word Dossiers (.docx) & Multi-Sheet Excel Engine (.xlsx)
⚪ Part 5: 24/7 Zero-Cost Cloud Deployment ($0/month), Mobile UX, and PWA

1. Frontend Tooling: Blazing Speeds with Vite & React ⚡

When configuring the client workspace (lifeops-app), the primary objective was maintaining a modular, lean codebase free from the dependency bloat that plagues modern web development.

I chose React 18/19 paired with Vite as our next-generation build tool:

{
  "name": "lifeops-app",
  "private": true,
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "lint": "oxlint",
    "preview": "vite preview"
  },
  "dependencies": {
    "@supabase/supabase-js": "^2.112.2",
    "lucide-react": "^1.31.0",
    "react": "^19.2.8",
    "react-dom": "^19.2.8",
    "react-router-dom": "^7.18.2",
    "recharts": "^3.10.1"
  },
  "devDependencies": {
    "@vitejs/plugin-react": "^6.0.4",
    "vite": "^8.2.0"
  }
}

Why this technical combination?

Instant Server Start & Hot Module Replacement (HMR): Vite serves source code over native browser ES Modules during development, completely eliminating the sluggish bundling delays of legacy setups like Webpack or Create React App.
Consistent Iconography with lucide-react: Featherweight SVG icons with unified stroke weight, fully configurable via native React props.
Declarative Data Visualization with recharts: Composable SVG-based chart primitives engineered specifically for React state, avoiding clunky imperative DOM manipulations.
Zero Bulky UI Frameworks: We avoid heavy CSS component libraries. Every component is styled using pure modern CSS, native variables, and GPU-accelerated backdrop blur filters.

2. Design System: Pure Glassmorphism Dark Mode 🎨

The visual identity of LifeOps revolves around translucent frosted glassmorphism: sleek cards floating above a deep slate backdrop (#0b0f17), accented by subtle emerald, cyan, and purple radial glows.

Rather than loading bloated CSS utilities, we defined our design tokens directly in :root inside src/index.css:

:root {
  /* Premium Dark Mode Base Palette */
  --bg-main: #0b0f17;
  --bg-sidebar: #111827;
  --bg-card: rgba(17, 24, 39, 0.7);
  --bg-card-hover: rgba(31, 41, 55, 0.8);
  --bg-glass: rgba(15, 23, 42, 0.65);
  
  /* Borders & Frosted Glass Blur */
  --border-color: rgba(255, 255, 255, 0.08);
  --border-glow: rgba(59, 130, 246, 0.3);
  --glass-shadow: 0 8px 32px 0 rgba(0, 0, 0, 0.37);
  --backdrop-blur: blur(16px);

  /* Semantic Color Accents */
  --accent-emerald: #10b981;
  --accent-emerald-glow: rgba(16, 185, 129, 0.25);
  --accent-cyan: #06b6d4;
  --accent-cyan-glow: rgba(6, 182, 212, 0.25);
  --accent-purple: #8b5cf6;
  --accent-purple-glow: rgba(139, 92, 246, 0.25);
  --accent-amber: #f59e0b;
  --accent-rose: #f43f5e;

  /* Typography */
  --font-sans: 'Inter', system-ui, -apple-system, sans-serif;
  --font-heading: 'Outfit', 'Inter', sans-serif;
}

Reusable Utility Classes: `.glass-panel` & `.glass-card`

With these tokens in place, we encapsulated the frosted glass effect into two reusable CSS classes:

.glass-panel {
  background: var(--bg-card);
  backdrop-filter: var(--backdrop-blur);
  -webkit-backdrop-filter: var(--backdrop-blur);
  border: 1px solid var(--border-color);
  border-radius: 16px;
  box-shadow: var(--glass-shadow);
}

.glass-card {
  background: linear-gradient(145deg, rgba(30, 41, 59, 0.5) 0%, rgba(15, 23, 42, 0.6) 100%);
  backdrop-filter: var(--backdrop-blur);
  -webkit-backdrop-filter: var(--backdrop-blur);
  border: 1px solid var(--border-color);
  border-radius: 16px;
  transition: all 0.25s cubic-bezier(0.4, 0, 0.2, 1);
}

.glass-card:hover {
  border-color: rgba(255, 255, 255, 0.18);
  transform: translateY(-2px);
  box-shadow: 0 12px 40px 0 rgba(0, 0, 0, 0.45);
}

The key trick lies in layering backdrop-filter: blur(16px) with an angled linear gradient (145deg) and a hairline semi-transparent border (rgba(255, 255, 255, 0.08)). This produces an authentic specular edge highlight on the top-left corner, mimicking physical bevelled glass.

3. Reactive Authentication & FastAPI Integration 🔐

The frontend communicates with two core cloud services:

Supabase Auth: User identity management, session tokens, and cryptographic verification.
FastAPI Backend on Render: Business domain logic, aggregated analytics, and streaming report generation.

`AuthContext.jsx`: Real-Time Session Lifecycle

We built a centralized context provider subscribing to auth state transitions via onAuthStateChange:

import React, { createContext, useContext, useEffect, useState } from 'react';
import { supabase } from '../lib/supabase';

const AuthContext = createContext();

export function AuthProvider({ children }) {
  const [user, setUser] = useState(null);
  const [session, setSession] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    // 1. Fetch initial session on application mount
    supabase.auth.getSession().then(({ data: { session } }) => {
      setSession(session);
      setUser(session?.user ?? null);
      setLoading(false);
    });

    // 2. Listen to active auth transitions (login, logout, token refresh)
    const { data: { subscription } } = supabase.auth.onAuthStateChange((_event, session) => {
      setSession(session);
      setUser(session?.user ?? null);
      setLoading(false);
    });

    return () => subscription.unsubscribe();
  }, []);

  const signIn = (email, password) => supabase.auth.signInWithPassword({ email, password });
  const signOut = () => supabase.auth.signOut();

  return (
    <AuthContext.Provider loading, session, signIn, signOut user, value="{{" }}>
      {children}
    </AuthContext.Provider>
  );
}

export const useAuth = () => useContext(AuthContext);

`apiFetch`: Seamless JWT Injection

To ensure every API call to FastAPI is authenticated without manual boilerplate, we crafted a lightweight wrapper in src/lib/api.js:

import { supabase } from './supabase';

export const API_BASE_URL = import.meta.env.VITE_API_URL || '[https://lifeops-api.onrender.com](https://lifeops-api.onrender.com)';

export async function apiFetch(endpoint, options = {}) {
  // Extract active JWT access token from Supabase session
  const { data: { session } } = await supabase.auth.getSession();
  const token = session?.access_token;

  const headers = {
    'Content-Type': 'application/json',
    ...(token ? { Authorization: `Bearer ${token}` } : {}),
    ...(options.headers || {}),
  };

  const response = await fetch(`${API_BASE_URL}${endpoint}`, { ...options, headers });

  if (!response.ok) {
    const errorData = await response.json().catch(() => ({ detail: response.statusText }));
    throw new Error(errorData.detail || `HTTP Error ${response.status}`);
  }

  return response.status === 204 ? null : response.json();
}

Through this abstraction, individual components never touch raw authorization headers: whenever a signed-in user triggers an action, their JWT is transparently forwarded to FastAPI.

4. Engineering the 360° Dashboard 📊

The Main Dashboard (DashboardPage.jsx) is the command center that greets the user upon login, designed to communicate a holistic view of life and work metrics in under 5 seconds.

┌────────────────────────────────────────────────────────────────────────┐
│  👋 Welcome back, Diego!                                               │
│  Daily overview of personal telemetry and professional project flow.   │
├─────────────────┬─────────────────┬─────────────────┬──────────────────┤
│ 🏃 ACTIVITIES   │ 💼 PROJECTS     │ 📋 TASKS        │ 🔥 HABITS        │
│      28         │        5        │      14         │     6 / 7        │
│ 142 total       │ Of 8 active     │ 2 overdue       │ Active streaks   │
├─────────────────┴─────────────────┴─────────────────┴──────────────────┤
│  ⚡ QUICK ACTIONS: [+ Log Workout] [+ New Book] [+ Task] [+ Report]     │
├──────────────────────────────────────┬─────────────────────────────────┤
│  📊 ACTIVITY BREAKDOWN (30 DAYS)     │  📡 BACKEND HEALTH MONITOR      │
│  [Recharts Bar Chart with Neon Bars] │  🟢 FastAPI Online (Render.com) │
│  ■ Fitness  ■ Books  ■ Cinema        │  🗄️ Supabase DB (lifeops schema)│
└──────────────────────────────────────┴─────────────────────────────────┘

4.1. Navigation Architecture: Sidebar and Shortcuts Menu (`Sidebar.jsx`)

To keep navigation intuitive without cluttering the screen, we organized the sidebar into two functional tiers: primary top-level areas (Dashboard, Personal Area, Professional Area, Reports, Settings) and quick thematic shortcuts linking directly to everyday logging flows (Fitness, Books, Cinema, Kanban Board):

4.2. KPI Stat Cards (`StatWidget.jsx`)

The top metrics grid features semantic accent variants designed for quick cognitive parsing:

export function StatWidget({ title, value, subtitle, icon: Icon, color = 'emerald' }) {
  return (
    <div className={`stat-widget glass-card color-${color}`}>
      <div className="stat-widget-header">
        <span className="stat-title">{title}</span>
        {Icon && (
          <div className="stat-icon-wrapper">
            <Icon size="{20}"/>
          </div>
        )}
      </div>
      <div className="stat-widget-body">
        <span className="stat-value">{value ?? 0}</span>
        {subtitle && <span className="stat-subtitle">{subtitle}</span>}
      </div>
    </div>
  );
}

Each color variant (color-emerald, color-cyan, color-purple, color-amber) washes the icon container in a 20% opacity translucent glow (--accent-emerald-glow), establishing instant visual categorization without visual noise.

4.3. Activity Telemetry with Recharts

To visualize monthly activity volume, we fetch data from /api/v1/stats/breakdown and render a responsive bar chart:

import { BarChart, Bar, XAxis, YAxis, Tooltip, ResponsiveContainer, Cell } from 'recharts';

const chartData = [
  { name: 'Sport', count: breakdown?.sport || 0, color: '#10b981' },
  { name: 'Books', count: breakdown?.book || 0, color: '#06b6d4' },
  { name: 'Cinema/TV', count: breakdown?.film || 0, color: '#8b5cf6' },
  { name: 'Learning', count: breakdown?.learning || 0, color: '#f59e0b' },
  { name: 'Journal', count: breakdown?.journal || 0, color: '#ec4899' },
];

<div style={{ width: '100%', height: 220 }}>
  <ResponsiveContainer height="100%" width="100%">
    <BarChart -20, 0 10, bottom: data="{chartData}" left: margin="{{" right: top: }}>
      <XAxis dataKey="name" fontSize="{12}" stroke="#6b7280" tickLine="{false}"/>
      <YAxis allowDecimals="{false}" fontSize="{12}" stroke="#6b7280" tickLine="{false}"/>
      <Tooltip '#fff', '8px', 'rgba(17, 'rgba(255, 0.1)', 0.95)', 24, 255, 39, backgroundColor: borderColor: borderRadius: color: contentStyle="{{" }}/>
      <Bar 0, 0]} 6, dataKey="count" radius="{[6,">
        {chartData.map((entry, index) => (
          <Cell fill="{entry.color}" key="{`cell-${index}`}"/>
        ))}
      </Bar>
    </BarChart>
  </ResponsiveContainer>
</div>

4.4. Quick Actions Menu (`QuickActions.jsx`)

Friction is the number one reason personal productivity dashboards fall out of use. Logging a workout or finishing a book chapter must never require navigating through multiple nested views. From the central hub, the QuickActions panel exposes direct action buttons that launch focused data entry modals instantly:

5. Production Resilience: Handling Render Cold-Starts (`SystemHealth`) 🛡️

As noted in Part 1, our backend runs on the free tier of Render.com, which automatically puts containers to sleep after 15 minutes of inactivity.

When an end-user visits LifeOps after several hours of downtime, the initial HTTP handshake takes 20 to 40 seconds while the container spins up. Without proactive frontend handling, users would encounter frozen loaders or abrupt network errors.

To solve this, I designed the SystemHealth.jsx component:

export function SystemHealth() {
  const [health, setHealth] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);
  const [retryCount, setRetryCount] = useState(0);

  const checkHealth = async (isAutoRetry = false) => {
    setLoading(true);
    if (!isAutoRetry) setError(null);

    try {
      const data = await api.getHealth();
      setHealth(data);
      setError(null);
    } catch (err) {
      setError(err.message || 'API Connection Error');
      
      // Auto-retry up to 3 times with 6-second backoff while Render wakes up
      if (retryCount < 3) {
        setTimeout(() => setRetryCount((prev) => prev + 1), 6000);
      }
    } finally {
      setLoading(false);
    }
  };

  useEffect(() => {
    checkHealth(retryCount > 0);
  }, [retryCount]);

  return (
    <div className="system-health-widget glass-panel">
      {error ? (
        <div className="health-alert error">
          <AlertCircle size="{18}"/>
          <span>Render instance waking up (Cold start)... retrying automatically.</span>
        </div>
      ) : (
        <div className="health-alert success">
          <CheckCircle2 size="{18}"/>
          <span>{health?.engine} — Online (Schema: {health?.schema})</span>
        </div>
      )}
    </div>
  );
}

[!NOTE]
This automatic retry strategy converts what would otherwise look like an outage into an informative, real-time telemetry indicator.

6. Featherweight Native Internationalization (i18n) 🌐

Many single-page apps install heavy internationalization suites that bundle unnecessary complexity. For LifeOps, I built an elegant, zero-dependency translation engine in under 80 lines within LanguageContext.jsx:

import React, { createContext, useContext, useState, useEffect } from 'react';
import { es } from '../i18n/locales/es';
import { en } from '../i18n/locales/en';

const translations = { es, en };
const LanguageContext = createContext();

export function LanguageProvider({ children }) {
  const [language, setLanguageState] = useState(() => {
    const saved = localStorage.getItem('lifeops_language');
    if (saved === 'es' || saved === 'en') return saved;
    return navigator.language?.toLowerCase().startsWith('es') ? 'es' : 'en';
  });

  const toggleLanguage = () => {
    const next = language === 'es' ? 'en' : 'es';
    setLanguageState(next);
    localStorage.setItem('lifeops_language', next);
    document.documentElement.lang = next;
  };

  // Dot-notation resolver with dynamic token interpolation
  const t = (path, params = {}) => {
    const dict = translations[language] || translations.es;
    let val = path.split('.').reduce((prev, curr) => prev?.[curr], dict) || path;
    if (typeof val === 'string') {
      return Object.keys(params).reduce((str, key) => str.replace(new RegExp(`\\{${key}\\}`, 'g'), params[key]), val);
    }
    return val;
  };

  return (
    <LanguageContext.Provider language, t toggleLanguage, value="{{" }}>
      {children}
    </LanguageContext.Provider>
  );
}

export const useLanguage = () => useContext(LanguageContext);

Key Architectural Benefits:

Zero External Dependencies: Shaves over 100 KB from production bundle footprints.
Intuitive API: Translates seamlessly via t('dashboard.welcome') or interpolates counts with t('sport.stats.distance', { count: 10 }).
Smart Persistence & Auto-Detection: Stores preference in localStorage and detects the browser's preferred locale on first visit.

Conclusion & What's Next 🎯

With our React frontend fully configured, the Glassmorphism Dark Mode design system operational, reactive authentication connected to Supabase, and the 360° Dashboard displaying real-time metrics, LifeOps now has an engaging, modern client ready for daily use.

In Part 3 of this series, we dive directly into the functional core:

Fitness & Sport Module: Logging runs, gym workouts, and cycling sessions with pace calculations, Personal Bests (PB), and calorie tracking.
Reading & Cinema Tracking: Dynamic page completion bars, streaming platform catalogs, and ratings.
Professional Kanban Board: 4-column project workflow, task prioritization, and chronological progress logging with timestamps stored in PostgreSQL JSONB.

References & Useful Links 🔗

🚀 Production Application: Try the live app at datalaria.com/apps/lifeops.
🌐 Backend API: Interactive OpenAPI Swagger documentation at lifeops-api.onrender.com/docs.
⚛️ React Documentation: Official React 19 documentation at react.dev.
⚡ Vite: Next-generation frontend tooling at vite.dev.
📊 Recharts: Declarative charting library for React at recharts.org.
🎨 Lucide Icons: Clean, open-source SVG icon library at lucide.dev.

See you in Part 3! Feel free to share your thoughts or frontend architectural tips in the comments below. 👇

Vite+ Beta Explained: The Future of JavaScript Tooling?

Wed, 08 Jul 2026 13:54:52 +0000

The team behind Vite has introduced Vite+, a new unified frontend toolchain currently available in beta. At first glance, it might look like just another CLI on top of Vite. But after reading the announcement, it's clear that the vision is much bigger.

Vite+ isn't a replacement for Vite. Instead, it's an attempt to bring together the tools we commonly use throughout the frontend development lifecycle under one consistent developer experience.

If you've ever found yourself juggling multiple CLIs, configuration files, linters, formatters, test runners, and build tools, Vite+ is trying to simplify that entire workflow.

Let's take a closer look.

What is Vite+?

Vite+ is a unified frontend toolchain from VoidZero that combines project creation, development, building, testing, linting, formatting, type checking, runtime management, package management, and task execution through a single CLI called vp.

Instead of treating these as separate tools that developers have to install, configure, and maintain individually, Vite+ bundles them into one cohesive ecosystem.

The idea is simple:

One toolchain. One CLI. One consistent developer experience.

If you've worked on multiple React or Vite projects, you've probably seen each repository using a slightly different combination of tools. One project uses ESLint, another uses Oxlint. One uses Prettier, another uses Biome. Some rely on npm scripts, while others use custom task runners.

None of these choices are wrong, but they do increase the amount of project-specific knowledge every developer has to learn.

Vite+ aims to reduce that friction.

What's Included?

Rather than introducing brand-new tools, Vite+ brings together some of the best modern tooling into a single ecosystem.

Vite

Vite continues to power the development server and production builds with its fast startup time and excellent developer experience.

If you're already using Vite, this part will feel familiar.

Vitest

Testing is handled by Vitest, which has become the preferred testing framework for many Vite projects thanks to its speed and compatibility with the Vite ecosystem.

Instead of deciding between multiple testing solutions, Vite+ embraces a single, well-integrated choice.

Rolldown

One of the most interesting additions is Rolldown, the Rust-based bundler that's designed to deliver Rollup compatibility with significantly better performance.

As Rolldown continues to mature, it has the potential to reduce build times without requiring developers to rewrite their existing build configurations.

tsdown

Vite+ also includes tsdown, a tool focused on building TypeScript libraries.

If you've published TypeScript packages before, you'll know that creating optimized builds and declaration files often requires additional setup. tsdown aims to make that workflow much simpler.

Oxlint and Oxfmt

Linting and formatting are handled by Oxlint and Oxfmt.

These Rust-powered tools focus on performance while maintaining compatibility with modern JavaScript and TypeScript development.

For larger repositories, even small improvements in linting and formatting speed can noticeably improve the development experience.

Runtime and Package Management

Vite+ also manages JavaScript runtimes and package managers through the same interface.

Instead of expecting developers to install and configure everything manually, the toolchain attempts to provide a more consistent environment across machines and teams.

Task Runner

The new task runner allows common development tasks to be executed through the same CLI instead of scattering them across multiple npm scripts.

This makes projects easier to understand and helps establish consistent conventions.

Why This Is More Than Just Another CLI

The biggest takeaway from Vite+ isn't the new commands.

It's the shift toward opinionated consistency.

Modern frontend projects often rely on a collection of excellent tools, but they're usually assembled manually. Every project makes different decisions, leading to different commands, different configurations, and different maintenance requirements.

Vite+ doesn't claim that existing tools are inadequate.

Instead, it asks a different question:

What if all these tools worked together as one product instead of separate projects?

That approach offers several practical benefits:

Faster project onboarding.
Fewer configuration files to maintain.
More consistent workflows across repositories.
Easier upgrades.
Reduced decision fatigue when starting new projects.

Experienced developers can certainly assemble this stack themselves.

The value of Vite+ lies in providing these integrations out of the box.

Why Vite+ Feels Built for the AI Era

One aspect of the announcement that stood out to me wasn't a feature, it was the direction.

We're no longer writing code alone.

Whether you use GitHub Copilot, Cursor, Claude Code, or other AI coding assistants, these tools work best when projects follow predictable structures and conventions.

AI assistants have to infer how your project is organized.

If every repository uses different commands, different build tools, different scripts, and different configuration patterns, that inference becomes harder.

A unified toolchain changes that.

When creating, building, testing, linting, formatting, and running tasks all follow consistent conventions, AI agents spend less time guessing and more time helping.

That's a subtle but important advantage.

I don't think Vite+ was created solely for AI-assisted development, but it certainly feels aligned with where software development is heading.

Should You Adopt It Today?

Since Vite+ is currently in beta, I'd approach it differently depending on the project.

If you're starting a personal project or exploring new tooling, it's absolutely worth trying. It offers a glimpse into what the future of frontend tooling might look like.

For production applications that are already stable, I'd wait until the ecosystem matures further before migrating.

The good news is that Vite+ builds upon technologies many developers are already using, so adopting it later shouldn't feel like learning an entirely new ecosystem.

Final Thoughts

Vite+ isn't trying to replace every frontend tool.

It's trying to replace the experience of stitching those tools together yourself.

That's an important distinction.

Frontend development has reached a point where most teams use the same categories of tools, bundlers, test runners, linters, formatters, package managers, and task runners. The challenge is no longer finding good tools; it's making them work well together.

Vite+ is VoidZero's answer to that challenge.

Will it become the standard frontend toolchain? It's too early to say.

But one thing is clear: the conversation is shifting from building faster tools to building more cohesive developer experiences.

And if Vite+ delivers on that vision, it could influence how frontend projects are built for years to come.

Rebuilding Defrag98: Getting the Details Right

Tue, 30 Jun 2026 18:36:59 +0000

There's a specific kind of satisfaction that comes from watching the Windows 98 defrag screen do its thing. Clusters shuffling around. That progress bar crawling. The sense that your computer was doing something important, even if you had no idea what.

That's the feeling I wanted to bottle when I built the first version of defrag98.com back in 2024. The project took off beyond anything I'd expected. It got picked up by Hacker News and The Verge, and people from all over the world spent time staring at a browser tab the way their younger selves once stared at a CRT monitor. Mission accomplished.

But the more I looked at it, the more I noticed the cracks.

It wasn't quite right

The most significant problem was the simulation logic. The original Windows 98 defragmenter didn't march through clusters sequentially. It read blocks, wrote them, and shuffled them around in a messier, more organic process that made watching it genuinely hypnotic. My first implementation was too orderly. It looked like a simulation. The real one looked like a machine thinking.

The legend was missing too. The real Windows 98 defragmenter had a dedicated button that opened a dialog explaining what each block color meant: optimized, reading, writing, bad cluster. Without it, the simulation was just a pretty light show. Now it has one.

On the visual side, the cluster grid also had a black background, when the real defragmenter used white. A small detail, but exactly the kind of thing that breaks the spell for anyone who actually remembers the original.

Then there was the progress bar. The real utility didn't draw a smooth, continuous fill. It revealed a row of chunky segmented blocks one at a time, with a "% Complete" caption underneath. Mine was too modern, too clean. Now it fills block by block the way it should, and the window is sized to give it room to breathe.

Even the controls were missing some manners. The original asked you to confirm before stopping a defrag, and it told you plainly when the job was Paused or Stopped. Small things, but they're the difference between a screensaver and a tool you can actually operate.

The rebuild: Next.js to Vite, and a faithful simulation

I moved the project from Next.js to Vite + React. This might sound like a lateral move, but it was the right call for what defrag98.com actually is: a single-page, entirely client-side app with no routing, no server-side data, and no need for SSR. Next.js is excellent at what it does, but fighting its SSR model to build something that runs entirely in the browser felt like wearing a suit to go swimming.

Vite gave back the dev experience that SSR had been quietly taxing. Faster builds, instant HMR, and a mental model that actually matches the app. While I was in there, the rest of the stack got a refresh too: Tailwind CSS v4 through its native Vite plugin (no more PostCSS pipeline), Base UI for the accessible dialogs, selects and checkboxes, Zustand for state, TypeScript 6, and the Rust-based oxc toolchain (oxlint and oxfmt) in place of ESLint and Prettier for near-instant linting and formatting.

The bigger change was moving cluster rendering to a <canvas> element. Instead of creating and updating hundreds of DOM nodes, I'm now drawing directly to a 2D canvas context. The number of clusters rendered adapts to whichever disk size you select, so a larger virtual drive produces a denser, more satisfying grid. The difference is easy to feel: the animation is smoother, the browser is happier, and it scales without complaint. I also size the canvas before the first paint, which killed the layout shift that used to jump around on mobile.

On the simulation side, I rewrote the defrag algorithm to properly model read and write operations on individual clusters, with non-sequential processing that mirrors how the original utility actually behaved. If you remember the way blocks would jump around seemingly at random before gradually settling into order, that's what it does now.

The sound got some attention too. The hard disk loop and the completion chime were re-encoded to a fraction of their old size (the HDD loop went from over a megabyte to around 350KB), shipped as Opus/WebM with an AAC fallback, and the Win98 fonts are preloaded now so nothing flashes on first paint. There are also toggles in Settings to mute the hard disk sound or the mouse clicks, and your choice is remembered the next time you visit.

When a defrag finishes, you now get the authentic Windows 98 "Disk Defragmenter" message box telling you it's done, chime and all, instead of the run just quietly ending.

A couple of things changed off-screen that I care about as much as the visible ones. I dropped Google Analytics and Tag Manager in favor of Cloudflare's cookieless Web Analytics, so there's no tracking cookie and no consent banner getting between you and the nostalgia. The site is hosted on Cloudflare Workers as static assets, and it ships an llms.txt so the AI crawlers that come poking around get a clean description of what this thing is.

defrag98.com also ships a web app manifest, so on supported browsers you can install it to your device and launch it like a native app. And it now runs fully offline: a service worker built with vite-plugin-pwa and Workbox precaches the app shell and every runtime asset, the fonts, cursors, audio, and icons, so once you've opened it once you can defragment a virtual drive on a plane with no signal. New builds activate quietly on the next launch, with no update prompt to nag you. Feels right for something built to feel like software from another era.

There's also a hidden Easter egg somewhere in the app. I'll leave it at that. If you grew up on Windows 98, you'll know it when you see it.

A quieter ask

The original version had a donation banner styled as an authentic Windows ME system notification: yellow background, full viewport width, sliding down from the top of the screen five seconds into your session. It was accurate to the era. It was also an interruption, landing right in the middle of the nostalgic moment it was supposed to be protecting.

The data confirmed it. Despite solid traffic, very few visitors converted to donors.

The new approach takes a cue from pre-release Windows software, the small line of unobtrusive text in the corner of the screen that says something like "This is a pre-release version". I added a quiet line in the bottom-right of the desktop area, linking to my Buy Me a Coffee page. It's there if you want it. It doesn't demand your attention. The only other time donating comes up is in that completion message box, once the defrag has actually finished and you've had your moment: a gentle Yes or No, never an interruption. The minimum donation has also dropped from $5 to $3, because the goal was never to extract money. It's to help cover the domain and hosting costs that keep defrag98.com running for anyone who gets something out of it.

Why this still matters to me

I've received $148 in total donations since launching. That's not a business. But it's proof that people feel something when they use it, enough to voluntarily send a few dollars to a stranger on the internet for a free toy.

That's the part that keeps me iterating on this instead of moving on. It's not a portfolio piece. It's a tiny time machine, and apparently enough people want to visit 1998 for a few minutes that keeping the lights on feels worth caring about.

If you haven't tried it yet, go defragment something. If you used to stare at this screen as a kid, I hope it hits the way I intended. And if you find the Easter egg, well, you'll know what to do.

How I Migrated From Astro 5 to 6 With All My React Islands

Mon, 25 May 2026 12:18:52 +0000

I run EdgeKits on the full Cloudflare stack, and the marketing site is mostly Astro with a handful of React islands - a newsletter form, a toaster, a desktop nav. Astro 6 moved the dev server into workerd so local development finally mirrors production. I expected a version bump. I got an afternoon of debugging.

Here is every error I hit, in the order I met it, with the log that produced it, why it happened, and the exact fix. If you are doing an Astro 5 to 6 migration with React islands on Cloudflare Workers, this is the map I wish I'd had.

My stack: Astro 6.3.6, @astrojs/cloudflare 13.5.x, @astrojs/react 5.0.5, React 19, Vite 7, Tailwind 4, output: 'server' on Workers.

First wall: the Vite dependency scan crashes

The very first npm run dev printed this before the server was even ready:

[ERROR] [vite] (!) Failed to run dependency scan. Skipping dependency pre-bundling.
X [ERROR] Unexpected newline after "throw"
    src/domain/analytics/components/ConsentBanner.astro:7:24
      7 | if (consentStatus) throw

The confusing part: that line in my source says return, not throw. I never wrote a throw there.

The cause. Astro compiles a top-level early return in component frontmatter into a throw. esbuild's dependency scanner then tries to parse the compiled output and trips on JavaScript's automatic-semicolon-insertion rule: throw cannot be followed by a newline. A single offending file aborts the scan for the entire project.

The knock-on effect is the dangerous part. With the scan dead, Vite stops pre-bundling and starts discovering dependencies lazily - one at a time, on each request. Remember that; it is the root of the next two crashes.

The fix. Move the condition out of the frontmatter and into the template:

---
// before: if (consentStatus) return
const showBanner = !consentStatus
---

{showBanner && <ConsentUI >}

Do the same anywhere you have a bare early return in frontmatter. (You can also lean on the dependency pre-declaration from the next section, which makes the failed scan harmless - but cleaning up the returns is the tidy fix.)

The boss fight: Invalid hook call in Astro 6 on Cloudflare

With the site loading, the first page render exploded:

[ERROR] [vite] Invalid hook call. Hooks can only be called inside
of the body of a function component.
[ERROR] [vite] TypeError: Cannot read properties of null (reading 'useState')
    at useState (.../.vite/deps_ssr/chunk-EMAOOZFV.js)
    at useSubscribeNewsletter (src/hooks/useSubscribeNewsletter.ts)
    at NewsletterFlow (src/components/layout/islands/NewsletterFlow.tsx)

The React message lists three suspects: mismatched versions, broken rules of hooks, or more than one copy of React. None of them was true in the usual sense. Two clues told me this was a dev-server problem, not my code:

It only failed on the first load. A browser refresh rendered the page fine.
Switching to the Node adapter made it vanish completely.

The cause. In Astro 6 the Cloudflare adapter runs SSR inside workerd via @cloudflare/vite-plugin. Vite optimizes server dependencies into a deps_ssr folder. Because my dependency scan had failed, deps were being discovered lazily; every discovery re-ran optimization and reloaded the worker. React and react-dom/server landed in different optimize passes, and after a reload react-dom/server held a reference to a React instance whose hook dispatcher was now null. Calling useState read that null.

That is the "more than one copy of React" warning - except the split was in the optimizer, not on disk. npm ls react showed a single, deduped react@19. The duplication was a timing artifact, not a packaging one.

The fix that did not work: vite.ssr.optimizeDeps

My first instinct was to list the deps in vite.ssr.optimizeDeps.include. Nothing changed. That cost me a while, so learn from it:

With the Cloudflare plugin, SSR is its own Vite environment, and vite.ssr.optimizeDeps never reaches it. The documented way to configure that environment's optimizer is a small Vite plugin using the configEnvironment hook.

The config that worked: a configEnvironment optimizer plugin

A tiny plugin that pre-bundles the server graph for every non-client environment:

const SERVER_OPTIMIZE_DEPS = [
  'react',
  'react-dom',
  'react-dom/server.edge',
  'react/jsx-runtime',
  'react-hook-form',
  '@hookform/resolvers/zod',
  'sonner',
  'cmdk',
  'radix-ui',
  'class-variance-authority',
  'tailwind-merge',
  'zod',
  'drizzle-orm',
  'drizzle-orm/d1',
  '@astrojs/rss',
]

function optimizeServerDeps() {
  return {
    name: 'optimize-server-deps',
    configEnvironment(name) {
      if (name !== 'client') {
        return { optimizeDeps: { include: SERVER_OPTIMIZE_DEPS } }
      }
    },
  }
}

Then two lines in vite.resolve that matter as much as the include list:

resolve: {
  dedupe: ['react', 'react-dom'],
  alias: { 'react-dom/server': 'react-dom/server.edge' },
}

dedupe keeps a single React instance across the client and worker graphs. The alias forces the Web-Streams ("edge") build of react-dom/server everywhere. In Astro 5 I only needed that build in production; now that dev runs in workerd, it has to be the edge build in dev too.

The whole idea: get every dependency optimized in one pass at startup, so there is no lazy discovery, no reload mid-render, and nothing to desync. Add the same list to the client-side vite.optimizeDeps.include so the browser graph doesn't churn either.

The i18n ghost: the astro:i18n virtual module forces one last reload

After that, the reload cascade shrank to a single line - and a new crash:

[vite] new dependencies optimized: astro/virtual-modules/i18n.js
[vite] reloading
[ERROR] Cannot read properties of undefined (reading 'i18n')
    at getComponentByRoute (.../deps_ssr/astro_app_entrypoint_dev.js)

Same disease, different mask. The one remaining late reload came from Astro's own astro:i18n virtual module, pulled in by the i18n: {} block in my config. The reload re-instantiated the worker mid-request and left the app config object undefined - so reading .i18n off it threw.

The catch: it is a virtual module, so I can't pre-bundle it through include. But I can tell the optimizer to leave it alone:

optimizeDeps: {
  include: SERVER_OPTIMIZE_DEPS,
  exclude: ['astro:i18n', 'astro/virtual-modules/i18n.js'],
}

No optimization for that module means no reload, which means the React chunks stay put. Both crashes gone. This was also the moment I confirmed my custom KV-based i18n engine was never the culprit - it was Astro's built-in virtual module all along.

React icons brought it back: @phosphor-icons/react

Adding @phosphor-icons/react reintroduced the cascade risk, because it is one more island dependency the SSR pass meets on first render. The fix is identical: add it to both the client and server include lists.

One trap I walked straight into: the docs-friendly @phosphor-icons/react/dist/ssr subpath throws type and resolution errors under moduleResolution: "bundler", which Vite and Astro use by default. The plain @phosphor-icons/react import works in both .astro files and React islands, so I dropped the dist/ssr subpath entirely. In .astro files the icon renders server-side and ships only HTML; in islands, named imports tree-shake. No bundle-size penalty either way.

The whole astro.config.mjs, in one place

Here is the migration-relevant shape of my config - the two helper constants, the optimizer plugin, and where they plug into defineConfig. Everything unrelated (fonts, image, i18n locales, markdown) is unchanged from Astro 5 and trimmed out:

// astro.config.mjs
import { defineConfig } from 'astro/config'
import cloudflare from '@astrojs/cloudflare'
import tailwindcss from '@tailwindcss/vite'
import react from '@astrojs/react'
import mdx from '@astrojs/mdx'

// Pre-bundle these for the SSR/workerd environment in ONE pass at startup, so
// Vite never discovers them lazily and reloads the worker mid-render.
const SERVER_OPTIMIZE_DEPS = [
  'react',
  'react-dom',
  'react-dom/server.edge',
  'react-dom/client',
  'react/jsx-runtime',
  'react-hook-form',
  '@hookform/resolvers/zod',
  'sonner',
  'cmdk',
  'radix-ui',
  '@phosphor-icons/react',
  'class-variance-authority',
  'tailwind-merge',
  'clsx',
  'zod',
  'drizzle-orm',
  'drizzle-orm/d1',
  'drizzle-orm/sqlite-core',
  'drizzle-zod',
  '@astrojs/rss',
  // Astro internals that were optimized lazily right before the i18n crash.
  // Real package exports, safe to pre-bundle.
  'astro/zod',
  'astro/assets/services/noop',
  'astro/actions/runtime/entrypoints/server.js',
]

// Virtual modules the optimizer must NOT touch. Excluding astro:i18n kills the
// last late reload - the one that desynced React and threw "Invalid hook call".
const SERVER_OPTIMIZE_EXCLUDE = ['astro:i18n', 'astro/virtual-modules/i18n.js']

// SSR is its own Vite environment under @cloudflare/vite-plugin. The only way to
// reach its optimizer is configEnvironment - vite.ssr.optimizeDeps is ignored.
function optimizeServerDeps() {
  return {
    name: 'optimize-server-deps',
    /** @param {string} name */
    configEnvironment(name) {
      if (name !== 'client') {
        return {
          optimizeDeps: {
            include: SERVER_OPTIMIZE_DEPS,
            exclude: SERVER_OPTIMIZE_EXCLUDE,
          },
        }
      }
    },
  }
}

export default defineConfig({
  adapter: cloudflare({
    configPath: 'wrangler.jsonc',
    imageService: 'cloudflare',
  }),
  integrations: [react(), mdx()],
  // site, image, i18n, markdown - unchanged from Astro 5, omitted here.

  vite: {
    plugins: [tailwindcss(), optimizeServerDeps()],
    resolve: {
      dedupe: ['react', 'react-dom'],
      // dev now runs in workerd, so use the edge build of react-dom/server everywhere
      alias: { 'react-dom/server': 'react-dom/server.edge' },
    },
    // same list for the client graph so the browser doesn't churn either
    optimizeDeps: {
      include: [
        'react',
        'react-dom',
        'react-dom/client',
        'react/jsx-runtime',
        'react-hook-form',
        '@hookform/resolvers/zod',
        'sonner',
        'cmdk',
        'radix-ui',
        '@phosphor-icons/react',
        'class-variance-authority',
        'tailwind-merge',
      ],
    },
    ssr: {
      // cookie is CommonJS and chokes workerd's optimizer - keep it external
      external: [
        'async_hooks',
        'node:fs',
        'node:path',
        'node:url',
        'node:crypto',
        'cookie',
      ],
    },
  },

  output: 'server',
  build: { inlineStylesheets: 'always' }, // kills the render-blocking CSS request
})

The production-only twist: a cold hit served the homepage

Local dev was clean, so I deployed. Then a direct hit on an article URL did something I could never reproduce on my machine: the first request to /en/blog/<slug>/ returned the homepage, and only a second request showed the article. An external link landing cold on the page did the same. Refresh, and it behaved. The classic "works on the second try."

The i18n middleware was the obvious suspect, since it does locale redirects, so I instrumented every context.redirect with a log line and watched wrangler tail. On a valid deep URL: nothing. The middleware never ran. That was the tell.

The cause. My wrangler.jsonc had run_worker_first: false. With that, Cloudflare's static-asset layer answers before the Worker. On a cold hit to an SSR route with no matching static file, that layer short-circuited and served the landing page - my middleware and SSR never executed. The warm second request reached the Worker and rendered the article. It is also why dev never showed it: there is no Cloudflare asset layer in astro dev, so the middleware always runs locally.

The fix. One line, so the Worker - and the middleware it carries - runs first on every route:

// wrangler.jsonc
"assets": { "directory": "./dist", "binding": "ASSETS", "run_worker_first": true }

Redeployed, hit the URL cold: article on the first try. But true has a cost - now every request, including each /_astro/* chunk, font, and image, travels through the Worker instead of being served straight from the asset layer. On a mostly-static site that is wasted latency.

So the setting I actually shipped is the array form, which runs the Worker first only for page routes and lets static assets bypass it:

// wrangler.jsonc
"assets": { "directory": "./dist", "binding": "ASSETS", "run_worker_first": ["/*", "!/_astro/*"] }

Pages still hit the Worker first - middleware runs, no homepage fallback - while /_astro/* goes straight to the asset layer. I confirmed it with wrangler tail: under true every asset request showed up in the Worker logs; with the array, the /_astro/* lines vanish and only page routes remain. Same fix for the bug, asset latency back to normal.

The short checklist: Astro 5 → 6 with React islands on Cloudflare

If you are migrating Astro 5 → 6 with React islands on Cloudflare, this is the whole thing on one page:

Move frontmatter early return into template conditionals (or accept the harmless scan warning).
Configure the SSR optimizer through a configEnvironment plugin, not ssr.optimizeDeps.
resolve.dedupe React, and alias react-dom/server to react-dom/server.edge in dev too.
Pre-include every island dependency so the optimizer runs once at startup.
exclude the astro:i18n virtual module to kill the last reload.
Import Phosphor icons from the main entry, never /dist/ssr.
inlineStylesheets: 'always' clears the CSS render-block.
Make the Worker run first on page routes via run_worker_first in wrangler.jsonc - use the array ["/*", "!/_astro/*"] so pages get the middleware but /_astro/* still serves straight from the asset layer. Otherwise the SSR middleware silently won't run on a cold hit and Cloudflare serves the landing page instead.

Clear the optimizer cache (node_modules/.vite) between attempts - stale chunks will lie to you. After all of it: the dev server boots clean, every island hydrates on the first load, and PageSpeed lands in the high 90s on mobile and around 90 on desktop.

Rethinking the Frontend: My Journey from Static HTML to React's Modular World

Sat, 31 Jan 2026 13:34:56 +0000

React is a Mindset, Not Just Syntax

When I first started moving from plain HTML to React, I thought I just needed to learn some new syntax. I was wrong. The real challenge wasn't the code; it was unlearning how I viewed a website.
I remember working on my first portfolio project right after finishing my CSS course. My instructor had a strict rule: No pre-made templates. I had to build everything from scratch. It was a nightmare. Even though I was using Bootstrap to speed things up, I found myself lost in a sea of thousands of utility classes. My HTML files became "div-soups," with lines like class="d-flex justify-content-center align-items-center col-lg-4 col-md-6 mb-4". Debugging a simple layout shift took me hours, and by the time I finished, it had taken nearly two full weeks of frustrating trial and error. Finding an original idea that wasn't a clone of a template while managing all those classes was the hardest part.
That struggle was my turning point. In the old days, I’d look at a page as a single, overwhelming document. React changed that. It taught me to stop seeing "pages" and start seeing "systems." Instead of micromanaging the browser, I now describe what I want the UI to look like, and React handles the heavy lifting.

Tip: Think of React components like Lego blocks. You build small, solid pieces first, and then you snap them together to create something complex.

Step 1: Ditching the Slow Lane - Why I Use Vite

Before you can build anything, you need an environment that doesn't get in your way. For a while, Create React App (CRA) was the default, but it’s become slow for today’s standards.

Why Vite Feels Like a Superpower

I switched to Vite (which means "fast" in French), and the difference was night and day. Unlike the old days of waiting for my portfolio to refresh every time I changed a Bootstrap class, Vite uses Native ESM. This means it doesn't make you wait for the whole project to bundle before you can see your changes. Your edits show up instantly.

Setting up the project scaffold

npm create vite@latest my-react-app -- --template react

Figure 1: Initializing the project using Vite and installing necessary dependencies through the terminal.

Don't forget this part! (I've missed it more than once)

cd my-react-app
npm install
npm run dev

Quick Note: If you ever run npm run dev and see a blank page or a "command not found" error, 99% of the time it's because you skipped npm install or you are not in the correct project folder. Make sure your terminal is opened inside the main directory where package.json lives. We've all been there!

Feature	The Old Way (HTML + Bootstrap)	The New Way (React + Bootstrap)
Organization	One massive, confusing HTML file	Multiple small, clean files
Logic	Manual jQuery or JS updates	Automatic updates via Props/State
Debugging	Hard to find where tags end	Easy to isolate the component

What Makes a Good Component?

A clean component should do one thing well. It takes in some info (Props) and spits out the UI (JSX). Here’s a quick example of a StatusCard I built using Bootstrap classes within React:

/**
 * A simple card to show service health using Bootstrap classes.
 */
function StatusCard({ title, status }) {
  // Logic to change the Bootstrap badge color based on status
  const badgeClass = status === 'online' ? 'bg-success' : 'bg-danger';

  return (
    <div className="card shadow-sm m-2" style={{ width: '18rem' }}>
      <div className="card-body">
        <h5 className="card-title">{title}</h5>
        <span className={`badge ${badgeClass}`}>
          {status === 'online' ? 'Service Up' : 'Service Down'}
        </span>
      </div>
    </div>
  );
}

export default StatusCard;

Figure 2: Implementing modular logic within the StatusCard component and managing the local file structure in VS Code.

What’s happening here?

Clean Logic: I use a simple variable (badgeClass) to toggle between bg-success and bg-danger. No more manual DOM manipulation.
Reusability: Instead of copying and pasting the card's HTML 10 times, I just call <StatusCard > with different props.

Figure 3: The final rendered UI in the browser, demonstrating dynamic styling and component reusability on localhost:5173.

Solving the Bootstrap "Mess": Logic over Layout

A huge part of my two-week portfolio frustration was keeping track of where one Bootstrap row ended and another began. In a giant HTML file, one missing </div> can break your entire layout.

How React Components Tamed Bootstrap

In React, I don't have to look at 500 lines of HTML at once. I can put my Navbar in one file, my Hero section in another, and my Footer in a third.
No more "Div-Soup": Each component only contains the code it needs.
Easier Debugging: If the Grid layout is broken in the Header, I know exactly which small file to check.
Component-Level Styling: I can still use Bootstrap for the heavy lifting, but React handles the structure.

JSX: It’s Like HTML, But With Brains

JSX looks like HTML, but it’s actually JavaScript. This is where most of my early "bugs" came from because I kept trying to use standard HTML attributes.

Three Rules I Learned the Hard Way

The Parent Rule: You can't return two things side-by-side. Wrap them in a tag or a Fragment <> ... <>.
CamelCase Everything: Since it’s JS, you can’t use class. You must use className.
Close Your Tags: Every tag must be closed, even <br > or <img >.

Technical Inquiry & Retrospective: Resolving Common Development Challenges

Q1: Integration of CSS Frameworks (Bootstrap)
•Inquiry: Is it feasible to maintain Bootstrap within a React-based ecosystem?
•Insight: Absolutely. However, the transition from class to className is crucial. Beyond syntax, the real shift is moving from global styling to Component-Level Styling, ensuring that Bootstrap elements remain modular and don't create "Div-Soup."
Q2: Performance and Rendering Optimization
•Inquiry: Why do initial React applications sometimes experience performance lag?
•Insight: This is often a result of inefficient component structure. During my Movie Watchlist project, I learned that a monolithic file causes unnecessary re-renders. By refactoring into specialized components, we leverage the Virtual DOM more effectively, ensuring high-speed UI updates.

Conclusion: Focus on the Logic, Not Just the Look

Moving to React is a journey of unlearning. To anyone stuck in the "Bootstrap Spaghetti" phase: focus on making your components small.

Clean code isn't about how it looks today—it's about how easily you can change it next week or later.

References

React Docs: Thinking in React
Vite: Getting Started Guide

Guide to Containerizing a Modern JavaScript SPA (Vue/Vite/React) with a Multi-Stage Nginx Build

Tue, 07 Oct 2025 17:15:59 +0000

This guide outlines the professional, multi-stage Docker strategy required to package a built Single Page Application (SPA), ensuring the final image is secure, minimal, and correctly configured to serve the application and handle remote API calls. This architecture is valid for Vue, Vite, React, Angular, or Svelte applications.

1. Multi-Stage Dockerfile: Build vs. Serve

This file uses a two-stage build to drastically reduce the final image size (eliminating Node.js and build tools) and enhance security.

# Dockerfile

# Stage 1: Build the Application (AS build)
FROM docker.io/node:20-alpine AS build

# 1. Inject API URL at build time 
ARG VITE_API_URL=http://localhost:3000/api
ENV VITE_API_URL=$VITE_API_URL

WORKDIR /app
COPY package*.json ./
RUN npm ci 
COPY . .
RUN npm run build:deploy 

# ---

# Stage 2: Serve the Application (AS final)
FROM docker.io/library/nginx:stable-alpine AS final

# 1. Custom Nginx Configuration Setup
RUN rm /etc/nginx/nginx.conf
COPY nginx-main.conf /etc/nginx/nginx.conf
COPY nginx.conf /etc/nginx/conf.d/

# 2. Grant Non-Root User Permissions (CRITICAL for security & stability)
# Fixes 'mkdir() "/var/cache/nginx/client_temp" failed (13: Permission denied)'
RUN mkdir -p /var/run/nginx \
    && chown -R nginx:nginx /var/cache/nginx \
    && chown -R nginx:nginx /var/run/nginx
    
# 3. Copy only the required static files from the build stage
COPY --from=build /app/dist /usr/share/nginx/html

EXPOSE 8080

# 4. Run as Non-Root User (Security Best Practice)
USER nginx

CMD ["nginx", "-g", "daemon off;"]

2. Nginx Configuration Files (The Missing Pieces)

These custom files are necessary to resolve critical permission and port errors when running Nginx as a non-root user.

A. Main Configuration (`nginx-main.conf`)

This file replaces the default /etc/nginx/nginx.conf. It controls the Master Process directives.

# nginx-main.conf (Copied to /etc/nginx/nginx.conf)

# Fixes 'open() "/run/nginx.pid" failed (13: Permission denied)'
# This MUST be in the main context.
pid /var/run/nginx/nginx.pid; 

# Sets the user for worker processes (ignored by Dockerfile's USER, but good practice)
user  nginx; 
worker_processes  auto;

events {
    worker_connections  1024;
}

http {
    include       mime.types;
    default_type  application/octet-stream;
    sendfile        on;
    keepalive_timeout  65;

    # Include our custom server block
    include /etc/nginx/conf.d/*.conf; 
}

B. Server Block (`nginx.conf`)

This file defines how your application is served and is placed in the conf.d directory.

# nginx.conf (Copied to /etc/nginx/conf.d/nginx.conf)

server {
    # Fixes 'bind() to 0.0.0.0:80 failed (13: Permission denied)'
    # Nginx listens on a high port (>1024) which the non-root user can bind to.
    listen 8080; 
    root /usr/share/nginx/html;
    index index.html;

    # Security: Hides the Nginx version
    server_tokens off;

    # SPA Routing: Directs all unmatched requests to index.html
    location / {
        try_files $uri $uri/ /index.html;
    }

    # Security: Block access to hidden files
    location ~ /\. {
        deny all;
    }
}

3. Local Development with Podman Compose

Using a docker-compose.yaml file automates the entire process.

version: '3.8'

services:
  frontend:
    build:
      context: .
      dockerfile: Dockerfile
      args:
        VITE_API_URL: https:// http://localhost:3000/api/v1
    
    container_name: frontend-container
    
    # Maps host's 8080 port to the container's 8080 listening port
    ports:
      - "8080:8080"
    
    image: my-frontend-app:v1.0.0
    restart: always

Essential Podman Compose Commands

Command	Action
`podman compose build`	Executes the `Dockerfile` with the specified `args`.
`podman compose up -d`	Builds (if needed) and starts the container in the background.
`podman compose ps`	Checks the running status of the service(s).
`podman compose down`	Stops and removes the container(s) and network.

4. Guide Reusability and Troubleshooting

This architecture is reusable for nearly any SPA. Just update the VITE_API_URL in docker-compose.yaml and adjust the build script (npm run build:deploy) and output folder (/app/dist) in the Dockerfile if needed.

The most critical errors encountered and resolved are:

Error Logged	Cause	Solution in this Guide
`bind() to 0.0.0.0:80 failed`	Non-root user attempting to use privileged port 80.	Change `listen` to `8080` in `nginx.conf`.
`open() "/run/nginx.pid" failed`	Non-root user lacking write permission to the default PID file location.	Add `pid /var/run/nginx/nginx.pid;` to `nginx-main.conf`.
`mkdir() "/var/cache/..." failed`	Non-root user lacking permission to Nginx cache directory.	Add `chown -R nginx:nginx /var/cache/nginx` to `Dockerfile`.

You can see the files there with a lot more remarks i made coding-remarks

5. Conclusion

By implementing this Multi-Stage Build and carefully configuring Nginx for a non-root user, you've achieved the trifecta of modern container deployment: security, stability, and speed. Every step—from moving the PID file to changing the listen port—is a direct defense against common production pitfalls and security vulnerabilities. This standardized approach is the most reliable way to ship any modern JavaScript SPA, ensuring your application moves seamlessly from local development to production. You are now equipped with the knowledge to troubleshoot the most common containerization challenges and build a robust, production-ready frontend environment.