Gutenberg Code Standards

Gutenberg is based in React, Javascript, and PHP and should follow those but have a few differences or nuances that we should be aware of.

PHP

PMC's default coding standards are used for all PHP files in this plugin. More on that here.

React & Javascript

For React and JavaScript, we've adopted the @wordpress/eslint-plugin and its coding standards. More on that here.

Goots™/Block Editor

Additionally we're following best practices for WordPress documentation and organization defined by the Gutenberg Repo (opens in a new tab).

General Architecture and Standards

Our architectural decisions for PMC Gutenberg are outlined in detail in the Gutenberg Engineering Design Doc. A few primary standards:

• We only use dynamic, server-side rendered blocks.
• Block-editor-related code is never contributed to a theme - everything lives in PMC Plugins.
• Brand-specific customizations are handled with configuration added to the PMC Gutenberg plugin configuration class.
• Every block must have a snapshot test - this includes even core blocks that are used with no customizations (see this guide).
• The view of the blocks on the front-end of a site is built with core Larva modules (see this guide).
• We use functional components with React hooks, not class-based components and lifecycle methods. Details here
• There is an npm script for scaffolding a block in the PMC Gutenberg that will create block files according to our standards. Additionally, we use the wp-scripts ESLint and prettier formatting to ensure consistency.

Programmatic state updates & undo history

Sometimes, a block will programmatically change state, such as when a story block's configuration changes and related attributes are updated as blocks load. When this happens, it can prevent a user from undoing block insertion by creating an infinite loop of state changes that are re-applied each time the undo feature is triggered. Gutenberg provides a function that should be called before such an update is made, which ensures that the undo functionality behaves as expected.

The following is an abridged example:

import { useDispatch } from '@wordpress/data';
 
const { __unstableMarkNextChangeAsNotPersistent } = useDispatch(
	'core/block-editor'
);
 
__unstableMarkNextChangeAsNotPersistent();
setAttributes( { example: true } );

See the story block's edit.js for a complete implementation.

Props to talldan's PR (opens in a new tab) for highlighting how to address this situation.