ACF Block Generator

This package provides a command-line tool to scaffold an ACF block quickly with modern block.json conventions.

It creates a directory with your block slug and generates:

• A PHP render template
• A CSS file
• A block.json file

The generated block is fixed to v2:

• WordPress Block API version 2
• ACF block version 2
• ACF mode set to edit

Installation

You can install this tool either globally or locally depending on your needs:

Globally

For global installation, use the following command:

npm install -g acf-block-generator

This will install acf-block-generator globally, allowing you to use it in any project.

Locally

For local installation within your project, use:

npm install acf-block-generator --save-dev

This will install acf-block-generator as a development dependency in your project.

Usage

After installation, you can generate an ACF block by running:

Globally

If installed globally, directly use:

create-acf-block "Your Block Name"

Locally

If installed locally, use npx to run the command:

npx create-acf-block "Your Block Name"

In both cases, replace "Your Block Name" with the desired name for your block.

Template Options

Both template types are intentionally barebones and include no example get_field() calls.

To generate a block with the advanced template structure:

npx create-acf-block "Your Block Name" advanced

To generate in default mode explicitly:

npx create-acf-block "Your Block Name" default

CLI Options

Use any of the options below after the block name and template type:

• --category=<value> Block category (default: orchard)
• --icon=<value> Dashicon slug (default: cover-image)
• --post-types=<csv> Restrict block to post types, example: post,page
• --description=<text> Block description
• --keywords=<csv> Extra keywords, example: hero,banner
• --output-dir=<path> Output base directory (default: current working directory)
• --overwrite Replace files if they already exist
• --help Show usage

Examples

# v2 default scaffold
npx create-acf-block "Hero Banner" advanced --category=design

# post type restrictions
npx create-acf-block "Feature Grid" default --post-types=page,post

Features

• Generates a PHP template with:
  • WordPress wrapper attribute support for frontend output
  • Preview-safe output in editor context
  • anchor/class/align handling
  • no example ACF fields or values
• Creates a CSS file with no default style rules.
• Produces a block.json with:
  • $schema
  • apiVersion: 2
  • ACF blockVersion: 2
  • ACF mode: edit
  • supports defaults (anchor, align, spacing)
• Adds keyword defaults from your block name and merges any custom keywords.
• Uses slug-safe folder and file naming.

Output

Upon successful execution, the tool will create a directory named after the block (in hyphenated form). Inside this directory, you'll find:

• [block-name].php: The PHP template for the block.
• [block-name].css: The CSS file for block styling.
• block.json: The JSON configuration file for the block.

License

This project is licensed under the MIT License - see the License file for details.