Compression Configuration

Sonamu uses the @fastify/compress plugin to automatically compress HTTP responses. It supports various compression algorithms including gzip, brotli (br), and deflate.

Why is Compression Needed?

Compression reduces the size of data transmitted over the network.

Without Compression

With Compression

Benefits:

Transfer size: 100KB to 10KB (90% reduction)
Download time: 1 second to 0.1 second (10x faster)
Bandwidth savings

Basic Configuration

sonamu.config.ts

import { type SonamuConfig } from "sonamu";

export const config: SonamuConfig = {
  server: {
    plugins: {
      compress: true,  // Enable compression (default settings)
    },
  },
};

Default behavior:

threshold: 1024 (only compress 1KB or larger)
encodings: ["br", "gzip", "deflate"] (in priority order)
Automatically applied to all APIs

Configuration Options

boolean
CompressOptions

Simple enable/disable

plugins: {
  compress: true,   // Enable (default settings)
  compress: false,  // Disable
}

Detailed configuration

import type { FastifyCompressOptions } from "@fastify/compress";

plugins: {
  compress: {
    threshold: 1024,  // Minimum compression size (bytes)
    encodings: ["br", "gzip", "deflate"],  // Compression algorithm priority
    customTypes: /^text\/|application\/json/,  // Content-Type to compress
  } as FastifyCompressOptions
}

Compression Algorithms

Brotli (br)

The algorithm with the highest compression ratio

plugins: {
  compress: {
    threshold: 1024,
    encodings: ["br"],  // Use Brotli only
  }
}

Characteristics:

Compression ratio: Best (15-20% better than gzip)
Speed: Slow (high CPU usage)
Support: Modern browsers (not supported in IE)

Suitable for:

Static content (can be pre-compressed)
When bandwidth is critical
When server CPU has capacity

Gzip

The most universal algorithm

plugins: {
  compress: {
    threshold: 1024,
    encodings: ["gzip"],  // Use Gzip only
  }
}

Characteristics:

Compression ratio: Medium
Speed: Fast
Support: All browsers

Suitable for:

Dynamic API responses
Real-time compression
When compatibility is important

Deflate

Legacy algorithm

plugins: {
  compress: {
    threshold: 1024,
    encodings: ["deflate"],
  }
}

Characteristics:

Compression ratio: Similar to gzip
Speed: Fast
Support: Most browsers

Recommendation: Use gzip (more stable)

Compression Priority

Set priority when the browser supports multiple encodings.

plugins: {
  compress: {
    encodings: ["br", "gzip", "deflate"],  // Priority: br > gzip > deflate
  }
}

How it works:

Browser request: Accept-Encoding: br, gzip, deflate

Supports br? -> Compress with br
No br, supports gzip? -> Compress with gzip
No gzip, supports deflate? -> Compress with deflate
None supported? -> No compression

Threshold (Minimum Size)

Small responses are not compressed.

plugins: {
  compress: {
    threshold: 1024,  // Only compress 1KB or larger
  }
}

Reasons:

Small data has low compression efficiency
Compression/decompression overhead may be larger
HTTP header size increases

Recommended values:

Default: 1024 (1KB)
Aggressive: 256 (256B)
Conservative: 4096 (4KB)

Example

// 100 byte response
threshold: 1024  // No compression (too small)

// 2KB response
threshold: 1024  // Compress (>= 1KB)

Custom Types

Compress only specific Content-Types.

plugins: {
  compress: {
    customTypes: /^text\/|application\/json/,  // Regex
  }
}

Default behavior: Compresses most text-based responses

text/* (text/html, text/css, text/plain)
application/json
application/javascript
application/xml

Images/videos are already compressed:

image/png, image/jpeg (already compressed formats)
video/mp4 (already compressed format)
Additional compression has no effect

Control with Function

plugins: {
  compress: {
    customTypes: (contentType: string) => {
      // Only compress JSON
      return contentType === 'application/json';
    }
  }
}

Practical Configuration Examples

1. Basic Configuration (Recommended)

export const config: SonamuConfig = {
  server: {
    plugins: {
      compress: true,  // Simply enable
    },
  },
};

Settings used:

threshold: 1024 (1KB)
encodings: ["br", "gzip", "deflate"]

2. High-Performance API Server

export const config: SonamuConfig = {
  server: {
    plugins: {
      compress: {
        threshold: 256,  // Compress small responses too
        encodings: ["br", "gzip", "deflate"],  // All algorithms
      }
    },
  },
};

Characteristics:

Maximum compression ratio (brotli priority)
Compress everything 256 bytes and above
Bandwidth optimization

3. Legacy Browser Support

export const config: SonamuConfig = {
  server: {
    plugins: {
      compress: {
        threshold: 1024,
        encodings: ["gzip", "deflate"],  // Exclude brotli
      }
    },
  },
};

Characteristics:

Support for old browsers like IE
Use gzip only (stable)

4. Selective Compression

When you want to control compression per API:

export const config: SonamuConfig = {
  server: {
    plugins: {
      compress: {
        global: false,  // No compression by default
        threshold: 1024,
        encodings: ["br", "gzip", "deflate"],
      }
    },
  },
};

// Per-API settings
@api({
  httpMethod: 'GET',
  compress: true,  // Compress only this API
})
async getData() {
  return this.findMany({});
}

Use case:

Most APIs don’t need compression
Selectively compress specific APIs

5. CPU Saving (Conservative)

export const config: SonamuConfig = {
  server: {
    plugins: {
      compress: {
        threshold: 4096,  // Only compress 4KB or larger
        encodings: ["gzip"],  // gzip only (fast)
      }
    },
  },
};

Characteristics:

Minimize CPU usage
Only compress large responses
Fast processing

Environment-Based Configuration

export const config: SonamuConfig = {
  server: {
    plugins: {
      compress: process.env.NODE_ENV === 'production'
        ? {
            threshold: 256,
            encodings: ["br", "gzip", "deflate"],
          }
        : false,  // Disable in development environment
    },
  },
};

Development environment: Disable compression

Easier debugging
Fast response (no compression overhead)

Production: Aggressive compression

Bandwidth savings
Improved user experience

Verifying Compression

Browser Developer Tools

Network tab -> Select request -> Headers tab

Response Headers:
  Content-Encoding: gzip
  Content-Length: 1234 (compressed size)

Size:
  10.5 KB (compressed size)
  52.3 KB (original size)

curl Command

# Request with gzip compression
curl -H "Accept-Encoding: gzip" http://localhost:3000/api/products -v

# Check response headers
< Content-Encoding: gzip
< Content-Length: 1234

Precautions

Precautions when using compression:

Exclude already compressed files: Images and videos have no compression benefit

compress: {
  customTypes: /^text\/|application\/json/,  // Text only
}

Don’t compress small responses: Use threshold setting

compress: {
  threshold: 1024,  // Don't compress under 1KB
}

Consider CPU load: brotli has high CPU usage

// Avoid using brotli on low-spec servers
encodings: ["br"]

// Use gzip (fast)
encodings: ["gzip"]

brotli only supported over HTTPS: Use gzip over HTTP
Watch for decompression errors: Verify that the client decompresses properly

Performance Impact

Advantages

Bandwidth savings: 70-90% size reduction
Download speed: Especially effective on slow networks
Cost reduction: Reduced CDN transfer volume

Disadvantages

Increased CPU usage: Compression/decompression overhead
Response latency: Additional compression time (usually a few ms)
Memory usage: Compression buffers

Recommendations

// Recommended: Large JSON responses
@api({ compress: true })
async getLargeData() {
  return this.findMany({ num: 1000 });  // 100KB+
}

// Not recommended: Small responses
@api({ compress: true })
async getStatus() {
  return { status: "ok" };  // 10 bytes
}

Next Steps

Compression Presets

Predefined compression settings

Per-API Control

Compression settings in @api decorator

Performance Optimization

Compression optimization strategies

​Why is Compression Needed?

​Without Compression

​With Compression

​Basic Configuration

​sonamu.config.ts

​Configuration Options

​Compression Algorithms

​Brotli (br)

​Gzip

​Deflate

​Compression Priority

​Threshold (Minimum Size)

​Example

​Custom Types

​Control with Function

​Practical Configuration Examples

​1. Basic Configuration (Recommended)

​2. High-Performance API Server

​3. Legacy Browser Support

​4. Selective Compression

​5. CPU Saving (Conservative)

​Environment-Based Configuration

​Verifying Compression

​Browser Developer Tools

​curl Command

​Precautions

​Performance Impact

​Advantages

​Disadvantages

​Recommendations

​Next Steps

Compression Presets

Per-API Control

Performance Optimization

Why is Compression Needed?

Without Compression

With Compression

Basic Configuration

sonamu.config.ts

Configuration Options

Compression Algorithms

Brotli (br)

Gzip

Deflate

Compression Priority

Threshold (Minimum Size)

Example

Custom Types

Control with Function

Practical Configuration Examples

1. Basic Configuration (Recommended)

2. High-Performance API Server

3. Legacy Browser Support

4. Selective Compression

5. CPU Saving (Conservative)

Environment-Based Configuration

Verifying Compression

Browser Developer Tools

curl Command

Precautions

Performance Impact

Advantages

Disadvantages

Recommendations

Next Steps