Dennis · July 23, 2026
Blockstudio 7.5
Blockstudio 7.5 rounds out Blockstudio’s file-first workflow: custom field types, file-backed Site Editor templates, block islands, Storh database storage, logical discovery sources, composable block tags, and faster deployment and runtime paths.
Reusable custom fields already let projects define a group of existing fields
once and reuse it with type: "custom/{name}". Custom field types solve a
different problem. They let a theme or plugin register a new namespaced field
type, provide its own editor control, and store the value as normal
Blockstudio data.
The short version:
- Logical discovery sources: runtimes can supply a composed logical theme inventory, including provenance and cache identity, while Blockstudio keeps ownership of discovery, sibling resolution, generated assets, Canvas, and Tailwind behavior.
- PHP field type registry: themes and plugins can register namespaced field
types such as
acme/dimensionswithbs_register_field_type()or theblockstudio/field_typesfilter. - Editor control registry: custom editor scripts can call
window.blockstudio.registerFieldType()and render the matching React control in the normal Blockstudio field UI. - Structured values: custom fields can store strings, numbers, booleans, arrays, or objects without coercing object values through option field normalization.
- Storage support: post meta and option-backed custom fields can declare their value type and REST schema, including object and array values.
- Native integration: custom field types work inside groups, tabs, repeaters, reusable custom fields, templates, and extension template paths.
- Site Editor templates: themes can define
wp_templateandwp_template_partsources fromtemplate.json,part.json, and Blockstudio template files. - Block islands: blocks can render a cache-safe shell first, then hydrate or batch-fetch request-specific fragments after the page loads.
- Storh database storage:
bs.dbcan use an indexed file-per-record store in uploads, with public integer IDs preserved and JSONC-to-Storh migration through WP-CLI. - Parser and bsui refinements: mapped richtext paragraphs need less custom
parser glue,
InnerBlockscan use tokenizedallowedBlocks, nestedbs_render_block()output matches frontend rendering in editor previews, andbsui/buttongains icons plus easier styling hooks. - Composable block tags: prefix tags can resolve through another prefix
(
<theme-ui-input>tobsui/input), and prefix and alias tags render in block-template output, not only in page content. - Host-safe build caches: runtime and editor caches now default outside uploads, support configurable locations, and prune stale entries so long-running projects do not accumulate cache files.
- Incremental page reconciliation: deployment tools can reconcile the complete file-page inventory, skip unchanged posts, report exactly what changed, and persist a verified source identity after activation.
- Faster warm rendering: valid runtime caches hydrate before discovery, concurrent cold requests publish one atomic result, and Tailwind keeps a site-sized cache with reusable compiler state.
- Safe batch rendering: exporters can reset request-scoped render state between documents without rebuilding discovery and can collect source dependencies while blocks render.
New features
7.5 lands a broad set of new capabilities across discovery, templates, and storage.
Logical discovery sources
Blockstudio normally discovers files from physical theme directories. 7.5 adds a lower-level source API for runtimes that assemble a theme from overlays, previews, generated files, remote mounts, or other composed inventories.
An integration can provide a final logical file tree while Blockstudio keeps ownership of block, field, page, pattern, Site Editor, Canvas, asset, and Tailwind behavior:
use Blockstudio\Inventory_Discovery_Source;
add_filter(
'blockstudio/discovery/sources',
function (array $sources, string $context): array {
if ('blocks' !== $context) {
return $sources;
}
return [
new Inventory_Discovery_Source(
'preview:feature-card',
'/runtime-preview/feature-card/blockstudio',
[
'card/block.json' => [
'path' => '/theme/blockstudio/card/block.json',
'provenance' => ['layer' => 'parent'],
],
'card/index.php' => [
'path' => '/runtime-preview/feature-card/blockstudio/card/index.php',
'provenance' => ['layer' => 'preview'],
],
],
'preview-fingerprint'
),
];
},
10,
2
);
Logical paths remain stable even when sibling files come from different physical roots. Source IDs and fingerprints feed the runtime and Tailwind cache identities, watch inputs invalidate them, and provenance controls where generated files may be written. The default filesystem source is unchanged for normal themes.
File-backed Site Editor templates
Pages and patterns already let teams keep content structures in files. 7.5 extends that model to the Site Editor itself.
theme/
templates/
front-page/
template.json
index.php
parts/
header/
part.json
index.php
{
"slug": "front-page",
"title": "Front Page"
}
<div class="site-shell">
<block name="core/template-part" slug="header" />
<main>
<h1>Welcome</h1>
<block name="core/post-content" />
</main>
</div>
Blockstudio compiles the source through the same parser used by pages and patterns, then exposes the result to WordPress as a normal Site Editor template or template part. The Site Editor sees the template, the frontend can render it, and WordPress still owns customizations.
That last part matters. File-backed templates are the source fallback. If a user
saves a template in the Site Editor, WordPress creates the normal
wp_template or wp_template_part database customization and that version
wins. Reset the customization, and the latest file source is visible again.
Incremental page deployment
File-backed pages gained a deployment reconciliation API in 7.5. As of 7.6.2,
that explicit API and wp bs pages sync are the only synchronization entry
points; ordinary requests never apply source changes:
$report = Blockstudio\Pages::reconcile([
'authoritative' => true,
'plan_valid' => true,
'source' => [
'commit' => $commit,
'dirtyHash' => $dirtyHash,
],
]);
The pass discovers the complete desired page inventory, compares content and sync-engine fingerprints, and reports created, updated, unchanged, removed, and failed pages. Pages with equal fingerprints perform no post or postmeta writes. Missing managed pages are only pruned after discovery completes without errors.
Reconciliation returns a deterministic source identity but does not mark a deployment successful. Deployment tooling stores that identity only after the matching files and routes are active and verified. Ordinary WP-CLI bootstrap registers cached collection post types and rewrites without discovering and syncing every page.
Block islands
Most Blockstudio blocks are server-rendered. That is a good fit for WordPress, but it creates a familiar caching problem: one personalized block can make the whole page hard to cache.
Block islands split that boundary at the block level.
{
"name": "acme/cart-count",
"blockstudio": {
"island": "dynamic"
}
}
A dynamic island renders only a cache-safe placeholder in the first response. The browser then sends one batched request for all ready dynamic islands on the page, and Blockstudio renders those fragments in the visitor’s real request context.
That means a full page cache can store the page shell while the cart count, account controls, permission-gated UI, or other per-user pieces still stay fresh.
<div class="cart-count-placeholder">Loading cart...</div>
<div class="cart-count">
<?php echo esc_html(acme_cart_count()); ?>
</div>
For blocks that already render cache-safe HTML and only need a frontend mount signal, use a hydrated island:
{
"name": "acme/tabs",
"blockstudio": {
"island": "hydrate"
}
}
Hydrated islands do not make a REST request. They render normally and receive a
blockstudio:island:hydrate event on the frontend.
Dynamic islands also work through the programmatic render paths:
bs_render_block([
'name' => 'acme/cart-count',
'data' => ['productId' => 42],
]);
And through block tags:
<bs:acme-cart-count product-id="42" />
The endpoint is deliberately narrow. It only renders registered Blockstudio blocks that are dynamic and explicitly marked as dynamic islands. Attributes are filtered to the block schema and the island allow-list, and each marker carries a signature generated by the serving WordPress site.
Storh database storage
Blockstudio’s database layer already supports tables, SQLite, JSONC, post meta,
and custom post types. 7.5 adds storage: "storh" for projects that want a
file-backed store with safer concurrent writes and schema-derived indexes, but
do not want live records committed next to block source files.
return [
'storage' => 'storh',
'fields' => [
'title' => ['type' => 'string', 'required' => true],
'status' => ['type' => 'string'],
'count' => ['type' => 'integer'],
],
];
Storh records live in uploads:
wp-content/uploads/blockstudio/db/my-theme-my-block/default/
The public API stays unchanged. bs.db(), REST, and Db::get() still return
integer id values. Internally, Blockstudio maps those IDs to Storh’s UUIDv7
document IDs, so existing client code does not need to change.
Every declared schema field is indexed for equality filters, numeric and date-like fields get range indexes, and explicit unique hints are passed through. For projects that started with JSONC seed files, the new CLI migration keeps the source file in place and writes an equivalent Storh store:
wp bs db migrate my-theme/app subscribers --to=storh
That gives JSONC a clearer role as a simple, committable seed/config format, while Storh becomes the better default file backend for writable production data.
Parser and bsui refinements
7.5 also rounds off smaller pieces that tend to show up once a project leans harder on file-backed templates and bundled UI.
Element mapping can now handle the common richtext paragraph case without a
custom builder. If <p> maps to a registered non-core Blockstudio block with a
content richtext attribute, simple inner text is copied to that attribute.
Nested tags and mapped child elements still parse as inner blocks.
InnerBlocks accepts tokenized allowedBlocks in templates:
<InnerBlocks allowedBlocks="<?php echo esc_attr(wp_json_encode([
'core/paragraph',
'category:content',
'bsui/field',
])); ?>" />
Supported tokens are namespace/*, category:<slug>, and @theme. They are
expanded on the server before the editor receives the template, so the frontend
render path stays unchanged.
Programmatic embeds are also more predictable. bs_render_block() and
bs_block() now render embedded blocks as frontend-resolved HTML even when
called from inside another block’s editor preview. That means nested blocks do
not leak raw <RichText /> or <InnerBlocks /> pseudo-components into preview
markup.
For bundled UI, bsui/button now supports an icon attribute and
iconPosition. Bundled bsui/* inline styles are emitted in an @layer bsui
cascade layer, and button variants can be extended with
blockstudio/ui/button/variants-style plus the existing
blockstudio/blocks/attributes filter.
Block tags compose further, too. A prefix can resolve through another prefix, so
<theme-ui-input /> with a theme project prefix over a ui namespace prefix resolves
bsui/input. Registered prefix and alias tags now also render in block-template
output, not just page content, so a template can emit them directly instead of
calling bs_render_block().
Custom block builders registered through
blockstudio/block_tags/builders also participate in tag and mapped-element
parsing consistently. Explicit renderer filters still run afterward and can
override the builder.
Faster warm requests and exports
The runtime and editor caches now default to
wp-content/blockstudio/cache instead of uploads. The location can be changed
through cache.path or blockstudio/cache/dir, which keeps persistent caching
available on hosts that block PHP payloads under uploads. Runtime, editor asset,
and Tailwind caches also prune stale entries automatically, so long-running
projects no longer accumulate unbounded cache files on disk.
Warm frontend requests now hydrate a valid runtime registry before constructing discovery sources. That skips recursive source discovery, block construction, field parsing, and repeated cache-key tree walks. Production and staging requests trust a validated watch snapshot for 20 seconds by default, while local and development environments still check on every request.
Cold cache creation is single-flight. One request builds and atomically publishes the payload while concurrent requests wait for the completed result. Tailwind now retains up to 1,000 compiled entries for 30 days by default and reuses warm compiler construction state, so a site-sized route set no longer churns through a tiny cache.
Long-lived exporters can call Blockstudio\Batch_Render::reset() between
documents. This clears request-scoped counters, assets, islands, layouts, and
Tailwind generation without rebuilding discovery. The
blockstudio/render/dependencies filter exposes the template and asset paths
used by each rendered block for dependency graphs.
Reliability and compatibility
Several fixes complete the release:
- Field definitions changed through
blockstudio/blocks/attributesnow drive render-time option validation as well as the editor schema. Typed numeric and boolean option values also resolve consistently. - Editor block wrappers use the same generated classes as frontend renders,
and Canvas can copy the configured frontend body classes through the new
blockstudio/editor/canvas/body_classfilter. - Content Sync validates the complete source plan before destructive writes, keeps prune operations inside the configured content set, and reports file write failures without advancing that entity’s sync state.
- Composer packages bundled in symlinked active or parent themes resolve editor assets from the public theme URL.
- Keyed file pages preserve editor-owned Blockstudio field values, migrate the older nested key shape on sync, and accept numeric zero as a valid key.
- Dynamic islands verify signatures before request attribute filters, ignore unsigned request context, restore same-origin logged-in visitors, and avoid anonymous per-user cache collisions.
- Raw Markdown page endpoints now respect post visibility and password protection.
- Editor controls handle empty conditions, checkbox toggle-all values, async option refreshes, dynamic render ordering, and repeater RichText or WYSIWYG state more reliably.
Custom field types
More on the custom field types introduced above.
Why custom field types?
Blockstudio should stay useful out of the box, but real projects often have domain-specific controls: spacing token pickers, design-system color roles, responsive dimensions, icon sources, product selectors, or editorial controls that map to a structured value.
Before 7.5, those projects could either compose several built-in fields or fork the editor. 7.5 gives them a supported middle ground: Blockstudio owns the field lifecycle, and the project owns the control.
add_action('init', function () {
wp_register_script(
'acme-field-dimensions',
get_stylesheet_directory_uri() . '/fields/dimensions.js',
['blockstudio-blocks', 'wp-components', 'wp-element'],
'1.0.0',
true
);
bs_register_field_type('acme/dimensions', [
'attribute' => 'object',
'default' => [],
'editor_script' => 'acme-field-dimensions',
'storage' => [
'type' => 'object',
'rest_schema' => [
'type' => 'object',
'additionalProperties' => ['type' => 'string'],
],
],
]);
});
const { createElement: el } = wp.element;
const { TextControl } = wp.components;
window.blockstudio.registerFieldType('acme/dimensions', {
component(props) {
const value =
props.value &&
typeof props.value === 'object' &&
!Array.isArray(props.value)
? props.value
: {};
const sides = props.sides || ['top', 'right', 'bottom', 'left'];
return el(
'div',
{},
sides.map((side) =>
el(TextControl, {
key: side,
label: side,
value: value[side] || '',
onChange(nextValue) {
props.onChange({
...value,
[side]: nextValue,
});
},
}),
),
);
},
});
Then the field can be used in block.json like a native field:
{
"blockstudio": {
"attributes": [
{
"id": "margin",
"type": "acme/dimensions",
"label": "Margin",
"sides": ["top", "bottom"],
"default": {
"top": "md",
"bottom": "md"
}
}
]
}
}
Normal template values
The saved value is available in PHP, Twig, and Blade like any other Blockstudio attribute.
<div class="<?php echo esc_attr('mt-' . ($a['margin']['top'] ?? '')); ?>">
<?php echo esc_html($a['title'] ?? ''); ?>
</div>
The same object paths also work in extension templates:
{
"blockstudio": {
"extend": "core/group",
"attributes": [
{
"id": "margin",
"type": "acme/dimensions",
"set": [
{
"attribute": "class",
"value": "mt-{attributes.margin.top} mb-{attributes.margin.bottom}"
}
]
}
]
}
}
Compatibility notes
Existing built-in field types are unchanged. Existing custom/{name} reusable
field groups are unchanged too. Custom field type names must be lowercase and
namespaced, for example acme/dimensions; the custom/ and blockstudio/
namespaces stay reserved.
If PHP registers a field type but its editor script does not register the matching control, Blockstudio keeps the saved value and shows a non-editable notice in the editor. If a field type is not registered in PHP, Blockstudio leaves it out of generated WordPress attributes.
7.5.1 maintenance update
7.5.1 removes an array-to-string conversion warning emitted while preparing multiple select values for rendering. The saved and rendered values were already correct, but debug logs could receive one warning per field render.
The accompanying blockstudio/phpstan v0.1.7 update also recognizes fields
nested inside anonymous groups across PHP, Twig, Blade, and inferred template
attribute shapes. Existing projects can receive that package fix with
composer update blockstudio/phpstan.