Conventions for examples

Specific conventions have been established for the examples in this repository to ensure the repository as a whole is scalable and maintainable. This guide details those conventions.

Example conventions

Important

Several examples in this repository use a to ensure uniqueness. This was once a requirement for all examples, but it is now optional to simplify the process of adding new examples.

General setup

• All examples are plugins and they are placed in the repository's plugins folder.
• The plugin folder name (<plugin-folder>) should be the <slug>. For example, my-example-plugin-64756b.

package.json

Start by ensuring the example's package.json file adheres to the following conventions.

• name: should follow the convention @block-development-examples/<slug>. For example, "name": "@block-development-examples/my-example-plugin-64756b".
• files: This property should be set to *. For example, "files": [ "*" ].
• scripts: It should have, at least, the following scripts defined:

        "scripts": {
            "build": "wp-scripts build",
            "plugin-zip": "wp-scripts plugin-zip",
            "start": "wp-scripts start"
        }

• devDependencies: It should have, at least, @wordpress/scripts as a dependency for development:

        "devDependencies": {
            "@wordpress/scripts": "^27.8.0"
        }

index.php (or main plugin file)

In the plugin header comment, the Plugin Name: value should follow the convention: Block Development Examples - <example-name> <unique-code>. For example, Plugin Name: Block Development Examples - My Example Plugin 64756b.

block.json

• name: This property should follow the convention block-development-examples/<slug>. Make sure the block registered at index.js uses the same name. For example:
  • block.json: "name": "block-development-examples/my-example-plugin-64756b"
  • index.js: registerBlockType( 'block-development-examples/my-example-plugin-64756b',...
• textdomain: If an example includes the textdomain property, it should be set to block-development-examples.

Block styles (CSS)

Block CSS classes should follow the convention .wp-block-block-development-examples-<slug>. For example, .wp-block-block-development-examples-my-example-plugin-64756b

Repository-specific conventions

Important

It's important to add any new example to _data/examples.json so it can also be added to the main table automatically through npm run table:update scripts and to the app at https://wordpress.github.io/block-development-examples/

After a new example has been added to the plugins folder, you need to ensure it works and displays properly in this repository.

• .wp-env.json: The local path of each example plugin (starting from root) should be included in the array "plugins" in the .wp-env.json file. For example, "./plugins/my-example-plugin-64756b".
• _data/example.json: Each example needs to be added to the example.json file in the _data folder. Examples are represented as objects with the following properties: slug, description, tags. The tags property should contain an array of tags from the available list in _data/tags.json. Here's an example:

{
    "slug": "my-example-plugin-64756b",
    "description": "My Example Block",
    "tags": [
      "minimal",
      "no-build"
    ]
  }

• README.md: After a new example is added, you need to add a new row with the plugin/example information. You can do so by running npm run table:update.

After ensuring all of these conventions have been applied, reinstall dependencies and generate a fresh build from the root of the project.

pnpm i
npm run build