AI-native block development
Files and no build step, which is what agents are good at.
Describe a block, get a block
AI coding agents can scaffold blocks, pages, and patterns from one prompt. No GUI and no database, just files.
~/starter-theme
❯ Create a pricing block with three tiers, a monthly/annual toggle, and a CTA for each tier.
✓ Created pricing/block.json
✓ Created pricing/index.php
✓ Created pricing/style.css
❯ Now create a pricing page with a hero and FAQ section.
✓ Created pages/pricing/page.json
✓ Created pages/pricing/index.php
Files
blockstudio/
├── pricing/ New
├── block.json
├── index.php
└── style.css
pages/
├── pricing/ New
├── page.json
└── index.php
File-based everything
Blocks, pages, patterns, and extensions are directories with JSON config and templates. Agents read and write them natively.
Zero database config
No admin panels to click through. Every setting is a JSON key, so an agent can scaffold the library without a browser.
Predictable structure
Every block follows the same convention: block.json, a template, and optional styles. Learn the pattern once.
Context, not guesswork
A compact index of the documentation, plus the full text for tools that want all of it.
An index the agent reads first
blockstudio-llm.txt lists every document once, with its route, source file, purpose, and the settings, hooks, PHP functions, and CLI commands it owns. At about 11k tokens an agent reads it whole, then opens only the page it needs.
blockstudio-llm-full.txt carries every document and JSON schema in one file, about 169k tokens, for tools that want the whole corpus. Turn on ai.enableContextGeneration and your site serves both.
# Blockstudio documentation index
This is the primary context file for coding assistants. It is an index, not
the documentation itself. Each entry names one document, what it is for, and
the identifiers that document owns. Read this index, then open only the
document you need.
Every document is addressable two ways: as a URL on https://blockstudio.dev,
and as a Markdown file in the Blockstudio repository. The full text of every
document and schema is also available in one file at /blockstudio-llm-full.txt
for tools that want everything at once.A contract for your project
The documentation describes Blockstudio. AGENTS.md describes the project the agent is about to change.
One command writes AGENTS.md
vendor/bin/blockstudio-agents describes the project it runs in: what it contains, which features blockstudio.json enables, what analysis will reject, and the commands that apply.
Every line comes from your files, your settings, or the selected analysis preset. Regenerating keeps the notes you wrote by hand, and --check fails when the contract is stale.
# Blockstudio contract for Acme
## Project
- Kind: WordPress theme `Acme`.
- Configuration: `blockstudio.json`.
- Analysis preset: `extreme-theme`.
## What this project contains
- Blocks: 1 in `blockstudio`.
- Pages: 1 in `pages`.
- Block namespaces: `acme`.
- Block templates are written in PHP.# Write or refresh the contract
vendor/bin/blockstudio-agents
# Fail CI when it no longer matches the project
vendor/bin/blockstudio-agents --checkMistakes caught before commit
Four analysis presets, each a superset of the last, and a hook that runs them on every commit.
Analysis that knows block.json
The blockstudio/phpstan presets read your blocks, pages, and settings. A template that reads a field its block.json never declared, or echoes it unescaped, fails analysis.
Templates read a $a typed from the block.json beside them, with a concrete PHP type for every field type, and Db::get() returns records shaped by db.php. A misspelled settings path or hook name fails with the closest real name suggested.
Set githooks.commit and run vendor/bin/blockstudio-githooks sync: the managed pre-commit hook runs the same analysis, so a broken block never reaches a commit.
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"phpstan": { "preset": "extreme-theme" },
"githooks": { "commit": true }
}$ vendor/bin/blockstudio-githooks sync
$ vendor/bin/blockstudio-phpstan -- --no-progress
Line blockstudio/hero/index.php
3 Dynamic Blockstudio attributes must be escaped before output.
blockstudio.output.unescaped
3 Field "subtitle" does not exist in block.json (block: acme/hero).
blockstudio.fieldbase
Every $a key a template reads exists in block.json; hooks, settings paths, and block tags are real.
theme
Theme headers, declared assets, %selector% scoping, field defaults, and repeater bounds.
extreme-theme
PHPStan max, escaped output, no shelling out, valid Tailwind classes, and clean JavaScript.
wordpress-render
Extreme theme plus a live WordPress render probe you supply. It runs without a shell, and a failed render becomes a finding.
Twig, Blade, and scripts
Twig, Blade, and block tags are checked against the same fields. The extreme layer also reads JavaScript and Interactivity directives against your markup and stores.
Existing projects
A PHPStan baseline holds back recorded findings while new code meets the full preset. blockstudioScanRoots reads block libraries outside the root, and shipped stubs type the public API.
Inventory and rendering from PHP
A few calls let an agent see what a project registers, render any part of it and check what it stored.
Ask the project, render the answer
Canvas::inventory() returns every page, block, pattern, Site Editor template, template part, and UI example a project registers, without rendering anything.
Render::document() renders any of them as a complete HTML document with exactly the assets it used, so an agent can check its work outside the editor.
Canvas::documents() renders exactly the records you select. Render::composition() and Render::content() return nested declarations or serialized block content as HTML, and Ui::inventory() and Ui::examples() list the bundled component families with one renderable declaration each.
For one block, bs_block_fields(), bs_block_extension_fields(), bs_block_values(), and bs_block_assets() return its fields, values, and assets without rendering it, and bs_validate_block() checks stored attributes before you save them.
use Blockstudio\Canvas;
use Blockstudio\Render;
$project = Canvas::inventory(['blocks' => true]);
foreach ($project['inventory']['blocks'] as $block) {
echo $block['name'] . "\n";
}
$doc = Render::document(
['name' => 'acme/hero', 'data' => ['heading' => 'Hello']],
['title' => 'Hero preview']
);
file_put_contents('hero.html', $doc['html']);$fields = bs_block_fields('acme/card');
$extended = bs_block_extension_fields('core/paragraph');
$assets = bs_block_assets('acme/card');
$block = parse_blocks($post->post_content)[0];
$a = bs_block_values($block['blockName'], $block['attrs']);
$findings = bs_validate_block($block['blockName'], $block['attrs']);$ wp bs blocks render
$ wp bs blocks render acme/card --attributes='{"variant":"wide"}'
$ wp bs blocks validate 42 57 --format=jsonLess than half the tokens per page
Agents write plain HTML. Blockstudio turns it into serialized WordPress block markup on sync: less to generate and less to get wrong.
Blockstudio
What agents write
<h1>Build Websites That Convert</h1>
<p>The all-in-one platform for creating
beautiful, high-performance landing pages.</p>
<block name="core/columns">
<block name="core/column">
<h3>Lightning Fast</h3>
<p>Pages load in under one second.</p>
</block>
<block name="core/column">
<h3>Easy to Use</h3>
<p>No technical skills required.</p>
</block>
<block name="core/column">
<h3>SEO Optimized</h3>
<p>Built-in best practices from day one.</p>
</block>
</block>
<img src="/dashboard.jpg" alt="Dashboard" />WordPress
What the parser writes for it
<!-- wp:heading {"level":1} -->
<h1 class="wp-block-heading">Build Websites That Convert</h1>
<!-- /wp:heading -->
<!-- wp:paragraph -->
<p>The all-in-one platform for creating
beautiful, high-performance landing pages.</p>
<!-- /wp:paragraph -->
<!-- wp:columns -->
<div class="wp-block-columns">
<!-- wp:column -->
<div class="wp-block-column">
<!-- wp:heading {"level":3} -->
<h3 class="wp-block-heading">Lightning Fast</h3>
<!-- /wp:heading -->
<!-- wp:paragraph -->
<p>Pages load in under one second.</p>
<!-- /wp:paragraph -->
</div>
<!-- /wp:column -->
<!-- wp:column -->
<div class="wp-block-column">
<!-- wp:heading {"level":3} -->
<h3 class="wp-block-heading">Easy to Use</h3>
<!-- /wp:heading -->
<!-- wp:paragraph -->
<p>No technical skills required.</p>
<!-- /wp:paragraph -->
</div>
<!-- /wp:column -->
<!-- wp:column -->
<div class="wp-block-column">
<!-- wp:heading {"level":3} -->
<h3 class="wp-block-heading">SEO Optimized</h3>
<!-- /wp:heading -->
<!-- wp:paragraph -->
<p>Built-in best practices from day one.</p>
<!-- /wp:paragraph -->
</div>
<!-- /wp:column -->
</div>
<!-- /wp:columns -->
<!-- wp:image {"alt":"Dashboard","url":"/dashboard.jpg"} -->
<figure class="wp-block-image"><img src="/dashboard.jpg" alt="Dashboard"/></figure>
<!-- /wp:image -->Measured on the two panels above: 540 characters of HTML against the 1,233 characters of block markup the stock parser writes for it, divided by four, the usual estimate of characters per token. The markup is shown with line breaks added for reading.
Less output to generate
Agents write HTML without block delimiters, generated classes, or wrapper markup.
Less to get wrong
The parser guarantees valid block output from the simpler input.
Faster and cheaper
Fewer output tokens mean faster responses and lower model costs.
Works with every AI coding tool
Any agent that can read and write files works with Blockstudio out of the box.
Built for the AI workflow
Blocks, pages, patterns, settings. Everything is a file an agent can read, write, and modify.
Two files per block
A JSON config and a template are the entire block. The small surface makes first-pass generation reliable.
27 field types
Text, files, repeaters, colors, dates, and more, defined in JSON. Selects populate from posts, terms, and users.
JSON Schema validation
Every config has a schema, which gives agents exact rules and catches mistakes immediately.
Auto-registration
Drop files into a directory and blocks register automatically, without another config list.
Canvas overview
Every managed page, or every block with its default values, in one zoomable view.
Live canvas
Live mode refreshes the affected artboards over Server-Sent Events about a second after a save. Click a label to focus one artboard.
Tailwind built-in
TailwindPHP compiles the classes each page uses, with no Node configuration.
Element Grabber
Copy an element’s template path and markup as instant context for an agent.
HTML to blocks
Pages and patterns are plain files that become native WordPress blocks.
Render smoke test
wp bs blocks render renders every block the way a page does and exits with 1 when a template raises a notice, warning, or error.
Stored content checks
wp bs blocks validate checks the saved fields of posts, and pages sync warns about attributes a block stores but never renders.
Inspect from the terminal
List settings, custom fields, and assets with wp bs, and compile a snippet or file with wp bs tailwind compile or wp bs scss compile.
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