TL;DR
Must Include Headers is a developer-focused feature that ensures NitroPack only optimizes requests containing specific HTTP headers. It offers advanced control and is especially useful in complex setups like proxies, CDNs, or server-side rendering environments.
In highly customized web environments—like when you’re working with proxies, CDNs, or server-side rendering setups—not every request should trigger optimization.
In fact, sometimes you need strict control over which requests are processed at all.
That’s where the Must Include Headers feature comes into play. It gives developers the power to ensure speed engines like NitroPack only optimize requests that include specific HTTP headers.
If your workflow involves selective caching, warmup bots, or API-driven traffic, this technique helps you avoid unnecessary optimizations while maintaining performance where it matters most for a fast WordPress site.
What is Must Include Headers?
In some complex setups, you don’t want NitroPack to optimize every request. Maybe you’re serving content through a proxy or API, or testing requests made by specific tools.
That’s where Must Include Headers comes in. This feature ensures NitroPack only processes and optimizes requests that contain specific HTTP headers that you define.
It acts as a gatekeeper, filtering out all irrelevant or unintended traffic.
Test NitroPack yourself
With vs Without Must Include Headers (Example)
Let’s say you have a proxy server making requests to your site for caching purposes. You don’t want NitroPack to optimize every visit—only the ones made by your proxy.
By setting a custom header (like X-Cache-Warmup: true), you can:
- Whitelist requests from your proxy
- Prevent NitroPack from optimizing user visits during testing
- Gain fine-tuned control over what’s cached and optimized
| Scenario | Without Must Include Headers | With Must Include Headers |
| Proxy cache warmup requests | All requests optimized | Only proxy requests with header optimized |
| Development tool accessing site | Unintended optimization occurs | Only tagged requests are processed |
| General site visitor browsing | May trigger optimization | Blocked unless header is present |
Why Is Must Include Headers Important?
Advanced performance workflows often need this type of granular filtering. Here’s why:
- Avoid Over-Optimization – Prevent NitroPack from working on unwanted traffic or internal tools.
- Improve Testing Accuracy – Keep test runs clean by optimizing only what’s needed.
- Secure Edge Setups – Helpful in CDN and proxy environments with layered caching strategies.
- Minimize Load – Conserve resources by skipping unnecessary optimization jobs.
In short, Must Include Headers gives you surgical control over what NitroPack sees and processes.
Must Include Headers by NitroPack Explained
When enabled, NitroPack checks for specific HTTP headers on every request. If the headers match your configuration, optimization happens. If not, the request is ignored.
You can define:
- Header names
- Expected header values
- Whether multiple headers must be matched
This feature is best for:
- Developers managing custom environments
- Sites behind load balancers or CDNs
- Teams working with headless setups or custom APIs
NitroPack vs No Header Filtering
| Feature | No Header Filtering | Must Include Headers |
| Optimizes all incoming traffic | ✅ Yes | ❌ Only matching headers |
| Ideal for technical teams | ❌ Not recommended | ✅ Yes |
| Reduces test interference | ❌ No filtering | ✅ High filtering control |
| Proxy/CDN compatible | ❌ Risk of over-optimization | ✅ Optimized for edge cases |
How to Use Optimize Only URLs by NitroPack
Using this feature is simple for developers:
- Go to your NitroPack dashboard
- Navigate to Cache Settings >> Cache
- Enable “Must Include Headers”
- Add your desired header name and value
From this point on, only requests containing this header will be eligible for optimization.
Need more help? Check out our Must Include Headers setup guide.
Optimize what matters most. Get started with NitroPack →
FAQs
Can I use Must Include Headers on a live site?
Yes, it’s ideal for production environments with custom infrastructure.
What happens if the header is missing?
NitroPack skips optimization for that request.
Can I set multiple headers?
Yes, you can configure multiple name-value pairs.
Does Must Include Headers affect cache hit ratios?
Yes, positively. It ensures only valid, consistent requests are optimized and cached.
