Coding Guidelines

This document outlines coding guidelines specific to the Gutenberg project. Base coding guidelines follow the WordPress Coding Standards.

JavaScript

Language Features

Gutenberg uses modern JavaScript (ECMAScript) and JSX syntax, enabled through @wordpress/babel-preset-default. Important: Only language features that have reached Stage 4 (“Finished”) in the TC39 proposal process are supported.

Import Organization

Organize imports with multi-line comments separating different types:

/**
 * External dependencies
 */
import moment from 'moment';
import clsx from 'clsx';

/**
 * WordPress dependencies
 */
import { __ } from '@wordpress/i18n';
import { useState } from '@wordpress/element';

/**
 * Internal dependencies
 */
import BlockToolbar from './block-toolbar';
import InspectorControls from './inspector-controls';

Import Types

External dependencies: Third-party packages from npm

import moment from 'moment';

WordPress dependencies: Packages from the @wordpress namespace

import { __ } from '@wordpress/i18n';

Internal dependencies: Relative imports within your package

import VisualEditor from '../visual-editor';

Strings

Use single quotes for string literals, unless the string contains a single quote:

// Good
const name = 'Matt';
const pet = 'Matt's dog';
const oddString = "She said 'This is odd.'";

// Bad
const name = "Matt";
const pet = "Matt's dog"; // Should use real apostrophe

Apostrophes: Use real apostrophes (') not single quotes (') in user-facing strings:

// Good (user-facing)
const message = 'It's working';

// OK (test code)
const testMsg = 'it's working';

Template literals: Prefer template strings over concatenation:

const name = 'Stacey';

// Good
alert(`My name is ${name}.`);

// Bad
alert('My name is ' + name + '.');

Objects

Use shorthand notation when possible:

const a = 10;

// Good
const object = {
  a,
  performAction() {
    // ...
  },
};

// Bad
const object = {
  a: a,
  performAction: function () {
    // ...
  },
};

Optional Chaining

Optional chaining can be convenient but has pitfalls: Avoid when negating:

// Problematic: returns true if nodeRef.current is null/undefined
const hasFocus = !nodeRef.current?.contains(document.activeElement);

// Better: explicit check
const hasFocus = nodeRef.current?.contains(document.activeElement) === true;

Be careful with boolean contexts:

// Problematic: may pass undefined instead of false
document.body.classList.toggle(
  'has-focus',
  nodeRef.current?.contains(document.activeElement)
);

// Better: ensure boolean value
document.body.classList.toggle(
  'has-focus',
  Boolean(nodeRef.current?.contains(document.activeElement))
);

React Components

Implement all components as function components using hooks:

import { useState } from '@wordpress/element';

function MyComponent({ title }) {
  const [isActive, setIsActive] = useState(false);

  return (
    <div>
      <h2>{title}</h2>
      <button onClick={() => setIsActive(!isActive)}>
        Toggle
      </button>
    </div>
  );
}

Exception: Class components are acceptable only for error boundaries.

CSS

Class Naming Convention

Follow a BEM-inspired naming convention: Format: package-directory__descriptor-foo-bar

Root element: package-directory
Child elements: package-directory__descriptor

Example:

// In packages/components/src/notice/index.js
export default function Notice({ children, onRemove }) {
  return (
    <div className="components-notice">
      <div className="components-notice__content">{children}</div>
      <Button className="components-notice__dismiss" onClick={onRemove} />
    </div>
  );
}

State Modifiers

Use modifier classes with is- prefix for state:

import clsx from 'clsx';

function Panel({ isOpen }) {
  const classes = clsx('components-panel', {
    'is-open': isOpen,
  });

  return <div className={classes}>...</div>;
}

In CSS:

.components-panel {
  /* base styles */
}

.components-panel.is-open {
  /* open state styles */
}

Component Isolation

A component’s class name should never be used outside its own folder (with rare exceptions).

Don’t inherit styles from other components
Render instances of other components instead
Duplicate styles if necessary to maintain isolation

SCSS File Naming for Blocks

style.scss: Loads on both frontend and editor

// Block styles that apply everywhere
.wp-block-gallery {
  display: flex;
}

editor.scss: Loads only in the editor

// Editor-specific styles
.wp-block-gallery {
  outline: 1px dashed #ccc;
}

TypeScript & JSDoc

Gutenberg uses TypeScript via JSDoc for type checking JavaScript files.

Custom Types

Define custom types with @typedef:

/**
 * A block selection object.
 *
 * @typedef WPBlockSelection
 *
 * @property {string} clientId     Block client ID.
 * @property {string} attributeKey Block attribute key.
 * @property {number} offset       Attribute value offset.
 */

Naming: Use WP prefix and descriptive names without redundant suffixes.

Type Unions

Define sets of options as union types:

/**
 * Named breakpoint sizes.
 *
 * @typedef {'huge'|'wide'|'large'|'medium'|'small'|'mobile'} WPBreakpoint
 */

Importing Types

Use TypeScript import syntax in JSDoc:

/** @typedef {import('@wordpress/data').WPDataRegistry} WPDataRegistry */

Generic Types

Always provide details for generic types:

// Bad
/** @type {Object} */
/** @type {Promise} */

// Good
/** @type {Record<string, number>} */
/** @type {{[key: string]: any}} */
/** @type {Promise<string>} */
/** @type {(key: string) => boolean} */

Documenting Components

Document component props using dot notation:

/**
 * Renders a block title.
 *
 * @param {Object} props
 * @param {string} props.clientId Client ID of block.
 *
 * @return {string|null} Block title.
 */
function BlockTitle({ clientId }) {
  // ...
}

Examples in Documentation

Include usage examples with code blocks:

/**
 * Selects a store.
 *
 * @param {string} name Store name.
 *
 * @example
 * ```js
 * select('my-shop').getPrice('hammer');
 * ```
 *
 * @return {Object} Store selectors.
 */

PHP

PHP_CodeSniffer

Gutenberg uses PHP_CodeSniffer with WordPress Coding Standards.

Running PHP Checks

# Check standards
npm run lint:php
# or
vendor/bin/phpcs

# Auto-fix issues
vendor/bin/phpcbf

# Specific file
vendor/bin/phpcs path/to/file.php
vendor/bin/phpcbf path/to/file.php

Installing Locally

# Install via Composer
composer install

# Run checks
composer lint

Private and Experimental APIs

Private APIs

Use the @wordpress/private-apis package for internal-only APIs:

// Opt-in to private APIs
import { __dangerousOptInToUnstableAPIsOnlyForCoreModules } from '@wordpress/private-apis';

export const { lock, unlock } = __dangerousOptInToUnstableAPIsOnlyForCoreModules(
  'I acknowledge private features are not for use in themes or plugins...',
  '@wordpress/my-package'
);

// Lock private functions
const privateFunction = () => {};
export const publicObject = {};
lock(publicObject, { privateFunction });

// Unlock in other packages
const { privateFunction } = unlock(publicObject);

Plugin-Only APIs

Export APIs only in the Gutenberg plugin:

if (globalThis.IS_GUTENBERG_PLUGIN) {
  export { experimentalFeature } from './api';
}

Legacy Experimental APIs

Avoid using __experimental or __unstable prefixes for new APIs. Use private APIs or plugin-only APIs instead.

Code Quality Tools

ESLint

JavaScript linting with ESLint:

npm run lint:js
npm run lint:js:fix

Prettier

Code formatting with Prettier:

npm run format

TypeScript

Type checking via TypeScript:

npm run build:packages

Next Steps

Review Testing Guide for testing conventions
Check Architectural Decisions for design patterns
See Common Pitfalls to avoid mistakes

Getting Involved

Development

JavaScript

Language Features

Import Organization

Import Types

Strings

Objects

Optional Chaining

React Components

CSS

Class Naming Convention

State Modifiers

Component Isolation

SCSS File Naming for Blocks

TypeScript & JSDoc

Custom Types

Type Unions

Importing Types

Generic Types

Documenting Components

Examples in Documentation

PHP

PHP_CodeSniffer

Running PHP Checks

Installing Locally

Private and Experimental APIs

Private APIs

Plugin-Only APIs

Legacy Experimental APIs

Code Quality Tools

ESLint

Prettier

TypeScript

Next Steps

​JavaScript

​Language Features

​Import Organization

​Import Types

​Strings

​Objects

​Optional Chaining

​React Components

​CSS

​Class Naming Convention

​State Modifiers

​Component Isolation

​SCSS File Naming for Blocks

​TypeScript & JSDoc

​Custom Types

​Type Unions

​Importing Types

​Generic Types

​Documenting Components

​Examples in Documentation

​PHP

​PHP_CodeSniffer

​Running PHP Checks

​Installing Locally

​Private and Experimental APIs

​Private APIs

​Plugin-Only APIs

​Legacy Experimental APIs

​Code Quality Tools

​ESLint

​Prettier

​TypeScript

​Next Steps

JavaScript

Language Features

Import Organization

Import Types

Strings

Objects

Optional Chaining

React Components

CSS

Class Naming Convention

State Modifiers

Component Isolation

SCSS File Naming for Blocks

TypeScript & JSDoc

Custom Types

Type Unions

Importing Types

Generic Types

Documenting Components

Examples in Documentation

PHP

PHP_CodeSniffer

Running PHP Checks

Installing Locally

Private and Experimental APIs

Private APIs

Plugin-Only APIs

Legacy Experimental APIs

Code Quality Tools

ESLint

Prettier

TypeScript

Next Steps