Skip to main content

​
Design Principles

The story editor’s architecture follows these core design principles:

Whitelabel

Written from scratch as a modern React codebase with only thin layers (usually REST endpoints) connecting to WordPress. This design makes it possible to quickly port the editor to other CMS platforms.

Touch-Friendly

Uses universal pointer events, touch-friendly tap targets, and alternatives for hover UI to work across touch screens, touch pads, and mouse input.

Responsive

Adapts to small and very large screen sizes, from iPad to 6K monitors. The editor doesn’t expect to run full screen.

Extensible

Ships with the minimum viable set of media controls, document-level settings, and analytics. Provides integration points to extend functionality.

Accessible

Clear goal to provide an excellent experience to the broadest user base possible, including keyboard and screen-reader users.

Performant

Performance is a hard requirement. All user actions must have a visual response in less than 100ms. Continuous animations update at 60fps (30fps as fallback).

​
Project Structure

The Web Stories plugin follows a monorepo architecture using npm workspaces.

​
Root Structure

web-stories-wp/
├── assets/              # Compiled JavaScript and CSS assets
├── bin/                 # Build and development scripts
│   └── local-env/      # Docker local environment setup
├── includes/           # PHP source code
├── packages/           # JavaScript packages (monorepo)
├── tests/              # Test configurations
├── web-stories.php     # Main plugin file
├── package.json        # Root package configuration
└── composer.json       # PHP dependencies

​
PHP Architecture

PHP code is organized in the includes/ directory: 
includes/
├── AMP/                # AMP-related functionality
├── Admin/              # WordPress admin integration
├── Block/              # Gutenberg block implementation
├── Exception/          # Custom exception classes
├── Integrations/       # Third-party integrations
├── REST_API/           # REST API endpoints
├── Assets.php          # Asset management
├── Analytics.php       # Analytics integration
├── Discovery.php       # Story discovery features
├── Story_Post_Type.php # Custom post type definition
└── ...
Key PHP Components:
  • Story_Post_Type.php - Registers the custom post type for stories
  • Assets.php - Manages plugin assets (JS/CSS) and enqueuing
  • REST_API/ - Custom REST endpoints for editor and dashboard
  • AMP/ - AMP validation and optimization
  • Integrations/ - Third-party service integrations (Analytics, Ads)

​
JavaScript Architecture

The JavaScript codebase uses a monorepo structure with packages in packages/: 
packages/
├── story-editor/        # Main story editor React application
├── dashboard/           # Stories dashboard React application
├── design-system/       # Shared UI component library
├── element-library/     # Pre-built story elements
├── elements/            # Core story element components
├── animation/           # Animation utilities and engine
├── media/               # Media upload and processing
├── output/              # Story rendering/output
├── patterns/            # Story patterns and templates
├── templates/           # Story templates
├── text-sets/           # Pre-designed text combinations
├── fonts/               # Font management
├── tracking/            # Analytics tracking
├── e2e-tests/           # End-to-end tests
├── e2e-test-utils/      # E2E testing utilities
└── ...

​
Core JavaScript Packages

Location: packages/story-editor/The main story editor React application. Contains:
  • Canvas rendering engine
  • Element manipulation tools
  • Timeline and animation controls
  • Property panels and inspectors
  • Media library integration
Entry point: Built and loaded via WordPress asset system
Location: packages/dashboard/Stories management dashboard React application. Features:
  • Story list and grid views
  • Template browser
  • Story creation wizard
  • Bulk operations
  • Search and filtering
Location: packages/design-system/Shared UI component library used across editor and dashboard:
  • Buttons, inputs, dropdowns
  • Modal dialogs
  • Tooltips and popovers
  • Theme system
  • Icons and typography
Location: packages/elements/Core story element components:
  • Text elements with rich formatting
  • Image and video elements
  • Shape elements
  • GIF support
  • Element behaviors and interactions
Location: packages/animation/Animation engine and utilities:
  • Animation definitions
  • Keyframe management
  • Timeline integration
  • Effect presets
Location: packages/media/Media handling utilities:
  • Upload management
  • Image optimization
  • Video processing
  • Video transcoding integration
  • Media library integration
Location: packages/output/Story rendering and output generation:
  • AMP HTML generation
  • Story markup rendering
  • SEO optimization
  • Performance optimization

​
Build System

The project uses Webpack 5 for bundling JavaScript:
  • webpack.config.cjs - Main Webpack configuration
  • Multiple entry points for editor, dashboard, and other components
  • Code splitting for optimal loading
  • Production and development builds
  • React Fast Refresh support in development

​
Build Scripts

{
  "build:js": "Production build",
  "dev": "Development build with watch mode",
  "serve": "Development server with Fast Refresh"
}
See package.json:198-208 for complete build script definitions.

​
REST API

The plugin provides custom REST API endpoints for the editor and dashboard: Base namespace: /web-stories/v1/ Key endpoints:
  • /web-stories/v1/web-story - Story CRUD operations
  • /web-stories/v1/media - Media upload and management
  • /web-stories/v1/fonts - Font management
  • /web-stories/v1/settings - Plugin settings
  • /web-stories/v1/templates - Story templates
Endpoints are defined in includes/REST_API/.

​
Data Flow

1

User Interaction

User interacts with the React-based story editor in the browser
2

State Management

Editor state is managed using React Context and reducers
3

API Communication

Changes are saved via WordPress REST API endpoints
4

PHP Processing

PHP backend processes requests, validates data, and stores in WordPress database
5

Story Rendering

Stories are rendered as AMP-valid HTML on the frontend

​
Testing Architecture

The project includes multiple test suites:
  • PHP Unit Tests - PHPUnit tests in tests/phpunit/
  • JavaScript Unit Tests - Jest tests alongside source code
  • Integration Tests - Karma/Jasmine tests in packages/*/karma/
  • E2E Tests - Puppeteer tests in packages/e2e-tests/
See Testing Guide for details.

​
Browser Support

The editor supports modern browsers:
  • Chrome (latest 2 versions)
  • Firefox (latest 2 versions)
  • Safari (latest 2 versions)
  • Edge (Chromium-based)
For detailed browser support information, see docs/browser-support.md in the source.

​
Canvas Layering

The story editor uses a sophisticated canvas layering system for element rendering and manipulation. See docs/canvas.md in the source repository for detailed documentation.

​
Next Steps

Testing

Learn how to run and write tests

Contributing

Start contributing to the project

Build docs developers (and LLMs) love

Get started for freeTalk to us