unreleased unreleased 68
Added
2
-
Shared cross-subdomain cookies:
brand.sharedCookieRootspluswriteSharedCookie/clearSharedCookieon server (jskelet/cookies) and client (jskelet/client).Securefollows https /x-forwarded-proto(notNODE_ENV); the client read-back fails into handoff when the browser rejectsDomain. Optionalauth.crossSubdomainHandoffmountsPOST /_jskelet/auth/handoff(one-time ticket →?handoff=) and documents awindow.namebridge. Large tokens are refused — put a short session id in the cookie, not a JWT. -
HTML cache key vary (
cache().vary):host: trueadds the public Host (x-forwarded-hostorHost, lowercase, no port) ash=…|before the path; optionalheadersandfn(req)add further segments. Required on host-based locale sites so one locale's HTML is not served on another. Classic prewarm acceptsprewarm.originsfor multi-host warming when vary is on.
Changed
1
- Marketing example visual language: darker ink canvas, solid cyan primary CTAs, cyan-only glow/grid (indigo accents removed), and a measured trust bar on the homepage (payload gzip, Node, license, zero web fonts) instead of the marquee.
Added
6
-
Dynamic Open Graph images (Next.js
ImageResponse/opengraph-image):ogImage,sendOgImage,ogHandler, andImageResponseturn card fields or raw SVG into PNG whensharpis installed (SVG fallback otherwise). Wired inexamples/blogas/og/blog/:slug.pngandmetadata.openGraph.image. -
Early HTML cache refresh before TTL expiry: the last successful produce time (
produceMs) sets a lead window (min(max(produceMs×2, 250ms), ttl/2)). A still-freshHITin that window revalidates in the background; idle entries are soft-staled by a sweeper and drained over HTTP even without classicprewarmPaths(PREWARM=0disables both). In-flight refreshes no longer drop the entry whenstaleUntilelapses. -
Route-level stylesheets: put files in
styles/pages/*.cssand load them from the controller withstyles: ["home.css"](same contract as islandentries). The layout emits them after globalapp.css; dev hot-swaps any changed.cssmanifest key without a full reload. -
Dev overlay Errors tab now lists failed SSR and browser
fetchcalls with page path, API URL, optional island name, and expandable response-body details (JSON instead of[object Object]). Serverconsole.error/console.warnrecords also carry the current page when they fire during render. -
Visit-driven HTML prewarm (
cache().prewarm.onVisit): after each public cacheable page response, same-origin links in the HTML are warmed in the background (document order,perPagecap). Mutually exclusive with classic prewarm (max/priority/rotate/hooks.prewarmPaths, etc.) — mixing them fails at config load. -
Runtime remote image optimizer: set
images.remote.allowHoststo proxy allowlisted http(s) images through/_jskelet/image?url=&w=&q=as resized webp (disk cache under.jskelet/image-cache/).image()rewrites matching remotesrcvalues automatically;remoteImageUrl()builds URLs by hand. Requiressharpat runtime; without it the endpoint 302-redirects to the source.
Breaking
1
-
The cache admin panel moved to a top-level
admin()config section at/_jskelet/admin(wascache().panelat/_jskelet/cache). Enable withadmin() { return { enabled: true } }orJSKELET_ADMIN=1.JSKELET_CACHE_PANELandcache().panelare removed. Auth is unchanged (per-process password in the server log, cookie session, 404 for strangers); the action CSRF header is nowX-JSkelet-Admin.
Fixed
3
-
Remote image optimizer cache hits no longer 404. Disk cache lives under
.jskelet/image-cache/; ExpresssendFileignores dotfiles by default, so the file was written but the response still failed.sendCachednow passesdotfiles: "allow". -
Cloudflare analytics in the cache panel no longer asks for an open-ended window. Queries used only
datetime_geq, so Cloudflare closed the range at query time and a default 24h lookback became1dplus network delay — Free zones reject anything wider than one day. Both ends are now pinned from the same clock (datetime_leqincluded). -
Missing
/assets/*responses no longer keep the long-livedimmutableCache-Control thatheadersMiddlewarestamps for static prefixes. A deploy race (prune-before-write) could 404 a hashed CSS URL for a moment; a CDN then cached that HTML 404 for a year and browsers refused it as a stylesheet (MIME type 'text/html'). Catch-all andnotFoundhandlers now setCache-Control: no-store. CSS and sprite builds write the new file before pruning older hashes so the same content hash never has a gap.
Added
17
-
Devtools SEO check: an SEO tab in the overlay lists document, heading, image, link and social-tag issues with error/warning severity. Optional page highlights draw red or yellow boxes around the offending elements; the label shows the short title and a click opens the full explanation. Served only in development as
/__jskelet/dev/seo.jsbeside the overlay. -
Marketing homepage ops storyboard: Redis L2,
/_jskelet/adminpanel mock and Cloudflare purge flow, with tabbed visual scenes animated by the vanillamotionAPI (Framer Motion’s non-React package) via anops-storyisland. -
VS Code / Cursor extension skeleton under
extensions/vscode-jsk:.jsklanguage id, TextMate highlighting ({{ }}/{#if}/{#each}/ components), language config, and snippets. Install from that folder or launch JSK: Extension from the repo root. Bound attrs on HTML tags (:src="… + '/path'") highlight nested single-quoted strings. -
Compile-time known components are discovered from named exports in
views/components/**/*.js(plus.jskcomponent files), not from the file basename — so<SectionHead />resolves whensectionHeadlives inui.jswithout a stub re-export. Docs cover the.jsktemplate-vs-component boundary and a{ items, error }loader /LoadErrorStatepattern so upstream failures are not mistaken for empty data. -
Build-time
.jsktemplates: declarative HTML-like syntax compiled to ESM render modules under.jskelet/templates/(no request-time parse,eval, ornew Function). Coexists with EJS; compiled.jskwins when both exist. Syntax:{{ }}/{{{ }}},{#if}/{#each}/{#include}, PascalCase components (:propbindings), built-insLink/Image/Icon/CsrfField/PreloadImage. -
Feature-first conventions:
paths.features/paths.shared, multi-root views and components,features/<name>/index.jsroute registration afterroutes/. CLI:jskelet generate feature|page|island.jskelet initscaffolds a feature-first.jskskeleton (features/home/with route, page, component and island; globalviews/pages/not-found.jsk). -
Template compile step in
jskelet build; icon scan and Tailwind docs cover.jsk/features/shared. Bench:node scripts/bench-templates.mjs. -
Top-level
logsconfig for persistent sinks: daily NDJSON files (logs.file) and batched S3 PutObject (logs.s3) with embedded SigV4 — no@aws-sdkdependency.kindsselectshttp/event/error;consoletoggles runtime stdout lines.JSKELET_LOG_BUCKET/JSKELET_S3_BUCKET(+ optionalJSKELET_S3_KEY_PREFIX) may be a plain bucket or abucket/prefix/…path; with credentials present the sink turns on withoutenabled: true.JSKELET_S3_API_URLsets the S3-compatible endpoint (region defaults toauto). Env:JSKELET_LOG_BUCKET,JSKELET_S3_*. -
Admin panel pages under
/_jskelet/admin: Overview, Cache, Routes, Views, Logs and System. ConfigurableallowIps(exact or CIDR),blockBots(default on — crawler UAs get 404 before login), andlogSize. Live Logs use an in-process ring plus SSE (/api/logs/stream) with client-side filters for method, status, cache, kind, path/route and text. Routes and Views are read-only inventories; HTTP finish middleware records timings only while the panel is enabled. -
trailingSlashinjskelet.config.mjs(defaultfalse). Whentrue, canonical page URLs end with/and return 200; a request without the slash is sent to the slashed form with a 308 (not 301). File URLs and/.well-known/**are left alone. Whenfalse, no slash is enforced — unlike Next.js, the default does not strip trailing slashes. -
cache().query, a pattern → allowlist mapping that decides which query parameters belong to the HTML cache key. An allowlist caches one entry per distinct value of the listed parameters and ignores the rest, so every?utm_source=…variant of a path shares one copy;trueputs the whole query in the key and[]ignores it entirely. Parameters enter the key sorted, so?a=1&b=2and?b=2&a=1are one entry. -
A cache admin panel surface (now under
admin()— see Breaking) that lists what the in-process tier holds (key, size, status, remaining TTL, dependency count, precompressed bodies for HTML; key and TTL for data), reports whether the Redis tier is connected or bypassed, and runs the operations you would otherwise hand-write an admin route for: targeted invalidation with an optional hard mode, dropping a single entry, clearing either cache, unlinking the shared keys and triggering a prewarm pass. Unlike the dev overlay it does not look atNODE_ENV, because "why is this page stale" is a production question — but nothing is mounted until it is explicitly enabled, so the path does not exist by default. Access is a 32-character password regenerated on every process start and printed once to the server log; there is no persistent secret to leak and a deploy revokes old access on its own. The password is never accepted in a query string, three failed attempts ban the IP for 24 hours, and every banned or unauthorised response is a404rather than a 401 that would confirm the panel exists. The panel is excluded from indexing, prewarming and navigation speculation. -
A language picker in the cache panel header, Turkish and English. The first visit follows the browser's language, the choice is kept in
localStorageand carries over to the login page, and switching costs no request. To keep this from leaking UI concerns into the server, an/actionresponse now returns{ ok, code, params }instead of an English sentence and the panel builds the text — the framework's log and API stay in one language while the panel speaks two. -
Cloudflare cache management, from the panel and from code. Set
JSKELET_CLOUDFLARE_KEYandJSKELET_CLOUDFLARE_ZONE_ID(orcache().cloudflare) and the panel gains the CDN tier next to the origin one: purge everything, purge every URL currently held in memory with one button or a single row withcf purge, purge by prefix, host or cache tag, toggle development mode, cache level, browser cache TTL, query string sorting, Always Online, Tiered Cache, Regional Tiered Cache and Cache Reserve, clear Cache Reserve, and read the cache hit ratio. This matters becauseinvalidateHtmlCache()refreshes the origin while the copy your visitors get keeps being served from the edge until its TTL expires. The same surface is exported aspurgeCloudflare(),toCloudflareUrls(),fetchCloudflareOverview(),fetchCacheAnalytics(),fetchPathEdges()andgetCloudflareStatus(); none of them throw, so a CDN outage returns{ ok: false, error }instead of breaking a publish flow. Long purge lists are batched at Cloudflare's 100-keys-per-request limit and sent sequentially to stay inside the rate limit. The token is read from the environment, is never returned in a response, and only cache related zone settings can be changed. -
An edge breakdown for a single path:
fetchPathEdges()reports which Cloudflare colos served it from cache and which went to the origin. This is observation, not inventory — Cloudflare has no endpoint that lists which edges currently hold a URL, and no way to warm an edge you pick, so the panel says as much rather than implying otherwise. -
getRedisDetails()reports where the shared tier actually points — address, TLS, database, namespace, which kinds are shared and whether the purge channel is subscribed — because "connected" alone does not explain a Redis that shares nothing because of a wrong namespace. The password is never part of the output.inspectRedis()counts the keys per kind plusDBSIZEandused_memory; it runs aSCAN, so the panel keeps it behind its own button instead of the refresh loop. When Redis is off, the panel explains what a shared tier would buy and shows the memory and disk state of the host instead, which is the number that decides whethermaxEntriesis too high. -
dropHtmlCacheKey()anddropDataCacheKey()drop one exact cache key.invalidateHtmlCache()matches a path pattern and takes down every query variant of a path, which is the right default for a webhook but wrong when you want/list?page=2gone and/list?page=3left hot.
Changed
23
-
README rewritten for the current surface: build-time
.jskas the default template story (EJS still supported), feature-firstinitexamples,mountisland contract, path-basedinvalidateHtmlCache(replacing the outdated “no targeted invalidation” claim), Redis / admin / data-cache callouts, and bilingual doc links underdocs/anddocs/en/. -
Marketing compare live latency demo now measures two same-sized fragments (cached vs
no-store) with an explicit 80 ms simulated upstream inside the shared producer — a hit skips that wait so the gap is visible even when RTT dominates the wall clock. The island prints transferred bytes, Server-Timingproduceduration, and a View Source section contrasts__NEXT_DATA__payload tax with plain JSkelet HTML. The measured-weight block also shows an estimated Next.js App Router first-load breakdown beside this site’s real gzip totals (clearly labelled estimate, not a build from this repo). -
Duplicate component named exports (or the same PascalCase tag in two files) now fail at build and at server startup instead of warning and letting the second definition win. Overwriting
components/index.jsbarrel exports remains allowed. -
examples/minimalpages moved to.jsk; addsfeatures/demoas a co-located route + view sample. -
Marketing compare/FAQ copy no longer claims targeted invalidation is missing; it points at
invalidateHtmlCache()(and Redis pub/sub for multi-instance). -
An adaptive per-host rate limit for upstream calls,
cache().upstream. It sits in thefetchwrapper rather than in the prewarm pass, because what spends the quota is the API call, not the page: one render may make one call or twenty, soprewarm.rpscould never bound the real thing. A token bucket caps the average rate, a concurrency limit caps the calls in flight, andrateis treated as a ceiling that the limiter pulls down on its own — a 429 or 503 halves the rate,Retry-Afterstops the bucket for exactly as long as the upstream asked, and clean windows climb back one step at a time. A host that returnsbreakerFailuresrate limits in a row is bypassed forbreakerCooldownMs, which stops the worst waste: because a 429 counts as transient, the HTML produced by a throttled call is never stored, so a pass in that state spends quota and keeps nothing. Only 429 and 503 penalise the rate; a 400 or 500 is not a quota problem. Off by default — setrateto turn it on. -
getUpstreamLimiterStatus()reports the current rate, calls in flight, 429 count and breaker state per host. The dev panel's Server tab shows the same. -
getDataCacheStats()counts how the data cache was used: fresh hits, stale hits, misses, coalesced concurrent reads, values promoted from the shared tier and — the only number that reaches the quota — real producer runs. A prewarm pass now prints its own share of that (`12 upstream calls for 430 data reads -
The dev overlay header now shows the installed JSkelet version next to the title, labelled
latestwhen it matches npm andoutdatedwith the newer version when it does not, so you can tell at a glance which version the project runs without opening the Server tab. -
An optional Redis tier behind both caches, turned on with
cache().redis: { enabled: true, url }andnpm install ioredis. The in-process cache stays primary and every request still reads it; Redis only does the two things a single process cannot. An instance that has never seen a path finds the HTML another replica already produced, so a fresh container or a post-deploy replacement does not re-render and re-fetch everything from scratch. AndinvalidateHtmlCache(),clearHtmlCache()andclearDataCache()now reach every replica over pub/sub instead of only the one that received the webhook — until now the others waited out the TTL and a visitor saw old or new content depending on where they landed. Keys live under_jskelet:{namespace}:{buildId}:…, where the build id makes HTML from a previous deploy expire on its own rather than pointing at asset files that no longer exist. Personalised (storable: false), degraded and non-200 responses are never shared. Ifioredisis missing, Redis is unreachable or it goes down mid-flight, a warning is printed and the site keeps serving from memory. -
getRedisStatus()reports whether the shared tier is connected, which key prefix and build id it is using, and how many command failures there have been — usable from a healthcheck endpoint. The same summary appears in the dev panel report. -
Servers started with
startServer()now shut down onSIGTERM/SIGINTinstead of being killed: the listener is closed and the Redis connection is drained so in-flight writes are not cut mid-command. -
Targeted HTML invalidation:
invalidateHtmlCache(target, { hard })takes a path, the config pattern syntax (/news/:slug), a regular expression or a list of them, and returns how many entries were affected. By default it stales the entries rather than deleting them, so a webhook that touches hundreds of pages does not turn into hundreds of cold renders at the worst possible moment: visitors keep getting the old HTML while the refresh runs in the background, once per key. Matching is done against the path, so every query variant of a page is covered by one call, and a render already in flight when the purge arrives is not stored. -
clearDataCache()now refreshes the HTML too. ThewithDataCachekeys read during a render are recorded, so droppingnews:abcstales every page that actually read it — the article, the home page listing it and the tag page — without the application declaring any tags. Turn it off withcache().trackDependencies: false;getHtmlCacheEntries()reports the dependency count per page asdeps. -
Invalidated paths go to the front of the next prewarm pass, so an updated page is refreshed without waiting for a visitor, while still respecting the
rpslimit. The pass summary counts them separately. -
An upstream data cache:
withDataCache(key, ttlSeconds, producer)and thedataCache(fn, { key, revalidate })wrapper, withclearDataCache(prefix?),getDataCacheSize()andgetDataCacheEntries()alongside them. It keeps JSON rather than HTML, so its default limit is 10,000 entries: a long-tail page that was never prewarmed still renders without touching the API. Concurrent reads of the same key collapse into one upstream request, an expired entry is served immediately while it refreshes in the background, a failing producer falls back to the stale value, and empty answers (null/undefined) are not stored unlessstoreEmpty: trueis passed. -
cache().prewarm.prioritydecides the warm-up order and accepts both the config pattern syntax (/news/:slug) and plain regular expressions. Matching paths are warmed on every pass. -
Drip prewarming for large sites:
cache().prewarm.rps(alsoPREWARM_RPS) caps requests per second regardless of parallelism, androtate(on by default) makes periodic passes continue through the queue where the previous one stopped instead of re-warming the same first slice. A pass is skipped while the previous one is still running. -
cache().prewarm.retryDelayMs(alsoPREWARM_RETRY_DELAY_MS) waits before the retry pass, since rate limit windows are measured in seconds. -
cache().maxEntriesconfigures the HTML cache limit, which used to be a fixed 500. -
Transient upstream failures are now detected without any application code:
globalThis.fetchis wrapped during startup and429,5xxand network errors raised inside a render are reported on their own, so rate limits stop turning existing pages into 404s even when the data layer never callsreportUpstreamFailure(). Requests outside a render and requests to the server itself are ignored, deterministic answers such as404are not reported, and the wrapper can be turned off with `cache().trackUpstream: -
cache().transientRetry({ attempts: 1, delayMs: 300 }by default) retries a page that callednotFound()while upstream was failing. Each attempt runs in a fresh upstream and per-request cache scope, so a page whose data arrives on the second try is served and cached as usual instead of degrading to an error. -
The dev report now includes the data cache entry count under
cache.data.
Changed
13
-
Admin panel System meters (CPU, memory, disk) show this process's share of the host — RSS and project disk footprint against machine totals, plus process CPU across all cores — instead of whole-machine fullness. The panel content width is wider (
1600px) so Overview, Routes, Views and System use the screen better. -
The release history page in
examples/marketingnow shows one release at a time: the newest one is expanded and older releases collapse to a single header row with their date, status and change count. Every release used to be printed open in a two-column grid, which made the page an unreadable wall as soon as a few versions piled up. Version links and the quick-jump strip still work, and they open the collapsed release they point at. -
The prewarm retry pass no longer retries permanent failures. A
400,403or404does not get better on the second try, so those paths are dropped from the retry round and counted asN not retried (permanent)in the summary. The wait before the round now also honours the upstream rate limit: if aRetry-Afteror an open circuit breaker is holding calls back, the pass waits that out instead of retrying into the same 429. - Errors and warnings raised during a prewarm pass are no longer logged one per page. Request errors and the per-page render warnings (`was produced with
- The marketing example's changelog page is now a timeline: releases are laid out along a rail with a sticky version column, each change group gets its own card with a coloured rule and item count, and a row of version chips at the top jumps straight to a release.
-
The dev tools panel is now fed over a WebSocket (
<devBasePath>/ws) instead of polling/statsevery two seconds. The server pushes statistics as they change and sends live reload and CSS hot-swap events over the same connection, so an open tab no longer keeps hitting the server while the panel is closed. No new dependency is involved; if the socket cannot be opened, the panel falls back to the previous SSE plus polling path. -
The server now binds to
::instead of0.0.0.0when noHOSTis given, so a single dual-stack socket answers both IPv6 and IPv4. Browsers resolvelocalhostto::1first and, unlike ordinary requests, a WebSocket handshake does not fall back to IPv4 — which made the dev panel's live channel fail on an IPv4-only socket. Where IPv6 is unavailable the bind falls back to0.0.0.0. -
Prewarming no longer holds up the rest of the dev server. In development it now runs with a single worker and a default limit of 4 requests per second (
prewarm.rps/PREWARM_RPSstill override it), so page requests and the dev panel stay responsive while a warm-up round is going on. Production behaviour is unchanged. -
notFound()is no longer served as a 404 when a transient upstream failure (429,5xx, network error) happened during the same render. The page is retried first and, if upstream is still failing, responds with an uncached503andRetry-After. A temporary rate limit is no longer frozen into "this page does not exist" for the whole TTL. A retry that gets a clean answer saying the page is gone still returns a normal 404. -
Responses produced with missing data are no longer offered to shared caches: a
degradedrender is sent withprivate, no-storeinstead ofpublic, s-maxage=…. TheX-JSkelet-Cachediagnostic header is still written. -
The prewarm summary distinguishes paths left for the next pass (
700 deferred to the next pass) from paths dropped entirely (700 over the limit). -
The changelog page of the marketing example is generated from the project's
CHANGELOG.mdinstead of a hand-written list, and shows the version published on npm next to the installed one. -
The marketing example reads its markdown (documentation and changelog) from the repository over GitHub's raw endpoint, falling back to the installed package when the network is unavailable, so a deployment that ships without
node_modulescan still serve the docs. In development the local file wins and nothing is cached. The branch is overridable withDOCS_REF.
Fixed
1
-
The dev panel's WebSocket handshake was answered with a
Sec-WebSocket-Acceptvalue derived from a mistyped protocol constant. Browsers verify that value and closed the connection immediately with "Incorrect 'Sec-WebSocket-Accept' header value", so the panel silently fell back to polling.
Breaking
1
-
A request that carries a query parameter is now dynamic by default: it is not written to the HTML cache and the response is sent with
private, no-store, even when acache().htmlpattern covers the path. Every query variant used to become its own cache entry, which let campaign parameters (?utm_source=…) mint unbounded keys and evict real pages from a 500-entry store. Pages whose output genuinely depends on the query keep their cache by listing the relevant parameters undercache().query.