feat: Initial scaffold of Toolbar #432

josephfusco · 2025-10-08T14:49:17Z

Zero-build toolbar implementation for headless WordPress applications.

Package Structure

@wpengine/hwp-toolbar

Pure JavaScript implementation, no transpilation required
Framework-agnostic core with React adapter
WordPress context management (user session, post state, preview mode)

WordPress Plugins

hwp-cors-local – Local development CORS headers
hwp-frontend-links – Admin bar frontend routing
hwp-wp-env-helpers – Docker environment REST API patches

Implementation

Vanilla

import { Toolbar } from '@wpengine/hwp-toolbar';

const toolbar = new Toolbar({
  position: 'bottom',
  onPreviewChange: (enabled) => console.log('Preview:', enabled)
});

toolbar.setWordPressContext({
  user: { id: 1, name: 'Admin' },
  post: { id: 42, title: 'Hello World' }
});

React

import { useToolbar } from '@wpengine/hwp-toolbar/react';

function MyToolbar() {
  const { state, nodes } = useToolbar(toolbar);
  return <div>User: {state.user?.name}</div>;
}

Technical Details

Direct source consumption – No build pipeline, modules served as-is
Deterministic port assignment – Hash-based calculation prevents conflicts
Modular architecture – Core, renderer, and framework adapters decoupled
Composer integration – Reusable plugin distribution
Complete examples – Vanilla/Vite and React/Next.js 15 implementations

Running Examples

# Vanilla
cd examples/vanilla/toolbar-demo && npm run example:start  # localhost:3644

# Next.js
cd examples/next/toolbar-demo && npm run example:start     # localhost:3975

Fixes #427

changeset-bot · 2025-10-08T14:49:22Z

⚠️ No Changeset found

Latest commit: a5ada57

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

Integrate toolbar demo with real WordPress instance using wp-env: - Add CORS headers via mu-plugin for localhost:3000 - Fetch real WordPress user via REST API - Fetch posts using WPGraphQL - Update demo UI with real data workflow - Document WordPress integration in README Updates: - Use query parameter format for REST API (/?rest_route=) - Use query parameter format for GraphQL (/?graphql) - Add lifecycle script for permalink setup - Update demo instructions for real WordPress workflow

…base styles for full developer control

…tion Switch vanilla example from hardcoded configs to auto-generated approach. Files like mu-plugin.php, .htaccess, and .wp-env.json are now generated from centralized templates by the setup-env.js script. - Add setup-env.js script that generates configs from templates - Remove mu-plugin.php, .htaccess, .wp-env.json from version control - Update .gitignore to exclude auto-generated example files

Add comprehensive Next.js App Router example demonstrating the toolbar with real WordPress integration. - Complete Next.js example with App Router - Hash-based port calculation for deterministic ports - Template-based configuration (mu-plugin, .htaccess, .wp-env.json) - One-command startup with concurrently - Real WordPress data integration (no mocks) - WPGraphQL for post fetching - Responsive toolbar with real user data

Enhance toolbar with configurable options and example improvements: Toolbar Package: - Add position config (top/bottom) with CSS positioning - Add theme config with custom CSS variables and className - Add getConfig/setConfig methods for runtime updates - Improve CSS with position-aware dropdown menus Vanilla Example: - Use hash-based port calculation from setup-env.js - Load ports from generated .env file in Vite config - Update scripts to use template-based configuration - Add pnpm workspace configuration - Remove hardcoded mu-plugin.php (now generated)

Introduces three reusable, single-responsibility plugins for headless WordPress development: - hwp-cors-local: Enables CORS headers for local development environments - hwp-frontend-links: Adds "View on Frontend" links to WordPress admin interface - hwp-wp-env-helpers: Fixes wp-env REST API routing quirks Each plugin is independently configurable via HEADLESS_FRONTEND_URL constant and can be used standalone or in combination based on project needs.

… plugins Updates toolbar demo examples to use production-ready configuration: - WP_HOME points to WordPress instance (not frontend) - HEADLESS_FRONTEND_URL configured separately for frontend application - Replaces mu-plugin template approach with modular plugin references - Updates PHP version to 8.3 - Removes mu-plugin mapping in favor of standard plugin loading This allows WordPress to remain fully functional while supporting headless architecture, and enables composable plugin usage across different projects.

wp-env cannot resolve relative plugin paths from subdirectories. Changed setup-env.js to generate absolute paths using path.resolve() and path.join(), ensuring plugins load correctly in both vanilla and Next.js examples. Also added comprehensive implementation breakdown documentation.

Updated example:start scripts in both toolbar demos to use concurrently properly. WordPress and frontend now start together using concurrently, with a 5 second delay on frontend to ensure WordPress completes startup. Changes: - Separated wp-env setup (npm install) into wp:ensure script - Modified wp:start to only run wp-env start (no blocking npm install) - Used concurrently to run both services in parallel - Added sleep 5 before frontend start to allow wp-env initialization

… DRY - Remove mu-plugin.php template and generation code - Use relative paths for plugin references (portable across machines) - Simplify npm scripts (inline npm install, remove wp:ensure) - Add .gitignore files to exclude generated files - Align both toolbar examples with consistent configuration

Refactored plugin to support both single and multiple frontend configurations via HEADLESS_FRONTEND_URL or HWP_FRONTEND_LINKS. Admin bar and post row actions now display a 'View in [Label]' link for each configured frontend, improving flexibility for sites with multiple environments.

Copilot

Pull Request Overview

This PR introduces a comprehensive headless WordPress toolkit with a modular plugin architecture and production-ready toolbar package. It transforms the previous template-based approach into a maintainable, reusable system with dynamic configuration and comprehensive documentation.

Creates three single-responsibility WordPress plugins for CORS, frontend links, and wp-env helpers
Introduces the @wpengine/hwp-toolbar package with framework-agnostic design and React hooks
Updates examples to use the new plugin architecture with dynamic port calculation
Provides complete documentation and production-ready configuration patterns

Reviewed Changes

Copilot reviewed 44 out of 47 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/toolbar/*	Core toolbar package with TypeScript, React hooks, and vanilla renderer
plugins/*	Three modular WordPress plugins for headless development
examples//toolbar-demo/	Updated demo applications using new architecture
scripts/get-ports.js	Dynamic port calculation system for multi-example setup
IMPLEMENTATION_BREAKDOWN.md	Comprehensive implementation documentation

Comments suppressed due to low confidence (1)

plugins/hwp-wp-env-helpers/hwp-wp-env-helpers.php:1

Direct $_SERVER access should be validated. Consider using sanitize_text_field() or checking if the key exists before accessing.

<?php

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

packages/toolbar/src/index.ts

scripts/get-ports.js

examples/next/toolbar-demo/example-app/lib/wordpress.ts

josephfusco · 2025-10-09T14:23:20Z

@ahuseyn I'm working on resolving these last build issues but i'll mark it ready for review now :)

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

github-actions · 2025-10-09T15:42:44Z

📦 Plugin Artifacts Ready!

Download from GitHub Actions run

Available plugins:

✅ hwp-cli.zip

See the "Artifacts" section at the bottom of the Actions run page

Eliminate TypeScript compilation requirement and convert to vanilla JS following the CLI package pattern. Changes: - Convert src/index.ts → src/core/Toolbar.js (with JSDoc types) - Convert src/react.ts → src/react.js (with JSDoc types) - Create modular structure: src/core/Toolbar.js and src/core/VanillaRenderer.js - Update package.json to point to src/ instead of dist/ - Remove TypeScript configuration (tsconfig.json) - Remove build scripts and TypeScript dependencies - Fix Next.js example dev.sh to use npx Benefits: ✅ No build step required ✅ Direct source consumption ✅ Faster development (no compilation watch) ✅ Simpler package structure ✅ JSDoc provides IDE autocomplete/intellisense ✅ Same pattern as CLI package

Copilot

Pull Request Overview

Copilot reviewed 56 out of 59 changed files in this pull request and generated 6 comments.

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

packages/toolbar/src/core/VanillaRenderer.js

examples/next/toolbar-demo/example-app/lib/wordpress.ts

packages/toolbar/examples/plugins/hwp-cors-local/hwp-cors-local.php

examples/next/toolbar-demo/example-app/app/components/Toolbar.tsx

packages/toolbar/src/core/VanillaRenderer.js

scripts/get-ports.js

Copilot

Pull Request Overview

Copilot reviewed 56 out of 59 changed files in this pull request and generated 9 comments.

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

packages/toolbar/src/core/Toolbar.js

packages/toolbar/examples/vanilla/example-app/src/main.js

examples/next/toolbar-demo/example-app/lib/wordpress.ts

packages/toolbar/src/core/VanillaRenderer.js

packages/toolbar/examples/plugins/hwp-cors-local/hwp-cors-local.php

examples/vanilla/toolbar-demo/scripts/setup-env.js

scripts/get-ports.js

packages/toolbar/src/core/VanillaRenderer.js

examples/next/toolbar-demo/example-app/app/components/Toolbar.tsx

theodesp · 2025-10-10T10:43:09Z

@josephfusco awesome job.
Please resolve copilot comments.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Enhance error messages in Next.js toolbar example to provide specific, actionable guidance for common WordPress connection failures. Changes: - Add comprehensive status code handling (401, 403, 404, 500+) in wordpress.ts - Parse WordPress error response JSON for detailed error messages - Detect "No route was found" errors and suggest hwp-wp-env-helpers plugin - Provide specific troubleshooting steps for CORS, network, and server errors - Update page.tsx to display detailed error messages instead of generic text Error messages now include: - Multiple possible causes for each error type - Specific commands to resolve issues (npx wp-env start, etc.) - References to required plugins (hwp-cors-local, hwp-wp-env-helpers) - WordPress log checking instructions for server errors

Removed custom setup and dev scripts in favor of simplified npm scripts for app and WordPress management. Updated .wp-env.json for new PHP version, plugin paths, and config values. Improved README with clearer setup instructions, troubleshooting, and port configuration. Adjusted Vite config for default port fallback and cleaned up package.json scripts.

Simplifies environment setup by removing custom scripts and shell files, updating package.json scripts, and standardizing port usage to 8888 for WordPress. The README is rewritten for clarity, providing step-by-step instructions and improved documentation. Updates dependencies and example environment files to match the new configuration.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Relocated Next.js and Vanilla JS toolbar demo examples and related plugins from the root examples/ and plugins/ directories into packages/toolbar/examples/. Updated documentation, configuration, and paths to reflect the new structure. Removed IMPLEMENTATION_BREAKDOWN.md as part of project cleanup.

ahuseyn

Great work @josephfusco! Tested examples in their new directories and working.

Initial scaffold of Toolbar

eb31d3a

josephfusco added 6 commits October 9, 2025 07:52

Clean up toolbar demo

1fe19eb

Modern state management following TanStack/Zustand patterns. Minimal …

9465c96

…base styles for full developer control

Add centralized templates and shared port calculation

10bcabf

josephfusco force-pushed the toolbar branch from 2c46dc6 to f97b6a6 Compare October 9, 2025 11:57

josephfusco added 7 commits October 9, 2025 08:03

josephfusco requested review from ahuseyn and Copilot October 9, 2025 14:22

Copilot AI reviewed Oct 9, 2025

View reviewed changes

packages/toolbar/src/index.ts Outdated Show resolved Hide resolved

scripts/get-ports.js Outdated Show resolved Hide resolved

examples/next/toolbar-demo/example-app/lib/wordpress.ts Outdated Show resolved Hide resolved

josephfusco marked this pull request as ready for review October 9, 2025 14:23

josephfusco requested a review from a team as a code owner October 9, 2025 14:23

josephfusco and others added 5 commits October 9, 2025 10:38

Update wordpress.ts

5236d39

Update scripts/get-ports.js

316fb36

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

feat(plugins): add composer.json and standardize versions to 0.1.0

a3d62a2

feat(toolbar): add demo path indicator and use JSDoc comments

bd694fa

docs: add CHANGELOG.md files for initial 0.1.0 release

eca9b26

Add standard badges

d64b0ff

josephfusco requested a review from Copilot October 9, 2025 22:09

josephfusco requested a review from Copilot October 10, 2025 03:20

Copilot AI reviewed Oct 10, 2025

View reviewed changes

toolbar position

7ef2646

josephfusco requested a review from Copilot October 10, 2025 04:59

Copilot AI reviewed Oct 10, 2025

View reviewed changes

josephfusco and others added 6 commits October 10, 2025 06:53

Apply suggestion from @Copilot

78d6eb4

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Apply suggestion from @Copilot

c3a20f5

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Apply suggestion from @Copilot

8fedd1a

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Apply suggestion from @Copilot

65bdaa9

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Apply suggestion from @Copilot

1e65d15

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

colinmurphy mentioned this pull request Oct 15, 2025

[experimental]: Implement the initial, extendable toolbar core #427

Closed

4 tasks

colinmurphy and others added 7 commits October 16, 2025 10:29

Update packages/toolbar/src/core/VanillaRenderer.js

02b3807

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Fix for next example.

5f2aa1b

update readme

712bf6a

fix(toolbar): update example readmes, add htaccess to fix wp-env issues

a5ada57

ahuseyn approved these changes Oct 20, 2025

View reviewed changes

ahuseyn requested review from colinmurphy and theodesp October 20, 2025 08:02

colinmurphy approved these changes Oct 20, 2025

View reviewed changes

colinmurphy added this pull request to the merge queue Oct 20, 2025

Merged via the queue into main with commit 2ecf7b5 Oct 20, 2025
10 checks passed

colinmurphy deleted the toolbar branch October 20, 2025 10:26

feat: Initial scaffold of Toolbar #432

feat: Initial scaffold of Toolbar #432

Uh oh!

Conversation

josephfusco commented Oct 8, 2025 • edited by colinmurphy Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Package Structure

Implementation

Technical Details

Running Examples

Uh oh!

changeset-bot bot commented Oct 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

josephfusco commented Oct 9, 2025

Uh oh!

github-actions bot commented Oct 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📦 Plugin Artifacts Ready!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

theodesp commented Oct 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ahuseyn left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

josephfusco commented Oct 8, 2025 •

edited by colinmurphy

Loading

changeset-bot bot commented Oct 8, 2025 •

edited

Loading

github-actions bot commented Oct 9, 2025 •

edited

Loading

theodesp commented Oct 10, 2025 •

edited

Loading