also looking at this
feat: imgx integration — on-the-fly image transforms from query params
#2264
15 files
+1118
-16
| @@ -0,0 +1,102 @@ | ||
| 1 | # Image Transforms (imgx) | |
| 2 | ||
| 3 | rpx can transform image responses on the fly, driven by imgix/meema-style query params — powered by the [imgx](https://github.com/stacksjs/ts-images) pure-TypeScript pipeline. Enable it and every image your proxy (or static route) serves understands URLs like: | |
| 4 | ||
| 5 | ```txt | |
| 6 | https://app.localhost/hero.png?w=200&h=1200&q=80 | |
| 7 | https://app.localhost/hero.png?w=640&fm=webp | |
| 8 | https://app.localhost/hero.png?w=400&h=400&fit=crop&crop=top | |
| 9 | ``` | |
| 10 | ||
| 11 | The upstream never sees anything but the original request — any dev server, static directory, or app gains image resizing for free. | |
| 12 | ||
| 13 | ## Enabling | |
| 14 | ||
| 15 | ```ts | |
| 16 | import { startProxy } from '@stacksjs/rpx' | |
| 17 | ||
| 18 | await startProxy({ | |
| 19 | from: 'localhost:5173', | |
| 20 | to: 'my-app.localhost', | |
| 21 | imgx: true, // defaults; or pass an options object | |
| 22 | }) | |
| 23 | ``` | |
| 24 | ||
| 25 | Per-proxy in multi-proxy configs (overrides the shared setting): | |
| 26 | ||
| 27 | ```ts | |
| 28 | await startProxy({ | |
| 29 | imgx: true, | |
| 30 | proxies: [ | |
| 31 | { from: 'localhost:5173', to: 'app.localhost' }, | |
| 32 | { from: 'localhost:3000', to: 'api.localhost', imgx: false }, | |
| 33 | ], | |
| 34 | }) | |
| 35 | ``` | |
| 36 | ||
| 37 | Or from the CLI: | |
| 38 | ||
| 39 | ```bash | |
| 40 | rpx start --from localhost:5173 --to my-app.localhost --imgx | |
| 41 | ``` | |
| 42 | ||
| 43 | ## Supported query params | |
| 44 | ||
| 45 | Sizing: | |
| 46 | ||
| 47 | | Param | Meaning | | |
| 48 | | --- | --- | | |
| 49 | | `w`, `h` | Output width/height in px, or a `0–1` fraction of the source dimension | | |
| 50 | | `fit` | `clip` (default, fit within preserving AR), `max` (clip, never enlarge), `crop` (fill + crop overflow), `min` (crop, never enlarge), `scale` (stretch), `fill` (letterbox with `bg`) | | |
| 51 | | `crop` | Crop anchor for `fit=crop`: `top`, `bottom`, `left`, `right`, or combos (`top,left`) | | |
| 52 | | `ar` | Aspect ratio (`16:9`) used to derive a missing dimension | | |
| 53 | | `dpr` | Device pixel ratio multiplier, `0–5` (default `1`) | | |
| 54 | ||
| 55 | Output: | |
| 56 | ||
| 57 | | Param | Meaning | | |
| 58 | | --- | --- | | |
| 59 | | `q` | Quality `1–100` (default `80`, configurable) | | |
| 60 | | `fm` / `format` | `jpeg`, `png`, `webp`, `avif`, `gif`, `bmp`, or `auto` | | |
| 61 | | `auto` | `format` (negotiate from `Accept`, prefers WebP), `compress` | | |
| 62 | | `lossless` | Lossless WebP/AVIF encoding | | |
| 63 | ||
| 64 | Adjustments: | |
| 65 | ||
| 66 | | Param | Meaning | | |
| 67 | | --- | --- | | |
| 68 | | `blur` | Gaussian blur, imgix `0–2000` scale | | |
| 69 | | `sharp` | Sharpen | | |
| 70 | | `greyscale` / `grayscale` | Convert to grayscale | | |
| 71 | | `bri`, `sat` | Brightness/saturation offset `−100..100` | | |
| 72 | | `hue` | Hue rotation in degrees | | |
| 73 | | `tint` | Tint color (`tint=ff0000`) | | |
| 74 | | `rot` | Rotate by degrees (`bg` fills the corners) | | |
| 75 | | `flip`, `flop` | Vertical / horizontal mirror | | |
| 76 | | `bg` | Background color for `fit=fill` and `rot` (hex or `white`/`black`/`transparent`) | | |
| 77 | ||
| 78 | ## Options | |
| 79 | ||
| 80 | ```ts | |
| 81 | await startProxy({ | |
| 82 | from: 'localhost:5173', | |
| 83 | to: 'my-app.localhost', | |
| 84 | imgx: { | |
| 85 | quality: 80, // encode quality when the request has no `q` | |
| 86 | maxWidth: 8192, // clamp on requested output width | |
| 87 | maxHeight: 8192, // clamp on requested output height | |
| 88 | maxInputBytes: 32 * 1024 * 1024, // larger responses pass through untouched | |
| 89 | cache: true, // cache transformed variants in memory | |
| 90 | cacheMaxBytes: 64 * 1024 * 1024, // total cache byte budget | |
| 91 | cacheMaxEntries: 500, // max cached variants | |
| 92 | }, | |
| 93 | }) | |
| 94 | ``` | |
| 95 | ||
| 96 | ## Behavior notes | |
| 97 | ||
| 98 | - Only `GET` requests with a `200` image response (`jpeg`, `png`, `gif`, `bmp`, `webp`, `avif`) and at least one transform param are touched — everything else streams through untouched. | |
| 99 | - Transformed variants are cached in memory, keyed by path, params, and a hash of the upstream bytes: an unchanged image is never re-encoded twice, and a changed one misses naturally (no TTLs to tune). Cache state is visible in the `x-rpx-imgx: hit|miss` response header. | |
| 100 | - Any decode/encode failure falls back to serving the original bytes — the integration can slow an image down, but never break it. | |
| 101 | - Upstream `ETag`/`Last-Modified` headers are dropped from transformed responses (they described the original entity); `Cache-Control` is passed through. `auto=format` responses set `Vary: accept`. | |
| 102 | - WebP/AVIF encoding uses system `cwebp`/`avifenc` when available and falls back to the bundled pure-TS encoders; `auto=format` deliberately negotiates WebP (not AVIF) for that reason. | |