bluecadet-create-block

CLI scaffolding tool for Gutenberg blocks in Bluecadet WordPress projects.

Usage

Run from the root of a WordPress project:

npx @bluecadet/bluecadet-create-block

Or with the short alias:

npx bcb

First run — setup wizard

If no config file is found, the CLI runs a one-time setup wizard that asks for your project paths and saves a .bluecadet-create-block.js file to the project root.

Re-run the wizard at any time to update the config:

npx @bluecadet/bluecadet-create-block --config

Config file

The config file lives at .bluecadet-create-block.js in the project root and uses a defineConfig helper:

import { defineConfig } from '@bluecadet/bluecadet-create-block';

export default defineConfig({
  theme_path: './wp-content/themes/my-theme',
  blocks_path: './wp-content/themes/my-theme/editor/blocks/src',
  block_namespace: 'basecadet',
  acf_render_callback: '\\Basecadet\\Gutenberg\\ACFBlocksRenderer::render_acf_blocks',
  custom_render_callback: 'Basecadet\\Gutenberg\\BasecadetBlocksRenderer::render_basecadet_blocks($attributes, $content, $block);',
});

All paths are relative to the project root (where the config file lives).

| Key | Description | |---|---| | theme_path | Path to the WordPress theme | | blocks_path | Path to the blocks src directory | | block_namespace | WordPress block namespace prefix (default: basecadet) | | acf_render_callback | PHP render callback for ACF blocks | | custom_render_callback | PHP render callback for Custom blocks |

What gets created

DataComponent (always)

A PHP class at [theme_path]/lib/Basecadet/Twig/Data/Components/[BlockName].php extending AbstractComponentBuilder.

ACF Block

Directory: [blocks_path]/acf-[block-name]/

• block.json — registered as [block_namespace]/acf-[block-name]

Custom Block

Directory: [blocks_path]/custom-[block-name]/

• block.json — registered as [block_namespace]/custom-[block-name]
• index.js
• edit.js
• render.php

BlockConfig.php integration

The CLI reads [theme_path]/lib/Basecadet/Gutenberg/BlockConfig.php (required) and offers to add the new block to the allowed_blocks array for one or more post types defined in BLOCK_LAYOUT_MAP.

After selecting a post type, if it has template sub-keys (e.g. default, home) you'll be asked which templates to add the block to. Post types with a flat allowed_blocks array are updated directly.

BlockConfig.php is validated with php -l after modification and restored to its original state if validation fails.

Block name variants

The input name is normalized to several forms used across generated files:

| Form | Example | |---|---| | PascalCase | SomeBlock — PHP class name, filename | | kebab-case | some-block — directory names, block name field | | Title Case | Some Block — block title and description |