How to Build a Headless WordPress Blog with React

In today’s web development landscape, the concept of “headless” architecture is gaining significant traction.

This approach decouples the front-end (what users see) from the back-end (where content is managed).

For WordPress users, this means leveraging WordPress purely as a content management system (CMS) and building a custom, modern front-end using Javascript libraries like React.

This blog post will walk you through the provided React code for a headless WordPress application, explaining its core components and how you can get it up and running.

What is a Headless WordPress Application?

Traditionally, WordPress handles both content management and the visual presentation of your website. In a headless setup:

• WordPress (Backend): Acts as a powerful content repository. It uses its built-in REST API to expose your posts, pages, and other content as structured data (usually JSON).
• React (Frontend): Consumes this data from the WordPress API and renders it into a dynamic, interactive user interface.

Benefits of a Headless Approach:

• Performance: React applications can be incredibly fast, offering a smoother user experience.
• Flexibility: You’re not tied to WordPress themes. You have complete control over the design and user experience.
• Scalability: You can scale your front-end and back-end independently.
• Modern Tooling: Leverage the vast ecosystem of modern JavaScript tools and libraries.
• Multi-channel Publishing: Serve content to web, mobile apps, smart devices, etc., from a single WordPress backend.

Diving into the React Code

The provided React application is a simple yet effective example of a headless WordPress blog. Let’s break down its key parts:

1. State Management

import React, { useState, useEffect } from 'react';

// Main App component
const App = () => {
  const [posts, setPosts] = useState([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);
  // ... rest of the component
};

• posts: An array to store the blog post objects fetched from WordPress.
• loading: A boolean flag to indicate whether data is currently being fetched. This is useful for showing a loading spinner or message.
• error: Stores any error object that might occur during the API call, allowing for error display.

2. Fetching Data with useEffect

useEffect(() => {
  const wordpressApiUrl = 'https://demo.wp-api.org/wp-json/wp/v2/posts?_embed'; // IMPORTANT: Replace this URL!

  const fetchPosts = async () => {
    try {
      const response = await fetch(wordpressApiUrl);
      if (!response.ok) {
        throw new Error(`HTTP error! status: ${response.status}`);
      }
      const data = await response.json();
      setPosts(data);
    } catch (err) {
      setError(err);
    } finally {
      setLoading(false);
    }
  };

  fetchPosts();
}, []); // Empty dependency array means this runs once on component mount

• The useEffect hook is crucial here. The empty dependency array [] ensures that the fetchPosts function runs only once when the App component mounts.
• wordpressApiUrl: This is the most critical part for you to customize. It points to the WordPress REST API endpoint for posts. The ?_embed parameter is added to include embedded resources like featured images and author data, which makes displaying richer content easier.
• fetchPosts Function: An asynchronous function that uses the fetch API to make a network request to your WordPress site.
  • It checks for response.ok to catch HTTP errors (like 404s or 500s).
  • It parses the JSON response.
  • It updates the posts, loading, and error states based on the outcome of the fetch operation.

3. Conditional Rendering (Loading and Error States)

if (loading) {
  return (
    <div className="flex items-center justify-center min-h-screen bg-gray-100">
      <div className="text-xl font-semibold text-gray-700">Loading posts...</div>
    </div>
  );
}

if (error) {
  return (
    <div className="flex items-center justify-center min-h-screen bg-red-100 text-red-700 p-4 rounded-lg shadow-md m-4">
      <div className="text-xl font-semibold">Error: {error.message}</div>
      <p className="mt-2 text-sm">Please check your WordPress API URL and ensure your WordPress site is accessible.</p>
    </div>
  );
}

Before rendering the actual blog posts, the component checks the loading and error states. This provides immediate feedback to the user, preventing a blank screen and informing them if something went wrong.

4. Displaying Posts

return (
  <div className="min-h-screen bg-gray-50 font-sans text-gray-800 p-4 sm:p-6 md:p-8">
    {/* Header Section */}
    {/* ... */}

    {/* Posts Grid */}
    <div className="max-w-6xl mx-auto grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
      {posts.length > 0 ? (
        posts.map((post) => (
          <div key={post.id} className="bg-white rounded-xl shadow-lg hover:shadow-xl transition-shadow duration-300 overflow-hidden border border-gray-200">
            {/* Post Thumbnail */}
            {post._embedded && post._embedded['wp:featuredmedia'] && post._embedded['wp:featuredmedia'][0] && (
              <img src={post._embedded['wp:featuredmedia'][0].source_url} alt={post._embedded['wp:featuredmedia'][0].alt_text || post.title.rendered} className="w-full h-48 object-cover rounded-t-xl" onError={(e) => { e.target.onerror = null; e.target.src = `https://placehold.co/600x400/E0E0E0/333333?text=No+Image`; }} />
            )}
            {!post._embedded || !post._embedded['wp:featuredmedia'] || !post._embedded['wp:featuredmedia'][0] && (
              <div className="w-full h-48 bg-gray-200 flex items-center justify-center text-gray-500 text-sm rounded-t-xl">
                No Image Available
              </div>
            )}

            <div className="p-5">
              <h2 className="text-2xl font-bold text-gray-900 mb-3 leading-tight">
                {post.title.rendered}
              </h2>
              <div
                className="text-gray-700 text-base leading-relaxed line-clamp-3"
                dangerouslySetInnerHTML={{ __html: post.excerpt.rendered }}
              ></div>
              <a href={post.link} target="_blank" rel="noopener noreferrer" className="mt-4 inline-block bg-blue-600 text-white px-5 py-2 rounded-lg font-semibold hover:bg-blue-700 transition-colors duration-300 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-opacity-50">
                Read More
              </a>
            </div>
          </div>
        ))
      ) : (
        <div className="col-span-full text-center text-gray-600 text-lg p-8">
          No posts found. Please ensure your WordPress site has published posts.
        </div>
      )}
    </div>

    {/* Footer Section */}
    {/* ... */}
  </div>
);

• The posts array is mapped to render individual post cards.
• Each card displays the post title (post.title.rendered) and a truncated excerpt (post.excerpt.rendered).
• dangerouslySetInnerHTML is used to render the HTML content from the WordPress excerpt. Be cautious when using this in production with untrusted sources, as it can expose you to XSS attacks. For a blog, where you control the content, it’s generally acceptable.
• Featured images are displayed using post._embedded['wp:featuredmedia'][0].source_url. A fallback placeholder image is provided if no featured media is found.
• A “Read More” button links directly to the original post on your WordPress site.
• Tailwind CSS classes are used extensively for responsive and modern styling.

Setting Up Your Headless WordPress Blog

To make this application work with your own WordPress site, follow these steps:

1. Ensure WordPress REST API is Enabled: The WordPress REST API is enabled by default in modern WordPress installations (since version 4.7).
2. Identify Your WordPress API URL:Your posts API endpoint will typically be https://YOUR_WORDPRESS_SITE_URL/wp-json/wp/v2/posts.Remember to add ?_embed to include featured images and other linked data: https://YOUR_WORDPRESS_SITE_URL/wp-json/wp/v2/posts?_embed.
3. Update the wordpressApiUrl in the React Code:Locate this line in the App.js file:

   const wordpressApiUrl = 'https://demo.wp-api.org/wp-json/wp/v2/posts?_embed';
   
   

   Replace 'https://demo.wp-api.org' with your actual WordPress site’s domain.

4. Handle CORS (Cross-Origin Resource Sharing):If your React app is served from a different domain than your WordPress site, your browser will block the API requests due to CORS policies. You’ll need to configure your WordPress site to allow requests from your React app’s domain.
   • WordPress Plugins: Search for “CORS” plugins in the WordPress plugin directory. Plugins like “WP CORS” or “CORS Headers” can simplify this.
   • Server Configuration: You can manually add CORS headers to your server’s configuration (e.g., in .htaccess for Apache or your Nginx configuration). A common .htaccess rule might look like this:

     <IfModule mod_headers.c>
       Header set Access-Control-Allow-Origin "https://your-react-app-domain.com"
       Header set Access-Control-Allow-Methods "GET, POST, OPTIONS"
       Header set Access-Control-Allow-Headers "Content-Type, Authorization"
     </IfModule>
     
     

     Replace https://your-react-app-domain.com with the domain where your React app is hosted. For development, you might use * (e.g., Header set Access-Control-Allow-Origin "*") but this is not recommended for production.

5. Run Your React App:If you have a standard React setup (e.g., created with Create React App or Vite), you can typically run your app using:

   npm start
   # or
   yarn start
   
   

   This will usually open your app in your browser at http://localhost:3000 (or similar).

Conclusion

Building a headless WordPress blog with React offers a powerful combination of WordPress’s robust content management capabilities and React’s modern, performant front-end development.

This example provides a solid foundation for you to start experimenting and building more complex applications.

With the flexibility of React and the rich data available through the WordPress REST API, the possibilities are endless!