Cache-Control

Sonamu can automatically set HTTP Cache-Control headers to control caching behavior in browsers and CDNs. You can apply appropriate caching strategies for each resource type including API responses, static files, and SSR pages.

Basic Structure

import { defineConfig, CachePresets } from "sonamu";

export default defineConfig({
  server: {
    apiConfig: {
      cacheControlHandler: (req) => {
        switch (req.type) {
          case "assets":
            return CachePresets.immutable;
          case "api":
            return CachePresets.noCache;
          case "ssr":
            return CachePresets.ssr;
          case "csr":
            return CachePresets.shortLived;
        }
      },
    },
  },
  // ...
});

cacheControlHandler

A function that dynamically generates Cache-Control headers for each request. Type: (req: CacheControlRequest) => string | undefined

type CacheControlRequest = {
  type: "assets" | "api" | "ssr" | "csr";
  method: string;
  path: string;
};

Request Types

type:

"assets" - Static files (JS, CSS, images, etc.)
"api" - API endpoints
"ssr" - SSR pages
"csr" - CSR entry point (index.html)

method: HTTP method (GET, POST, PUT, DELETE, etc.) path: Request path (/api/user/list, /assets/main.js, etc.)

CachePresets

Predefined caching strategies provided by Sonamu.

import { CachePresets } from "sonamu";

Available Presets

CachePresets.noCache

Cache-Control: no-cache, no-store, must-revalidate

Always verify latest version from origin server
Use for: Real-time data, APIs requiring authentication

CachePresets.shortLived (1 minute)

Cache-Control: public, max-age=60

Cache for 1 minute
Use for: Frequently changing data, CSR entry point

CachePresets.mediumLived (5 minutes)

Cache-Control: public, max-age=300

Cache for 5 minutes
Use for: Data that changes at moderate intervals

CachePresets.longLived (1 hour)

Cache-Control: public, max-age=3600

Cache for 1 hour
Use for: Rarely changing static data

CachePresets.immutable (1 year)

Cache-Control: public, max-age=31536000, immutable

Cache for 1 year, never changes
Use for: Build files with hash in filename

CachePresets.ssr (10 seconds)

Cache-Control: public, max-age=10, stale-while-revalidate=60

Cache for 10 seconds, refresh in background
Use for: SSR pages

Basic Examples

Simple Configuration

import { defineConfig, CachePresets } from "sonamu";

export default defineConfig({
  server: {
    apiConfig: {
      cacheControlHandler: (req) => {
        // No cache for all APIs
        if (req.type === "api") {
          return CachePresets.noCache;
        }

        // Long cache for static files
        if (req.type === "assets") {
          return CachePresets.longLived;
        }

        // Short cache for SSR pages
        if (req.type === "ssr") {
          return CachePresets.ssr;
        }
      },
    },
  },
});

Detailed Assets Configuration

Permanent cache for files with hash, regular cache for others:

export default defineConfig({
  server: {
    apiConfig: {
      cacheControlHandler: (req) => {
        if (req.type === "assets") {
          // Files with hash (e.g., main-a3f2b1c.js)
          if (req.path.match(/-[a-f0-9]+\./)) {
            return CachePresets.immutable;
          }
          // Regular static files
          return CachePresets.longLived;
        }

        return CachePresets.noCache;
      },
    },
  },
});

Path-based API Caching

Cache only GET requests selectively:

export default defineConfig({
  server: {
    apiConfig: {
      cacheControlHandler: (req) => {
        if (req.type === "api") {
          // Consider caching only GET requests
          if (req.method === "GET") {
            // Short cache for specific paths
            if (req.path.startsWith("/api/static-data")) {
              return CachePresets.shortLived;
            }

            // Medium cache for terms, etc.
            if (req.path.startsWith("/api/terms")) {
              return CachePresets.mediumLived;
            }
          }

          // Default: no cache
          return CachePresets.noCache;
        }
      },
    },
  },
});

Practical Examples

Standard Web App

import { defineConfig, CachePresets } from "sonamu";

export default defineConfig({
  server: {
    apiConfig: {
      cacheControlHandler: (req) => {
        switch (req.type) {
          case "assets":
            // Files with hash: permanent cache
            if (req.path.match(/-[a-f0-9]+\./)) {
              return CachePresets.immutable;
            }
            return CachePresets.longLived;

          case "api":
            // Cache only GET requests
            if (req.method === "GET") {
              // Static data
              if (req.path.startsWith("/api/static")) {
                return CachePresets.mediumLived;
              }
            }
            return CachePresets.noCache;

          case "ssr":
            // SSR pages: 10 second cache
            return CachePresets.ssr;

          case "csr":
            // index.html: 1 minute cache
            return CachePresets.shortLived;
        }
      },
    },
  },
});

CDN Optimization

export default defineConfig({
  server: {
    apiConfig: {
      cacheControlHandler: (req) => {
        switch (req.type) {
          case "assets":
            // Long cache at CDN edge
            if (req.path.match(/-[a-f0-9]+\./)) {
              return CachePresets.immutable;
            }
            return CachePresets.longLived;

          case "api":
            // Don't cache APIs in CDN
            return CachePresets.noCache;

          case "ssr":
            // Short cache for SSR in CDN
            return "public, max-age=30, stale-while-revalidate=120";

          case "csr":
            return CachePresets.shortLived;
        }
      },
    },
  },
});

Development vs Production

const isDev = process.env.NODE_ENV === "development";

export default defineConfig({
  server: {
    apiConfig: {
      cacheControlHandler: (req) => {
        // Development: disable caching
        if (isDev) {
          return CachePresets.noCache;
        }

        // Production: normal caching strategy
        switch (req.type) {
          case "assets":
            if (req.path.match(/-[a-f0-9]+\./)) {
              return CachePresets.immutable;
            }
            return CachePresets.longLived;

          case "api":
            if (req.method === "GET") {
              return CachePresets.shortLived;
            }
            return CachePresets.noCache;

          case "ssr":
            return CachePresets.ssr;

          case "csr":
            return CachePresets.shortLived;
        }
      },
    },
  },
});

Custom Cache-Control

You can also return header values directly instead of using presets:

export default defineConfig({
  server: {
    apiConfig: {
      cacheControlHandler: (req) => {
        if (req.type === "api" && req.path.startsWith("/api/feed")) {
          // Feed: 5 minute cache + stale-while-revalidate
          return "public, max-age=300, stale-while-revalidate=600";
        }

        if (req.type === "assets" && req.path.endsWith(".woff2")) {
          // Fonts: 1 year cache
          return "public, max-age=31536000, immutable";
        }

        return CachePresets.noCache;
      },
    },
  },
});

Understanding Cache-Control

Key Directives

public

Can be cached by CDN and intermediate proxies
Suitable for static files, public APIs

private

Can only be cached by browser
Suitable for personalized data

no-cache

Cache but always verify with origin
Conditional requests (304 Not Modified) possible

no-store

Don’t cache anywhere
Use for sensitive data

max-age=N

Fresh state for N seconds
Use cache without revalidation during this period

immutable

Will never change
Browser skips revalidation
Optimal for hash-based files

stale-while-revalidate=N

Return stale version for N seconds after expiration
Refresh in background
Useful for SSR pages

Example Combinations

// Permanent cache (build files)
"public, max-age=31536000, immutable";

// Short cache + background refresh (SSR)
"public, max-age=10, stale-while-revalidate=60";

// Browser-only short cache (auth API)
"private, max-age=60";

// No cache (real-time data)
"no-cache, no-store, must-revalidate";

Returning undefined

Return undefined if you don’t want to set the header:

export default defineConfig({
  server: {
    apiConfig: {
      cacheControlHandler: (req) => {
        // No Cache-Control header for internal APIs
        if (req.path.startsWith("/api/internal")) {
          return undefined;
        }

        return CachePresets.noCache;
      },
    },
  },
});

Important Notes

1. APIs Requiring Authentication

// ❌ Bad: public cache for auth API
if (req.path.startsWith("/api/user/profile")) {
  return "public, max-age=300"; // Risk of exposing other user's data!
}

// ✅ Good: private or no-cache
if (req.path.startsWith("/api/user/profile")) {
  return "private, max-age=60"; // Or CachePresets.noCache
}

2. Don’t Cache POST/PUT/DELETE

if (req.type === "api") {
  // Only cache GET
  if (req.method === "GET") {
    return CachePresets.shortLived;
  }
  // POST, PUT, DELETE always no-cache
  return CachePresets.noCache;
}

3. Detecting Hash-based Files

// Common build tool hash patterns
const hashPatterns = [
  /-[a-f0-9]{8,}\./, // Vite: main-a3f2b1c4.js
  /\.[a-f0-9]{20}\./, // Webpack: main.a3f2b1c4d5e6f7a8b9c0.js
];

if (req.type === "assets") {
  if (hashPatterns.some((p) => p.test(req.path))) {
    return CachePresets.immutable;
  }
}

Next Steps

After completing Cache-Control configuration:

cache - Server-side caching (BentoCache)
compress - Response compression settings
advanced-features/ssr - Using Cache-Control in SSR

Get Started

Core Concepts

Database

API Development

Frontend Integration

Testing

Advanced Features

Tools & CLI

Configuration

API Reference

Troubleshooting

FAQ

Basic Structure

cacheControlHandler

Request Types

CachePresets

Available Presets

Basic Examples

Simple Configuration

Detailed Assets Configuration

Path-based API Caching

Practical Examples

Standard Web App

CDN Optimization

Development vs Production

Custom Cache-Control

Understanding Cache-Control

Key Directives

Example Combinations

Returning undefined

Important Notes

1. APIs Requiring Authentication

2. Don’t Cache POST/PUT/DELETE

3. Detecting Hash-based Files

Next Steps

​Basic Structure

​cacheControlHandler

​Request Types

​CachePresets

​Available Presets

​Basic Examples

​Simple Configuration

​Detailed Assets Configuration

​Path-based API Caching

​Practical Examples

​Standard Web App

​CDN Optimization

​Development vs Production

​Custom Cache-Control

​Understanding Cache-Control

​Key Directives

​Example Combinations

​Returning undefined

​Important Notes

​1. APIs Requiring Authentication

​2. Don’t Cache POST/PUT/DELETE

​3. Detecting Hash-based Files

​Next Steps

Basic Structure

cacheControlHandler

Request Types

CachePresets

Available Presets

Basic Examples

Simple Configuration

Detailed Assets Configuration

Path-based API Caching

Practical Examples

Standard Web App

CDN Optimization

Development vs Production

Custom Cache-Control

Understanding Cache-Control

Key Directives

Example Combinations

Returning undefined

Important Notes

1. APIs Requiring Authentication

2. Don’t Cache POST/PUT/DELETE

3. Detecting Hash-based Files

Next Steps