Skip to main content

Headless WordPress in Seravo's Environment

Learn how a headless WordPress architecture works on Seravo, how to deploy static React/Vue applications, and why GET requests are essential for REST and GraphQL APIs.

In a headless WordPress architecture, WordPress is used strictly as a content management system (the backend), while the public-facing site (the frontend) is built using a separate JavaScript framework such as React, Vue, or Next.js.

The user interface communicates with WordPress via either the WP REST API or WPGraphQL to fetch content dynamically.

Seravo's environment supports headless architectures well, though it is important to understand how the server handles static versus server-side rendered (SSR) JavaScript applications.

Static Headless Applications (SPA)

If your frontend is a static Single-Page Application (such as plain React, Vue, or a statically exported Gatsby/Next.js site), you can host both the frontend and WordPress on the same Seravo server.

In Seravo's nginx configuration, index.html is prioritized as the primary directory index before WordPress's index.php.

Deployment:

  1. Build your JavaScript application for production.

  2. Upload the compiled index.html file and its required assets (JavaScript and CSS files) to the site's root directory at /data/wordpress/htdocs/.

  3. Visitors arriving at your homepage will now automatically see your JavaScript application.

  4. The WordPress admin dashboard remains fully accessible as usual at /wp-admin/.

Note: Because Seravo's environment includes standard Node.js tools (such as npm, webpack, and gulp), you can also build your static frontend directly on the server over SSH during deployment or as part of an automated CI/CD pipeline.

Server-Side Rendered Applications (SSR)

Seravo's server environment is optimized for high-performance PHP execution (WordPress/WooCommerce) and aggressive HTTP caching. Running persistent, port-listening Node.js server processes (such as a server-side rendered Next.js or Express server) directly on Seravo is not supported.

If your project requires an SSR frontend:

  • Host the JavaScript application (frontend) on a platform specialized for Node.js workloads (such as Vercel or Netlify).

  • Use Seravo solely as the WordPress backend (e.g., at admin.example.com or api.example.com) from which your frontend fetches its content.

APIs, Caching, and Performance

On headless sites, WordPress performance depends entirely on the speed and cacheability of your API endpoints.

1. Prefer GET Requests for REST API and GraphQL

By default, Seravo's HTTP cache stores responses to GET and HEAD requests, but always bypasses the cache for POST requests.

If you use the WPGraphQL plugin, ensure your client application sends GET requests for queries whenever possible. If your frontend performs all data fetching via POST requests, Seravo's HTTP cache is bypassed, PHP must process every single request, and site performance will degrade significantly under heavy traffic.

2. Automate Cache Purging with Webhooks

When your frontend is decoupled, Seravo's standard WordPress cache purges (such as when saving or updating a post) do not automatically clear the cache on an external hosting platform or in visitors' browsers. Use webhooks (common in Jamstack workflows) to trigger a frontend rebuild or purge external caches whenever new content is published in WordPress.

Common Issues and Troubleshooting

  • The site displays a blank white page after deploying a static build: Verify that the .js and .css asset paths in your compiled index.html match your domain's root directory and are not pointing to an incorrect subdirectory.

  • CORS error (Cross-Origin Resource Sharing): If your frontend is hosted on a different domain (e.g., on Vercel) than your WordPress backend on Seravo, browsers may block API requests. Ensure WordPress is configured to allow requests from your frontend domain (for example, by sending appropriate CORS headers in functions.php or using a dedicated CORS plugin).

  • The headless site feels slow: Open your browser's Developer Tools (Network tab) and inspect the HTTP response headers for your API requests. If Seravo's server returns X-Cache: MISS or BYPASS for public content queries, caching is not working. The most common cause is using POST instead of GET to fetch data—switch your queries to GET requests.

See Also

A well-architected headless setup combines a modern JavaScript user interface with WordPress's flexible content management without sacrificing performance. If you need assistance optimizing API caching or configuring your environment for a headless workflow, our support team is happy to help at [email protected].

Did this answer your question?