WPGraphQL

https://github.com/wp-graphql/wp-graphql
Admin
WPGraphQL provides an extendable GraphQL API for WordPress, enabling modern development workflows...
Tokens:240,438
Snippets:2,919
Trust Score:8.1
License:GPL-3.0
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install Dependencies and Start Development Server

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql/packages/extensions/README.md

Run this command to install project dependencies and start the development server for the WPGraphQL extensions React app.

```shell
npm install && npm start
```

--------------------------------

### Initialize Development Environment

Source: https://github.com/wp-graphql/wp-graphql/blob/main/docs/DEVELOPMENT.md

Commands to clone the repository, set the Node version, install dependencies, and start the local WordPress environment.

```bash
# Clone the repository
git clone git@github.com:wp-graphql/wp-graphql.git
cd wp-graphql

# Use correct Node version (if using nvm)
nvm install && nvm use

# Install dependencies
npm install

# Start WordPress environment
npm run wp-env start
```

--------------------------------

### Initialize Development Environment

Source: https://github.com/wp-graphql/wp-graphql/blob/main/README.md

Commands to install dependencies and start the local WordPress environment for contributors.

```bash
npm install           # Install dependencies (uses workspaces)
npm run wp-env start  # Start WordPress environment with all plugins
```

--------------------------------

### Install and build the extension

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql-ide/docs/build-your-first-ide-extension.md

Command to install dependencies and compile the JavaScript source.

```bash
npm install && npm run build
```

--------------------------------

### Install Dependencies

Source: https://github.com/wp-graphql/wp-graphql/blob/main/design/brand/wpgraphql/README.md

Commands to install required Tailwind CSS packages and initialize shadcn/ui.

```bash
npm install tailwindcss tailwindcss-animate
npx shadcn@latest init
```

--------------------------------

### Quick Start Development Commands

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql-ide/CONTRIBUTING.md

Commands to initialize the environment and start the development server from the monorepo root.

```bash
# From monorepo root
npm install
npm run wp-env start

# Development (from plugin directory or monorepo root)
npm start -w @wpgraphql/ide

# Access
# http://localhost:8888/wp-admin (admin/password)
```

--------------------------------

### Install Test Environment

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql/docs/testing.md

Run the Composer script to download and set up a local WordPress installation, including the database and WPGraphQL.

```shell
composer install-test-env
```

--------------------------------

### Install Dependencies and Run Linter

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql-acf/vscode.md

Use Composer to install project dependencies and Yarn to run the linter from the command line. Ensure you have Composer and Yarn installed globally.

```bash
composer install
```

```bash
yarn lint # to test from CLI
```

--------------------------------

### Install Dependencies

Source: https://github.com/wp-graphql/wp-graphql/blob/main/websites/wpgraphql.com/README.md

Install all required project dependencies from the monorepo root.

```bash
npm install
```

--------------------------------

### Install Dependencies with npm

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql/packages/README.md

Run this command from the root of the plugin directory to install all necessary project dependencies.

```bash
npm install
```

--------------------------------

### Install ACF Pro via inline command

Source: https://github.com/wp-graphql/wp-graphql/blob/main/docs/TESTING.md

Provide the license key directly in the installation command.

```bash
ACF_LICENSE_KEY=your_license_key_here npm run -w @wpgraphql/wp-graphql-acf install-acf:pro
```

--------------------------------

### Full Local CI-like Run

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql-acf/README.md

Performs a full local run including build, wp-env setup, ACF installation, and E2E tests. Can be configured for ACF Free.

```bash
./bin/run-acf-e2e-local.sh
```

```bash
INSTALL_ACF_PRO=false ./bin/run-acf-e2e-local.sh
```

--------------------------------

### Quick Setup Commands

Source: https://github.com/wp-graphql/wp-graphql/blob/main/design/brand/ide/README.md

Commands to initialize the environment and copy necessary configuration files.

```bash
npm install tailwindcss tailwindcss-animate
npx shadcn@latest init

# For IDE standalone:
cp globals.css ./app/globals.css

# For a site that includes multiple products:
cp family-globals.css ./app/globals.css

cp tailwind.config.ts ./tailwind.config.ts
cp components.json    ./components.json
```

--------------------------------

### Install ACF Pro and Extended Pro via environment variables

Source: https://github.com/wp-graphql/wp-graphql/blob/main/docs/TESTING.md

Set both license keys as environment variables before installation.

```bash
export ACF_LICENSE_KEY=your_acf_pro_license_key
export ACF_EXTENDED_LICENSE_KEY=your_acf_extended_pro_license_key
npm run -w @wpgraphql/wp-graphql-acf install-acf:pro-extended
```

--------------------------------

### Run Development Server

Source: https://github.com/wp-graphql/wp-graphql/blob/main/websites/wpgraphql.com/README.md

Start the development server specifically for the wpgraphql-com package.

```bash
npm run dev -w @wpgraphql/wpgraphql-com
```

--------------------------------

### Mutation Examples

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql/src/Experimental/Experiment/EmailAddressScalarFieldsExperiment/README.md

Examples of how to use mutations for creating, updating, and registering users with email addresses.

```APIDOC
## Mutation Examples

### Create User with Email

```graphql
mutation CreateUser($input: CreateUserInput!) {
  createUser(input: $input) {
    user {
      id
      name
      emailAddress
    }
  }
}
```

**Variables:**

```json
{
  "input": {
    "username": "newuser",
    "emailAddress": "newuser@example.com",
    "password": "securePassword123"
  }
}
```

### Update User Email

```graphql
mutation UpdateUser($input: UpdateUserInput!) {
  updateUser(input: $input) {
    user {
      id
      emailAddress
    }
  }
}
```

**Variables:**

```json
{
  "input": {
    "id": "dXNlcjox",
    "emailAddress": "updated@example.com"
  }
}
```

### Register New User

```graphql
mutation RegisterUser($input: RegisterUserInput!) {
  registerUser(input: $input) {
    user {
      id
      name
      emailAddress
    }
  }
}
```

**Variables:**

```json
{
  "input": {
    "username": "registereduser",
    "emailAddress": "user@example.com"
  }
}
```
```

--------------------------------

### Setup and Development Commands

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql-ide/CLAUDE.md

Commands for initializing the environment and running the development server with hot reloading.

```bash
npm install                              # From monorepo root
npm run wp-env start                     # From monorepo root (Docker required)
npm run -w @wpgraphql/wp-graphql-ide start    # Dev server with hot reload
npm run -w @wpgraphql/wp-graphql-ide clean    # Remove node_modules + build dirs
```

--------------------------------

### Install Composer Dependencies

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql-smart-cache/docs/development.md

Installs plugin source and dependencies using Composer. Run this after initial checkout or updating composer.json.

```bash
composer install --optimize-autoloader
```

```bash
composer update --optimize-autoloader
```

--------------------------------

### Usage Examples

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql/docs/functions/graphql_get_nonce.md

Examples showing how to use the nonce in JavaScript fetch requests and how to localize it for scripts in PHP.

```javascript
fetch('/graphql', { headers: { 'Content-Type': 'application/json', 'X-WP-Nonce': wpGraphQLSettings.nonce }, body: JSON.stringify({ query: '{ viewer { name } }' }) });
```

```php
wp_localize_script( 'my-script', 'wpGraphQLSettings', [ 'nonce'    => graphql_get_nonce(), 'endpoint' => graphql_get_endpoint(), ] );
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/wp-graphql/wp-graphql/blob/main/websites/wpgraphql.com/README.md

Initialize the local environment configuration file from the provided example.

```bash
cp .env.local.example .env.local
```

--------------------------------

### Composer JSON Configuration for WPGraphQL

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql/docs/quick-start.md

An example composer.json file demonstrating how to configure WPGraphQL as a plugin dependency. It includes repository definitions for WPackagist and installer paths for WordPress plugins.

```json
{
    "name": "your-name/your-project",
    "description": "Your WordPress Project",
    "repositories":[
        {
            "type":"composer",
            "url":"https://wpackagist.org",
            "only": [
                "wpackagist-plugin/*",
                "wpackagist-theme/*"
            ]
        }
    ],
    "require": {
        "wpackagist-plugin/wp-graphql":"trunk",
    },
    "extra": {
        "installer-paths": {
            "wp-content/plugins/{$name}/": [
                "type:wordpress-plugin"
            ]
        }
    }
}
```

--------------------------------

### Example response for all settings query

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql/docs/settings.md

Sample JSON response structure for the allSettings query.

```json
{
  "data": {
    "allSettings": {
      "generalSettingsDateFormat": "F j, Y",
      "generalSettingsDescription": "Just another WordPress site",
      "generalSettingsLanguage": "",
      "generalSettingsStartOfWeek": 0,
      "generalSettingsTimeFormat": "g:i a",
      "generalSettingsTimezone": "America/Denver",
      "generalSettingsTitle": "Example Site Title",
      "generalSettingsUrl": "http://example.com",
      "readingSettingsPostsPerPage": 10,
      "discussionSettingsDefaultCommentStatus": "open",
      "discussionSettingsDefaultPingStatus": "open",
      "writingSettingsDefaultCategory": 1,
      "writingSettingsDefaultPostFormat": "",
      "writingSettingsUseSmilies": true
    }
  }
}
```

--------------------------------

### Clone and branch setup

Source: https://github.com/wp-graphql/wp-graphql/blob/main/docs/CONTRIBUTING.md

Commands to clone the repository and create a new feature branch.

```bash
git clone git@github.com:YOUR_USERNAME/wp-graphql.git
cd wp-graphql
```

```bash
git checkout -b feat/your-feature-name
```

--------------------------------

### Install NPM dependencies

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql/docs/contributing.md

Commands to set the Node.js version and install required project dependencies.

```shell
## If you're using nvm, make sure to use the correct Node.js version:
nvm install && nvm use

## Then install the NPM dependencies:
npm ci
```

--------------------------------

### Install PHP Dependencies with Composer

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql/docs/quick-start.md

Run this command in the plugin directory to install PHP dependencies. Use '--no-dev' for production environments.

```bash
composer install
```

```bash
composer install --no-dev
```

--------------------------------

### Install Test Dependencies and Run Tests

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql-acf/CLAUDE.md

Commands to install ACF and run WPUnit or e2e tests within the plugin workspace.

```bash
npm run -w @wpgraphql/wp-graphql-acf install-test-deps   # test dependencies
npm run -w @wpgraphql/wp-graphql-acf install-acf         # free ACF (or install-acf:pro for ACF Pro)

npm run -w @wpgraphql/wp-graphql-acf test:codecept:wpunit
npm run -w @wpgraphql/wp-graphql-acf test:e2e            # Playwright (needs wp-env + the installs above)
```

--------------------------------

### Install ACF Pro via .env file

Source: https://github.com/wp-graphql/wp-graphql/blob/main/docs/TESTING.md

Configure the license key in a .env file before installing ACF Pro.

```bash
# Create or edit plugins/wp-graphql-acf/.env
echo "ACF_LICENSE_KEY=your_license_key_here" >> plugins/wp-graphql-acf/.env

# Install ACF Pro + ACF Extended Free
npm run -w @wpgraphql/wp-graphql-acf install-acf:pro
```

--------------------------------

### Example upgrade notice output

Source: https://github.com/wp-graphql/wp-graphql/blob/main/scripts/README.md

The format of the generated upgrade notice within readme.txt.

```text
== Upgrade Notice ==

= 3.0.0 =

**⚠️ BREAKING CHANGES**: This release contains breaking changes that may require updates to your code.

* Remove deprecated `singlePost` query in favor of `post` query ([#1234](https://github.com/wp-graphql/wp-graphql/pull/1234))
* Change default pagination limit from 100 to 50 items ([#1235](https://github.com/wp-graphql/wp-graphql/pull/1235))

Please review these changes before upgrading.
```

--------------------------------

### Start wp-env environment

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql/docs/contributing.md

Initializes the Docker-based WordPress development environment.

```shell
npm run wp-env start
```

--------------------------------

### Install Composer Dependencies

Source: https://github.com/wp-graphql/wp-graphql/blob/main/docs/DEVELOPMENT.md

Manually trigger Composer dependency installation within the test container.

```bash
# Install Composer deps in the tests container
npm run wp-env -- run tests-cli --env-cwd=wp-content/plugins/wp-graphql/ -- composer install
```

--------------------------------

### graphql_init Action

Source: https://github.com/wp-graphql/wp-graphql/wiki/Action-and-Filter-Reference

Fires when the WPGraphQL plugin is initialized. Useful for setup tasks.

```php
/**
* Fire off init action
*
* @param WPGraphQL $instance The instance of the WPGraphQL class
*/
do_action( 'graphql_init', self::$instance );
```

--------------------------------

### Install GraphiQL using Brew

Source: https://github.com/wp-graphql/wp-graphql/wiki/Developer-Tools

Use Homebrew Cask to install the GraphiQL IDE on your system for composing GraphQL queries.

```bash
brew cask install graphiql
```

--------------------------------

### Add recipe code example

Source: https://github.com/wp-graphql/wp-graphql/blob/main/docs/CONTRIBUTING.md

Example of a PHP code block within a recipe markdown file.

```php
add_action( 'graphql_register_types', function () {
    // ...
} );
```

--------------------------------

### Experiment Graduation Plan Example

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql/docs/experiments-contributing.md

This markdown example shows the structure for a GitHub issue proposing an experiment's graduation to core. It includes a summary, usage stats, feedback, the graduation plan, and details on breaking changes.

```markdown
## Experiment Summary

The EmailAddress scalar experiment has been active for 3 releases and is ready to graduate to core.

## Usage Stats

(If available)

- X downloads/installs with experiment enabled
- Y production sites using it
- Z positive feedback comments

## Feedback Summary

**Positive:**

- Users love the built-in validation
- Reduced boilerplate code
- Clear error messages

**Concerns Addressed:**

- Initial performance concern resolved in v2.1
- Custom validation filter added in v2.2

## Graduation Plan

- [ ] Move implementation from experiment to core
- [ ] Keep experiment class with deprecation notice
- [ ] Update documentation
- [ ] Add to changelog
- [ ] Provide migration guide
- [ ] Set removal date (2 releases out)

## Breaking Changes

For users who enabled the experiment:

- No changes needed, it becomes always-on

For users who didn't enable the experiment:

- User.email changes from String → EmailAddress
- Migration guide: Update queries expecting String type

## Migration Timeline

- v2.5: Experiment graduates, remains available with deprecation notice
- v2.6: Deprecation notices continue
- v3.0: Experiment removed, feature is always-on
```

--------------------------------

### Install NPM Dependencies

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql/docs/testing.md

Install Node.js dependencies from the repository root. Ensure the correct Node.js version is active if using NVM.

```shell
## If you're using nvm, make sure to use the correct Node.js version:
nvm install && nvm use

## Then install the NPM dependencies:
npm install
```

--------------------------------

### Start Docker environment

Source: https://github.com/wp-graphql/wp-graphql/blob/main/docs/TESTING.md

Ensure Docker is running before executing test commands.

```bash
# Start Docker, then:
npm run wp-env start
```

--------------------------------

### Example JSON Response for Page Template

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql/docs/themes.md

Example JSON output when querying a page and its template, showing the 'Default' template name.

```json
{
  "data": {
    "pages": {
      "nodes": [
        {
          "title": "Sample Page",
          "template": {
            "templateName": "Default"
          }
        }
      ]
    }
  }
}
```

--------------------------------

### Install ACF Dependencies for Testing

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql-acf/README.md

Installs ACF Free by default. Set environment variables for ACF Pro and Extended license keys.

```bash
cd plugins/wp-graphql-acf && npm run install-test-deps
```

--------------------------------

### Run WPUnit tests

Source: https://github.com/wp-graphql/wp-graphql/blob/main/docs/TESTING.md

Execute the CodeceptJS WPUnit tests after installing dependencies.

```bash
npm run -w @wpgraphql/wp-graphql-acf test:codecept:wpunit
```

--------------------------------

### List All Plugins

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql/docs/plugins.md

Query for a list of all installed plugins. Requires 'update_plugins' capability.

```graphql
{
  plugins {
    nodes {
      id
      authorUri
      pluginUri
      description
      version
      author
    }
  }
}
```

--------------------------------

### Configure XDebug

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql/docs/contributing.md

Commands to start the development environment with XDebug enabled.

```shell
# To turn it on:
npm run wp-env start -- --xdebug

# Or enable specific modes with a comma-separated list:
npm run wp-env start -- --profile,trace,debug
```

--------------------------------

### Querying Menus and Menu Items

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql/docs/menus.md

Examples of how to retrieve lists of menus and their associated menu items.

```APIDOC
## GraphQL Query: menus

### Description
Retrieves a list of all menus and their associated menu items.

### Query
```graphql
{
  menus {
    nodes {
      id
      databaseId
      name
      menuItems {
        edges {
          node {
            id
            label
            parentId
          }
        }
      }
    }
  }
}
```
```

--------------------------------

### Run WordPress App with Docker Compose

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql-smart-cache/docs/development.md

Starts the WordPress application with the plugin installed and running. Access the app at http://localhost:8091/. You can specify WP and PHP versions.

```bash
docker compose up app
```

```bash
WP_VERSION=6.3 PHP_VERSION=8.2 docker compose up app
```

--------------------------------

### General Settings Response

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql/docs/settings.md

Example JSON response for a general settings query.

```json
{
  "data": {
    "generalSettings": {
      "title": "Name of Your Site",
      "description": "Just another WordPress site",
      "url": "https://example.com"
    }
  }
}
```

--------------------------------

### Access Testing App with Bash

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql-smart-cache/docs/development.md

Use this command to access the WP testing application via bash. No specific setup is required beyond having Docker Compose installed.

```bash
docker-compose run --entrypoint bash testing
```

--------------------------------

### apply_filters( 'graphql_allowed_hosts', $default_allowed_hosts )

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql/docs/filters/graphql_allowed_hosts.md

Filters the list of hostnames treated as belonging to the WordPress install. This is useful for multisite or multi-domain setups where additional domains should be recognized as part of the same site.

```APIDOC
## apply_filters( 'graphql_allowed_hosts', $default_allowed_hosts )

### Description
Filters hostnames treated as belonging to this WordPress install when resolving node URIs. By default, this includes the hosts from site_url() and home_url().

### Parameters
- **$allowed_hosts** (string[]) - Required - An array of hostnames permitted when comparing the parsed URI host.

### Usage
```php
add_filter( 'graphql_allowed_hosts', function( $allowed_hosts ) {
    $allowed_hosts[] = 'example.com';
    return $allowed_hosts;
});
```
```

--------------------------------

### WordPress Environment Lifecycle Script

Source: https://github.com/wp-graphql/wp-graphql/blob/main/docs/ARCHITECTURE.md

Configures a lifecycle script to automatically run setup tasks after the WordPress environment starts. This ensures the development environment is ready for use.

```json
{
  "lifecycleScripts": {
    "afterStart": "bash bin/setup-wp-env.sh"
  }
}
```

--------------------------------

### Query General Settings

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql/docs/settings.md

Example query to retrieve core WordPress general settings.

```graphql
{
  generalSettings {
    title
    description
    url
  }
}
```

--------------------------------

### Manage Dependencies

Source: https://github.com/wp-graphql/wp-graphql/blob/main/docs/CONTRIBUTING.md

Commands for installing packages into specific plugin workspaces or the root directory.

```bash
# Add to a specific plugin
npm install <package> -w @wpgraphql/wp-graphql

# Add to root (shared tooling)
npm install <package> -D
```

--------------------------------

### Start Test Environment and Run WPUnit Tests

Source: https://github.com/wp-graphql/wp-graphql/blob/main/docs/TESTING.md

Initializes the Docker-based WordPress environment and executes the WPUnit test suite.

```bash
# Start the test environment
npm run wp-env start

# Run WPUnit tests for wp-graphql
npm run -w @wpgraphql/wp-graphql test:codecept:wpunit
```

--------------------------------

### Install Playwright Chromium

Source: https://github.com/wp-graphql/wp-graphql/blob/main/design/brand/README.md

One-time installation of the Chromium browser required for rendering assets.

```bash
npx playwright install chromium
```

--------------------------------

### Experiment Directory Structure

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql/docs/experiments-creating.md

This example illustrates the standard directory structure for a WPGraphQL experiment. It shows the placement of the main experiment class, README.md, and optional helper files.

```tree
src/Experimental/Experiment/
├── AbstractExperiment.php                    # Base class (don't modify)
├── YourExperiment/
│   ├── YourExperiment.php                   # Main experiment class (required)
│   ├── README.md                            # Documentation (required)
│   └── helpers/                             # Optional: Additional files
│       └── validation.php
├── TestExperiment/
│   ├── TestExperiment.php
│   └── README.md
└── TestDependantExperiment/
    ├── TestDependantExperiment.php
    └── README.md

```

--------------------------------

### Install Composer Dependencies

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql/docs/testing.md

Install the development dependencies required for running tests using Composer.

```shell
composer install
```

--------------------------------

### Configure the WPGraphQL Client

Source: https://github.com/wp-graphql/wp-graphql/blob/main/websites/wpgraphql.com/src/lib/wpgraphql-client/README.md

Initialize the client with your templates and layout component.

```javascript
// src/lib/wpgraphql-client-config.js
import { configure } from "./wpgraphql-client"
import templates from "wp-templates"
import { Layout } from "components/Site/SiteLayout"

configure({ templates, Layout })
```

--------------------------------

### Configure wp-env Startup Options

Source: https://github.com/wp-graphql/wp-graphql/blob/main/docs/TESTING.md

Commands to start the environment with specific debugging or coverage tools enabled.

```bash
# Standard start
npm run wp-env start

# With PCOV code coverage enabled
PCOV_ENABLED=1 npm run wp-env start

# With Xdebug debugging enabled
npm run wp-env start -- --xdebug
```

--------------------------------

### Setup Smart Cache CSS

Source: https://github.com/wp-graphql/wp-graphql/blob/main/design/brand/smart-cache/README.md

Commands to copy the appropriate CSS globals for either standalone or unified product site configurations.

```bash
# For a standalone Smart Cache site:
cp globals.css ./app/globals.css

# For a unified product site (recommended):
cp family-globals.css ./app/globals.css
```

--------------------------------

### Manually Install Composer Dependencies

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql/docs/testing.md

Manually install Composer dependencies within the Docker container if needed.

```shell
## To install Composer dependencies inside the Docker container:
npm run wp-env -- run tests-cli --env-cwd=content/plugins/wp-graphql/ -- composer install
```

--------------------------------

### Build Website

Source: https://github.com/wp-graphql/wp-graphql/blob/main/websites/wpgraphql.com/README.md

Execute the production build process for the website.

```bash
npm run build -w @wpgraphql/wpgraphql-com
```

--------------------------------

### Generate recipe documentation

Source: https://github.com/wp-graphql/wp-graphql/blob/main/scripts/README.md

Builds recipe index files and copies them to the website directory.

```bash
npm run recipes:generate -- --plugin=wp-graphql
```

--------------------------------

### Install Composer Dependencies

Source: https://github.com/wp-graphql/wp-graphql/blob/main/docs/DEVELOPMENT.md

Runs composer install within the plugin directory via the wp-env CLI.

```bash
npm run wp-env -- run tests-cli --env-cwd=wp-content/plugins/wp-graphql/ -- composer install
```

--------------------------------

### Project file layout

Source: https://github.com/wp-graphql/wp-graphql/blob/main/websites/wpgraphql.com/src/lib/wpgraphql-client/docs/testing.md

Overview of the directory structure for the wpgraphql-client package.

```text
wpgraphql-client/
  index.js                      aggregate public API

  core/
    index.js                    re-exports core surface
    client.js                   fetch client
    endpoint.js                 env-var endpoint resolver
    hash.js                     sha256 (Web Crypto)
    print.js                    gql AST → string + getOperation
    seed-query.js               SEED_QUERY + normalizeSeed
    hierarchy.js                pure resolveTemplateName / buildCandidateNames
    templates.js                configure / getRegistry
    run-queries.js              parallel runner used by both
                                resolveTemplate and getLayoutData
    resolve-template.js         framework-agnostic orchestrator
    get-layout-data.js          run-only-Layout-queries helper

  react/
    index.js                    re-exports
    layout.js                   LayoutProvider / useLayoutData

  next/
    index.js                    re-exports
    get-template-static-props.js
                                Next.js getStaticProps wrapper around
                                core/resolveTemplate

  package.json                  type:module so node:test sees ESM
  __tests__/                    node:test unit tests
  docs/                         topic-specific documentation
```

--------------------------------

### Example Comment Status Update Response

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql/docs/comments.md

This is an example of a successful response after updating a comment's status.

```json
{
  "data": {
    "updateComment": {
      "comment": {
        "id": "Y29tbWVudDoy",
        "status": "SPAM",
        "content": "This is the comment content",
        "date": "2023-04-01T12:00:00"
      }
    }
  }
}
```

--------------------------------

### Fork and Branch for Experiment

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql/docs/experiments-contributing.md

Steps to set up your local repository for contributing an experiment, including forking, cloning, adding upstream, and creating a new feature branch.

```bash
# Fork the repository on GitHub first

# Clone your fork
git clone git@github.com:YOUR-USERNAME/wp-graphql.git
cd wp-graphql

# Add upstream remote
git remote add upstream git@github.com:wp-graphql/wp-graphql.git

# Create feature branch
git checkout -b experiment/email-address-scalar
```

--------------------------------

### Manual ACF installation via WP-CLI

Source: https://github.com/wp-graphql/wp-graphql/blob/main/docs/TESTING.md

Install ACF plugins manually using the wp-env CLI tool.

```bash
# Install ACF Free only (no ACF Extended with ACF Free)
npm run wp-env run tests-cli -- wp plugin install advanced-custom-fields --activate --allow-root

# With ACF Pro: install ACF Pro first, then optionally ACF Extended Free or Pro
export ACF_LICENSE_KEY=your_license_key
npm run wp-env run tests-cli -- wp plugin install "https://connect.advancedcustomfields.com/v2/plugins/download?p=pro&k=${ACF_LICENSE_KEY}" --activate --allow-root
# Then: npm run wp-env run tests-cli -- wp plugin install acf-extended --activate --allow-root  # Extended Free
```

--------------------------------

### Install Composer dependencies

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql/docs/contributing.md

Methods for installing PHP dependencies either inside the Docker container or on the local host.

```shell
## To install Composer dependencies inside the Docker container:
npm run wp-env -- run tests-cli --env-cwd=wp-content/plugins/wp-graphql/ -- composer install

## Or: if you're running Composer locally:
composer -d plugins/wp-graphql install
```

--------------------------------

### Run WPGraphQL in Dev Mode

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql/packages/README.md

Execute this command to start the development server. This enables hot-reloading for faster feedback loops when making code changes.

```bash
npm run start
```

--------------------------------

### Install ACF Pro and Extended Pro via .env

Source: https://github.com/wp-graphql/wp-graphql/blob/main/docs/TESTING.md

Configure both license keys in the .env file for full Pro feature support.

```bash
# Create or edit plugins/wp-graphql-acf/.env
cat >> plugins/wp-graphql-acf/.env << EOF
ACF_LICENSE_KEY=your_acf_pro_license_key
ACF_EXTENDED_LICENSE_KEY=your_acf_extended_pro_license_key
EOF

# Install ACF Pro + ACF Extended Pro
npm run -w @wpgraphql/wp-graphql-acf install-acf:pro-extended
```

--------------------------------

### Install ACF Free and run tests

Source: https://github.com/wp-graphql/wp-graphql/blob/main/docs/TESTING.md

Use this configuration for local development without requiring license keys.

```bash
# From repo root: install ACF Free only (no ACF Extended)
cd plugins/wp-graphql-acf && npm run install-test-deps && cd ../..

# Or use the alias
npm run -w @wpgraphql/wp-graphql-acf install-acf

# Then run tests
npm run -w @wpgraphql/wp-graphql-acf test:codecept:wpunit
```

--------------------------------

### GraphQL Response Example for User Data

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql/src/Experimental/Experiment/EmailAddressScalarExperiment/README.md

Example JSON response structure for a user query, including the custom 'workEmail' field.

```json
{
  "data": {
    "user": {
      "id": "dXNlcjox",
      "name": "John Doe",
      "workEmail": "john.doe@company.com"
    }
  }
}
```

--------------------------------

### Project File Structure

Source: https://github.com/wp-graphql/wp-graphql/blob/main/design/brand/wpgraphql/README.md

The expected directory layout for the WPGraphQL theme files.

```text
wpgraphql-theme/
├── globals.css          ← CSS custom properties + Tailwind imports
├── tailwind.config.ts   ← Full Tailwind config with WPGraphQL tokens
├── components.json      ← shadcn/ui CLI config
└── tokens.ts            ← TypeScript token reference
```

--------------------------------

### GraphQL Trace Data Example

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql/docs/debugging.md

Example of trace data returned for a GraphQL request, showing overall duration and field-specific timings.

```json
  ...,
  "tracing": {
    "version": 1,
    "startTime": "1600294443.335",
    "endTime": "1600294443.381",
    "duration": 45998,
    "execution": {
      ...

```

--------------------------------

### Clone the repository

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql/docs/contributing.md

Initial steps to download the source code and navigate to the project directory.

```shell
git clone git@github.com:wp-graphql/wp-graphql.git
cd wp-graphql
```

--------------------------------

### Configure Preview API Routes

Source: https://github.com/wp-graphql/wp-graphql/blob/main/websites/wpgraphql.com/src/lib/wpgraphql-client/docs/preview.md

Implement the preview and exit-preview API routes using the provided helper functions from the WPGraphQL client library.

```javascript
// pages/api/preview.js
import { enterPreviewMode } from "lib/wpgraphql-client/next"
export default (req, res) => enterPreviewMode(req, res)

// pages/api/exit-preview.js
import { exitPreviewMode } from "lib/wpgraphql-client/next"
export default (req, res) => exitPreviewMode(req, res)
```

--------------------------------

### Copy Theme Files

Source: https://github.com/wp-graphql/wp-graphql/blob/main/design/brand/wpgraphql/README.md

Commands to copy configuration and CSS files to the project directory.

```bash
# Copy to your project root
cp tailwind.config.ts  ./tailwind.config.ts
cp components.json     ./components.json

# Copy globals.css to your app directory
cp globals.css         ./app/globals.css   # Next.js App Router
# or
cp globals.css         ./src/index.css     # Vite
```

--------------------------------

### Multiple Variables Example

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql/docs/graphql-queries.md

An example showing how to define and use multiple variables within a single GraphQL query to filter and limit results.

```APIDOC
## Multiple Variables

### Description
This query fetches posts, allowing filtering by status and limiting the number of results using variables.

### GraphQL Query
```graphql
query GetPosts($status: PostStatusEnum, $first: Int) {
  posts(where: { status: $status }, first: $first) {
    nodes {
      id
      title
    }
  }
}
```
```

--------------------------------

### Query Comment Author Email Example

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql/src/Experimental/Experiment/EmailAddressScalarFieldsExperiment/README.md

Example GraphQL query to retrieve comment author email addresses, highlighting that `emailAddress` is only visible to moderators.

```APIDOC
## Query Comment Author Email

```graphql
query GetComments {
  comments(first: 5) {
    nodes {
      id
      content
      author {
        node {
          name
          emailAddress  # Only visible to moderators
        }
      }
    }
  }
}
```
```

--------------------------------

### Install ACF Pro via environment variable

Source: https://github.com/wp-graphql/wp-graphql/blob/main/docs/TESTING.md

Set the license key as a session environment variable.

```bash
export ACF_LICENSE_KEY=your_license_key_here
npm run -w @wpgraphql/wp-graphql-acf install-acf:pro
```

--------------------------------

### GraphiQL Syntax Error Example

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql/docs/debugging.md

Example of a 'SyntaxError: Unexpected token < in JSON at position 0' error message in GraphiQL, indicating a non-JSON response.

```text
SyntaxError: Unexpected token < in JSON at position 0
```

--------------------------------

### GraphQL Query Example for User with Custom Email Field

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql/src/Experimental/Experiment/EmailAddressScalarExperiment/README.md

Example GraphQL query to retrieve a user's ID, name, and custom 'workEmail' field.

```graphql
query GetUser($id: ID!) {
  user(id: $id) {
    id
    name
    workEmail # Custom field using EmailAddress scalar
  }
}
```

--------------------------------

### PHP Template File Example

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql/docs/themes.md

Example of a PHP template file header comment used to define a custom page template in classic WordPress themes.

```php
<?php
/**
 * Template Name: My Custom Template
 */

```

--------------------------------

### Creating a Post with WPGraphQL

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql/docs/graphql-mutations.md

Example mutation for creating a new post, including optional fields like categories and tags. Variables are used for input data.

```graphql
mutation CreatePost($input: CreatePostInput!) {
  createPost(input: $input) {
    post {
      id
      title
      status
      uri
    }
  }
}
```

```json
{
  "input": {
    "title": "My New Post",
    "content": "Post content here...",
    "status": "PUBLISH",
    "categories": {
      "nodes": [
        { "id": "category-id-here" }
      ]
    },
    "tags": {
      "nodes": [
        { "id": "tag-id-here" }
      ]
    }
  }
}
```

```json
{
  "data": {
    "createPost": {
      "post": {
        "id": "cG9zdDo1",
        "title": "My New Post",
        "status": "PUBLISH",
        "uri": "/my-new-post"
      }
    }
  }
}
```

```json
{
  "errors": [
    {
      "message": "Sorry, you are not allowed to create posts",
      "category": "user"
    }
  ]
}
```

--------------------------------

### GraphQL Query Log Data Example

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql/docs/debugging.md

Example of query log data output in the 'extensions' portion of a GraphQL response, detailing executed SQL queries.

```json
{
  "sql": "SELECT  FROM wp_posts WHERE id = 1 LIMIT 1",
  "time": "0.000123",
  "stack": "#0 WP_Query->get_posts called at ..."
}
```

--------------------------------

### Experiment README.md Example

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql/docs/experiments-creating.md

This markdown file documents an experiment, detailing its purpose, schema changes, usage, dependencies, and limitations. It's crucial for understanding and using the experiment.

```markdown
# Email Address Scalar Experiment

**Status**: Active  
**Slug**: `email_address_scalar`  
**Since**: x-release-please-version

## Overview

This experiment adds a custom EmailAddress scalar type to the GraphQL schema for better validation and type safety when working with email fields.

## What It Does

When activated, this experiment:

1. Registers an `EmailAddress` scalar type that validates email addresses
2. Updates the `User.email` field to use the EmailAddress scalar
3. Provides better type safety and validation for email fields

## Schema Changes

### New Types

**`EmailAddress` (Scalar)**
- Validates email format using WordPress's `is_email()` function
- Sanitizes email addresses before returning to clients
- Throws validation errors for invalid email formats

### Modified Fields

**`User.email`**
- **Before**: `String`
- **After**: `EmailAddress`

### Example Query

\```graphql
query GetUser($id: ID!) {
  user(id: $id) {
    email # Now returns EmailAddress type with validation
  }
}
\```

## Usage

See the main [Using Experiments](/docs/experiments-using.md) guide for general instructions.

## Dependencies

**Required Dependencies**: None  
**Optional Dependencies**: None

## Known Limitations

- Only validates format, not email deliverability
- Uses WordPress's `is_email()` which may differ from HTML5 validation
- Breaking change if graduating: `String` → `EmailAddress` type change

## Feedback

Please provide feedback on this experiment:
- GitHub: https://github.com/wp-graphql/wp-graphql/issues

## References

- [What are Experiments?](/docs/experiments.md)
- [Creating Experiments](/docs/experiments-creating.md)

```

--------------------------------

### GraphQL Field Trace Data Example

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql/docs/debugging.md

Example of trace data for a specific field within a GraphQL request, detailing its path, parent type, and duration.

```json
...,
{
  "path": [
    "posts",
    "nodes",
    0,
    "title"
  ],
  "parentType": "Post",
  "fieldName": "title",
  "returnType": "String",
  "startOffset": 27518,
  "duration": 797
},
...
```

--------------------------------

### graphql_init

Source: https://github.com/wp-graphql/wp-graphql/wiki/Action-and-Filter-Reference

Fires when the WPGraphQL plugin is initialized. Useful for setting up plugin-specific configurations.

```APIDOC
## `graphql_init`

### Description

Fire off init action.

### Parameters

- **$instance** (WPGraphQL) - The instance of the WPGraphQL class.

### Code Example

```php
do_action( 'graphql_init', self::$instance );
```
```

--------------------------------

### GraphQL Query Example

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql-smart-cache/docs/persisted-queries.md

These are two examples of the same GraphQL query with different formatting. They will be stored as a single GraphQL Document in WordPress, but clients may generate different hashes for each.

```graphql
{posts{nodes{id,title,__typename}}}
```

```graphql
{
  posts {
    nodes {
      id
      title
      __typename
    }
  }
}
```

--------------------------------

### Query User Email Example

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql/src/Experimental/Experiment/EmailAddressScalarFieldsExperiment/README.md

Example GraphQL query to retrieve a user's email address using the new `emailAddress` field, and the deprecated `email` field.

```APIDOC
## Query User Email

```graphql
query GetUser($id: ID!) {
  user(id: $id) {
    id
    name
    emailAddress  # New field using EmailAddress scalar
    email         # Deprecated but still works
  }
}
```

**Response:**
```json
{
  "data": {
    "user": {
      "id": "dXNlcjox",
      "name": "John Doe",
      "emailAddress": "john@example.com",
      "email": "john@example.com"
    }
  }
}
```
```

--------------------------------

### Use Case: Building a User Directory

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql/src/Experimental/Experiment/EmailAddressScalarFieldsExperiment/README.md

Example query to retrieve a list of users, including their ID, name, and validated `emailAddress`.

```graphql
query GetAllUsers {
  users(first: 100) {
    nodes {
      id
      name
      emailAddress  # Validated email addresses
    }
  }
}
```

--------------------------------

### Query Site Admin Email Example

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql/src/Experimental/Experiment/EmailAddressScalarFieldsExperiment/README.md

Example GraphQL query to fetch the site's admin email address using the `adminEmail` field, noting it's only visible to administrators.

```APIDOC
## Query Site Admin Email

```graphql
query GetSiteSettings {
  generalSettings {
    title
    url
    adminEmail  # Only visible to site administrators
    email       # Deprecated but still works
  }
}
```
```

--------------------------------

### Run Network Cache with Varnish

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql-smart-cache/docs/development.md

Initiate a network cache using Varnish to simulate caching behavior for GraphQL requests. This requires Docker Compose and Varnish to be available.

```bash
WP_VERSION=6.1 PHP_VERSION=8.1 docker compose up varnish
```

--------------------------------

### Example: Feature Enhancement

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql/src/Experimental/Experiment/TestDependantExperiment/README.md

Demonstrates how an experiment enhancing existing functionality can declare its dependencies. This example shows a feature that adds validation rules, requiring a base scalar type to be present.

```php
class EmailValidationRulesExperiment extends AbstractExperiment {
    public function get_dependencies(): array {
        return [
            'required' => [ 'email_address_scalar' ],
        ];
    }
}
```

--------------------------------

### GraphQL Mutation Example for Updating User Work Email

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql/src/Experimental/Experiment/EmailAddressScalarExperiment/README.md

Example GraphQL mutation to update a user's work email address using the 'updateUserWorkEmail' mutation and EmailAddress scalar.

```graphql
mutation UpdateWorkEmail($userId: ID!, $workEmail: EmailAddress!) {
  updateUserWorkEmail(input: { userId: $userId, workEmail: $workEmail }) {
    success
    email
  }
}
```

--------------------------------

### Example response for settings group query

Source: https://github.com/wp-graphql/wp-graphql/blob/main/plugins/wp-graphql/docs/settings.md

Sample JSON response structure for a specific settings group query.

```json
{
  "data": {
    "generalSettings": {
      "dateFormat": "F j, Y",
      "description": "Just another WordPress site",
      "language": "",
      "startOfWeek": 0,
      "timeFormat": "g:i a",
      "timezone": "America/Denver",
      "title": "Example Site Title",
      "url": "http://example.com"
    }
  }
}
```
Tokens:
Raw