How to Precompress Static Assets at Build Time

This guide is part of Compression: Brotli & Zstandard, within Network & Server Response Optimization. Static assets — hashed JavaScript and CSS bundles, SVGs, static HTML from site generators, JSON data files — are identical for every request until the next build. Compressing them on every request wastes CPU and forces a low compression level to keep latency acceptable. Compressing them once at build time lets you use the slowest, strongest settings: Brotli level 11 and gzip level 9 (or Zopfli), typically 5–10% smaller than on-the-fly levels, at zero runtime cost.

The build produces app.js, app.js.br and app.js.gz side by side. The server (or CDN) inspects Accept-Encoding and serves the matching precompressed file with the right Content-Encoding header. The pieces that go wrong are serving configuration (files exist but are not used), wrong headers (Content-Type set to application/x-brotli), and stale compressed files after a build change.

Rapid Diagnosis

• Check build output for .br/.gz files next to assets.
• Check response headers: content-encoding: br and correct content-type for JS and CSS.
• Compare transfer size with a locally computed Brotli 11 size; a larger transfer means on-the-fly compression at a lower level.
• Check server CPU for compression time on static routes.

Root Cause Analysis

1. No precompression step. Assets are compressed per request by the server or CDN.

2. Precompressed files ignored. Server lacks brotli_static/gzip_static or equivalent.

3. CDN recompresses. The CDN compresses at the edge at its own level instead of using origin files.

4. Wrong headers. Compressed files served with incorrect Content-Type break loading.

Step-by-Step Resolution

1. Add a precompression step

Use a bundler plugin (for example vite-plugin-compression, compression-webpack-plugin) or a small script after the build.

// vite.config.js
import compression from 'vite-plugin-compression2';
export default {
  plugins: [
    compression({ algorithm: 'brotliCompress', include: /\.(js|css|html|svg|json|xml|txt|wasm)$/, threshold: 1024 }),
    compression({ algorithm: 'gzip', include: /\.(js|css|html|svg|json|xml|txt|wasm)$/, threshold: 1024 }),
  ],
};
// trade-off: maximum Brotli adds build time (seconds per large bundle); cache
// build outputs so unchanged hashed files are not recompressed.

2. Serve precompressed files

location /assets/ {
  brotli_static on;          # serve .br when Accept-Encoding includes br
  gzip_static on;            # serve .gz otherwise
  add_header Cache-Control "public, max-age=31536000, immutable";
  add_header Vary Accept-Encoding;
}

For Node.js, express-static-gzip or similar middleware serves precompressed variants. Static hosts (Netlify, Cloudflare Pages, Vercel) compress automatically; check whether they use your precompressed files or compress at the edge.

3. Upload to object storage correctly

When serving from S3-like storage behind a CDN, upload the compressed body under the original name with Content-Encoding: br, or use the CDN's encoding-aware variants. Never serve .br files with Content-Type: application/x-brotli.

4. Exclude already-compressed files

Skip images, fonts (WOFF2), video, audio and archives.

Verification

curl -s -H 'Accept-Encoding: br' -D - -o /tmp/a.br https://example.com/assets/app.4f2a.js | grep -iE 'content-(encoding|type|length)'
ls -l dist/assets/app.4f2a.js.br
# trade-off: the transferred Content-Length should equal the .br file size; a
# mismatch means something recompressed or decompressed it along the way.

Worked Example: A Static Documentation Site

A documentation site deployed 1,800 pages of static HTML plus assets to a self-managed nginx behind a CDN. nginx compressed with gzip level 6 per request; the CDN cached gzip variants. Adding Brotli 11 and Zopfli precompression to the build (adding 50 seconds to a 4-minute build) and enabling brotli_static/gzip_static reduced HTML transfer by 19% and JS by 17%. Origin CPU during cache refills dropped by 60%. LCP p75 improved by 90ms on mobile, mostly from smaller HTML.

Precompression on Static Hosts and CDNs

Platforms differ. Some static hosts compress at the edge automatically with Brotli at good levels; precompressing yourself may not change much. Others serve files as uploaded, so precompression is required for Brotli. Some CDNs ignore origin Content-Encoding and recompress. Test what users actually receive: compare the transferred size of a known asset against your locally computed Brotli 11 size. If they match, precompression is effective; if the transferred size is larger, something in the chain recompresses at a lower level.

Making Precompression Part of CI

Treat precompressed outputs as part of the build contract. A CI step can verify that every text asset above the size threshold has .br and .gz siblings, that each compressed file decompresses back to the original bytes, and that compressed sizes stay within budget. After deployment, a smoke test requests a few assets with Accept-Encoding: br and compares Content-Length with the size of the matching .br file in the build output. This catches the most common failure — compressed files present but not served — on the first deploy rather than months later.

Common Mistakes

• Precompressing but not serving the files. Server configuration missing.
• Wrong Content-Type on compressed files. Scripts and styles fail to load.
• Stale compressed files. Old .br files served after source changes when names are not hashed.
• Compressing tiny files. Overhead with no benefit; use a threshold.

Edge Cases

Unhashed files. For files like index.html or robots.txt, regenerate compressed variants on every build and avoid long cache lifetimes.

Source maps. Compress them too if served publicly; they are large text files.

WebAssembly. WASM compresses moderately with Brotli; include it.

Service worker precaching. Service workers store decompressed responses; precompression helps the network transfer, not cache storage.

FAQ

Related

• Enabling Brotli on nginx and CDNs — serving configuration.
• Compression dictionary transport — beyond single-file compression.
• Advanced caching strategies & CDN architecture — hashed filenames and immutable caching that make precompression safe.