feat: Client example of fetching data for Next.js app router using the fetch API

.gitignore

@@ -13,6 +13,7 @@ test-results/
 # WordPress
 .wp-env
 .wp-env.override.json
+uploads/
 
 # Environment
 .env
@@ -21,4 +22,4 @@ test-results/
 # IDE and OS
 .DS_Store
 .idea
-.vscode
+.vscode

examples/README.md

@@ -2,4 +2,5 @@
 
 This directory contains examples demonstrating how to use various features of the Headless WordPress Toolkit.
 
-- **next-pages-apollo-authentication**: An example project showcasing authentication with Next.js, Apollo Client, and Headless WordPress.
+- **next-pages-apollo-authentication**: An example project showcasing authentication with Next.js, Apollo Client, and Headless WordPress.
+- **next/client-app-router-fetch-data**: An example WordPress application using Next.js App Router and the fetch API to fetch data from WordPress using WPGraphQL

examples/next/client-app-router-fetch-data/.wp-env.json

@@ -0,0 +1,26 @@
+{
+  "phpVersion": "7.4",
+  "plugins": [
+      "https://github.com/wp-graphql/wp-graphql/releases/latest/download/wp-graphql.zip",
+      "https://github.com/wp-graphql/wpgraphql-ide/releases/latest/download/wpgraphql-ide.zip",
+      "https://github.com/AdvancedCustomFields/acf/releases/download/6.3.12/advanced-custom-fields-6.3.12.zip",
+      "https://github.com/wp-graphql/wpgraphql-acf/releases/latest/download/wpgraphql-acf.zip",
+      "https://github.com/wpengine/wp-graphql-content-blocks/releases/latest/download/wp-graphql-content-blocks.zip"
+  ],
+  "config": {
+    "WP_DEBUG": true,
+    "SCRIPT_DEBUG": false,
+    "GRAPHQL_DEBUG": true,
+    "WP_DEBUG_LOG": true,
+    "WP_DEBUG_DISPLAY": false,
+    "SAVEQUERIES": false
+  },
+  "mappings": {
+    "db": "./wp-env/db",
+    "wp-content/uploads": "./wp-env/uploads",
+    ".htaccess": "./wp-env/setup/.htaccess"
+  },
+  "lifecycleScripts": {
+    "afterStart": "wp-env run cli -- wp plugin update wpgraphql-acf && wp-env run cli -- wp rewrite structure '/%postname%/' && wp-env run cli -- wp rewrite flush"
+  }
+}

examples/next/client-app-router-fetch-data/README.md

@@ -0,0 +1,155 @@
+# Example: Next.js App Router using the Fetch API
+
+# Table of Contents
+
+- [Overview](#overview)
+    - [Prerequisites](#prerequisites)
+    - [Project Structure](#project-structure)
+    - [Features](#features)
+    - [Screenshots](#screenshots)
+
+- [Running the Example with wp-env](#running-the-example-with-wp-env)
+    - [Prerequisites](#prerequisites-1)
+    - [Setup Repository and Packages](#setup-repository-and-packages)
+    - [Build and Start the Application](#build-and-start-the-application)
+    - [Command Reference](#command-reference)
+    - [Database Access](#database-access)
+
+# Overview
+
+An example headless WordPress application using Next.js App Router and the fetch API to fetch data from WordPress using WPGraphQL It showcases different data fetching strategies, state management techniques, and modern web development patterns in a real-world application context. This also contains a full example using wp-env and sample data.
+
+## Prerequisites
+
+- Node.js (v18+ recommended)
+- [pnpm](https://pnpm.io/)
+- [Docker](https://www.docker.com/) (if you plan on running the example see details below)
+
+
+## Project Structure
+
+```
+/
+├── example-app/            # Next.js App Headless Example Application
+│   ├── app/                # Application-specific pages and routes
+│   ├── components/         # Reusable UI components
+│   ├── lib/                # Utility functions and libraries and WP GraphQL Fragments
+|
+├── wp-env/                 # WordPress local environment setup
+│   ├── wp-env.json
+│   ├── db/                 # Example database export to be imported for the example setup
+│   ├── setup/              # .htaccess file to fix a CORS issue
+|   |-- screenshots/        # Example screenshots for this README
+│   ├── uploads.zip         # Zipped wp-content/uploads directory for the example application
+│   ├── uploads/            # Unzipped wp-content/uploads directory when the example application is run.
+├── package.json            # Scripts for running the example application
+```
+
+## Features
+
+- **Covers various rendering patterns of Next.js**
+
+  - Server-Side Rendering (SSR) for dynamic pages
+  - Static Site Generation (SSG) for static pages
+  - Client-Side data fetching (CSR) for blog settings
+  - Hybrid data fetching, combining SSR and CSR
+
+- **Blog features**
+
+  - Listing posts with pagination
+  - Fetching posts and pages using nodeByUri of WPGraphQL
+  - Fetching static pages at build time
+  - Commenting posts
+  - Header with dynamic blog title
+  - Featured image
+  - Includes category and tag blog post listings
+
+- **Other Template Features**
+  - Page template
+  - CPT template with listings for a CPT events (can be adapted for other CPT)
+  - Single CPT page with ACF custom meta fields
+
+## Screenshots
+
+Here are some screenshots of the application:
+
+### Blog Listings
+![Listing](wp-env/screenshots/blog-listing.png)
+![Pagination](wp-env/screenshots/blog-listing-pagination.png)
+
+### Blog Post
+![Blog Post](wp-env/screenshots/blog-single.png)
+![Comments](wp-env/screenshots/blog-comments.png)
+![Comment Form](wp-env/screenshots/blog-comment-form.png)
+![Comment Form Submitted](wp-env/screenshots/blog-comment-form-submitted.png)
+
+### CPT
+![Event Listings](wp-env/screenshots/cpt-event-listing.png)
+![Event Single](wp-env/screenshots/cpt-event-single.png)
+
+
+# Running the example with wp-env
+
+## Prerequisites
+
+**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
+- Setup a .env file under `examples/next/client-app-router-fetch-data/example-app` with `NEXT_PUBLIC_WORDPRESS_URL=http://localhost:8888`
+e.g.
+
+```bash
+echo "NEXT_PUBLIC_WORDPRESS_URL=http://localhost:8888" > examples/next/client-app-router-fetch-data/example-app/.env
+```
+
+## Build and start the application
+
+- `cd examples/next/client-app-router-fetch-data`
+- Then run `pnpm 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.
+
+| Frontend | Admin                        |
+|----------|------------------------------|
+| [http://localhost:3000/](http://localhost:3000/) | [http://localhost:8888/wp-admin/](http://localhost:8888/wp-admin/) |
+
+
+> **Note:** The login details for the admin is username "admin" and password "password"
+
+
+## Command Reference
+
+| Command                | Description                                                                 |
+|------------------------|-----------------------------------------------------------------------------|
+| `example:build`        | Prepares the environment by unzipping images, 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`.              |
+| `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`.
+
+### Database access
+
+If you need database access add the following to your wp-env `"phpmyadminPort": 11111,` (where port 11111 is not allocated).
+
+You can check if a port is free by running `lsof -i :11111`

examples/next/client-app-router-fetch-data/example-app/.gitignore

@@ -0,0 +1,41 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts

examples/next/client-app-router-fetch-data/example-app/eslint.config.mjs

@@ -0,0 +1,14 @@
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+import { FlatCompat } from "@eslint/eslintrc";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const compat = new FlatCompat({
+  baseDirectory: __dirname,
+});
+
+const eslintConfig = [...compat.extends("next/core-web-vitals")];
+
+export default eslintConfig;

examples/next/client-app-router-fetch-data/example-app/jsconfig.json

@@ -0,0 +1,7 @@
+{
+  "compilerOptions": {
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  }
+}

examples/next/client-app-router-fetch-data/example-app/next.config.mjs

@@ -0,0 +1,18 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  reactStrictMode: true,
+  images: {
+    // Allow images from localhost.
+    // Please change this to your domain if you are using a different domain.
+    domains: ["localhost"],
+  },
+  // Note: env variables are set in next.config.js only accept string values so used publicRuntimeConfig instead
+  publicRuntimeConfig: {
+    // Controls posts per page for blog, category and tag pages
+    wordPressDisplaySettings: {
+      postsPerPage: 5,
+    },
+  },
+};
+
+export default nextConfig;