Skip to content

Improve Documentation for Block Registration: namespace in Block Name #71022

@acketon

Description

@acketon

What problem does this address?

The documentation on Block Registration only lightly touches on the namespace:
https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/#block-name

Choosing a namespace when starting with block development is very important and it's not clear from the documentation that this cannot be changed later and must be thoughtfully named. This documentation should be expanded or link to another page with more examples, and clear documentation showing the consequences of using the wrong namespaces.

For instance there are a lot of create-block/some-block named blocks across Github. https://github.com/search?q=%22create-block%2F&type=code

What is your proposed solution?

  • Add clarification that block namespaces cannot be changed later so must be carefully selected. The block name is part of the HTML comment and is stored in the post content of the posts using that block so it cannot be changed without editing each post or using scripts to find/replace the name in all posts across a site or multi-site network.
  • That in most cases all blocks in a plugin or theme should share a namespace. To be cautious about sharing namespaces across multiple plugins or themes unless that is intended.
  • That namespaces should be unique across any themes/plugins that are added later so avoid generic names like editorial/some-block or block/some-block-name.
  • Additionally that registerBlockCollection() only supports a single namespace.

How do I know this is an issue?

Got burned as an early adopter and building lots of blocks used in thousands of posts across a large multi-site, multi-network environment and am now dealing with the consequences of not understanding how important and immutable the block name is. 😢

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions