Refactor Next.js toolbar demo setup and docs

colinmurphy · colinmurphy · commit be0c467c4df1 · 2025-10-16T11:58:35.000+01:00
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.
diff --git a/examples/next/toolbar-demo/README.md b/examples/next/toolbar-demo/README.md
@@ -1,43 +1,35 @@
-# Toolbar Demo - React Hooks
+# Next.js Toolbar Demo
 
-React hooks example with Next.js App Router demonstrating the Headless WordPress Toolbar.
+In this example we show how to integrate the Headless WordPress Toolbar into a Next.js application using React hooks and WordPress backend using WPGraphQL.
 
-## Features
-
-- React hooks (`useToolbar`, `useToolbarState`, `useToolbarNodes`)
-- Next.js App Router (App Directory)
-- TypeScript
-- Framework-agnostic state management
-- WordPress context integration
+## Getting Started
 
-## Quick Start
+> [!IMPORTANT]
+> Docker Desktop needs to be installed to run WordPress locally.
 
-```bash
-# Install dependencies (from monorepo root)
-pnpm install
+1. Create a `.env.local` file in the `examples/next/toolbar-demo` directory with the following content:
+   ```
+   NEXT_PUBLIC_WP_URL=http://localhost:8888
+   ```
+2. Run `npm run example:setup` to install dependencies and configure the local WP server.
+3. Run `npm run example:start` to start the WP server and Next.js development server.
 
-# Start WordPress (from this directory)
-npx wp-env start
 
-# Start Next.js dev server (from example-app directory)
-cd example-app
-pnpm dev
-```
+>[!NOTE]
+> Port 8888 is the default port for wp-env.
 
-Open:
-- Next.js App: [http://localhost:3001](http://localhost:3001)
-- WordPress Admin: [http://localhost:8001/wp-admin](http://localhost:8001/wp-admin)
-  - Username: `admin`
-  - Password: `password`
+The example will be available at:
+- **Frontend**: http://localhost:3000
+- **WordPress**: http://localhost:8888
+- **WordPress Admin**: http://localhost:8888/wp-admin (`admin` / `password`)
+- **GraphQL**: http://localhost:8888/?graphql
 
-## Key Files
+> [!NOTE]
+> When you kill the long running process this will not shutdown the local WP instance, only Next.js. You must run `npm run example:stop` to kill the local WP server.
 
-- `lib/toolbar.ts` - Singleton toolbar instance
-- `lib/wordpress.ts` - WordPress REST API integration
-- `app/components/Toolbar.tsx` - Toolbar component using React hooks
-- `app/page.tsx` - Demo page with WordPress integration
+## What This Example Shows
 
-## Usage Pattern
+### 1. React Hooks Integration
 
 ```tsx
 import { toolbar } from '@/lib/toolbar';
@@ -48,90 +40,144 @@ function MyComponent() {
 
   return (
     <div>
-      {nodes.map(node => (
-        <button key={node.id} onClick={node.onClick}>
-          {typeof node.label === 'function' ? node.label() : node.label}
-        </button>
-      ))}
+      {/* Toolbar UI */}
     </div>
   );
 }
 ```
 
-## State Management
+### 2. WordPress Context Integration
+
+```tsx
+import { fetchWordPressUser } from '@/lib/wordpress';
+
+// Fetch user and set WordPress context
+const user = await fetchWordPressUser();
+toolbar.setWordPressContext({
+  user: {
+    id: user.id,
+    name: user.name,
+    email: user.email
+  },
+  site: {
+    url: 'http://localhost:8888',
+    adminUrl: 'http://localhost:8888/wp-admin'
+  }
+});
+```
+
+### 3. State Management
+
+```tsx
+const { state, nodes } = useToolbar(toolbar);
+
+// Subscribe to state changes
+useEffect(() => {
+  console.log('Toolbar state:', state);
+}, [state]);
+```
+
+### 4. Custom Node Registration
+
+```tsx
+toolbar.register('home', 'Home', () => {
+  router.push('/');
+});
+```
 
-The toolbar follows modern state management patterns (TanStack/Zustand):
+## Features
 
-1. **Framework-agnostic core** - `Toolbar` class manages state
-2. **React integration** - Hooks subscribe to state changes
-3. **Full UI control** - You render the toolbar however you want
+- ✅ React hooks (`useToolbar`, `useToolbarState`, `useToolbarNodes`)
+- ✅ Next.js App Router (App Directory)
+- ✅ TypeScript support
+- ✅ Framework-agnostic state management
+- ✅ WordPress context integration
+- ✅ Real WordPress data integration
+- ✅ WPGraphQL support
 
-## WordPress Integration
+## Project Structure
 
-The demo integrates with a local WordPress instance via REST API.
+```
+toolbar-demo/
+├── example-app/           # Next.js application
+│   ├── app/
+│   │   ├── components/    # React components
+│   │   │   └── Toolbar.tsx
+│   │   ├── globals.css
+│   │   ├── layout.tsx
+│   │   └── page.tsx      # Demo page
+│   ├── lib/
+│   │   ├── toolbar.ts    # Singleton toolbar instance
+│   │   └── wordpress.ts  # WordPress API integration
+│   ├── next.config.ts
+│   ├── package.json
+│   └── tsconfig.json
+├── wp-env/               # WordPress environment
+├── .wp-env.json          # wp-env configuration
+├── package.json
+└── README.md
+```
 
-### Demo Authentication
+## Available Scripts
 
-By default, the demo uses **mock authentication** to simplify the setup:
+```bash
+# Initial setup - installs dependencies and starts WordPress
+npm run example:setup
 
-```ts
-// Demo user (no actual WordPress login required)
-const user = await getCurrentUser(); // Returns mock user
+# Start development servers (WordPress + Next.js)
+npm run example:start
 
-// Public posts endpoint (no authentication needed)
-const posts = await getPosts(); // Fetches from /wp/v2/posts
+# Stop WordPress server
+npm run example:stop
+
+# Reset everything and start fresh
+npm run example:prune
+
+# WordPress-only commands
+npm run wp:start
+npm run wp:stop
+npm run wp:destroy
 ```
 
-This lets you test the toolbar immediately without WordPress login complexity.
+## Key Files
 
-### Production Authentication
+- **`lib/toolbar.ts`** - Singleton toolbar instance configuration
+- **`lib/wordpress.ts`** - WordPress REST API integration helpers
+- **`app/components/Toolbar.tsx`** - Main toolbar component using React hooks
+- **`app/page.tsx`** - Demo page showing WordPress integration
 
-For production use, implement proper authentication using **WordPress Application Passwords**:
+## WordPress Setup
 
-1. **Generate Application Password**:
-   - Go to WordPress Admin → Users → Profile
-   - Scroll to "Application Passwords"
-   - Create a new password
+The wp-env configuration includes:
+- WordPress with WPGraphQL plugin
+- Admin credentials: `admin` / `password`
+- GraphQL endpoint: `http://localhost:8888/?graphql`
+- REST API endpoint: `http://localhost:8888/?rest_route=/wp/v2/...`
+- Pretty permalinks enabled
+- CORS headers enabled for localhost:3000
 
-2. **Configure Environment**:
-   ```bash
-   cp .env.local.example .env.local
-   # Add your credentials to .env.local
-   ```
+## Environment Configuration
 
-3. **Update `lib/wordpress.ts`**:
-   ```ts
-   const auth = btoa(`${process.env.WP_USERNAME}:${process.env.WP_APP_PASSWORD}`);
-
-   export async function fetchFromWordPress(endpoint: string) {
-     const response = await fetch(`${WP_API_URL}/wp-json${endpoint}`, {
-       headers: {
-         'Authorization': `Basic ${auth}`
-       }
-     });
-     // ...
-   }
-   ```
+The example uses standard ports (3000 for frontend, 8888 for WordPress) to match other hwptoolkit examples.
+
+## TypeScript Support
+
+The example includes full TypeScript support with proper types for:
+- Toolbar state and nodes
+- WordPress API responses
+- React hook return types
 
-### Features Demonstrated
+## Trouble Shooting
 
-- **WordPress Connection**: Fetch data from WordPress REST API
-- **Post Management**: Load and display WordPress posts
-- **Dynamic Toolbar**: Nodes appear/disappear based on WordPress context
-- **Error Handling**: Clear error messages for connection issues
+To reset the WP server and re-run setup you can run `npm run example:prune` and confirm "Yes" at any prompts.
 
-### Troubleshooting
+## Learn More
 
-**CORS Errors**
-- Make sure wp-env is running: `npx wp-env start`
-- Check WordPress is accessible at http://localhost:8001
-- MU plugin should enable CORS headers automatically
+- [@wpengine/hwp-toolbar documentation](../../../packages/toolbar/README.md)
+- [Next.js Documentation](https://nextjs.org/docs)
+- [React Hooks Documentation](https://reactjs.org/docs/hooks-intro.html)
+- [WPGraphQL](https://www.wpgraphql.com/)
 
-**Connection Failed**
-- Verify wp-env is running: `npx wp-env start`
-- Check the port matches `.wp-env.json` (default: 8001)
-- Try accessing http://localhost:8001 in your browser
+## License
 
-**No Posts Available**
-- Create sample posts in WordPress Admin
-- Or run: `npx wp-env run cli wp post generate --count=5`
+BSD-3-Clause
diff --git a/examples/next/toolbar-demo/example-app/.env.local.example b/examples/next/toolbar-demo/example-app/.env.local.example
@@ -2,7 +2,7 @@
 # Copy this file to .env.local and update with your values
 
 # WordPress Site URL
-NEXT_PUBLIC_WP_URL=http://localhost:8891
+NEXT_PUBLIC_WP_URL=http://localhost:8888
 
 # Production Authentication (optional)
 # For real authentication, generate Application Passwords in WordPress:
diff --git a/examples/next/toolbar-demo/example-app/dev.sh b/examples/next/toolbar-demo/example-app/dev.sh
diff --git a/examples/next/toolbar-demo/example-app/package.json b/examples/next/toolbar-demo/example-app/package.json
@@ -3,14 +3,13 @@
   "version": "0.1.0",
   "private": true,
   "scripts": {
-    "predev": "node ../scripts/setup-env.js",
-    "dev": "bash dev.sh",
+    "dev": "next dev --port 3000",
     "build": "next build",
     "start": "next start"
   },
   "dependencies": {
-    "@wpengine/hwp-toolbar": "workspace:*",
-    "next": "^15.4.7",
+    "@wpengine/hwp-toolbar": "file:../../../../packages/toolbar",
+    "next": "^15.5",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
diff --git a/examples/next/toolbar-demo/package.json b/examples/next/toolbar-demo/package.json
@@ -4,10 +4,12 @@
   "description": "React hooks toolbar demo with Next.js App Router",
   "private": true,
   "scripts": {
-    "example:dev": "npm --prefix ./example-app run dev",
-    "example:build": "npm --prefix ./example-app run build",
-    "example:start": "node scripts/setup-env.js && npm install && concurrently \"npm run wp:start\" \"sleep 5 && npm run example:dev\"",
+    "example:setup": "npm run app:install && npm run wp:start",
+    "example:start": "concurrently \"npm run wp:start\" \"sleep 5 && npm run app:dev\"",
     "example:stop": "npm run wp:stop",
+    "example:prune": "npm run wp:destroy && npm run example:setup && npm run example:start",
+    "app:dev": "cd example-app && npm run dev && cd ..",
+    "app:install": "cd example-app && npm install && cd ..",
     "wp:start": "wp-env start",
     "wp:stop": "wp-env stop",
     "wp:destroy": "wp-env destroy"
diff --git a/examples/next/toolbar-demo/scripts/setup-env.js b/examples/next/toolbar-demo/scripts/setup-env.js
