Cache Strategy 🔒 Premium
Caching improves performance, reduces load time, and provides offline support by storing assets locally. Transcodes offers two cache modes:
Automatic (Default)
Transcodes automatically applies a basic caching strategy for your assets in the free tier, using a network-only. To access enhanced caching features — like persistent asset storage and customizable expiration — you can upgrade to a paid plan at any time.
Advanced
Advanced mode allows you to customize cache settings per file type across six categories:
- Script
- Navigate (HTML)
- Image
- Style (CSS)
- Font
- Media
For each category, you can define:
- Route or Regex pattern (e.g.
/static/js/,.*\.png) - Maximum number of cached files
- Expiration time (e.g., 1 day, 1 week)
- Caching strategy (see below)
Configuration Targets
In Advanced mode, you can define caching rules based on how files are matched and categorized. Transcodes supports three ways to identify target assets:
1. Route (File Type-Based)
A route defines asset groups based on the request type. This is determined by inspecting the file’s Content-Type or request destination.
| Route Type | Matches | Use Case Example |
|---|---|---|
script | .js, .mjs, or Content-Type: script | Your app’s bundled JavaScript files |
style | .css or Content-Type: text/css | Theme stylesheets |
image | .png, .jpg, .svg, .webp, etc. | Icons, banners, product images |
media | .mp4, .mp3, video/*, audio/* | Demo videos, audio guides |
font | .woff2, .ttf, .otf | Custom font files |
navigate | request.mode === 'navigate' | HTML pages and document shells |
✅ Best for: general content classification
2. Regex (Custom Pattern Matching)
Use custom regular expressions to match asset URLs with high precision. This gives you fine-grained control over caching behavior.
Sample Regex Use Cases
| Regex Pattern | Matches |
| ------------------------------------ | ---------------------------------------------- | -------------------------------- |
| /.*\\.js$/ | All .js files at any path |
| /images\\/thumbnails\\/.*\\.webp$/ | All .webp thumbnails in images/thumbnails/ |
| /assets\\/fonts\\/.\*\\.(woff2 | ttf)$/ | Font files under assets/fonts/ |
| /.*service-worker.*\\.js$/ | Only files named like service-worker.js |
⚠️ Escaping is required (
\\.instead of.) when writing inline string-based patterns.
✅ Best for: targeting by file naming convention or folder structure
3. Path (Static URL Matching)
Path-based rules match exact or base URLs for files. You can specify full or partial paths relative to your PWA origin.
Examples:
| Path Pattern | Matches |
|---|---|
/static/manifest.json | Exact match to manifest file |
/static/assets/ | Any file within this base path |
/docs/v1/user-guide.pdf | Specific asset for offline reading |
✅ Best for: pinning or prioritizing specific URLs that don’t change
Summary
| Match Type | Best For | Pattern Style |
|---|---|---|
route | Broad file categories (e.g. script, css) | Predefined keywords |
regex | Dynamic or structured asset paths | Full regex syntax |
path | Known URLs or fixed asset entries | URL-relative paths |
You can combine multiple pattern types for full control. For example, use
route: image for general image caching, and regex: /icons\\/.*\\.svg$/ to
optimize icons with stricter rules.
Caching Strategies
| Strategy | Description |
|---|---|
Cache First | Returns cache if available; fetches network only if not cached. Fast but may serve outdated data. |
Network First | Tries network first; falls back to cache if offline. Good for HTML/pages. |
Network Only | Always fetches from the network. Used when fresh content is critical. |
Stale While Revalidate | Returns cached version immediately, then fetches updated version in the background. Best for balancing performance and freshness. |
Best Practices
Avoid setting a high maximum file count for caching. Large caches can consume excessive storage, slow down the service worker lifecycle, and negatively impact app performance.
Using a long expiration time may prevent users from seeing updated content. Cached assets can stay stale, especially on frequently updated apps. Additionally, some browsers impose cache size limits, which may purge long-lived entries unpredictably.
When to Use Advanced Mode
Use Advanced caching if you:
- Need precise control over cache storage size
- Want to apply different strategies for fonts vs. media vs. scripts
- Manage updates in dynamic content environments