docs: Next.js WP Theme rendered blocks

examples/next/render-blocks-pages-router/README.md

@@ -66,6 +66,12 @@ npm install
 npm run dev
 ```
 
+### Fetch WP Global Styles
+
+```bash
+npm run fetch-styles
+```
+
 http://localhost:3000/ should render the blocks as shown below.
 
 ![Animated screenshot, scrolling down and revealing the blocks supported by this example rendered on the page.](./public/screenshot.gif)

examples/next/render-blocks-pages-router/example.env.local

@@ -0,0 +1,10 @@
+# WordPress GraphQL Endpoint
+WORDPRESS_GRAPHQL_ENDPOINT=https://your-wp-site.com/graphql
+
+# Global Stylesheet settings
+WP_GLOBAL_STYLES_OUTPUT=public/hwp-global-styles.css
+WP_GLOBAL_STYLES_TYPES=variables,presets,styles,base-layout-styles
+WP_GLOBAL_STYLES_MINIFY=true
+
+# Set to true for verbose output
+WP_GLOBAL_STYLES_VERBOSE=false

examples/next/render-blocks-pages-router/package.json

@@ -3,10 +3,11 @@
   "version": "0.1.0",
   "private": true,
   "scripts": {
-    "dev": "next dev",
-    "build": "next build",
+    "dev": "pnpm fetch-styles && next dev",
+    "build": "pnpm fetch-styles && next build",
     "start": "next start",
-    "lint": "next lint"
+    "lint": "next lint",
+    "fetch-styles": "node scripts/fetchWpGlobalStyles.js"
   },
   "dependencies": {
     "@wordpress/style-engine": "^2.20.0",
@@ -18,6 +19,8 @@
   "devDependencies": {
     "@eslint/eslintrc": "^3",
     "@tailwindcss/postcss": "^4",
+    "commander": "^11.1.0",
+    "dotenv": "^16.4.1",
     "eslint": "^9",
     "eslint-config-next": "15.2.3",
     "tailwindcss": "^4"

examples/next/render-blocks-pages-router/scripts/fetchWpGlobalStyles.js

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const { program } = require('commander');
+
+// Load environment variables from .env.local if not in production
+if (process.env.NODE_ENV !== 'production') {
+    try {
+        const dotenv = require('dotenv');
+        // First check for .env.local, then fallback to .env
+        const envFile = fs.existsSync(path.resolve(process.cwd(), '.env.local'))
+            ? '.env.local'
+            : '.env';
+
+        dotenv.config({ path: path.resolve(process.cwd(), envFile) });
+    } catch (error) {
+        console.warn('dotenv is not installed. Environment variables must be set manually.');
+    }
+}
+
+// Configure CLI options with defaults from environment variables
+program
+    .name('fetch-wp-styles')
+    .description('Fetch WordPress global stylesheets for Next.js integration')
+    .option(
+        '-e, --endpoint <url>',
+        'WordPress GraphQL endpoint URL',
+        process.env.WORDPRESS_GRAPHQL_ENDPOINT
+    )
+    .option(
+        '-o, --output <path>',
+        'Output CSS file path',
+        process.env.WP_GLOBAL_STYLES_OUTPUT || 'public/hwp-global-styles.css'
+    )
+    .option(
+        '-t, --types <types...>',
+        'Style types to fetch (variables, presets, styles, base-layout-styles)',
+        parseStyleTypes(process.env.WP_GLOBAL_STYLES_TYPES)
+    )
+    .option(
+        '-v, --verbose',
+        'Show verbose output',
+        process.env.WP_GLOBAL_STYLES_VERBOSE === 'true'
+    )
+    .option(
+        '--minify <boolean>',
+        'Minify CSS output',
+        parseBooleanOption(process.env.WP_GLOBAL_STYLES_MINIFY, process.env.NODE_ENV === 'production')
+    )
+    .parse(process.argv);
+
+const options = program.opts();
+
+// Validate required options
+if (!options.endpoint) {
+    console.error('Error: WordPress GraphQL endpoint is required. Use --endpoint option or set WORDPRESS_GRAPHQL_ENDPOINT env variable.');
+    process.exit(1);
+}
+
+async function fetchGlobalStyles() {
+    const { endpoint, output, types, verbose, minify } = options;
+
+    if (verbose) {
+        console.log(`Fetching global styles from: ${endpoint}`);
+        console.log(`Requested style types: ${types.join(', ')}`);
+        console.log(`Output will be saved to: ${output}`);
+        console.log(`Minification enabled: ${minify}`);
+    }
+
+    // Convert type strings to enum values for the GraphQL query
+    const typeEnums = types.map(type => {
+        // Convert to uppercase and replace dashes with underscores for GraphQL enum format
+        return type.toUpperCase().replace(/-/g, '_');
+    });
+
+    try {
+        // Prepare the GraphQL query with type selection
+        const query = `
+      query FetchGlobalStylesheet {
+        globalStylesheet(types: [${typeEnums.join(', ')}])
+      }
+    `;
+
+        const response = await fetch(endpoint, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({ query }),
+        });
+
+        if (!response.ok) {
+            throw new Error(`HTTP error! Status: ${response.status}`);
+        }
+
+        const json = await response.json();
+
+        if (json.errors) {
+            throw new Error(`GraphQL errors: ${json.errors.map(e => e.message).join(', ')}`);
+        }
+
+        if (!json.data || !json.data.globalStylesheet) {
+            throw new Error('No stylesheet data returned from the API');
+        }
+
+        let styles = json.data.globalStylesheet;
+
+        // Process the CSS if needed (minify, etc.)
+        if (minify) {
+            // Simple minification - remove comments, whitespace, and newlines
+            styles = styles
+                .replace(/\/\*[\s\S]*?\*\//g, '')  // Remove comments
+                .replace(/\s+/g, ' ')              // Collapse whitespace
+                .replace(/\s*([{}:;,])\s*/g, '$1') // Remove spaces around symbols
+                .trim();
+        }
+
+        // Make sure the directory exists
+        const outputDir = path.dirname(output);
+        fs.mkdirSync(path.resolve(process.cwd(), outputDir), { recursive: true });
+
+        // Write the CSS file
+        fs.writeFileSync(path.resolve(process.cwd(), output), styles);
+
+        if (verbose) {
+            console.log(`Global styles successfully saved to: ${output} (${styles.length} bytes)`);
+        } else {
+            console.log(`Global styles successfully saved to: ${output}`);
+        }
+    } catch (error) {
+        console.error('Error fetching global styles:', error);
+        process.exit(1);
+    }
+}
+
+// Helper function to parse style types from env variable
+function parseStyleTypes(typesString) {
+    if (!typesString) {
+        return ['variables', 'presets', 'styles', 'base-layout-styles'];
+    }
+
+    return typesString.split(',').map(type => type.trim());
+}
+
+// Helper function to parse boolean options.
+function parseBooleanOption(value, defaultValue = false) {
+    if (value === undefined || value === null) {
+        return defaultValue;
+    }
+
+    if (typeof value === 'boolean') {
+        return value;
+    }
+
+    if (typeof value === 'string') {
+        return value.toLowerCase() === 'true';
+    }
+
+    return Boolean(value);
+}
+
+fetchGlobalStyles();

examples/next/render-blocks-pages-router/src/pages/_app.js

@@ -1,5 +1,6 @@
 import "water.css/out/light.min.css";
 import "@/styles/globals.css";
+// import '/hwp-global-styles.css'; // Add this line.
 
 export default function App({ Component, pageProps }) {
   return <Component {...pageProps} />;

plugins/hwp-global-stylesheet/hwp-global-stylesheet.php

@@ -0,0 +1,127 @@
+<?php
+/**
+ * Plugin Name: HWP Global Stylesheet
+ * Description: Exposes WordPress global stylesheets through WPGraphQL
+ * Version: 1.0.0
+ * Author: WP Engine
+ * Text Domain: hwp-global-stylesheet
+ * Domain Path: /languages
+ *
+ * @package WPGlobalStylesheet
+ */
+
+// Exit if accessed directly.
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+/**
+ * Class WP_Global_Stylesheet
+ */
+class WP_Global_Stylesheet {
+
+	/**
+	 * Instance of this class.
+	 *
+	 * @var WP_Global_Stylesheet
+	 */
+	private static $instance = null;
+
+	/**
+	 * Get an instance of this class.
+	 *
+	 * @return WP_Global_Stylesheet
+	 */
+	public static function get_instance() {
+		if ( null === self::$instance ) {
+			self::$instance = new self();
+		}
+		return self::$instance;
+	}
+
+	/**
+	 * Initialize the plugin.
+	 */
+	private function __construct() {
+		// Check if WPGraphQL is active
+		if ( class_exists( 'WPGraphQL' ) ) {
+			add_action( 'graphql_register_types', [ $this, 'register_global_stylesheet_field' ] );
+			return;
+		}
+
+		// Add admin notice if WPGraphQL is not active
+		add_action( 'admin_notices', [ $this, 'wpgraphql_missing_notice' ] );
+	}
+
+	/**
+	 * Admin notice for missing WPGraphQL dependency.
+	 */
+	public function wpgraphql_missing_notice() {
+		if ( current_user_can( 'activate_plugins' ) ) {
+			?>
+			<div class="notice notice-error">
+				<p><?php esc_html_e( 'WP Global Stylesheet requires WPGraphQL plugin to be installed and activated.', 'hwp-global-stylesheet' ); ?></p>
+			</div>
+			<?php
+		}
+	}
+
+	/**
+	 * Registers a field on the RootQuery called "globalStylesheet" which
+	 * returns the stylesheet resulting of merging core, theme, and user data.
+	 *
+	 * @return void
+	 */
+	public function register_global_stylesheet_field() {
+		register_graphql_enum_type(
+			'GlobalStylesheetTypesEnum',
+			[
+				'description' => __( 'Types of styles to load', 'hwp-global-stylesheet' ),
+				'values' => [
+					'VARIABLES' => [
+						'value' => 'variables',
+					],
+					'PRESETS' => [
+						'value' => 'presets',
+					],
+					'STYLES' => [
+						'value' => 'styles',
+					],
+					'BASE_LAYOUT_STYLES' => [
+						'value' => 'base-layout-styles',
+					],
+				],
+			]
+		);
+
+		register_graphql_field(
+			'RootQuery',
+			'globalStylesheet',
+			[
+				'type' => 'String',
+				'args' => [
+					'types' => [
+						'type' => [ 'list_of' => 'GlobalStylesheetTypesEnum' ],
+						'description' => __( 'Types of styles to load.', 'hwp-global-stylesheet' ),
+					],
+				],
+				'description' => __( 'Returns the stylesheet resulting of merging core, theme, and user data.', 'hwp-global-stylesheet' ),
+				'resolve' => function( $root, $args, $context, $info ) {
+					$types = $args['types'] ?? null;
+
+					// Check if wp_get_global_stylesheet function exists (WordPress 5.9+)
+					if ( function_exists( 'wp_get_global_stylesheet' ) ) {
+						return wp_get_global_stylesheet( $types );
+					} else {
+						return '/* wp_get_global_stylesheet function is not available. Your WordPress version might be too old. */';
+					}
+				},
+			]
+		);
+	}
+}
+
+// Initialize the plugin
+add_action( 'plugins_loaded', function() {
+	WP_Global_Stylesheet::get_instance();
+});