WeAmp.PageSpeed.AspNetCore 2.0.42

WeAmp.PageSpeed for ASP.NET Core

Drop-in ASP.NET Core middleware that improves Core Web Vitals without touching your app code. It adds critical CSS inlining, LCP preload injection, lazy loading, and on-demand WebP/AVIF image transcoding to every HTML response. The C++23 PageSpeed engine runs in-process via P/Invoke and serves cache hits zero-copy.

Single-package install. Hot-reloadable config. Optimization runs out of the box, so you can evaluate it without a license. While unlicensed, responses carry an X-PageSpeed-Warn: unlicensed header. Production use requires a commercial license — but the software never locks you out.

Buy or apply a key from the in-app console at /console/ — see plans at modpagespeed.com/pricing/.

Quick Start

1. Install the package

dotnet add package WeAmp.PageSpeed.AspNetCore

The matching native binaries for your runtime (linux-x64, linux-arm64, osx-arm64, or win-x64) come in transitively: no separate NativeAssets package reference required.

2. Register the middleware in Program.cs

using WeAmp.PageSpeed.AspNetCore;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddPageSpeed();

var app = builder.Build();

app.UsePageSpeed();    // before anything that writes the response body
app.UseStaticFiles();

app.Run();

No extra wiring required: with no Worker section, the worker process starts automatically and coordinates over an auto-resolved per-process socket. Add a Worker section only to change that — see Configuration. Optimization is on by default; see step 3 to license it for production.

3. License it for production

You can evaluate the middleware right away. Production use requires a commercial license — but the software never locks you out: until a license is applied, every response carries an X-PageSpeed-Warn: unlicensed header and the console shows an unlicensed notice. To license it, run your app and navigate to http://<your-app-host>/console/ in a browser, then buy a subscription — monthly or annual, billed immediately, cancel anytime. The issued key is applied automatically and persisted to the cache volume, then reused on subsequent runs. You can also paste an existing key into the same /console/ page. (/console/ is an admin surface — see Security before exposing it beyond localhost.)

4. How do I know it's working?

Three checks, from quickest to most thorough. These examples assume your app listens on :5050 (set ASPNETCORE_URLS=http://localhost:5050 or adjust the URLs to your port) and serves at least one HTML page and one image.

Hit a content route and look for the X-PageSpeed header:

curl -i http://localhost:5050/

HTTP/1.1 200 OK
X-PageSpeed: HIT

HIT means the response was served from the optimized cache; MISS means the worker is building the variant and you'll see HIT on the next request. (The /console/* routes are short-circuited before the middleware, so they intentionally do not carry X-PageSpeed — only content routes like / and your assets do.)

Open http://localhost:5050/console/. Once a few requests have run, the Dashboard and Metrics show non-zero counts. If everything reads zero, see How do I know it's working? in the docs.

Confirm image transcoding via content negotiation. We don't rewrite URLs in 2.0: the same /hero.jpg URL serves WebP to WebP-capable clients and AVIF to AVIF-capable ones, selected by the request Accept header:

curl -s -o /dev/null -D - http://localhost:5050/hero.jpg -H 'Accept: image/jpeg'
# Content-Length: 98230   Content-Type: image/jpeg   Vary: Accept, Save-Data, User-Agent

curl -s -o /dev/null -D - http://localhost:5050/hero.jpg -H 'Accept: image/webp'
# Content-Length: 2422    Content-Type: image/webp   Vary: Accept, Save-Data, User-Agent

curl -s -o /dev/null -D - http://localhost:5050/hero.jpg -H 'Accept: image/avif'
# Content-Length: 415     Content-Type: image/avif   Vary: Accept, Save-Data, User-Agent

Same URL, materially smaller bytes, and a Vary: Accept, Save-Data, User-Agent header so caches keep the variants apart. (Byte counts are from one sample image; yours will differ.)

What It Does

• HTML optimization: critical CSS inlining, lazy loading, LCP preload injection, third-party preconnect hints
• Image transcoding: on-demand conversion to WebP and AVIF, viewport-aware resizing, Save-Data support
• CSS/JS minification: whitespace removal, comment stripping
• Zero-copy caching: cache hits served from the memory-mapped Cyclone cache with no copy, up to 36 optimized variants per resource (format × viewport × density × Save-Data)

The middleware buffers HTML responses, passes them through the native libpagespeed library, and notifies the worker process to generate optimized asset variants asynchronously.

Platform Support

Native binaries (libpagespeed, factory_worker) are bundled with the matching WeAmp.PageSpeed.NativeAssets.* package, pulled in transitively by WeAmp.PageSpeed.AspNetCore. The worker process starts automatically on application boot. The Linux binaries statically link the C++ runtime (libc++/libc++abi/libunwind), so no additional shared libraries need to be present on the host beyond the system glibc.

On Linux and want a reverse proxy instead of in-process middleware? WeAmp.PageSpeed.Sidecar runs mod_pagespeed 1.15 as a bundled nginx + ngx_pagespeed reverse proxy in front of Kestrel (Linux-only). Use it when you want the classic nginx module in a sidecar; use this package for cross-platform in-process optimization with WebP/AVIF.

Each NativeAssets package also ships a BUILD_INFO.json file at runtimes/<rid>/native/BUILD_INFO.json with git_sha, git_sha_short, build_timestamp_utc, and rid. It is intended for support correlation — matching compliance-report heartbeats (which emit the worker's git_commit) to a specific package build — and for verifying package provenance without running the worker.

Configuration

Add a PageSpeed section to appsettings.json. Only Cache is shown below; every key in the table is optional and falls back to its default.

{
  "PageSpeed": {
    "Cache": {
      "VolumePath": "/var/cache/pagespeed/volume.dat",
      "VolumeSizeBytes": 1073741824
    }
  }
}

Set Cache.VolumePath to a location that is writable in your environment. The default /var/cache/pagespeed/ assumes a Linux host; on Windows, macOS, or containers without that path, point it somewhere writable (for example ./cache/volume.dat or %TEMP%).

Top-level keys:

Cache section:

Worker section:

Console section:

Options support hot-reload via IOptionsMonitor<PageSpeedOptions>.

Worker IPC

The middleware ↔ worker channel uses Unix domain sockets on Linux and macOS, and Windows Named Pipes on win-x64. Selection is automatic; no configuration required. The console and license endpoints are served on the app port; the worker's HTTP API is bound to 127.0.0.1 on an ephemeral port by default and is not exposed externally unless you set Worker.ApiPort explicitly.

Security

The /console/ admin console and /v1/license/* proxy are served on the same origin as your app. The worker requires Content-Type: application/json and X-Requested-With: XMLHttpRequest on POSTs to /v1/license/*, which blocks cross-origin form posts. It does not protect against same-origin scripts: a third-party script loaded into your app (via XSS or a supply-chain dependency) can drive a license POST such as POST /v1/license/apply to install an attacker-supplied key, because that endpoint is auth-exempt to allow bootstrapping before an API token is configured.

Treat /console/ as an admin surface:

• Set Console.RequireHttps = true in production.
• Don't expose /console/ to untrusted networks. Gate it at your reverse proxy, or use Console.MountPath to move the path off a guessable location.
• Avoid loading untrusted third-party scripts into apps with this middleware enabled.

License

Licensed under the Business Source License 1.1 (BUSL-1.1).

• Change Date: Four years after the first public release of each version (see the Change Date in the packaged LICENSE file).
• Change License: Apache License 2.0

After the Change Date, each version becomes available under Apache 2.0. See the LICENSE file in the package for full terms.

Links

• modpagespeed.com/pricing/ — plans, pricing, and purchase
• modpagespeed.com/features/#aspnet-core — ASP.NET Core overview
• WeAmp.PageSpeed.Sidecar — mod_pagespeed 1.15 as a bundled-nginx sidecar (Linux)
• modpagespeed.com — product documentation and filter reference
• we-amp.com — We-Amp B.V.