chore: Tidy up examples

.gitignore

@@ -15,6 +15,7 @@ test-results/
 .wp-env.override.json
 uploads/
 debug.log
+__MACOSX
 
 # Environment
 .env
@@ -27,4 +28,5 @@ debug.log
 
 ## Examples
 examples/**/package-lock.json
-examples/**/__MACOSX
+examples/**/__MACOSX
+``

examples/README.md

@@ -12,31 +12,113 @@ This directory contains examples demonstrating how to use various features of th
 
 ## Next.js Examples
 
-| Title                                                                                 | Description                                                                                                  |
-| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| [apollo-authentication](next/apollo-authentication)                                   | Showcases authentication with Next.js, Apollo Client, and Headless WordPress.                                |
-| [apollo-client-data-fetch](next/apollo-client-data-fetch)                             | Explores data fetching strategies and state management using Next.js, Apollo Client, and Headless WordPress. |
-| [apollo-client-filesystem-routing](next/apollo-client-filesystem-routing)             | Integrates WPGraphQL and WPGraphQL for ACF with Next.js for a headless WordPress site.                       |
-| [client-app-router-fetch-data](next/client-app-router-fetch-data)                     | Uses Next.js App Router and fetch API to retrieve data from WordPress via WPGraphQL.                         |
-| [client-multisite-app-router-fetch-data](next/client-multisite-app-router-fetch-data) | Implements a multisite headless WordPress app with Next.js App Router and fetch API.                         |
-| [custom-sitemap-apollo](next/custom-sitemap-apollo)                                   | Generates a custom sitemap using Next.js, Apollo Client, and WPGraphQL with an extended plugin.              |
-| [custom-sitemap-vanilla-wpgraphql](next/custom-sitemap-vanilla-wpgraphql)             | Creates a custom sitemap using Next.js and WPGraphQL without extending its endpoints.                        |
-| [hybrid-sitemap-apollo](next/hybrid-sitemap-apollo)                                   | Fetches and transforms WordPress sitemaps for clean URL formatting with Next.js.                             |
-| [proxied-sitemap-apollo](next/proxied-sitemap-apollo)                                 | Provides a proxied sitemap by transforming WordPress XML sitemaps for SEO-friendly frontend URLs.            |
-| [proxied-graphql-debug](next/proxied-graphql-debug)                                 | Provides a proxied GraphQL API for development, enabling response inspection and query complexity analysis.            |
-| [render-blocks-pages-router](next/render-blocks-pages-router)                         | Renders WordPress Blocks with JSX in Next.js, including utilities for hierarchical block data.               |
+| Title                                                                                 | Description                                                                                                                  |
+| ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| [apollo-authentication](next/apollo-authentication)                                   | Showcases authentication with Next.js, Apollo Client, and Headless WordPress.                                                |
+| [apollo-client-data-fetch](next/apollo-client-data-fetch)                             | Explores data fetching strategies and state management using Next.js, Apollo Client, and Headless WordPress.                 |
+| [apollo-client-filesystem-routing](next/apollo-client-filesystem-routing)             | Integrates WPGraphQL and WPGraphQL for ACF with Next.js for a headless WordPress site.                                       |
+| [client-app-router-fetch-data](next/client-app-router-fetch-data)                     | Uses Next.js App Router and fetch API to retrieve data from WordPress via WPGraphQL.                                         |
+| [client-multisite-app-router-fetch-data](next/client-multisite-app-router-fetch-data) | Implements a multisite headless WordPress app with Next.js App Router and fetch API.                                         |
+| [custom-sitemap-apollo](next/custom-sitemap-apollo)                                   | Generates a custom sitemap using Next.js, Apollo Client, and WPGraphQL with an extended plugin.                              |
+| [custom-sitemap-vanilla-wpgraphql](next/custom-sitemap-vanilla-wpgraphql)             | Creates a custom sitemap using Next.js and WPGraphQL without extending its endpoints.                                        |
+| [hybrid-sitemap-apollo](next/hybrid-sitemap-apollo)                                   | Fetches and transforms WordPress sitemaps for clean URL formatting with Next.js.                                             |
+| [proxied-sitemap-apollo](next/proxied-sitemap-apollo)                                 | Provides a proxied sitemap by transforming WordPress XML sitemaps for SEO-friendly frontend URLs.                            |
+| [proxied-graphql-debug](next/proxied-graphql-debug)                                   | Provides a proxied GraphQL API for development, enabling response inspection and query complexity analysis.                  |
+| [render-blocks-pages-router](next/render-blocks-pages-router)                         | Renders WordPress Blocks with JSX in Next.js, including utilities for hierarchical block data.                               |
+| [wp-theme-rendered-blocks](next/wp-theme-rendered-blocks)                             | Demonstrates how to fetch and apply WordPress Global Styles in a Next.js project using the `globalStylesheet` GraphQL field. |
 
 ## SvelteKit Examples
 
-| Title                                                                                    | Description                                                                                                                  |
-| ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| [template-hierarchy-data-fetching-urql](sveltekit/template-hierarchy-data-fetching-urql) | Demonstrates template hierarchy and data fetching with SvelteKit, URQL, and Headless WordPress.                              |
-| [wp-theme-rendered-blocks](next/wp-theme-rendered-blocks)                                | Demonstrates how to fetch and apply WordPress Global Styles in a Next.js project using the `globalStylesheet` GraphQL field. |
+| Title                                                                                    | Description                                                                                     |
+| ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| [template-hierarchy-data-fetching-urql](sveltekit/template-hierarchy-data-fetching-urql) | Demonstrates template hierarchy and data fetching with SvelteKit, URQL, and Headless WordPress. |
+
+## Nuxt Examples
+
+| Title                                                               | Description                                                                                                                                                           |
+| ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [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. |
 
 ## 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.
 
+### Best practices for the new examples
+
+You can copy on of existing examples to use it as a _skeleton_ of your new example. The guide below explains the key parts our standard example format.
+
+1. **Project Structure**
+
+   Organize your project with a clear separation between the frontend application and the WordPress environment configuration.
+
+   ```bash
+   .
+   ├── example-app/          # Front-end code
+   │   └── ...
+   ├── .wp-env.json          # Configuration for the local WordPress environment
+   └── wp-env/
+       └── db/
+           └── database.sql  # Initial database state
+   ```
+
+2. **Local WordPress with wp-env**
+
+   Use wp-env to create a local, containerized WordPress environment. Create a .wp-env.json file in your project root and include all of the required plugins and config to make your example work:
+
+   ```json
+   {
+     "phpVersion": "7.4",
+     "plugins": ["https://github.com/wp-graphql/wp-graphql/releases/latest/download/wp-graphql.zip"],
+     "config": {
+       "WP_DEBUG": true
+     },
+     "mappings": {
+       "db": "./wp-env/db",
+       "wp-content/uploads": "./wp-env/uploads",
+       ".htaccess": "./wp-env/setup/.htaccess"
+     },
+     "lifecycleScripts": {
+       "afterStart": "wp-env run cli -- wp rewrite structure '/%postname%/' && wp-env run cli -- wp rewrite flush"
+     }
+   }
+   ```
+
+3. **Scripts**
+
+   Scripts in your package.json help automate common tasks. You can use our standard scripts to achieve the recommended workflow..
+
+   ```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"
+   },
+   ```
+
+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:
+
+   - Prerequisites: Node.js, Docker.
+
+   - Setup Steps: A simple list on how to clone, install dependencies, and run the start script.
+
+   - Demo Credentials: Provide login details for the local WordPress admin (/wp-admin). Default for wp-env is admin / password.
+
+   - Security implications, and other considerations for the users, if applicable.
+
+   - Don't forget to include your example to this common README file as well, inside one of the tables above.
+
 ## Screenshots
 
 > **Feature Highlight:** Here are some sample screenshots of the examples listed above.

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

@@ -4,7 +4,7 @@
   "version": "0.0.1",
   "scripts": {
     "example:bootstrap": "npm install & npm run app:install",
-    "example:start": "pnpm run wp:start && npm run app:dev",
+    "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",

examples/next/apollo-authentication/README.md

@@ -55,7 +55,6 @@ echo "NEXT_PUBLIC_WORDPRESS_URL=http://localhost:8888" > examples/next/apollo-au
 - `cd examples/next/apollo-authentication`
 - Then run `npm run example:build` will build and start your application.
 - This does the following:
-  - Unzips `wp-env/uploads.zip` to `wp-env/uploads` which is mapped to the wp-content/uploads directory for the Docker container.
   - 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`
@@ -73,7 +72,7 @@ Congratulations, WordPress should now be fully set up.
 
 | Command               | Description                                                                                                             |
 | --------------------- | ----------------------------------------------------------------------------------------------------------------------- |
-| `example:build`       | Prepares the environment by unzipping images, starting WordPress, importing the database, and starting the application. |
+| `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.                                                                    |
@@ -85,8 +84,6 @@ Congratulations, WordPress should now be fully set up.
 | `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`.                                                           |
-| `wp:images:unzip`     | Extracts the WordPress uploads directory.                                                                               |
-| `wp:images:zip`       | Compresses the WordPress uploads directory.                                                                             |
 
 > **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`.
 

examples/next/apollo-authentication/package.json

@@ -15,8 +15,6 @@
     "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:images:unzip": "rm -rf wp-env/uploads/ && unzip wp-env/uploads.zip -d wp-env;",
-    "wp:images:zip": "zip -r wp-env/uploads.zip wp-env/uploads",
     "wp-env": "wp-env"
   },
   "keywords": [

examples/next/apollo-client-data-fetch/README.md

@@ -53,24 +53,22 @@ This example demonstrates various approaches to integrate WordPress as a headles
 └── wp-env
     ├── db
     │   └── database.sql                # WordPress database including all demo data for
-    ├── setup
-    └── uploads.zip                     # WordPress content to be used by wp-env
+    └── setup
 ```
 
 ## Running the example with wp-env
 
 ### Prerequisites
 
 - Node.js (v18+ recommended)
-- [pnpm](https://pnpm.io/)
 - [Docker](https://www.docker.com/) (if you plan on running the example see details below)
 
 **Note** Please make sure you have all prerequisites installed as mentioned above and Docker running (`docker ps`)
 
 ### Setup Repository and Packages
 
 - Clone the repo `git clone https://github.com/wpengine/hwptoolkit.git`
-- Install packages `cd hwptoolkit && pnpm install`
+- Install packages `cd hwptoolkit && npm install`
 - Setup a .env file under `examples/next/apollo-client-data-fetch/example-app` and add these values inside:
 
 ```bash
@@ -87,9 +85,8 @@ echo "NEXT_PUBLIC_WORDPRESS_URL=http://localhost:8888\\nNEXT_PRIVACY_POLICY_URI=
 ### Build and start the application
 
 - `cd examples/next/apollo-client-data-fetch`
-- Then run `pnpm example:build` will build and start your application.
+- Then run `npm run example:build` will build and start your application.
 - This does the following:
-  - Unzips `wp-env/uploads.zip` to `wp-env/uploads` which is mapped to the wp-content/uploads directory for the Docker container.
   - 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`
@@ -107,7 +104,7 @@ Congratulations, WordPress should now be fully set up.
 
 | Command               | Description                                                                                                             |
 | --------------------- | ----------------------------------------------------------------------------------------------------------------------- |
-| `example:build`       | Prepares the environment by unzipping images, starting WordPress, importing the database, and starting the application. |
+| `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.                                                                    |
@@ -119,10 +116,8 @@ Congratulations, WordPress should now be fully set up.
 | `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`.                                                           |
-| `wp:images:unzip`     | Extracts the WordPress uploads directory.                                                                               |
-| `wp:images:zip`       | Compresses the WordPress uploads directory.                                                                             |
 
-> **Note** You can run `pnpm 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`.
+> **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`.
 
 ### Database access