-
Notifications
You must be signed in to change notification settings - Fork 4.5k
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-block
orblock/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. 😢