JSkelet sürüm notları ve geçmişi

Shared cross-subdomain cookies

brand.sharedCookieRoots plus writeSharedCookie / clearSharedCookie on server (jskelet/cookies) and client (jskelet/client). Secure follows https / x-forwarded-proto (not NODE_ENV); the client read-back fails into handoff when the browser rejects Domain. Optional auth.crossSubdomainHandoff mounts POST /_jskelet/auth/handoff (one-time ticket → ?handoff=) and documents a window.name bridge. Large tokens are refused — put a short session id in the cookie, not a JWT.

HTML cache key vary (cache().vary)

host: true adds the public Host (x-forwarded-host or Host, lowercase, no port) as h=…| before the path; optional headers and fn(req) add further segments. Required on host-based locale sites so one locale's HTML is not served on another. Classic prewarm accepts prewarm.origins for multi-host warming when vary is on.

Dynamic Open Graph images (Next.js ImageResponse / opengraph-image)

ogImage, sendOgImage, ogHandler, and ImageResponse turn card fields or raw SVG into PNG when sharp is installed (SVG fallback otherwise). Wired in examples/blog as /og/blog/:slug.png and metadata.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-fresh HIT in that window revalidates in the background; idle entries are soft-staled by a sweeper and drained over HTTP even without classic prewarmPaths (PREWARM=0 disables both). In-flight refreshes no longer drop the entry when staleUntil elapses.

Route-level stylesheets

put files in styles/pages/*.css and load them from the controller with styles: ["home.css"] (same contract as island entries). The layout emits them after global app.css; dev hot-swaps any changed .css manifest key without a full reload.

Dev overlay Errors tab now lists failed SSR and browser fetch calls with page path, API URL, optional island name, and expandable response-body details (JSON instead of [object Object]). Server console.error / console.warn records 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, perPage cap). Mutually exclusive with classic prewarm (max / priority / rotate / hooks.prewarmPaths, etc.) — mixing them fails at config load.

Runtime remote image optimizer

set images.remote.allowHosts to proxy allowlisted http(s) images through /_jskelet/image?url=&w=&q= as resized webp (disk cache under .jskelet/image-cache/). image() rewrites matching remote src values automatically; remoteImageUrl() builds URLs by hand. Requires sharp at runtime; without it the endpoint 302-redirects to the source.

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.js beside the overlay.

Marketing homepage ops storyboard

Redis L2, /_jskelet/admin panel mock and Cloudflare purge flow, with tabbed visual scenes animated by the vanilla motion API (Framer Motion’s non-React package) via an ops-story island.

VS Code / Cursor extension skeleton under extensions/vscode-jsk

.jsk language 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 .jsk component files), not from the file basename — so <SectionHead /> resolves when sectionHead lives in ui.js without a stub re-export. Docs cover the .jsk template-vs-component boundary and a { items, error } loader / LoadErrorState pattern so upstream failures are not mistaken for empty data.

Build-time .jsk templates

declarative HTML-like syntax compiled to ESM render modules under .jskelet/templates/ (no request-time parse, eval, or new Function). Coexists with EJS; compiled .jsk wins when both exist. Syntax: {{ }} / {{{ }}}, {#if} / {#each} / {#include}, PascalCase components (:prop bindings), built-ins Link / Image / Icon / CsrfField / PreloadImage.

Feature-first conventions

paths.features / paths.shared, multi-root views and components, features/<name>/index.js route registration after routes/. CLI: jskelet generate feature|page|island. jskelet init scaffolds a feature-first .jsk skeleton (features/home/ with route, page, component and island; global views/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 logs config for persistent sinks

daily NDJSON files (logs.file) and batched S3 PutObject (logs.s3) with embedded SigV4 — no @aws-sdk dependency. kinds selects http / event / error; console toggles runtime stdout lines. JSKELET_LOG_BUCKET (and logs.s3.bucket) may be a plain bucket or a bucket/prefix/… path. JSKELET_S3_API_URL sets the R2/MinIO endpoint (region defaults to auto). Missing credentials warn and disable the S3 sink without taking the site down. Env: JSKELET_LOG_BUCKET, JSKELET_S3_ACCESS_KEY_ID, JSKELET_S3_SECRET_ACCESS_KEY, JSKELET_S3_SESSION_TOKEN, JSKELET_S3_REGION, JSKELET_S3_API_URL.

Admin panel pages under /_jskelet/admin

Overview, Cache, Routes, Views, Logs and System. Configurable allowIps (exact or CIDR), blockBots (default on — crawler UAs get 404 before login), and logSize. 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.

trailingSlash in jskelet.config.mjs (default false). When true, 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. When false, no slash is enforced — unlike Next.js, the default does not strip trailing slashes.

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 at NODE_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 a 404 rather 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 localStorage and carries over to the login page, and switching costs no request. To keep this from leaking UI concerns into the server, an /action response 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.

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; true puts the whole query in the key and [] ignores it entirely. Parameters enter the key sorted, so ?a=1&b=2 and ?b=2&a=1 are one entry.

Cloudflare cache management, from the panel and from code. Set JSKELET_CLOUDFLARE_KEY and JSKELET_CLOUDFLARE_ZONE_ID (or cache().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 with cf 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 because invalidateHtmlCache() refreshes the origin while the copy your visitors get keeps being served from the edge until its TTL expires. The same surface is exported as purgeCloudflare(), toCloudflareUrls(), fetchCloudflareOverview(), fetchCacheAnalytics(), fetchPathEdges() and getCloudflareStatus(); 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 plus DBSIZE and used_memory; it runs a SCAN, 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 whether maxEntries is too high.

A cache admin panel at /_jskelet/cache, turned on with cache().panel: { enabled: true } or JSKELET_CACHE_PANEL=1. It 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 at NODE_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 a 404 rather than a 401 that would confirm the panel exists. The panel is excluded from indexing, prewarming and navigation speculation.

dropHtmlCacheKey() and dropDataCacheKey() 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=2 gone and /list?page=3 left hot.

An adaptive per-host rate limit for upstream calls, cache().upstream. It sits in the fetch wrapper 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, so prewarm.rps could never bound the real thing. A token bucket caps the average rate, a concurrency limit caps the calls in flight, and rate is treated as a ceiling that the limiter pulls down on its own — a 429 or 503 halves the rate, Retry-After stops the bucket for exactly as long as the upstream asked, and clean windows climb back one step at a time. A host that returns breakerFailures rate limits in a row is bypassed for breakerCooldownMs, 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 — set rate to 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 (97% from the data cache)), which is what tells you whether the fix is a longer TTL or a rate limit. The dev report has a Data cache card for it.

The dev overlay header now shows the installed JSkelet version next to the title, labelled latest when it matches npm and outdated with 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 } and npm 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. And invalidateHtmlCache(), clearHtmlCache() and clearDataCache() 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. If ioredis is 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 on SIGTERM/SIGINT instead 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. The withDataCache keys read during a render are recorded, so dropping news:abc stales 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 with cache().trackDependencies: false; getHtmlCacheEntries() reports the dependency count per page as deps.

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 rps limit. The pass summary counts them separately.

Transient upstream failures are now detected without any application code

globalThis.fetch is wrapped during startup and 429, 5xx and 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 calls reportUpstreamFailure(). Requests outside a render and requests to the server itself are ignored, deterministic answers such as 404 are not reported, and the wrapper can be turned off with cache().trackUpstream: false.

cache().transientRetry ({ attempts: 1, delayMs: 300 } by default) retries a page that called notFound() 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.

route(fn, { private: true }) for pages that depend on the visitor. The HTML

cache is bypassed, cache.html patterns can no longer turn caching on for that route, and the response is sent with private, no-store, Vary: Cookie and no ETag.

A runtime guard against identity leaks: when a cacheable route reads

Cookie, Authorization or a session field, the rendered HTML is never stored. In development the request fails with an explanation, in production it is served with no-store and logged.

fragment() for layout-less partial responses, with no-store and cache

bypass built in.

CSRF protection. Cross-site state-changing requests are rejected based on

Origin and Sec-Fetch-Site; requests carrying neither header still pass, so webhooks keep working. An optional double-submit token layer is enabled with security.csrf.token and rendered into forms by the new csrfField() helper.

Signed cookie helpers under jskelet/cookies: parseCookies(),

setCookie(), clearCookie(), setSignedCookie(), getSignedCookie(), randomToken() and safeEqual(). Defaults are HttpOnly, SameSite=Lax and Secure outside development.

A security configuration section

trustProxy, cookieSecret and csrf.

seeOther() for the post/redirect/get flow, which needs 303 rather than the

method-preserving 307 that redirect() sends.

Island cleanup. A mount() function may return a teardown callback; it is now

stored and called by the new unmount(root) export when the subtree leaves the DOM.

Client helpers for partial updates: swap() and startSwapLinks() for

fetching and replacing a region, enhanceForm() and startForms() for submitting forms without a full page load while keeping the no-JavaScript path working.

A fourth example, examples/dashboard: sign-in with a signed cookie session,

a private page, a paginated table fragment, a CSRF-protected mutation and an island with cleanup, covered by its own smoke.mjs.

An npm version badge in the README, linking to the package page.

An English edition of the documentation under docs/en/, mirroring every

chapter of the Turkish docs/.

The dev overlay now compares the installed version against the latest tag on

npm: the Server tab shows the version, marks an update chip when a newer release exists and offers the upgrade command. The lookup is cached for six hours, never blocks the server and can be turned off with JSKELET_VERSION_CHECK=0.

English README, plus CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md,

a LICENSE file, issue and pull request templates, and a CI workflow.

An English-first examples/marketing with a Turkish translation, serving the

package documentation under /docs and reading its version, dependencies and bundle sizes from the installed package.

Express 5 server with EJS rendering: createApp(), startServer(),

route(), renderPage(), renderView(), renderNotFound().

In-process HTML TTL cache with stale-while-revalidate, plus prewarm at boot.

Island runtime with visibility, eager and idle hydration strategies, a small

cross-island store, and DOM helpers.

Configuration through jskelet.config.mjs: brand, paths, navigation,

icons, fonts, clientEnv, redirects(), rewrites(), headers(), cache() and hooks.

Build pipeline: fonts, SVG sprite from used icons, Tailwind v4 CSS, esbuild

bundles with code splitting, webp variants, hashed output and brotli/gzip precompression.

Dev server with watch build, CSS hot-swap, automatic restart and a devtools

overlay (requests, errors, upstream calls, cache dump, Web Vitals).

CLI: jskelet dev, jskelet build, jskelet start, jskelet init.

Documentation under docs/ and three examples: minimal, blog,

marketing.