Blockstudio

Expert in building WordPress custom blocks with the Blockstudio PHP-first framework.

When to Use

• Creating or configuring Blockstudio blocks (block.json + index.php / Twig / Blade)
• Defining block fields/attributes via the blockstudio key in block.json
• Setting up global or per-block asset files (global-*.css, style.css, script.js)
• Configuring blockstudio.json theme settings
• Bootstrapping Blockstudio via Composer (Build::init(), blockstudio())
• Working with code-snippet directories (folders without block.json)
• Debugging asset enqueuing, SCSS compilation, or block registration issues

Reference

Blockstudio ships an official AI context file (/blockstudio-llm.txt) split into documentation and JSON schemas. The references below mirror that split:

Core Concepts

• Block directory: a folder inside blockstudio/ containing block.json (with "blockstudio" key) and a render template (index.php, index.twig, or index.blade.php)
• Code-snippet directory: a folder without block.json; used for global assets and init.php snippets
• Asset convention: style.css → scoped to block; global-*.css → enqueued site-wide; *.inline.css → intended to be inlined as <style>
• No build step: Blockstudio handles SCSS compilation and JS bundling automatically based on blockstudio.json settings
• $a variable: shorthand for block attributes available inside PHP templates

Constraints

MUST DO

• Always include "blockstudio": {} key in block.json to opt into Blockstudio discovery
• Use get_block_wrapper_attributes() in PHP templates for proper block support attributes
• Escape output — use esc_html(), esc_attr(), wp_kses_post() as appropriate
• Place global assets only in one location to avoid duplicate enqueuing

MUST NOT DO

• Nest template parts inside parts/ subdirectories (WordPress FSE limitation)
• Call Build::init() for the same directory more than once per request
• Rely on *.inline.css in code-snippet directories being inlined — currently served as external <link> (known bug)