Repository navigation
Improve Documentation for Block Registration: namespace in Block Name #71022
Description
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-blockorblock/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. 😢
Activity
Sahil1617 commentedon Aug 2, 2025
Hi @acketon, @mtias, and team 👋,
Thanks for raising this — I completely agree that namespace clarity in block registration is a critical but under-documented area, especially for newer developers starting with block development.
I'd like to contribute to improving this documentation and propose the following approach:
Proposed Approach:
If this sounds good, I can begin working on a documentation pull request. Please let me know if you’d prefer this content to be integrated into the current Block API guide or whether it should be a dedicated “naming best practices” page linked from there.
Looking forward to your feedback and happy to help improve the dev experience around block development. 🙌
acketon commentedon Aug 5, 2025
Thanks @Sahil1617, this looks great.