Next.js GraphQL Proxy Debugger

A debugging utility for proxied GraphQL APIs within WordPress environments, offering enhanced query inspection, request/response logging, and real-time query complexity estimation.

Features

• GraphQL Proxy Debugging - Intercepts and forwards GraphQL requests through a custom proxy.
• Debug Print Output - Logs proxied GraphQL queries and their responses for easier debugging.
• Query Complexity Estimation - Calculates the complexity of each GraphQL query using a customizable estimation algorithm.

Prerequisites

• Node.js (v18+ recommended)
• WordPress with WPGraphQL plugin installed
• wp-env
• Docker running (docker ps)

Setup

Install Dependencies

Run:

npm install

Environment Variables

Create a .env file and put the content below inside. If your proxy requires environment-specific configs add them too.

NEXT_PUBLIC_WORDPRESS_URL=http://localhost:8888

or run the command below to create the .env file:

echo "NEXT_PUBLIC_WORDPRESS_URL=http://localhost:8888" > examples/next/proxied-graphql-debug/example-app/.env

Start the Environment

To start WordPress and run your proxy/debugger setup:

npm run example:build

How It Works

This debugging tool:

• Intercepts GraphQL POST requests sent to the WordPress GraphQL endpoint.
• Logs the incoming query, variables, and response payload.
• Estimates the complexity of the query based on field nesting and predefined multipliers.
• Provides output via console or log files.

Complexity Estimation

The complexity estimator:

• Traverses the GraphQL AST to measure query depth and individual field cost.
• Applies configurable multipliers for specific fields or types.
• Can be integrated into request handlers to reject or warn on overly expensive queries.

Running the Example with wp-env

Clone and Install

git clone https://github.com/wpengine/hwptoolkit.git
cd hwptoolkit
npm install

Build and Start Application

cd examples/next/graphql-proxy-debug
npm run example:setup

This will:

• Start wp-env
• Import the database from wp-env/db/database.sql
• Install Next.js dependencies for example-app
• Run the Next.js dev server

Frontend	Admin
http://localhost:3000/	http://localhost:8888/wp-admin/

Login details: Username admin, Password password

Command Reference

Command	Description
example:setup	Prepares the environment, starts WordPress, imports the database, and starts the application.
example:dev	Runs the Next.js development server.
example:dev:install	Installs required Next.js packages.
example:start	Starts WordPress and the Next.js dev server.
example:stop	Stops the WordPress environment.
example:prune	Rebuilds and restarts the environment by destroying and recreating it.
wp:start	Starts the WordPress environment.
wp:stop	Stops the WordPress environment.
wp:destroy	Removes the WordPress environment.
wp:db:query	Executes a database query in WordPress.
wp:db:export	Exports the WordPress database to wp-env/db/database.sql.
wp:db:import	Imports the WordPress database from wp-env/db/database.sql.

Note: You can run npm run wp-env and use other wp-env commands as needed.

Database Access (Optional)

If you need direct database access, add the following to your wp-env.json:

"phpmyadminPort": 11111

Check if the port is free:

lsof -i :11111