# 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.

[Static prerendering](https://blockstudio.dev/docs/production/static-prerendering/)

blockstudio.json

```
{
  "performance": {
    "staticPrerender": {
      "enabled": true,
      "ttl": 3600,
      "earlyServe": true,
      "dynamicPaths": ["/account", "/checkout"]
    }
  }
}
```

## 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](https://blockstudio.dev/docs/blocks/hooks/php/#blockstudio-static_prerender-request_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](https://blockstudio.dev/docs/production/static-prerendering/#early-serving-and-atomic-deployment)

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.

[Early serving](https://blockstudio.dev/docs/production/static-prerendering/#early-serving-and-atomic-deployment)

Terminal

```
# 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 teardown
```

## Fresh 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.

[Signature and graph modes](https://blockstudio.dev/docs/production/static-prerendering/#signature-and-graph-modes)

deploy.php

```
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']));
```

## 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.

[CDN setup](https://blockstudio.dev/guides/static-prerendering/#putting-a-cdn-in-front)

nginx.conf

```
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;
}
```

## 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.

[Block islands](https://blockstudio.dev/docs/blocks/islands/)

block.json

```
{
  "name": "acme/cart-count",
  "title": "Cart count",
  "blockstudio": {
    "island": {
      "mode": "dynamic",
      "attributes": ["productId"],
      "loading": "visible",
      "event": "cart:updated",
      "cache": {
        "ttl": 60,
        "per": "user"
      }
    }
  }
}
```

## 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.

[Profiler](https://blockstudio.dev/docs/production/performance/#profiler)

blockstudio.json

```
{
  "dev": {
    "perf": true
  },
  "performance": {
    "measurement": {
      "enabled": true,
      "headers": true,
      "timings": true
    }
  }
}
```

## 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 profiles](https://blockstudio.dev/docs/production/performance/#performance-profiles)

blockstudio.json

```
{
  "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.

[Media](https://blockstudio.dev/docs/production/media/)

index.php

```
<?php
echo bs_media_image([
  'src' => 'assets/images/hero.webp',
  'alt' => 'Hero',
  'eager' => true,
]);
```

## [One cache directory](https://blockstudio.dev/docs/production/caching/)

Every generated file lives under cache.path, keyed by a runtime identity.

## [Single-flight builds](https://blockstudio.dev/docs/production/caching/#concurrency-and-retention)

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](https://blockstudio.dev/docs/production/performance/#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](https://blockstudio.dev/docs/general/settings/#assets)

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](https://blockstudio.dev/docs/blocks/assets/registering/#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](https://blockstudio.dev/docs/blocks/assets/registering/#load-order)

Block CSS is added right before the closing head tag, after the theme and plugin stylesheets.

## [Skip unused assets](https://blockstudio.dev/docs/blocks/assets/registering/#disable-enqueuing)

A template that returns nothing enqueues no assets. assets.enqueue false hands every asset to you.

## [Cache commands](https://blockstudio.dev/docs/dev/cli/)

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](https://blockstudio.dev/docs/blocks/hooks/php/#error-handling)

error/logged and error/exception forward Blockstudio errors to an external logger or tracker.

## [Batch rendering](https://blockstudio.dev/docs/production/performance/#in-process-batch-rendering)

Batch_Render::reset() clears request state between documents in one process. render/dependencies lists each block’s files.

Plus

## 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

[Get Plus](https://blockstudio.dev/plus/)
