Static when it can be
Prerendered pages and production defaults, set in blockstudio.json.
Prerender anonymous pages
Static prerendering is off by default. Turn on performance.staticPrerender and Blockstudio stores each complete HTML document an anonymous visitor receives, then answers the next anonymous visitor from that copy.
Requests that must stay live never touch it: non-GET requests, query strings, admin, REST, Ajax, cron, feeds, search, previews, nonce-bearing pages, every path under dynamicPaths, and logged-in visitors unless serveLoggedIn is on.
{
"performance": {
"staticPrerender": {
"enabled": true,
"ttl": 3600,
"earlyServe": true,
"dynamicPaths": ["/account", "/checkout"]
}
}
}<!-- blockstudio:no-cache -->
<p class="stock">
<?php echo esc_html( $a['label'] ); ?>
</p>Off by default
Nothing changes until blockstudio.json names the feature.
Dynamic paths
A dynamic path of /account covers /account/orders but not /accounting.
Opt-out marker
A blockstudio:no-cache comment keeps any response out of the cache.
Logged-in visitors
With serveLoggedIn they read stored pages; their own pages are never stored.
Custom bypass
The static_prerender/request_bypass filter keeps any request you name, such as one with a cart cookie, off stored pages.
Warm queue
A durable queue re-renders stale pages on the interval you set.
Long-tail routes
Routes outside the deployed map are served early too, once WordPress has rendered and stored them.
Stylesheet check
A stored page whose linked Tailwind stylesheet is gone is re-rendered, never served unstyled.
Served before WordPress boots
With earlyServe on, Blockstudio installs an advanced-cache.php drop-in that streams a stored page before WordPress, plugins, or the theme load. It never overwrites a drop-in, a route map, or a WP_CACHE line it did not write.
This site runs it. On October 8, 2026, blockstudio.dev pages answered with x-blockstudio-static-prerender: HIT-EARLY, the header the drop-in sends.
# Identity, files, queue, and hit/miss counters
wp bs prerender status
# Re-render stale entries now
wp bs prerender warm
# Dead or orphaned early-serve map entries
wp bs prerender map status
wp bs prerender map prune --dry-run
# Remove the drop-in and map this install owns
wp bs teardowncurl -sI https://blockstudio.dev/ | grep -i x-blockstudio
# x-blockstudio-static-prerender: HIT-EARLYFresh after every change
The default signature mode fills the cache on an anonymous miss and rotates it after site-level changes. Saving or deleting a post purges that post and the front page, or queues them for a re-render when warming is on.
graph mode is for deploy tooling. It records the files each page read, so a build re-renders only the routes whose files changed, then activates the new set as one artifact. If a referenced file fails validation, the previous artifact stays live.
Installing an artifact compares bytes and swaps changed documents atomically. last_promotion() reports how many routes were promoted, replaced, skipped, or kept, so a deploy can log it and compare the active build id.
use Blockstudio\Static_Prerender_Runtime;
$plan = Static_Prerender_Runtime::build_plan($sourceUrls);
foreach ($plan['affectedUrls'] as $url) {
$result = render_with_dependencies($url);
Static_Prerender_Runtime::persist_built_response(
$url,
$result['html'],
$result['files'],
$result['virtualHashes']
);
}
Static_Prerender_Runtime::garbage_collect(array_keys($plan['live']));use Blockstudio\Static_Prerender_Early_Serve;
use Blockstudio\Static_Prerender_Runtime;
$entry = Static_Prerender_Runtime::artifact_entry($targetUrls);
Static_Prerender_Early_Serve::install_artifact_entry(
$entry,
Static_Prerender_Runtime::cache_root_path()
);
$counts = Static_Prerender_Early_Serve::last_promotion();Behind a CDN
The prerender header already says which responses are safe to share. Map HIT and HIT-EARLY to a Cache-Control lifetime at the origin, cache only what carries one, and bypass the edge for the wordpress_logged_in_, wp-postpass_, and comment_author_email_ cookies, your dynamicPaths, wp-admin, and wp-json.
Pages cached at the edge keep linking the content-hashed stylesheet they were rendered with. Raise cache.namespaceGrace to the longest time such a copy can live, and retired stylesheets stay on disk until it expires.
map $upstream_http_x_blockstudio_static_prerender $edge_cache_control {
"~^HIT" "public, s-maxage=604800";
default "";
}
location ~ \.php$ {
include fastcgi_params;
fastcgi_pass unix:/run/php/php-fpm.sock;
add_header Cache-Control $edge_cache_control;
}{
"cache": {
"namespaceGrace": 777600
},
"tailwind": {
"enabled": true,
"output": "link"
}
}One live block on a cached page
Set blockstudio.island to dynamic and the cached page carries a placeholder instead of the block. The browser collects every dynamic island on the page and fetches their fragments in one batched request, each signed with the block name and its allow-listed attributes.
hydrate keeps the full HTML in the page and only sends a mount event. Dynamic islands can wait until they are visible, refresh when a window event fires, and cache fragments per user or globally.
{
"name": "acme/cart-count",
"title": "Cart count",
"blockstudio": {
"island": {
"mode": "dynamic",
"attributes": ["productId"],
"loading": "visible",
"event": "cart:updated",
"cache": {
"ttl": 60,
"per": "user"
}
}
}
}<div class="cart-count-placeholder">
Loading cart...
</div>window.dispatchEvent(new Event('cart:updated'));See where render time goes
Add ?blockstudio-perf to any frontend URL and a panel lists per-block render times, call counts, and the transform, template, and component phases. The same timings go out as Server-Timing headers, which still work when a CDN caches the HTML.
Only logged-in users with edit_posts see the output, and every other request switches the profiler off at init. performance.measurement adds profile and config hash headers and a Performance_Measurement::snapshot() API.
{
"dev": {
"perf": true
},
"performance": {
"measurement": {
"enabled": true,
"headers": true,
"timings": true
}
}
}use Blockstudio\Performance_Measurement;
$snapshot = Performance_Measurement::snapshot();One switch for production defaults
performance.profile set to speed removes generator, emoji, feed, and discovery output from the head, drops oEmbed discovery, disables XML-RPC and pingbacks, removes generic core frontend assets, throttles Heartbeat outside editors, and prefetches same-origin links on hover or focus.
The default is compat, which changes nothing. Every child value overrides the profile, so you can keep one behavior while taking the rest.
{
"performance": {
"profile": "speed",
"preload": {
"links": "off"
}
}
}Images that keep their space
Theme images live outside the media library, so WordPress knows nothing about their size. bs_media_image() reads real dimensions from a generated assets/media.json and reserves the aspect ratio before the file loads.
Turn on performance.media.lazy and the real URL waits behind a correctly sized placeholder until the image nears the viewport.
<?php
echo bs_media_image([
'src' => 'assets/images/hero.webp',
'alt' => 'Hero',
'eager' => true,
]);{
"performance": {
"media": {
"lazy": true,
"skeleton": true,
"metadata": true,
"rootMargin": "300px"
}
}
}One cache directory
Every generated file lives under cache.path, keyed by a runtime identity.
Single-flight builds
One request builds a cold cache key. Others wait, reuse the last good payload, or get a 503 with Retry-After.
OPcache-friendly payloads
Small cache payloads are plain PHP arrays OPcache can reuse from shared memory. Larger ones stay compressed.
Render cache
A self-closing block tag with the same attributes renders once per request. Repeats come from memory.
Coalesced choice refresh
A burst of content writes, such as an import, becomes one refresh of cached populated field choices.
Multi-tenant caches
Filter cache/site_key for your own tenant boundary and cache/context for runtime variants of the same site.
Compiled assets in the cache
With assets.output set to cache, compiled assets leave the block tree, so it deploys from an immutable checkout.
Sharded builds
Static_Prerender_Batch_Renderer splits a build into stable N/TOTAL shards, and a caller can compute the same partition.
Inline small stylesheets
assets.inlineLimit prints the smallest block stylesheets inline within a byte budget, in the same cascade order.
Block CSS last in the head
Block CSS is added right before the closing head tag, after the theme and plugin stylesheets.
Skip unused assets
A template that returns nothing enqueues no assets. assets.enqueue false hands every asset to you.
Cache commands
wp bs cache status, cleanup, and clear inspect, drain, and purge the runtime cache. wp bs prerender purge drops stored pages.
Clean teardown
wp bs teardown removes only the state this install owns.
Outcome hooks
cache/outcome and static_prerender/outcome report hits, builds, misses, and failures to your metrics.
Error hooks
error/logged and error/exception forward Blockstudio errors to an external logger or tracker.
Batch rendering
Batch_Render::reset() clears request state between documents in one process. render/dependencies lists each block’s files.
The official extension kit
Premium site templates, AI system instructions, and a private Discord community. One-time purchase, lifetime updates.
- 500+ site templates
- AI system instructions
- Lifetime updates
- Private Discord community