Directory Structure Best Practices

Organizing your Gutenberg block codebase is essential for maintainability and scalability. A well-structured folder layout makes it easier to locate files, manage dependencies, and collaborate with other developers.

Blocks

Separate blocks into individual folders, each containing the block’s JavaScript, and CSS files. This isolation ensures that each block is self-contained and can be easily reused or extended.

Example:

  /assets/src/blocks/

    ├── block-name/

    │   ├── block.json

    │   ├── edit.js

    │   ├── index.js

    │   ├── save.js

    │   ├── editor.scss

    │   ├── style.scss

    |   ├── variations.js

    |   ├── view.js

    |   ├── styles/

    |   |   ├── style.scss

    |   |   ├── variations/

    |   |       ├── variation-name.scss

    |   ├── components/

Block Styles

here’s a structure for core/blocks & custom/blocks.

Core Blocks

• Define core block styles in the theme: /themes/theme-name/inc/classes/block-styles

• CSS files should reside in: /themes/theme-name/assets/src/css/blocks/

• Example: For a block named core/paragraph, name the CSS file paragraph.scss and place it in the blocks/core/ directory.

Custom Blocks

• Custom block styles must be defined within the block’s block.json file, and the CSS should reside in the block’s styles folder.

• Example: /plugins/plugin-name/assets/src/blocks/button/styles/

Block Variations

here’s the structure for core/block-variations & custom/block-variations.

Core Blocks

• Define core block variations in the plugin: ../plugins/plugin-name/assets/src/block-variation/

Custom Blocks

• Create variations in variations.js within the block folder.

• Example: ../plugins/plugin-name/assets/src/blocks/testimonial-block/variations.js

Block Extensions

To extend blocks:

• Place JavaScript in ../plugins/plugin-name/assets/src/block-extension/

• Place PHP for extensions in ../plugins/plugin-name/inc/classes/block-extensions/