docs: Next.js WP Theme rendered blocks

examples/next/wp-theme-rendered-blocks/.gitignore

@@ -0,0 +1,3 @@
+example-app/package-lock.json
+package-lock.json
+wp-env/__MACOSX

examples/next/wp-theme-rendered-blocks/.wp-env.json

@@ -0,0 +1,24 @@
+{
+  "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",
+    "./wp-env/plugins/hwp-global-stylesheet"
+  ],
+  "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 rewrite structure '/%postname%/' && wp-env run cli -- wp rewrite flush"
+  }
+}

examples/next/wp-theme-rendered-blocks/README.md

@@ -0,0 +1,91 @@
+# Example: WordPress Global Styles in Next.js
+
+This example demonstrates how to **fetch and apply WordPress Global Styles** in a Next.js project using the `globalStylesheet` GraphQL field. These styles reflect your active theme’s typography, spacing, colors, and layout rules — ensuring that your frontend matches the WordPress editor and theme design.
+
+This pattern is especially helpful for users migrating from **Faust.js**, where similar global styles were automatically applied using utilities like `getGlobalStyles`.
+
+---
+
+## How it works
+
+- A script (`scripts/fetchWpGlobalStyles.mjs`) queries your WordPress site's GraphQL API for global styles.
+- The styles are saved to `styles/hwp-global-styles.css`.
+- The file is imported directly in your app and bundled at build time.
+
+This ensures that all block-rendered content in your app inherits the same styling as it would inside the WordPress editor.
+
+---
+
+## Example usage
+
+In `scripts/fetchWpGlobalStyles.mjs`, you define the fetch:
+
+```js
+fetchWpGlobalStyles(
+  "https://your-wp-site.com/graphql", // WordPress GraphQL endpoint
+  "styles/hwp-global-styles.css", // Output path
+  ["variables", "presets", "styles", "base-layout-styles"] // Style types to include
+);
+```
+
+In your `pages/_app.js`, you include the styles:
+
+```javascript
+import "@wordpress/base-styles"; // WordPress foundational styles
+import "@/styles/hwp-global-styles.css"; // Theme styles fetched from WP
+import "@/styles/globals.css"; // Optional custom app styles
+```
+
+## Project structure
+
+```
+/
+├── hwp-global-stylesheet/*             # WordPress Plugin.
+├── pages/
+│   ├── _app.js                         # Includes global styles.
+│   └── index.js                        # Basic page.
+├── styles/
+│   ├── hwp-global-styles.css           # Output of the fetch script.
+│   └── globals.css                     # Your optional global app styles.
+├── package.json                        # Project dependencies and scripts.
+```
+
+## Installation and Setup
+
+### Prerequisites
+
+1. Node.js 18.18 or later
+2. npm or another package manager
+3. [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`)
+
+### Clone the repository
+
+```bash
+git clone https://github.com/wpengine/hwptoolkit.git
+```
+
+### Install dependencies
+
+```bash
+cd hwptoolkit && npm install
+```
+
+### Build and start the application
+
+- `cd examples/next/wp-theme-rendered-blocks`
+- Then run `npm run example:build` will build and start your application.
+- This does the following:
+  - 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"

examples/next/wp-theme-rendered-blocks/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/wp-theme-rendered-blocks/example-app/.nvmrc

@@ -0,0 +1 @@
+lts/*

examples/next/wp-theme-rendered-blocks/example-app/eslint.config.mjs

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

examples/next/wp-theme-rendered-blocks/example-app/jsconfig.json

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

examples/next/wp-theme-rendered-blocks/example-app/next.config.mjs

@@ -0,0 +1,6 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  reactStrictMode: true,
+};
+
+export default nextConfig;

examples/next/wp-theme-rendered-blocks/example-app/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "wp-theme-styles-nextjs",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint",
+    "prettier": "prettier --write .",
+    "styles:fetch": "node scripts/fetchWpGlobalStyles.mjs"
+  },
+  "dependencies": {
+    "@wordpress/base-styles": "^5.21.0",
+    "next": "15.2.4",
+    "prettier": "^3.5.3",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "eslint": "^9",
+    "eslint-config-next": "15.2.3"
+  }
+}

examples/next/wp-theme-rendered-blocks/example-app/scripts/fetchWpGlobalStyles.mjs

@@ -0,0 +1,49 @@
+import fs from "fs";
+import path from "path";
+
+async function fetchWpGlobalStyles(
+  endpoint,
+  outputPath = "src/styles/hwp-global-styles.css",
+  types = ["variables", "presets", "styles", "base-layout-styles"]
+) {
+  const typeEnums = types.map((type) => type.toUpperCase().replace(/-/g, "_"));
+
+  const query = `
+        query {
+          globalStylesheet(types: [${typeEnums.join(", ")}])
+        }
+    `;
+
+  try {
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ query }),
+    });
+
+    const json = await response.json();
+
+    if (!json.data || !json.data.globalStylesheet) {
+      throw new Error("No stylesheet data returned from the API.");
+    }
+
+    let css = json.data.globalStylesheet;
+
+    // Optional minification for production use
+    css = css
+      .replace(/\/\*[\s\S]*?\*\//g, "")
+      .replace(/\s+/g, " ")
+      .replace(/\s*([{}:;,])\s*/g, "$1")
+      .trim();
+
+    const absoluteOutputPath = path.resolve(process.cwd(), outputPath);
+    fs.mkdirSync(path.dirname(absoluteOutputPath), { recursive: true });
+    fs.writeFileSync(absoluteOutputPath, css);
+
+    console.log(`Global styles saved to: ${absoluteOutputPath}`);
+  } catch (error) {
+    console.error("Error fetching global styles:", error.message);
+  }
+}
+
+fetchWpGlobalStyles("http://localhost:8888/graphql");

examples/next/wp-theme-rendered-blocks/example-app/src/pages/_app.js

@@ -0,0 +1,7 @@
+import '@wordpress/base-styles';         // WordPress foundational styles.
+import '@/styles/hwp-global-styles.css'; // The fetched global styles from WP (generated by your fetch script).
+import "@/styles/globals.css";           // Optional custom global styles.
+
+export default function App({ Component, pageProps }) {
+  return <Component {...pageProps} />;
+}

examples/next/wp-theme-rendered-blocks/example-app/src/pages/_document.js

@@ -0,0 +1,13 @@
+import { Html, Head, Main, NextScript } from "next/document";
+
+export default function Document() {
+  return (
+    <Html lang="en">
+      <Head />
+      <body className="antialiased">
+        <Main />
+        <NextScript />
+      </body>
+    </Html>
+  );
+}

examples/next/wp-theme-rendered-blocks/example-app/src/pages/index.js

@@ -0,0 +1,20 @@
+import Head from "next/head";
+
+export default function Home() {
+  return (
+    <>
+      <Head>
+        <title>WordPress Theme Styles Example</title>
+      </Head>
+      <main>
+        <h1>WordPress Global Styles in Next.js</h1>
+        <p>
+          This example shows how to fetch and apply global styles from a WordPress site using WPGraphQL. The theme styles you're seeing here were fetched from the WP instance and applied globally via CSS.
+        </p>
+        <p>
+          You can now render blocks in another part of your app and they will inherit the theme styling from your WordPress site.
+        </p>
+      </main>
+    </>
+  );
+}

examples/next/wp-theme-rendered-blocks/example-app/src/styles/globals.css

@@ -0,0 +1,9 @@
+.wp-element-caption {
+  font-size: 0.875rem;
+  line-height: 1.4;
+}
+
+.is-layout-flex {
+  display: flex;
+  gap: 1.2rem;
+}

examples/next/wp-theme-rendered-blocks/example-app/src/styles/hwp-global-styles.css

@@ -0,0 +1 @@
+/** Output from the script. **/