Case Study: Technical Debt in a Static Site After Just One Week
- Unexpected Refactoring from Rapid Development -

Introduction: "Refactoring a Static Site?"

"I didn't think refactoring would be necessary for a static site."

These were the words from our client just one week after development began. Indeed, static sites are generally considered simple and immune to major refactoring. However, reality proved different.

Project Overview

Development Period and Scale

• Development Period: June 9-16, 2025 (7 days)
• Content Volume:
  • News articles: 52
  • Tips articles: 11
  • Portfolio items: 7
• Page Count: 15+ types (effectively 30+ pages with bilingual support)
• Tech Stack: Next.js 15.3.3 (App Router) + TypeScript + Tailwind CSS

Main Features Implemented

• Multilingual support (Japanese/English)
• Dynamic OG image generation
• Structured data (SEO)
• AIEO service landing page
• Filter and search functionality
• Responsive design

Why Refactoring Was Needed After Just One Week

1. Gradual Changes in Data Structure

Initial Implementation (Day 1-3)

// All articles in a single file
/public/data/news.json
{
  "articles": [
    { "id": 1, "title": "Article 1", "content": "..." },
    { "id": 2, "title": "Article 2", "content": "..." },
    // 50+ articles...
  ]
}

Problems Emerged (Day 4-5)

• File size bloat (over 1MB)
• Frequent Git conflicts
• Inefficient loading of all articles on page load

After Refactoring (Day 6-7)

/public/data/news/
  ├── index.json      # Metadata only
  └── articles/       # Individual article files
      ├── 2025-06-16-article-1.json
      ├── 2025-06-16-article-2.json
      └── ...

2. Implementation Inconsistencies from Parallel Development

News Feature Implementation

// Server Component pattern
NewsPage → NewsGridNew → NewsCardNew

Tips Feature Implementation (Different timing)

// Client Component pattern (for filtering)
TipsPage → TipsPageClient → TipsFilteredGrid → TipsCardNew

Resulting in:

• Different data fetching patterns
• UI component inconsistencies
• Styling differences

3. Complexity Growth from Rapid Feature Addition

Day 1-3: Basic page structure Day 4: Filter functionality (Tips only) Day 5: AIEO service page (8 dedicated components) Day 6: FAQ feature, structured data Day 7: Refactoring necessity identified

Immediate Technical Debt Repayment

Typically, technical debt accumulates over months or years, but this project reached its limit in just one week. This "compressed technical debt" was due to:

1. High-speed development pace: 10+ content items per day
2. Feature retrofitting: Filters and sorting not initially planned
3. Scalability oversight: Complacency from "it's just a static site"

Lessons Learned

1. Architecture Matters Even for Static Sites

Even static sites need design that anticipates content growth:

• Data structure extensibility
• Component reusability
• Styling consistency

2. Benefits of Early Refactoring

Refactoring at 1 week

• Limited impact scope
• Easy specification changes
• Fresh in everyone's memory

If it had been 1 month later...

• More features with dependencies
• Exponentially increased refactoring cost
• Greater business impact

3. Balancing Development Speed and Quality

Rapid development is possible, but requires attention to:

✅ What Worked

• Quick value delivery
• Early feedback acquisition
• Reduced time to market

❌ What Needed Improvement

• Insufficient initial design investment
• Component design consistency
• Documentation

Actual Refactoring Content

Phase 1: Building Common Foundation

/* Define common styles in globals.css */
.container-base {
  @apply max-w-7xl mx-auto px-4 sm:px-6 lg:px-8;
}

.card-base {
  @apply bg-white rounded-2xl shadow-sm hover:shadow-xl transition-shadow;
}

Phase 2: Component Unification

• Create common grid components
• Standardize card designs
• Unify data fetching patterns

Phase 3: Optimization

• Remove unnecessary intermediate components
• Performance improvements
• Type definition cleanup

Conclusion: New Challenges for Static Sites

Modern static site generators are powerful enough to implement features comparable to dynamic sites. However, this also means they bring similar complexity to dynamic sites.

We must abandon the preconception that "static sites are simple" and embrace proper architectural design and continuous refactoring.

The key is not to fear technical debt, but to recognize it early and address it quickly.

This project, as a rare example of technical debt occurring in one week with immediate refactoring, provided many insights.