chore(examples): standardize npm scripts across examples

.github/workflows/example-scripts.yml

@@ -0,0 +1,37 @@
+# Checks that every example follows the standard npm scripts
+# (see examples/README.md "Running an example").
+
+name: Example Scripts
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'examples/**'
+      - 'plugins/*/examples/**'
+      - 'scripts/check-example-scripts.js'
+  pull_request:
+    paths:
+      - 'examples/**'
+      - 'plugins/*/examples/**'
+      - 'scripts/check-example-scripts.js'
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    name: Check example scripts
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+
+      - name: Check example scripts
+        run: node scripts/check-example-scripts.js

examples/README.md

@@ -39,6 +39,31 @@ This directory contains examples demonstrating how to use various features of th
 | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | [nuxt-headlesswp-gravity-forms](nuxt/nuxt-headlesswp-gravity-forms) | Shows you how to wire up a full headless WordPress backend—complete with Gravity Forms, WPGraphQL, and a pre-built "Questionnaire" form—alongside a Nuxt 3 front end. |
 
+## Running an example
+
+Every example has the same npm scripts. Run them from the example's directory (the one containing `.wp-env.json`). You'll need [Docker](https://www.docker.com/) for the local WordPress.
+
+```bash
+npm run setup   # once: install dependencies, start WordPress, import the database
+npm run dev     # start WordPress and the front end
+```
+
+| Script | What it does |
+| --- | --- |
+| `setup` | Installs dependencies, unzips any media into `wp-env/uploads`, starts WordPress and imports `wp-env/db/database.sql`. Doesn't start the front end. |
+| `dev` | Starts WordPress and the front end. |
+| `app:dev` | Starts only the front end. Use it to restart the app while WordPress keeps running. |
+| `stop` | Stops WordPress. Stopping the front end doesn't stop WordPress. |
+| `clean` | Removes the WordPress environment. Run `setup` again to start fresh. |
+| `wp:start` | Starts only WordPress. |
+| `db:import` / `db:export` | Imports or exports `wp-env/db/database.sql`. |
+| `db:query` | Runs a SQL query against the WordPress database, e.g. `npm run db:query -- "SELECT 1"`. |
+| `assets:unzip` / `assets:zip` | Unzips or re-zips `wp-env/uploads.zip`, for examples that include media. |
+
+Some examples add their own scripts on top; their READMEs list them. For any other wp-env command, use `npx wp-env`.
+
+If port 8888 is already in use, for example by another wp-env site, set `WP_ENV_PORT` for every command, e.g. `WP_ENV_PORT=8977 npm run setup`, and point the front end's WordPress URL at the same port.
+
 ## Contributing
 
 If you feel like something is missing or you want to add an example for another framework, we encourage you to contribute! Please check out our [Contributing Guide](https://github.com/wpengine/hwptoolkit/blob/main/CONTRIBUTING.md) for more details.
@@ -85,26 +110,26 @@ You can copy on of existing examples to use it as a _skeleton_ of your new examp
 
 3. **Scripts**
 
-   Scripts in your package.json help automate common tasks. You can use our standard scripts to achieve the recommended workflow..
+   Scripts in your package.json help automate common tasks. Use the standard scripts so every example works the same way:
 
    ```json
    "scripts": {
-       "example:build": "npm run example:dev:install && npm run wp:start && npm run wp:db:import && npm run example:start",
-       "example:dev:install": "cd example-app && npm install && cd ..",
-       "example:start": "npm run wp:start && npm run example:dev",
-       "example:stop": "npm run wp:stop",
-       "example:prune": "wp-env destroy && npm run example:build && npm run example:start",
-       "example:dev": "npm --prefix ./example-app run dev",
-       "wp:start": "npm install && wp-env start",
-       "wp:stop": "wp-env stop",
-       "wp:destroy": "wp-env destroy --config ./wp-env/wp-env.json",
-       "wp:db:query": "wp-env run cli -- wp db query",
-       "wp:db:export": "wp-env run cli -- wp db export /var/www/html/db/database.sql",
-       "wp:db:import": "wp-env run cli -- wp db import /var/www/html/db/database.sql",
-       "wp-env": "wp-env"
+       "setup": "npm install && npm --prefix ./example-app install && npm run wp:start && npm run db:import",
+       "dev": "npm run wp:start && npm run app:dev",
+       "app:dev": "npm --prefix ./example-app run dev",
+       "stop": "wp-env stop",
+       "clean": "wp-env destroy",
+       "wp:start": "wp-env start",
+       "db:import": "wp-env run cli -- wp db import /var/www/html/db/database.sql",
+       "db:export": "wp-env run cli -- wp db export /var/www/html/db/database.sql",
+       "db:query": "wp-env run cli -- wp db query"
    },
    ```
 
+   If the example includes media in `wp-env/uploads.zip`, add `assets:unzip` and `assets:zip`, and run `npm run assets:unzip` in `setup` before `wp:start`. See [Running an example](#running-an-example) for what each script does.
+
+   Run `pnpm check:examples` from the repository root to check that your example follows these scripts. CI runs the same check on pull requests.
+
 4. **Documentation (README.md)**
 
    A clear README.md with essential information would guide the new developers effectively and reduce the errors. Consider including the information below:

examples/angular/template-hierarchy-data-fetching/.wp-env.json

@@ -30,6 +30,6 @@
     ".htaccess": "./wp-env/setup/.htaccess"
   },
   "lifecycleScripts": {
-    "afterStart": "wp-env run cli -- wp theme activate twentytwentyone && wp-env run cli -- wp theme delete --all && wp-env run cli -- wp plugin delete hello-dolly && wp-env run cli -- wp rewrite structure '/%postname%/' && wp-env run cli -- wp rewrite flush"
+    "afterStart": "wp-env run cli -- wp theme activate twentytwentyone && wp-env run cli -- wp plugin delete hello-dolly && wp-env run cli -- wp rewrite structure '/%postname%/' && wp-env run cli -- wp rewrite flush"
   }
 }

examples/angular/template-hierarchy-data-fetching/README.md

@@ -12,23 +12,23 @@ In this example we show how to implement the **WordPress Template Hierarchy in A
 > [!IMPORTANT]
 > **Docker Desktop** needs to be installed to run WordPress locally.
 
-1. Run `npm run example:setup` to install dependencies and configure the local WP server.
-2. **Configure CORS:** Create a file named **`.env`** inside the **`/backend`** directory and add the following content to set the allowed frontend URL:
+1. Run `npm run setup` to install dependencies and configure the local WP server.
+2. **Configure CORS:** `setup` copies **`/backend/.env.example`** to **`/backend/.env`**, which sets the allowed frontend URL. Change it if your Angular app runs elsewhere:
     ```
     FRONTEND_URL=http://localhost:4200
     ```
     *(For more details on the backend service, please refer to the **`/backend/README.md`** file.)*
-3. Run `npm run backend:start` starts the backend server for template fetching at **http://localhost:3000/api/templates**
-4. Run `npm run example:start` to start the WordPress server and Angular development server.
+3. Run `npm run backend:dev` to start the backend server for template fetching at **http://localhost:3000/api/templates**
+4. Run `npm run dev` to start the WordPress server and Angular development server.
 
 > [!NOTE]
-> When you kill the long running process this will not shutdown the local WP instance, only Angular. You must run `npm run example:stop` to kill the local WP server.
+> When you kill the long running process this will not shutdown the local WP instance, only Angular. Run `npm run app:dev` to restart only the front end, or `npm run stop` to stop the local WP server.
 
 ## Trouble Shooting
 
 1. I get "Page Not Found. Sorry, the page you are looking for does not exist. Please check the URL." when opening the Angular app and trying to navigate through it.
-- Run `npm run backend:start` and verify that **http://localhost:3000/api/templates** returns correct data.
-- **Verify that you have created the `/backend/.env` file with the correct `FRONTEND_URL`** to resolve CORS issues.
+- Run `npm run backend:dev` and verify that **http://localhost:3000/api/templates** returns correct data.
+- **Verify that `/backend/.env` exists and has the correct `FRONTEND_URL`** to resolve CORS issues.
 - Check for any errors in the console.
 2. In some cases, you might have to install **`@angular/cli`** globally. In `/example-app/` run `npm install -g @angular/cli@latest`
-3. To reset the WP server and re-run setup you can run `npm run example:prune` and confirm "Yes" at any prompts.
+3. To reset the WP server, run `npm run clean` and confirm "Yes" at the prompt, then run `npm run setup` again.

examples/angular/template-hierarchy-data-fetching/backend/.env.example

@@ -1 +1 @@
-FRONTEND_URL=
+FRONTEND_URL=http://localhost:4200

examples/angular/template-hierarchy-data-fetching/package.json

@@ -3,21 +3,18 @@
   "type": "module",
   "version": "1.0.0",
   "scripts": {
-    "example:bootstrap": "npm install & npm run app:install",
-    "example:start": "npm run wp:start && npm run app:dev",
-    "example:setup": "npm run example:bootstrap && npm run wp:uploads:unzip && npm run wp:start && npm run wp:db:import && npm run example:stop",
-    "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 && ng serve --open",
-    "app:install": "npm install && cd backend && npm install",
-    "backend:start": "cd backend && npm run dev",
+    "setup": "npm install && npm --prefix ./example-app install && npm --prefix ./backend install && node -e \"const fs=require('fs');fs.existsSync('backend/.env')||fs.copyFileSync('backend/.env.example','backend/.env')\" && npm run assets:unzip && npm run wp:start && npm run db:import",
+    "dev": "npm run wp:start && npm run app:dev",
+    "app:dev": "npm --prefix ./example-app start",
+    "stop": "wp-env stop",
+    "clean": "wp-env destroy",
     "wp:start": "wp-env start",
-    "wp:stop": "wp-env stop",
-    "wp:destroy": "wp-env destroy --config ./wp-env/wp-env.json",
-    "wp:db:export": "wp-env run cli -- wp db export /var/www/html/db/database.sql",
-    "wp:db:import": "wp-env run cli -- wp db import /var/www/html/db/database.sql",
-    "wp:uploads:unzip": "rm -rf wp-env/uploads/ && unzip wp-env/uploads.zip;",
-    "wp:uploads:zip": "zip -r wp-env/uploads.zip wp-env/uploads"
+    "db:import": "wp-env run cli -- wp db import /var/www/html/db/database.sql",
+    "db:export": "wp-env run cli -- wp db export /var/www/html/db/database.sql",
+    "db:query": "wp-env run cli -- wp db query",
+    "assets:zip": "zip -r wp-env/uploads.zip wp-env/uploads",
+    "assets:unzip": "rm -rf wp-env/uploads && unzip -oq wp-env/uploads.zip",
+    "backend:dev": "npm --prefix ./backend run dev"
   },
   "devDependencies": {
     "@wordpress/env": "^12.0.0"

examples/astro/template-hierarchy-data-fetching-urql/README.md

@@ -12,12 +12,12 @@ In this example we show how to implement the WP Template Hierarchy in Astro for
 > [!IMPORTANT]
 > Docker Desktop needs to be installed to run WordPress locally.
 
-1. Run `npm run example:setup` to install dependencies and configure the local WP server.
-2. Run `npm run example:start` to start the WP server and Astro development server.
+1. Run `npm run setup` to install dependencies and configure the local WP server.
+2. Run `npm run dev` to start the WP server and Astro development server.
 
 > [!NOTE]
-> When you kill the long running process this will not shutdown the local WP instance, only Astro. You must run `npm run example:stop` to kill the local WP server.
+> When you kill the long running process this will not shutdown the local WP instance, only Astro. Run `npm run app:dev` to restart only the front end, or `npm run stop` to stop the local WP server.
 
 ## Trouble Shooting
 
-To reset the WP server and re-run setup you can run `npm run example:prune` and confirm "Yes" at any prompts.
+To reset the WP server, run `npm run clean` and confirm "Yes" at the prompt, then run `npm run setup` again.

examples/astro/template-hierarchy-data-fetching-urql/package.json

@@ -3,18 +3,15 @@
   "type": "module",
   "version": "0.0.1",
   "scripts": {
-    "example:bootstrap": "npm install & npm run app:install",
-    "example:start": "npm run wp:start && npm run app:dev",
-    "example:setup": "npm run example:bootstrap && npm run wp:start && npm run wp:db:import && npm run example:stop",
-    "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  && pwd &&  npm run dev && cd ..",
-    "app:install": "cd ./example-app && npm install && cd ..",
+    "setup": "npm install && npm --prefix ./example-app install && npm run wp:start && npm run db:import",
+    "dev": "npm run wp:start && npm run app:dev",
+    "app:dev": "npm --prefix ./example-app run dev",
+    "stop": "wp-env stop",
+    "clean": "wp-env destroy",
     "wp:start": "wp-env start",
-    "wp:stop": "wp-env stop",
-    "wp:destroy": "wp-env destroy --config ./wp-env/wp-env.json",
-    "wp:db:export": "wp-env run cli -- wp db export /var/www/html/db/database.sql",
-    "wp:db:import": "wp-env run cli -- wp db import /var/www/html/db/database.sql"
+    "db:import": "wp-env run cli -- wp db import /var/www/html/db/database.sql",
+    "db:export": "wp-env run cli -- wp db export /var/www/html/db/database.sql",
+    "db:query": "wp-env run cli -- wp db query"
   },
   "devDependencies": {
     "@wordpress/env": "^12.0.0"

examples/next/apollo-authentication/README.md

@@ -58,12 +58,7 @@ echo "NEXT_PUBLIC_WORDPRESS_URL=http://localhost:8888" > examples/next/apollo-au
 ### Build and start the application
 
 - `cd examples/next/apollo-authentication`
-- Then run `npm run example:build` will build and start your application.
-- This does the following:
-  - Starts up [wp-env](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-wp-env/)
-  - Imports the database from [wp-env/db/database.sql](wp-env/db/database.sql)
-  - Install Next.js dependencies for `example-app`
-  - Runs the Next.js dev script
+- Run `npm run setup` to set up the example, then `npm run dev` to start it.
 
 Congratulations, WordPress should now be fully set up.
 
@@ -75,22 +70,9 @@ Congratulations, WordPress should now be fully set up.
 
 ### Command Reference
 
-| Command               | Description                                                                                                             |
-| --------------------- | ----------------------------------------------------------------------------------------------------------------------- |
-| `example:build`       | Prepares the environment by starting WordPress, importing the database, and starting the application. |
-| `example:dev`         | Runs the Next.js development server.                                                                                    |
-| `example:dev:install` | Installs the required Next.js packages.                                                                                 |
-| `example:start`       | Starts WordPress and the Next.js development server.                                                                    |
-| `example:stop`        | Stops the WordPress environment.                                                                                        |
-| `example:prune`       | Rebuilds and restarts the application by destroying and recreating the WordPress environment.                           |
-| `wp:start`            | Starts the WordPress environment.                                                                                       |
-| `wp:stop`             | Stops the WordPress environment.                                                                                        |
-| `wp:destroy`          | Completely removes the WordPress environment.                                                                           |
-| `wp:db:query`         | Executes a database query within the WordPress environment.                                                             |
-| `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 any other wp-env command. You can also see <https://www.npmjs.com/package/@wordpress/env> for more details on how to use or configure `wp-env`.
+This example uses the [standard example scripts](../../README.md#running-an-example): run `npm run setup` once, then `npm run dev`. Use `npm run app:dev` to restart only the front end while WordPress keeps running, `npm run stop` to stop WordPress, and `npm run clean` to remove it.
+
+> **Note** You can run `npx wp-env` for any other wp-env command. See <https://www.npmjs.com/package/@wordpress/env> for details.
 
 ### Database access
 

examples/next/apollo-authentication/package.json

@@ -3,19 +3,15 @@
   "version": "1.0.0",
   "description": "An example demonstrating authentication with username and password in a headless WordPress setup, running Next.js as a frontend framework.",
   "scripts": {
-    "example:build": "npm run example:dev:install && npm run wp:start && npm run wp:db:import && npm run example:start",
-    "example:dev:install": "cd example-app && npm install && cd ..",
-    "example:start": "npm run wp:start && npm run example:dev",
-    "example:stop": "npm run wp:stop",
-    "example:prune": "wp-env destroy && npm run example:build && npm run example:start",
-    "example:dev": "npm --prefix ./example-app run dev",
-    "wp:start": "npm install && wp-env start",
-    "wp:stop": "wp-env stop",
-    "wp:destroy": "wp-env destroy --config ./wp-env/wp-env.json",
-    "wp:db:query": "wp-env run cli -- wp db query",
-    "wp:db:export": "wp-env run cli -- wp db export /var/www/html/db/database.sql",
-    "wp:db:import": "wp-env run cli -- wp db import /var/www/html/db/database.sql",
-    "wp-env": "wp-env"
+    "setup": "npm install && npm --prefix ./example-app install && npm run wp:start && npm run db:import",
+    "dev": "npm run wp:start && npm run app:dev",
+    "app:dev": "npm --prefix ./example-app run dev",
+    "stop": "wp-env stop",
+    "clean": "wp-env destroy",
+    "wp:start": "wp-env start",
+    "db:import": "wp-env run cli -- wp db import /var/www/html/db/database.sql",
+    "db:export": "wp-env run cli -- wp db export /var/www/html/db/database.sql",
+    "db:query": "wp-env run cli -- wp db query"
   },
   "keywords": [
     "headless",