Packages Overview

WordPress Gutenberg is organized as a monorepo containing multiple self-contained packages. These packages are published to npm and used by WordPress Core and other projects.

Monorepo Structure

The Gutenberg project uses npm workspaces and Lerna to manage its packages:

Location: All packages are in the /packages/ directory
Build System: Uses @wordpress/scripts for building and testing
Package Management: npm workspaces for dependency management
Publishing: Automated via Lerna synchronized with bi-weekly Gutenberg plugin releases

Package Guidelines

When working with Gutenberg packages, follow these principles:

Single, clear purpose - Each package should have one obvious responsibility
Complete documentation - Every package must include a README
Document prerequisites - State any API endpoints, authentication, or environment requirements
Public API documentation - All public APIs should have inline or linked documentation
Avoid utility packages - Don’t create catch-all packages without coherent domains
Specific scope - Define a specific domain instead of broad scopes like “utilities”

Package Types

WordPress Script Packages

Packages that expose to the wp global in WordPress:

{
  "name": "@wordpress/blocks",
  "wpScript": true
}

These packages are available in WordPress as wp.blocks, wp.data, etc.

Script Module Packages

Packages that expose as WordPress script modules:

{
  "wpScriptModuleExports": {
    ".": "./build-module/index.js"
  }
}

Dependency-Only Packages

Packages that don’t expose globally but are used as dependencies:

{
  "wpScript": false
}

Core Package Architecture

Three-Layer Editor Architecture

Gutenberg follows a strict layering principle:

Layer 1: Block Editor
Layer 2: Editor
Layer 3: Implementations

@wordpress/block-editor

Generic, WordPress-agnostic block editing
No knowledge of WordPress posts or REST API
Provides UI components and block manipulation
Version: 15.13.1

@wordpress/editor

WordPress post-type aware
Integrates with @wordpress/core-data
Handles post loading and saving
Version: 14.40.1

Lower layers MUST NOT depend on higher ones. For example, @wordpress/block-editor should never import from @wordpress/editor.

Key Packages

Data Management

@wordpress/data

Redux-like state management system for WordPressVersion: 10.40.0

@wordpress/core-data

Entity-based data access to WordPress REST API

Block System

@wordpress/blocks

Block registration, parsing, and serializationVersion: 15.13.0

@wordpress/block-editor

Generic block editor components and hooksVersion: 15.13.1

Editor Implementation

@wordpress/editor

Post-aware editor implementation with WordPress integrationVersion: 14.40.1

TypeScript Support

Many Gutenberg packages support TypeScript:

Type declarations are generated in build-types/ directory
Packages include "types": "build-types" in package.json
Use tsconfig.json to opt-in to TypeScript tooling

{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "rootDir": "src",
    "declarationDir": "build-types"
  }
}

Node.js and npm Requirements

All packages require:

Node.js: >= 18.12.0
npm: >= 8.19.2

These align with the Node.js Release Schedule to ensure Active LTS or Maintenance LTS support.

Installation

Install any Gutenberg package from npm:

npm install @wordpress/blocks --save
npm install @wordpress/block-editor --save
npm install @wordpress/editor --save
npm install @wordpress/data --save

Environment Requirements

All packages assume an ES2015+ environment. If you’re using an environment with limited ES2015 support, include the polyfill from @wordpress/babel-preset-default.

npm install @wordpress/babel-preset-default --save-dev

Side Effects

Packages declare side effects for tree-shaking optimization:

{
  "sideEffects": [
    "src/index.js",
    "src/store/index.js",
    "build-style/**"
  ]
}

This helps bundlers like webpack optimize the final bundle size.

Publishing Process

Packages are published to npm automatically:

Synchronized with bi-weekly Gutenberg plugin RC1 releases
Version bumps based on CHANGELOG.md entries
Follows semantic versioning
Pre-1.0 packages (0.x.x) can have breaking changes in minor versions

Package Dependencies

Packages use file: protocol for local dependencies during development:

{
  "dependencies": {
    "@wordpress/data": "file:../data",
    "@wordpress/blocks": "file:../blocks"
  }
}

These are resolved to proper version numbers when published to npm.

Development Workflow

Building Packages

# Build all packages
npm run build

# Development with watch
npm start

Testing Packages

# Run all tests
npm test

# Test specific package
npm run test:unit packages/blocks

Package Guidelines

Complete guidelines for creating and maintaining packages

Contributing Guide

How to contribute to Gutenberg packages

@wordpress/scripts

Build tooling for WordPress packages

Release Process

Package release and versioning process

Core Packages

UI Components

Editor Implementations

Developer Tools

Utilities

Packages Overview

Packages Overview

Monorepo Structure

Package Guidelines

Package Types

WordPress Script Packages

Script Module Packages

Dependency-Only Packages

Core Package Architecture

Three-Layer Editor Architecture

Key Packages

Data Management

@wordpress/data

@wordpress/core-data

Block System

@wordpress/blocks

@wordpress/block-editor

Editor Implementation

@wordpress/editor

TypeScript Support

Node.js and npm Requirements

Installation

Environment Requirements

Side Effects

Publishing Process

Package Dependencies

Development Workflow

Building Packages

Testing Packages

Package Guidelines

Contributing Guide

@wordpress/scripts

Release Process

​Packages Overview

​Monorepo Structure

​Package Guidelines

​Package Types

​WordPress Script Packages

​Script Module Packages

​Dependency-Only Packages

​Core Package Architecture

​Three-Layer Editor Architecture

​Key Packages

​Data Management

@wordpress/data

@wordpress/core-data

​Block System

@wordpress/blocks

@wordpress/block-editor

​Editor Implementation

@wordpress/editor

​TypeScript Support

​Node.js and npm Requirements

​Installation

​Environment Requirements

​Side Effects

​Publishing Process

​Package Dependencies

​Development Workflow

​Building Packages

​Testing Packages

​Related Resources

Package Guidelines

Contributing Guide

@wordpress/scripts

Release Process

Packages Overview

Monorepo Structure

Package Guidelines

Package Types

WordPress Script Packages

Script Module Packages

Dependency-Only Packages

Core Package Architecture

Three-Layer Editor Architecture

Key Packages

Data Management

Block System

Editor Implementation

TypeScript Support

Node.js and npm Requirements

Installation

Environment Requirements

Side Effects

Publishing Process

Package Dependencies

Development Workflow

Building Packages

Testing Packages

Related Resources