Skip to content

Commit fb2331a

Browse files
ahuseynahuseyn
authored
Merge pull request #304 from wpengine/chore-update-examples-iteration-1
chore: Tidy up examples
2 parents e8fb779 + 71decbb commit fb2331a

File tree

159 files changed

+1627
-4984
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

159 files changed

+1627
-4984
lines changed

‎.gitignore‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ test-results/
1515
.wp-env.override.json
1616
uploads/
1717
debug.log
18+
__MACOSX
1819

1920
# Environment
2021
.env
@@ -27,4 +28,5 @@ debug.log
2728

2829
## Examples
2930
examples/**/package-lock.json
30-
examples/**/__MACOSX
31+
examples/**/__MACOSX
32+
``

‎examples/README.md‎

Lines changed: 99 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -12,31 +12,113 @@ This directory contains examples demonstrating how to use various features of th
1212

1313
## Next.js Examples
1414

15-
| Title | Description |
16-
| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
17-
| [apollo-authentication](next/apollo-authentication) | Showcases authentication with Next.js, Apollo Client, and Headless WordPress. |
18-
| [apollo-client-data-fetch](next/apollo-client-data-fetch) | Explores data fetching strategies and state management using Next.js, Apollo Client, and Headless WordPress. |
19-
| [apollo-client-filesystem-routing](next/apollo-client-filesystem-routing) | Integrates WPGraphQL and WPGraphQL for ACF with Next.js for a headless WordPress site. |
20-
| [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. |
21-
| [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. |
22-
| [custom-sitemap-apollo](next/custom-sitemap-apollo) | Generates a custom sitemap using Next.js, Apollo Client, and WPGraphQL with an extended plugin. |
23-
| [custom-sitemap-vanilla-wpgraphql](next/custom-sitemap-vanilla-wpgraphql) | Creates a custom sitemap using Next.js and WPGraphQL without extending its endpoints. |
24-
| [hybrid-sitemap-apollo](next/hybrid-sitemap-apollo) | Fetches and transforms WordPress sitemaps for clean URL formatting with Next.js. |
25-
| [proxied-sitemap-apollo](next/proxied-sitemap-apollo) | Provides a proxied sitemap by transforming WordPress XML sitemaps for SEO-friendly frontend URLs. |
26-
| [proxied-graphql-debug](next/proxied-graphql-debug) | Provides a proxied GraphQL API for development, enabling response inspection and query complexity analysis. |
27-
| [render-blocks-pages-router](next/render-blocks-pages-router) | Renders WordPress Blocks with JSX in Next.js, including utilities for hierarchical block data. |
15+
| Title | Description |
16+
| ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
17+
| [apollo-authentication](next/apollo-authentication) | Showcases authentication with Next.js, Apollo Client, and Headless WordPress. |
18+
| [apollo-client-data-fetch](next/apollo-client-data-fetch) | Explores data fetching strategies and state management using Next.js, Apollo Client, and Headless WordPress. |
19+
| [apollo-client-filesystem-routing](next/apollo-client-filesystem-routing) | Integrates WPGraphQL and WPGraphQL for ACF with Next.js for a headless WordPress site. |
20+
| [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. |
21+
| [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. |
22+
| [custom-sitemap-apollo](next/custom-sitemap-apollo) | Generates a custom sitemap using Next.js, Apollo Client, and WPGraphQL with an extended plugin. |
23+
| [custom-sitemap-vanilla-wpgraphql](next/custom-sitemap-vanilla-wpgraphql) | Creates a custom sitemap using Next.js and WPGraphQL without extending its endpoints. |
24+
| [hybrid-sitemap-apollo](next/hybrid-sitemap-apollo) | Fetches and transforms WordPress sitemaps for clean URL formatting with Next.js. |
25+
| [proxied-sitemap-apollo](next/proxied-sitemap-apollo) | Provides a proxied sitemap by transforming WordPress XML sitemaps for SEO-friendly frontend URLs. |
26+
| [proxied-graphql-debug](next/proxied-graphql-debug) | Provides a proxied GraphQL API for development, enabling response inspection and query complexity analysis. |
27+
| [render-blocks-pages-router](next/render-blocks-pages-router) | Renders WordPress Blocks with JSX in Next.js, including utilities for hierarchical block data. |
28+
| [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. |
2829

2930
## SvelteKit Examples
3031

31-
| Title | Description |
32-
| ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
33-
| [template-hierarchy-data-fetching-urql](sveltekit/template-hierarchy-data-fetching-urql) | Demonstrates template hierarchy and data fetching with SvelteKit, URQL, and Headless WordPress. |
34-
| [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. |
32+
| Title | Description |
33+
| ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
34+
| [template-hierarchy-data-fetching-urql](sveltekit/template-hierarchy-data-fetching-urql) | Demonstrates template hierarchy and data fetching with SvelteKit, URQL, and Headless WordPress. |
35+
36+
## Nuxt Examples
37+
38+
| Title | Description |
39+
| ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
40+
| [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. |
3541

3642
## Contributing
3743

3844
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.
3945

46+
### Best practices for the new examples
47+
48+
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.
49+
50+
1. **Project Structure**
51+
52+
Organize your project with a clear separation between the frontend application and the WordPress environment configuration.
53+
54+
```bash
55+
.
56+
├── example-app/ # Front-end code
57+
│ └── ...
58+
├── .wp-env.json # Configuration for the local WordPress environment
59+
└── wp-env/
60+
└── db/
61+
└── database.sql # Initial database state
62+
```
63+
64+
2. **Local WordPress with wp-env**
65+
66+
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:
67+
68+
```json
69+
{
70+
"phpVersion": "7.4",
71+
"plugins": ["https://github.com/wp-graphql/wp-graphql/releases/latest/download/wp-graphql.zip"],
72+
"config": {
73+
"WP_DEBUG": true
74+
},
75+
"mappings": {
76+
"db": "./wp-env/db",
77+
"wp-content/uploads": "./wp-env/uploads",
78+
".htaccess": "./wp-env/setup/.htaccess"
79+
},
80+
"lifecycleScripts": {
81+
"afterStart": "wp-env run cli -- wp rewrite structure '/%postname%/' && wp-env run cli -- wp rewrite flush"
82+
}
83+
}
84+
```
85+
86+
3. **Scripts**
87+
88+
Scripts in your package.json help automate common tasks. You can use our standard scripts to achieve the recommended workflow..
89+
90+
```json
91+
"scripts": {
92+
"example:build": "npm run example:dev:install && npm run wp:start && npm run wp:db:import && npm run example:start",
93+
"example:dev:install": "cd example-app && npm install && cd ..",
94+
"example:start": "npm run wp:start && npm run example:dev",
95+
"example:stop": "npm run wp:stop",
96+
"example:prune": "wp-env destroy && npm run example:build && npm run example:start",
97+
"example:dev": "npm --prefix ./example-app run dev",
98+
"wp:start": "npm install && wp-env start",
99+
"wp:stop": "wp-env stop",
100+
"wp:destroy": "wp-env destroy --config ./wp-env/wp-env.json",
101+
"wp:db:query": "wp-env run cli -- wp db query",
102+
"wp:db:export": "wp-env run cli -- wp db export /var/www/html/db/database.sql",
103+
"wp:db:import": "wp-env run cli -- wp db import /var/www/html/db/database.sql",
104+
"wp-env": "wp-env"
105+
},
106+
```
107+
108+
4. **Documentation (README.md)**
109+
110+
A clear README.md with essential information would guide the new developers effectively and reduce the errors. Consider including the information below:
111+
112+
- Prerequisites: Node.js, Docker.
113+
114+
- Setup Steps: A simple list on how to clone, install dependencies, and run the start script.
115+
116+
- Demo Credentials: Provide login details for the local WordPress admin (/wp-admin). Default for wp-env is admin / password.
117+
118+
- Security implications, and other considerations for the users, if applicable.
119+
120+
- Don't forget to include your example to this common README file as well, inside one of the tables above.
121+
40122
## Screenshots
41123

42124
> **Feature Highlight:** Here are some sample screenshots of the examples listed above.

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
"version": "0.0.1",
55
"scripts": {
66
"example:bootstrap": "npm install & npm run app:install",
7-
"example:start": "pnpm run wp:start && npm run app:dev",
7+
"example:start": "npm run wp:start && npm run app:dev",
88
"example:setup": "npm run example:bootstrap && npm run wp:start && npm run wp:db:import && npm run example:stop",
99
"example:stop": "npm run wp:stop",
1010
"example:prune": "npm run wp:destroy && npm run example:setup && npm run example:start",

‎examples/next/apollo-authentication/.gitignore‎

Lines changed: 0 additions & 3 deletions
This file was deleted.

‎examples/next/apollo-authentication/README.md‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,6 @@ echo "NEXT_PUBLIC_WORDPRESS_URL=http://localhost:8888" > examples/next/apollo-au
5555
- `cd examples/next/apollo-authentication`
5656
- Then run `npm run example:build` will build and start your application.
5757
- This does the following:
58-
- Unzips `wp-env/uploads.zip` to `wp-env/uploads` which is mapped to the wp-content/uploads directory for the Docker container.
5958
- Starts up [wp-env](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-wp-env/)
6059
- Imports the database from [wp-env/db/database.sql](wp-env/db/database.sql)
6160
- Install Next.js dependencies for `example-app`
@@ -73,7 +72,7 @@ Congratulations, WordPress should now be fully set up.
7372

7473
| Command | Description |
7574
| --------------------- | ----------------------------------------------------------------------------------------------------------------------- |
76-
| `example:build` | Prepares the environment by unzipping images, starting WordPress, importing the database, and starting the application. |
75+
| `example:build` | Prepares the environment by starting WordPress, importing the database, and starting the application. |
7776
| `example:dev` | Runs the Next.js development server. |
7877
| `example:dev:install` | Installs the required Next.js packages. |
7978
| `example:start` | Starts WordPress and the Next.js development server. |
@@ -85,8 +84,6 @@ Congratulations, WordPress should now be fully set up.
8584
| `wp:db:query` | Executes a database query within the WordPress environment. |
8685
| `wp:db:export` | Exports the WordPress database to `wp-env/db/database.sql`. |
8786
| `wp:db:import` | Imports the WordPress database from `wp-env/db/database.sql`. |
88-
| `wp:images:unzip` | Extracts the WordPress uploads directory. |
89-
| `wp:images:zip` | Compresses the WordPress uploads directory. |
9087

9188
> **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`.
9289

‎examples/next/apollo-authentication/package.json‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,6 @@
1515
"wp:db:query": "wp-env run cli -- wp db query",
1616
"wp:db:export": "wp-env run cli -- wp db export /var/www/html/db/database.sql",
1717
"wp:db:import": "wp-env run cli -- wp db import /var/www/html/db/database.sql",
18-
"wp:images:unzip": "rm -rf wp-env/uploads/ && unzip wp-env/uploads.zip -d wp-env;",
19-
"wp:images:zip": "zip -r wp-env/uploads.zip wp-env/uploads",
2018
"wp-env": "wp-env"
2119
},
2220
"keywords": [

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

Lines changed: 5 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -53,24 +53,22 @@ This example demonstrates various approaches to integrate WordPress as a headles
5353
└── wp-env
5454
├── db
5555
│ └── database.sql # WordPress database including all demo data for
56-
├── setup
57-
└── uploads.zip # WordPress content to be used by wp-env
56+
└── setup
5857
```
5958

6059
## Running the example with wp-env
6160

6261
### Prerequisites
6362

6463
- Node.js (v18+ recommended)
65-
- [pnpm](https://pnpm.io/)
6664
- [Docker](https://www.docker.com/) (if you plan on running the example see details below)
6765

6866
**Note** Please make sure you have all prerequisites installed as mentioned above and Docker running (`docker ps`)
6967

7068
### Setup Repository and Packages
7169

7270
- Clone the repo `git clone https://github.com/wpengine/hwptoolkit.git`
73-
- Install packages `cd hwptoolkit && pnpm install`
71+
- Install packages `cd hwptoolkit && npm install`
7472
- Setup a .env file under `examples/next/apollo-client-data-fetch/example-app` and add these values inside:
7573

7674
```bash
@@ -87,9 +85,8 @@ echo "NEXT_PUBLIC_WORDPRESS_URL=http://localhost:8888\\nNEXT_PRIVACY_POLICY_URI=
8785
### Build and start the application
8886

8987
- `cd examples/next/apollo-client-data-fetch`
90-
- Then run `pnpm example:build` will build and start your application.
88+
- Then run `npm run example:build` will build and start your application.
9189
- This does the following:
92-
- Unzips `wp-env/uploads.zip` to `wp-env/uploads` which is mapped to the wp-content/uploads directory for the Docker container.
9390
- Starts up [wp-env](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-wp-env/)
9491
- Imports the database from [wp-env/db/database.sql](wp-env/db/database.sql)
9592
- Install Next.js dependencies for `example-app`
@@ -107,7 +104,7 @@ Congratulations, WordPress should now be fully set up.
107104

108105
| Command | Description |
109106
| --------------------- | ----------------------------------------------------------------------------------------------------------------------- |
110-
| `example:build` | Prepares the environment by unzipping images, starting WordPress, importing the database, and starting the application. |
107+
| `example:build` | Prepares the environment by starting WordPress, importing the database, and starting the application. |
111108
| `example:dev` | Runs the Next.js development server. |
112109
| `example:dev:install` | Installs the required Next.js packages. |
113110
| `example:start` | Starts WordPress and the Next.js development server. |
@@ -119,10 +116,8 @@ Congratulations, WordPress should now be fully set up.
119116
| `wp:db:query` | Executes a database query within the WordPress environment. |
120117
| `wp:db:export` | Exports the WordPress database to `wp-env/db/database.sql`. |
121118
| `wp:db:import` | Imports the WordPress database from `wp-env/db/database.sql`. |
122-
| `wp:images:unzip` | Extracts the WordPress uploads directory. |
123-
| `wp:images:zip` | Compresses the WordPress uploads directory. |
124119

125-
> **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`.
120+
> **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`.
126121
127122
### Database access
128123

0 commit comments

Comments
 (0)