Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.go-mizu.dev/llms.txt

Use this file to discover all available pages before exploring further.

Proper caching is crucial for frontend performance. Mizu implements intelligent caching based on asset types, content fingerprinting, and best practices.

​
Overview

The frontend middleware automatically applies caching based on three factors:
  1. File type (HTML, JS, CSS, images, etc.)
  2. Content fingerprinting (hash in filename)
  3. Custom patterns (your configuration)

​
Default Caching Strategy

Asset TypePatternCache DurationCache-Control
Hashed assets*.abc123.js1 yearpublic, max-age=31536000, immutable
Unhashed assetslogo.png1 weekpublic, max-age=604800
HTML files*.htmlNoneno-cache, no-store, must-revalidate
Source maps*.mapNoneno-cache

​
How Content Hashing Works

​
Build Tools Generate Hashes

When you build your frontend, tools like Vite add content hashes to filenames: 
Before build:
  main.js
  styles.css

After build:
  main.a1b2c3d4.js      ← Hash added
  styles.e5f6g7h8.css   ← Hash added
The hash is based on file contents. If the file changes, the hash changes: 
main.a1b2c3d4.js  →  main.x9y8z7w6.js

​
Why This Matters

Old approach (without hashing): 
<script src="/main.js"></script>
Problem: Browsers cache main.js. When you update it, users might still see the old cached version. New approach (with hashing): 
<script src="/main.a1b2c3d4.js"></script>
Benefit: When you update the file, the filename changes: 
<script src="/main.x9y8z7w6.js"></script>
Browsers see a new filename and fetch the new file. The old file stays cached harmlessly.

​
Asset Classification

Mizu automatically classifies assets: 
// Hashed assets (detected by pattern)
app.a1b2c3.js         → 1 year cache, immutable
vendor.xyz789.css     → 1 year cache, immutable
logo.abc123.png       → 1 year cache, immutable

// Unhashed assets
logo.png              → 1 week cache
favicon.ico           → 1 week cache

// HTML files
index.html            → no-cache
about.html            → no-cache

// Source maps
app.js.map            → no-cache (blocked by default)

​
Hash Detection Pattern

Mizu looks for this pattern in filenames: 
[._-][a-fA-F0-9]{6,}$
Examples that match:
  • main.a1b2c3.js ✅
  • vendor-xyz789.css ✅
  • chunk.ABC123DEF.js ✅
  • logo_12ab34cd.png ✅
Examples that don’t match:
  • main.js ❌ (no hash)
  • version-1.2.3.js ❌ (not a hex hash)
  • user-123.png ❌ (too short)

​
Custom Cache Configuration

​
Override Defaults

app.Use(frontend.WithOptions(frontend.Options{
    Mode: frontend.ModeProduction,
    Root: "./dist",
    CacheControl: frontend.CacheConfig{
        HashedAssets:   180 * 24 * time.Hour,  // 6 months instead of 1 year
        UnhashedAssets: 24 * time.Hour,         // 1 day instead of 1 week
        HTML:           0,                      // no-cache (default)
    },
}))

​
Pattern-Based Caching

Cache specific file types differently: 
app.Use(frontend.WithOptions(frontend.Options{
    Mode: frontend.ModeProduction,
    Root: "./dist",
    CacheControl: frontend.CacheConfig{
        Patterns: map[string]time.Duration{
            // Fonts: cache for 30 days
            "*.woff2": 30 * 24 * time.Hour,
            "*.woff":  30 * 24 * time.Hour,
            "*.ttf":   30 * 24 * time.Hour,

            // Images: cache for 14 days
            "*.jpg":  14 * 24 * time.Hour,
            "*.jpeg": 14 * 24 * time.Hour,
            "*.png":  14 * 24 * time.Hour,
            "*.svg":  14 * 24 * time.Hour,
            "*.webp": 14 * 24 * time.Hour,

            // Manifests and configs: no cache
            "manifest.json":    0,
            "robots.txt":       0,
            "sitemap.xml":      0,
        },
    },
}))
Pattern matching order:
  1. Check custom patterns first
  2. If no match, check if file has hash
  3. If hashed → use HashedAssets duration
  4. If unhashed → use UnhashedAssets duration
  5. If HTML → use HTML duration

​
Environment-Specific Caching

func getCacheConfig(env string) frontend.CacheConfig {
    if env == "production" {
        return frontend.CacheConfig{
            HashedAssets:   365 * 24 * time.Hour,
            UnhashedAssets: 7 * 24 * time.Hour,
        }
    }

    // Shorter cache for staging
    return frontend.CacheConfig{
        HashedAssets:   24 * time.Hour,
        UnhashedAssets: 1 * time.Hour,
    }
}

app.Use(frontend.WithOptions(frontend.Options{
    Mode:         frontend.ModeProduction,
    Root:         "./dist",
    CacheControl: getCacheConfig(os.Getenv("ENV")),
}))

​
Cache-Control Directives

​
immutable

Hashed assets get the immutable directive: 
Cache-Control: public, max-age=31536000, immutable
What it means:
  • public: Can be cached by browsers and CDNs
  • max-age=31536000: Cache for 1 year (in seconds)
  • immutable: File will never change (safe to cache forever)
Modern browsers skip revalidation for immutable resources.

​
no-cache vs no-store

HTML files get aggressive no-cache headers: 
Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache
Expires: 0
What each means:
  • no-cache: Revalidate before using cached copy
  • no-store: Don’t cache at all
  • must-revalidate: Obey the rules strictly
  • Pragma: no-cache: HTTP/1.0 compatibility
  • Expires: 0: Old-style expiration

​
CDN Caching

When using a CDN (CloudFlare, Fastly, etc.): 
app.Use(frontend.WithOptions(frontend.Options{
    Mode: frontend.ModeProduction,
    Root: "./dist",
    CacheControl: frontend.CacheConfig{
        // Aggressive caching for CDN
        HashedAssets:   365 * 24 * time.Hour,
        UnhashedAssets: 7 * 24 * time.Hour,

        Patterns: map[string]time.Duration{
            // Cache fonts for a very long time
            "*.woff2": 365 * 24 * time.Hour,
        },
    },
}))
CDN benefits:
  • Files cached at edge locations
  • Faster delivery to users
  • Reduced origin server load
  • Mizu’s cache headers work automatically

​
Best Practices

​
1. Always Use Asset Fingerprinting

Ensure your build tool fingerprints assets: Vite: 
// vite.config.ts
export default {
  build: {
    rollupOptions: {
      output: {
        entryFileNames: 'assets/[name].[hash].js',
        chunkFileNames: 'assets/[name].[hash].js',
        assetFileNames: 'assets/[name].[hash].[ext]'
      }
    }
  }
}
Angular: 
{
  "architect": {
    "build": {
      "configurations": {
        "production": {
          "outputHashing": "all"
        }
      }
    }
  }
}

​
2. Never Cache HTML Files

Always set HTML caching to 0: 
CacheControl: frontend.CacheConfig{
    HTML: 0,  // Critical!
}
Why: HTML files reference the hashed assets. If HTML is cached, users might request old asset filenames that no longer exist.

​
3. Use Longer Cache for Fonts

Fonts rarely change: 
Patterns: map[string]time.Duration{
    "*.woff2": 30 * 24 * time.Hour,  // 30 days
}

​
4. Test Cache Headers

Check headers with curl: 
curl -I https://yourdomain.com/assets/main.abc123.js
Should show: 
HTTP/2 200
cache-control: public, max-age=31536000, immutable

​
5. Monitor Cache Hit Rates

Use CDN analytics to track:
  • Cache hit rate (aim for >90%)
  • Bandwidth saved
  • Origin requests (should be minimal)

​
Debugging Cache Issues

​
Clear Browser Cache

Chrome: 
Cmd/Ctrl + Shift + R  (hard refresh)
Programmatically: 
// In browser console
caches.keys().then(names => {
    names.forEach(name => caches.delete(name))
})

​
Verify Cache Headers

# Check a hashed asset
curl -I localhost:3000/assets/main.abc123.js

# Should show long cache
cache-control: public, max-age=31536000, immutable

# Check HTML
curl -I localhost:3000/

# Should show no-cache
cache-control: no-cache, no-store, must-revalidate

​
Common Issues

Problem: Users see old version after deployment Solution: Check that:
  1. HTML files have cache-control: no-cache
  2. Asset filenames include content hash
  3. Build generated new hashes
Problem: Assets not caching Solution: Check that:
  1. Filenames include hash pattern
  2. Server is returning cache headers
  3. HTTPS is enabled (required for some cache APIs)

​
Next Steps

Production Mode

Production optimization guide

Security

Security headers and best practices

Manifest

Build manifest integration

Static Hosting

Deploy to CDN