Skip to content

Commit afc0ccb

Browse files
ahuseynahuseyn
authored
Merge pull request #290 from wpengine/example-hwp-previews-rest
docs(example): Headless WordPress Previews with Nextjs App Router and REST API
2 parents 8e09c54 + 155983b commit afc0ccb

File tree

28 files changed

+1189
-0
lines changed

28 files changed

+1189
-0
lines changed

‎examples/next/hwp-preview-rest/.wp-env.json

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
{
2+
"phpVersion": "7.4",
3+
"plugins": [
4+
"https://github.com/Tmeister/wp-api-jwt-auth/archive/refs/tags/1.3.8.zip",
5+
"../../../plugins/hwp-previews"
6+
],
7+
"config": {
8+
"WP_DEBUG": true,
9+
"SCRIPT_DEBUG": false,
10+
"GRAPHQL_DEBUG": true,
11+
"WP_DEBUG_LOG": true,
12+
"WP_DEBUG_DISPLAY": false,
13+
"SAVEQUERIES": false,
14+
"JWT_AUTH_SECRET_KEY": "dpntMEZgEFH6dwPXaL5lVIZ6F4i6MnL7"
15+
},
16+
"mappings": {
17+
"db": "./wp-env/db",
18+
"wp-content/uploads": "./wp-env/uploads",
19+
".htaccess": "./wp-env/setup/.htaccess"
20+
},
21+
"lifecycleScripts": {
22+
"afterStart": "wp-env run cli -- wp rewrite structure '/%postname%/' && wp-env run cli -- wp rewrite flush"
23+
}
24+
}

‎examples/next/hwp-preview-rest/README.md

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
# Example: Headless WordPress Previews with Nextjs App Router and REST API
2+
3+
> [!NOTE]
4+
> Check out [HWP Previews WPGraphQL example](https://github.com/wpengine/hwptoolkit/tree/main/examples/next/hwp-preview-wpgraphql) if you need the previews implementation with Nextjs pages router, Draft Mode or WordPress Application Passwords.
5+
6+
## Overview
7+
8+
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](https://github.com/wpengine/hwptoolkit/tree/main/examples/next/hwp-preview-wpgraphql) this example don't use [Draft Mode](https://nextjs.org/docs/pages/guides/draft-mode).
9+
10+
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.
11+
12+
> [!CAUTION]
13+
> 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.
14+
15+
## Screenshots
16+
17+
| | |
18+
| :------------------------------------------: | :----------------------------------------------------------: |
19+
| ![Login](./screenshots/login.png) <br> Login | ![Page preview](./screenshots/preview.png) <br> Page preview |
20+
21+
## Project Structure
22+
23+
```
24+
├── example-app
25+
├── src
26+
│ ├── app
27+
│ │ ├── page.js # Home page
28+
│ │ ├── pages
29+
│ │ │ └── [identifier]
30+
│ │ │ └── page.jsx # Single pages and previews
31+
│ │ └── posts
32+
│ │ └── [identifier]
33+
│ │ └── page.jsx # Single pages and previews
34+
│ ├── components # Reusable components
35+
│ └── lib
36+
│ ├── AuthProvider.js # Auth logic and context
37+
│ ├── authUtils.js # Utils for AuthProvider
38+
│ └── fetchWP.js # WordPress REST API helper
39+
├── .wp-env.json # wp-env configuration file
40+
└── wp-env
41+
├── db
42+
│ └── database.sql # WordPress database including all demo data for the example
43+
└── uploads.zip # WordPress content to be used by wp-env
44+
```
45+
46+
## Running the example with wp-env
47+
48+
### Prerequisites
49+
50+
- Node.js (v18+ recommended)
51+
- [Docker](https://www.docker.com/) (if you plan on running the example see details below)
52+
53+
**Note** Please make sure you have all prerequisites installed as mentioned above and Docker running (`docker ps`)
54+
55+
### Setup Repository and Packages
56+
57+
- Clone the repo `git clone https://github.com/wpengine/hwptoolkit.git`
58+
- Install packages `cd hwptoolkit && npm install`
59+
60+
### Build and start the application
61+
62+
- `cd examples/next/hwp-preview-rest`
63+
- Then run `npm run example:build` will build and start your application.
64+
- This does the following:
65+
- Unzips `wp-env/uploads.zip` to `wp-env/uploads` which is mapped to the wp-content/uploads directory for the Docker container.
66+
- Starts up [wp-env](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-wp-env/)
67+
- Imports the database from [wp-env/db/database.sql](wp-env/db/database.sql)
68+
- Install Next.js dependencies for `example-app`
69+
- Runs the Next.js dev script
70+
71+
Congratulations, WordPress should now be fully set up.
72+
73+
| Frontend | Admin |
74+
| ---------------------- | ------------------------------- |
75+
| http://localhost:3000/ | http://localhost:8888/wp-admin/ |
76+
77+
> **Note:** The login details for the admin is username "admin" and password "password"
78+
79+
### Add environment variable to the Nextjs
80+
81+
Create a .env file under `examples/next/hwp-preview-rest/example-app` and add copy-paste the environment variable below:
82+
83+
```bash
84+
NEXT_PUBLIC_WORDPRESS_URL=http://localhost:8888
85+
```
86+
87+
### Usage
88+
89+
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.
90+
91+
If you want to learn more about the preview plugin, check out [the documentation](/plugins/hwp-previews/README.md).
92+
93+
> [!CAUTION]
94+
> 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.
95+
96+
### Command Reference
97+
98+
| Command | Description |
99+
| --------------------- | ----------------------------------------------------------------------------------------------------------------------- |
100+
| `example:build` | Prepares the environment by unzipping images, starting WordPress, importing the database, and starting the application. |
101+
| `example:dev` | Runs the Next.js development server. |
102+
| `example:dev:install` | Installs the required Next.js packages. |
103+
| `example:start` | Starts WordPress and the Next.js development server. |
104+
| `example:stop` | Stops the WordPress environment. |
105+
| `example:prune` | Rebuilds and restarts the application by destroying and recreating the WordPress environment. |
106+
| `wp:start` | Starts the WordPress environment. |
107+
| `wp:stop` | Stops the WordPress environment. |
108+
| `wp:destroy` | Completely removes the WordPress environment. |
109+
| `wp:db:query` | Executes a database query within the WordPress environment. |
110+
| `wp:db:export` | Exports the WordPress database to `wp-env/db/database.sql`. |
111+
| `wp:db:import` | Imports the WordPress database from `wp-env/db/database.sql`. |
112+
| `wp:images:unzip` | Extracts the WordPress uploads directory. |
113+
| `wp:images:zip` | Compresses the WordPress uploads directory. |
114+
115+
> **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`.
116+
117+
### Database access
118+
119+
If you need database access add the following to your wp-env `"phpmyadminPort": 11111,` (where port 11111 is not allocated).
120+
121+
You can check if a port is free by running `lsof -i :11111`

‎examples/next/hwp-preview-rest/example-app/.gitignore

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
2+
3+
# dependencies
4+
/node_modules
5+
/.pnp
6+
.pnp.*
7+
.yarn/*
8+
!.yarn/patches
9+
!.yarn/plugins
10+
!.yarn/releases
11+
!.yarn/versions
12+
13+
# testing
14+
/coverage
15+
16+
# next.js
17+
/.next/
18+
/out/
19+
20+
# production
21+
/build
22+
23+
# misc
24+
.DS_Store
25+
*.pem
26+
27+
# debug
28+
npm-debug.log*
29+
yarn-debug.log*
30+
yarn-error.log*
31+
.pnpm-debug.log*
32+
33+
# env files (can opt-in for committing if needed)
34+
.env*
35+
36+
# vercel
37+
.vercel
38+
39+
# typescript
40+
*.tsbuildinfo
41+
next-env.d.ts

‎examples/next/hwp-preview-rest/example-app/eslint.config.mjs

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
import { FlatCompat } from "@eslint/eslintrc";
2+
import js from "@eslint/js";
3+
import { dirname } from "path";
4+
import { fileURLToPath } from "url";
5+
6+
const __filename = fileURLToPath(import.meta.url);
7+
const __dirname = dirname(__filename);
8+
9+
const compat = new FlatCompat({
10+
baseDirectory: __dirname,
11+
recommendedConfig: js.configs.recommended,
12+
});
13+
14+
const eslintConfig = [
15+
...compat.config({
16+
extends: ["eslint:recommended", "next/core-web-vitals"],
17+
}),
18+
];
19+
20+
export default eslintConfig;

‎examples/next/hwp-preview-rest/example-app/jsconfig.json

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"compilerOptions": {
3+
"paths": {
4+
"@/*": ["./src/*"]
5+
}
6+
}
7+
}

‎examples/next/hwp-preview-rest/example-app/next.config.mjs

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
/** @type {import('next').NextConfig} */
2+
const nextConfig = {
3+
eslint: {
4+
ignoreDuringBuilds: true,
5+
},
6+
};
7+
8+
export default nextConfig;

‎examples/next/hwp-preview-rest/example-app/package.json

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
{
2+
"name": "hwp-preview-rest-example-app",
3+
"version": "0.1.0",
4+
"private": true,
5+
"scripts": {
6+
"dev": "next dev",
7+
"build": "next build",
8+
"start": "next start",
9+
"lint": "next lint"
10+
},
11+
"dependencies": {
12+
"react": "^19.0.0",
13+
"react-dom": "^19.0.0",
14+
"next": "15.3.4"
15+
},
16+
"devDependencies": {
17+
"@tailwindcss/postcss": "^4",
18+
"tailwindcss": "^4",
19+
"eslint": "^9",
20+
"eslint-config-next": "15.3.4",
21+
"@eslint/eslintrc": "^3"
22+
}
23+
}

‎examples/next/hwp-preview-rest/example-app/postcss.config.mjs

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
const config = {
2+
plugins: ["@tailwindcss/postcss"],
3+
};
4+
5+
export default config;

‎examples/next/hwp-preview-rest/example-app/src/app/favicon.ico

25.3 KB
Binary file not shown.

‎examples/next/hwp-preview-rest/example-app/src/app/globals.css

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
@import "tailwindcss";
2+
3+
:root {
4+
--background: #ffffff;
5+
--foreground: #171717;
6+
}
7+
8+
@theme inline {
9+
--color-background: var(--background);
10+
--color-foreground: var(--foreground);
11+
--font-sans: var(--font-geist-sans);
12+
--font-mono: var(--font-geist-mono);
13+
}
14+
15+
body {
16+
background: var(--background);
17+
color: var(--foreground);
18+
font-family: Arial, Helvetica, sans-serif;
19+
}

0 commit comments

Comments
 (0)