ReviewOS

stacks/stx

serve: declare imageWarmup in StxConfig and ignore unserved default views when auto-detecting image builtins

#2113
Closed chris opened this 8 days ago ·
8 days ago

What happens

bun-plugin-stx 0.2.644 serve() reads imageWarmup, imageWarmupBindBudgetMs and imageWarmupGraceMs from the loaded stx config (stxConfig.imageWarmup ?? 'auto'), but StxConfig does not declare them. An app that sets imageWarmup: false in config/ui.ts with satisfies StxOptions fails type checking and has to widen the type by hand.

With 'auto', projectUsesImageBuiltins() scans every .stx file under the working directory except node_modules, dist, build, coverage and vendor. In a Stacks app that includes framework default views the app does not serve (the server logs them as "not served"), so a project that never uses <StxImage> still runs the warm-up. In production that warm-up can hold the bind for up to the 45 second default budget on a cold cache, and it writes AVIF/WebP derivatives of every raster under public/.

Seen in

stacksjs/the-settlers-iii-remake: after the converted original-sprite atlas grew to 1024x3178, CI's production server stopped binding within the browser check's 30 second readiness window (failed run). The app now sets imageWarmup: false with a widened config type (4cf422a); later runs pass.

Expected

  • StxConfig (or the type config/ui.ts satisfies) declares the serve options it reads.
  • Auto-detection considers only templates the app serves (its views root and components), not unserved framework defaults.
  • Optionally, image delivery accepts exclusions so game assets or pixel-art atlases under public/ are not re-encoded.
8 days ago

Fixed on main in 818064a.

Automatic image warm-up now starts from serve's discovered pages, after route exclusions and same-path page-root overrides. It follows literal layout, partial, @import and component references, including used plugin/framework fallback components. Unserved default views and unused resource definitions no longer launch placeholder/delivery workers. A fallback page that is actually served still enables warm-up. Detection does not execute server scripts.

Regression coverage: packages/bun-plugin/test/image-warmup-scope.test.ts (9 passing cases) and packages/bun-plugin/test/serve-bind-after-warmup.test.ts (real subprocess checks for skipped workers and served fallback pages). The full bun-plugin suite passed 355 tests with zero failures; final focused scope tests passed 9/9. Release preflight passed: package builds, typecheck, export validation, installed-package smoke, performance budgets, and 319 targeted tests. Lint has zero errors; formatting is clean. The config-type portion is already present, with public-type tests passing.

Version status: this is an unreleased main fix after v0.2.674; v0.2.674 does not include it. No new release was cut by this change. Runtime-computed template paths/image markup still require imageWarmup: true; false remains the opt-out for atlas/pixel-art apps. Asset exclusions were optional in this issue and are not introduced here. Craft is untouched.

Sign in to comment on this issue.