Merge pull request #521 from wpengine/fix-hwp-previews-examples

ahuseyn · web-flow · commit 776536fc84e1 · 2025-11-24T11:42:02.000Z
docs(previews): Fix examples, update example readmes
diff --git a/plugins/hwp-previews/examples/hwp-preview-rest/.wp-env.json b/plugins/hwp-previews/examples/hwp-preview-rest/.wp-env.json
@@ -2,7 +2,7 @@
   "phpVersion": "7.4",
   "plugins": [
     "https://github.com/Tmeister/wp-api-jwt-auth/archive/refs/tags/1.3.8.zip",
-    "../../../plugins/hwp-previews"
+    "https://github.com/wpengine/hwptoolkit/releases/download/%40wpengine%2Fhwp-previews-wordpress-plugin-0.0.12/hwp-previews.zip"
   ],
   "config": {
     "WP_DEBUG": true,
diff --git a/plugins/hwp-previews/examples/hwp-preview-rest/README.md b/plugins/hwp-previews/examples/hwp-preview-rest/README.md
@@ -1,16 +1,26 @@
-# Example: Headless WordPress Previews with Nextjs App Router and REST API
+---
+title: "Headless WordPress Previews with Next.js App Router and REST API"
+description: "This demonstrates the usage of HWP Previews with Next.js App Router and REST API. It uses JWT authentication to fetch posts in draft status and implements a login modal for front-end authentication, showcasing an alternative approach to the Draft Mode implementation."
+---
+
+# Example: Headless WordPress Previews with Next.js App Router and REST API
 
 > [!NOTE]
-> Check out [HWP Previews WPGraphQL example](../hwp-preview-wpgraphql) if you need the previews implementation with Nextjs pages router, Draft Mode or WordPress Application Passwords.
+> Check out [HWP Previews WPGraphQL example](../hwp-preview-wpgraphql) if you need the previews implementation with Next.js pages router, Draft Mode or WordPress Application Passwords.
 
 ## Overview
 
-The purpose of this example is to showcase different use cases of HWP Previews. The example demonstrates the usage of [HWP Previews](https://github.com/wpengine/hwptoolkit/tree/main/plugins/hwp-previews) with Nextjs App Router and REST API. Example uses credentials authentication to fetch the posts in draft status. Unlike [HWP Previews WPGraphQL example](../hwp-preview-wpgraphql) this example don't use [Draft Mode](https://nextjs.org/docs/pages/guides/draft-mode).
+The purpose of this example is to showcase different use cases of HWP Previews. The example demonstrates the usage of [HWP Previews](https://github.com/wpengine/hwptoolkit/tree/main/plugins/hwp-previews) with Next.js App Router and REST API. Example uses credentials authentication to fetch the posts in draft status. Unlike [HWP Previews WPGraphQL example](../hwp-preview-wpgraphql) this example doesn't use [Draft Mode](https://nextjs.org/docs/pages/guides/draft-mode).
 
 The example includes a wp-env setup, which will allow you to build and start this example quickly. With this wp-env setup, you don't need to have a separate WordPress instance or demo data to inspect the example.
 
-> [!CAUTION]
-> The HWP Previews plugin is currently in beta. While it's more stable than earlier versions, you may still encounter occasional bugs or incomplete features. Regular updates will continue as development progresses. Use with care and consider providing feedback to help improve the plugin.
+## What does this example do
+
+1. Preview posts, pages and custom post types using WordPress REST API
+2. Use JWT authentication for secure access to draft content
+3. Next.js App Router implementation without Draft Mode
+4. Login modal for front-end authentication
+5. Configured WordPress instance with demo data and required plugins, using wp-env.
 
 ## Screenshots
 
@@ -52,47 +62,42 @@ The example includes a wp-env setup, which will allow you to build and start thi
 
 **Note** Please make sure you have all prerequisites installed as mentioned above and Docker running (`docker ps`)
 
-### Setup Repository and Packages
+### 1. Setup Repository and Packages
 
 - Clone the repo `git clone https://github.com/wpengine/hwptoolkit.git`
 - Install packages `cd hwptoolkit && npm install`
 
-### Build and start the application
+### 2. Build and start the application
 
-- `cd examples/next/hwp-preview-rest`
+- `cd plugins/hwp-previews/examples/hwp-preview-rest`
 - 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`
-  - Runs the Next.js dev script
 
-Congratulations, WordPress should now be fully set up.
+This starts the wp-env instance and frontend application. You can access them now, but one more installation step remains.
+
+> [!IMPORTANT]
+> After logging in to the WordPress instance, ensure that all installed plugins are activated for this example to work properly.
 
 | Frontend               | Admin                           |
 | ---------------------- | ------------------------------- |
 | http://localhost:3000/ | http://localhost:8888/wp-admin/ |
 
 > **Note:** The login details for the admin is username "admin" and password "password"
 
-### Add environment variable to the Nextjs
-
-Create a .env file under `examples/next/hwp-preview-rest/example-app` and add copy-paste the environment variable below:
+### 3. Add environment variable to the Next.js application
 
+Create a .env file under `plugins/hwp-previews/examples/hwp-preview-rest/example-app` and add the environment variable below:
 
 ```bash
 NEXT_PUBLIC_WORDPRESS_URL=http://localhost:8888
 ```
 
-### Usage
+> [!CAUTION]
+> This setup is intended for demonstration purposes only. For production use, you should consider the security implications and implement appropriate measures based on your project's specific needs.
 
-After completing this step, login to your [WordPress instance](http://localhost:8888) and preview the posts as usual. Since all of the settings are configured for this example, clicking the preview button should redirect you to the front-end URL. To see the draft posts and pages you will need to login your WordPress account on front-end website, using the same credentials.
 
-If you want to learn more about the preview plugin, check out [the documentation](/plugins/hwp-previews/README.md).
+After completing this step, clicking the preview button in wp-admin should open the preview in your front-end app. Login with your admin credentials on the frontend to enable draft preview functionality.
 
-> [!CAUTION]
-> This setup is intended for demonstration purposes only. For production use, you should consider the security implications and implement appropriate measures based on your project’s specific needs.
+If you want to learn more about the preview plugin, check out [the documentation](../../../../docs/plugins/hwp-previews/index.md).
 
 ### Command Reference
 
diff --git a/plugins/hwp-previews/examples/hwp-preview-wpgraphql/.wp-env.json b/plugins/hwp-previews/examples/hwp-preview-wpgraphql/.wp-env.json
@@ -4,7 +4,7 @@
     "https://github.com/wp-graphql/wp-graphql/releases/latest/download/wp-graphql.zip",
     "https://github.com/AdvancedCustomFields/acf/releases/latest/download/advanced-custom-fields.zip",
     "https://github.com/wp-graphql/wpgraphql-acf/releases/latest/download/wpgraphql-acf.zip",
-    "../../"
+    "https://github.com/wpengine/hwptoolkit/releases/download/%40wpengine%2Fhwp-previews-wordpress-plugin-0.0.12/hwp-previews.zip"
   ],
   "config": {
     "WP_DEBUG": true,
diff --git a/plugins/hwp-previews/examples/hwp-preview-wpgraphql/README.md b/plugins/hwp-previews/examples/hwp-preview-wpgraphql/README.md
@@ -1,21 +1,23 @@
+---
+title: "Headless WordPress Previews with Next.js Pages Router and WPGraphQL"
+description: "This demonstrates the usage of HWP Previews with Next.js Pages Router and WPGraphQL. It uses WordPress Application Passwords for authentication and implements Draft Mode for secure preview functionality."
+---
+
 # Example: Headless WordPress Previews with Nextjs Draft Mode
 
 ## Overview
 
-This example shows the HWP Previews plugin in action. Example implements the [Draft Mode](https://nextjs.org/docs/pages/guides/draft-mode) of Nextjs. It uses WordPress [Application Passwords](https://wordpress.com/support/security/two-step-authentication/application-specific-passwords/) for the authentication and WPGraphQL for data fetching.
+This example shows the HWP Previews plugin in action. Example implements the [Draft Mode](https://nextjs.org/docs/pages/guides/draft-mode) of Next.js. It uses WordPress [Application Passwords](https://wordpress.com/support/security/two-step-authentication/application-specific-passwords/) for the authentication and WPGraphQL for data fetching.
 
 The example includes a wp-env setup, which will allow you to build and start this example quickly. With this wp-env setup, you don't need to have a separate WordPress instance or demo data to inspect the example.
 
-> [!CAUTION]
-> The HWP Previews plugin is currently in an beta state. It's still under active development, so you may encounter bugs or incomplete features. Updates will be rolled out regularly. Use with caution and provide feedback if possible.
-
 ## What does this example do
 
-1. `/api/preview/` route to enable Nextjs Draft Mode
-2. `/api/disable-preview` route to disable Nextjs Draft Mode
+1. `/api/preview/` route to enable Next.js Draft Mode
+2. `/api/disable-preview` route to disable Next.js Draft Mode
 3. Preview posts, pages and custom post types
 4. Use WordPress Application Password as an authentication method
-5. Configured WordPress instance with demo data and required plugins, using wp-env
+5. Configured WordPress instance with demo data and required plugins, using wp-env.
 
 ## Screenshots
 
@@ -55,34 +57,30 @@ The example includes a wp-env setup, which will allow you to build and start thi
 
 **Note** Please make sure you have all prerequisites installed as mentioned above and Docker running (`docker ps`)
 
-### Setup Repository and Packages
+### 1. Setup Repository and Packages
 
 - Clone the repo `git clone https://github.com/wpengine/hwptoolkit.git`
 - Install packages `cd hwptoolkit && npm install`
 
-### Build and start the application
+### 2. Build and start the application
 
 - `cd plugins/hwp-previews/examples/hwp-preview-wpgraphql`
 - Then run `npm run example:build` will build and start your application.
-- Copy .env.local to .env under example-app `cp example-app/.env.local example-app/.env`
-- 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`
-  - Runs the Next.js dev script
 
-Congratulations, WordPress should now be fully set up.
+This starts the wp-env instance and frontend application. You can access them now, but one more installation step remains.
+
+> [!IMPORTANT]
+> After logging in to the WordPress instance, ensure that all installed plugins are activated for this example to work properly.
 
 | Frontend               | Admin                           |
 | ---------------------- | ------------------------------- |
 | http://localhost:3000/ | http://localhost:8888/wp-admin/ |
 
 > **Note:** The login details for the admin is username "admin" and password "password"
 
-### Add environment variables to the Nextjs
+### 3. Add environment variables to the Nextjs
 
-In this step we will create an Application Password and a secret preview token for the previews. At the end we'll prepare a .env file for the Nextjs application and put it inside `examples/next/hwp-preview-wpgraphql/example-app` folder. Below are the step by step guide to achieve this.
+In this step we will create an Application Password and a secret preview token for the previews. At the end we'll prepare a .env file for the Next.js application and put it inside `plugins/hwp-previews/examples/hwp-preview-wpgraphql/example-app` folder. Below are the step by step guide to achieve this.
 
 1. Login to your newly created [wp-env instance](http://localhost:8888/wp-admin/). You can find the credentials above
 2. a. Follow [these instructions](https://wordpress.com/support/security/two-step-authentication/application-specific-passwords/) to create an Application Password. At the end it should look like this:
@@ -95,7 +93,7 @@ In this step we will create an Application Password and a secret preview token f
 
 ![index](./screenshots/preview_token.png "Change secret preview token")
 
-4. Create a .env file under `examples/next/hwp-preview-wpgraphql/example-app` and add these values inside:
+4. Create a .env file under `plugins/hwp-previews/examples/hwp-preview-wpgraphql/example-app` and add these values inside:
 
 ```bash
 NEXT_PUBLIC_WORDPRESS_URL=http://localhost:8888
@@ -110,7 +108,7 @@ WP_PREVIEW_SECRET=YOUR-SECRET-PREVIEW-TOKEN
 
 After completing this step, clicking the preview button in wp-admin should open the preview in your front-end app.
 
-If you want to learn more about the preview plugin, check out [the documentation](/plugins/hwp-previews/README.md).
+If you want to learn more about the preview plugin, check out [the documentation](../../../../docs/plugins/hwp-previews/index.md).
 
 ### Command Reference
 
