Skip to content

AI-native block development

Files and no build step, which is what agents are good at.

A silent screen recording: a coding agent builds a complete WordPress site with 10 custom blocks and 6 pages from a single prompt.

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

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

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

blockstudio.json
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "phpstan": { "preset": "extreme-theme" },
  "githooks": { "commit": true }
}

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.

inspect.php
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']);

Less 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

About 135 tokens
index.php
<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

About 310 tokens
post_content
<!-- 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.

Claude Code
Codex CLI
Gemini CLI
Cursor
Windsurf
Amp

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.

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