BASIC

Block JSON

The block.json file is the technical configuration file that WordPress uses to register and understand your block. It contains all the metadata and settings that define how your block works in Gutenberg.

You Don’t Edit It Directly

Unlike other sections (Content, Style, View), there is no tab for editing block.json. This file is completely autogenerated by FanCoolo based on the settings you configure throughout the block editor.

What Gets Generated

FanCoolo automatically creates your block.json file from the settings you provide:

Block Information:

  • Title – The display name of your block
  • Description – What your block does
  • Icon – The icon shown in the block inserter
  • Category – Which category your block appears in

Block Attributes:

  • All fields you create in the Attributes Manager are automatically added to block.json
  • Field types, default values, and settings are all generated for you

File References:

  • Paths to your Content (render.php)
  • Paths to your Style and Editor Style CSS files
  • Path to your View JavaScript (viewScript or viewScriptModule)

Block Settings:

  • Support features you enable (alignment, spacing, etc.)
  • Default alignment – written as the default of the align attribute, so new blocks start wide, full, left, centered or right
  • Inner blocks configuration
  • Any other block-specific settings

Supports:

  • By default a block supports all alignments (left, center, right, wide, full) and an anchor, plus html and innerBlocks when it uses inner blocks, and interactivity when it has View JavaScript.
  • A block can store its own supports settings, which win over these defaults. For example, "align": ["wide", "full"] limits alignment to wide and full, and "anchor": false turns off anchor support.
  • Set them through Claude (MCP) or the FanCoolo API (settings.supports). A stored value is kept when a later save leaves it out.

Icon check:

  • A WordPress icon (wpi: name) that does not exist is rejected on save with the message Unknown WordPress icon "…", instead of saving an icon that would not show.
  • An icon a block already uses stays valid, so older blocks still save.

How It Works

When you save your block, FanCoolo:

  1. Takes all your settings from the editor interface
  2. Collects attributes from the Attributes Manager
  3. References all the files you’ve created (content, styles, view)
  4. Generates a properly formatted block.json file
  5. Saves it alongside your block files

This ensures your block.json is always:

  • Correctly formatted
  • In sync with your block settings
  • Following WordPress standards
  • Including all necessary configuration

Why Autogeneration?

Eliminates Errors:

  • No manual JSON syntax mistakes
  • No typos in property names
  • No missing required fields

Always in Sync:

  • When you add an attribute, it’s automatically in block.json
  • When you change settings, block.json updates
  • No need to manually keep files synchronized

Follows Best Practices:

  • Uses WordPress block standards
  • Correct property naming
  • Proper file path references

What You Control

Instead of editing JSON directly, you control block.json through:

  • Block Settings Panel – Title, description, icon, category, default alignment
  • Attributes Manager – All your custom fields
  • Block Configuration – Support features, inner blocks, etc.
  • Content/Style/View Sections – FanCoolo links these files automatically