Category: Headless Nextjs

You built a blazing-fast Headless WordPress site with Astro or Next.js. The Lighthouse score is 100. The design is pixel-perfect.

But when you check Google Search Console, it’s a disaster.

Your canonical tags are pointing to the wrong domain (cms.yoursite.com instead of yoursite.com). Your schema data says “0 Words” because the content lives in ACF blocks, not the classic editor. And your internal links are leaking authority to your backend staging site.

In this guide, I’m sharing the exact “Headless SEO Suite” code I use on production sites to force Yoast to behave. This PHP snippet fixes the Schema, rewrites the URLs, and patches the Word Count bug automatically.

Why Traditional Plugins Fail in Headless SEO

The core issue is architectural mismatch. WordPress plugins like Yoast SEO, RankMath, and All in One SEO were built for the monolithic era—where the database, admin panel, and frontend theme all live on the same server and domain.

In a headless setup, you decouple the frontend (Astro, Next.js, Nuxt) from the backend (WordPress). This creates three major SEO gaps:

1. Domain Confusion: The plugin generates sitemaps, canonicals, and OpenGraph tags using the backend URL (e.g., admin.mysite.com). If search engines index these, they ignore your actual frontend, leading to duplicate content issues or indexing your login page.
2. Incomplete Schema Data: Standard SEO plugins scrape the the_content() loop to calculate word counts and “Time to Read” estimates. Since headless sites often use Advanced Custom Fields (ACF) or Gutenberg blocks served via API, the plugin sees an empty post. The result? wordCount: 0 in your schema, telling Google your detailed guide is “thin content.”
3. Preview & Drafts Break: Without special configuration, the “Preview” button in WordPress tries to load the backend theme (which doesn’t exist) instead of your headless frontend draft.

Why Go Headless Despite the SEO Challenges?

If fixing SEO requires custom code, is Headless WordPress worth it? For many enterprise and performance-focused sites, the answer is a resounding yes.

• Unmatched Performance: By pre-rendering content with static site generators (SSG) like Astro, you serve pure HTML/CSS on the edge. This leads to near-instant load times and Core Web Vitals scores that traditional WordPress struggles to hit without heavy caching plugins.
• Enhanced Security: Your WordPress database and admin panel are hidden from the public internet. Hackers attacking your frontend URL hit a static CDN, not your SQL database. This drastically reduces the attack surface for common WordPress vulnerabilities.
• Developer Experience: Frontend teams can use modern JavaScript frameworks (React, Vue, Svelte) and component-based architectures without being tied to PHP templates.

The goal is to get these benefits without sacrificing the robust SEO tools that content editors love in WordPress. That’s where our patch comes in.

Key Takeaways

• The Problem: Yoast SEO defaults to the CMS domain for canonicals and schema, confusing Google.
• The “0 Word” Bug: If you use ACF or Blocks, Yoast often reports empty content, hurting your E-E-A-T score.
• The Solution: You don’t need a heavy plugin. A single functions.php filter can intercept and rewrite the Yoast REST API response before it hits your frontend.

The Code: Headless SEO Patcher

This script hooks into the WordPress REST API. It grabs the data Yoast is about to send to your Astro/Next.js frontend and “sanitizes” it. It fixes the domain, the canonical tag, and the word count calculation in real-time.

Instructions: Add this to your theme’s functions.php file or a custom plugin.

/**
 * HEADLESS WORDPRESS SEO SUITE (Final Production Version)
 * Author: MD Pabel
 * 1. Schema Generator: Forces "TechArticle" & Author data for ALL content.
 * 2. URL Fixer: Rewrites CMS URLs to Frontend URLs.
 * 3. Data Patcher: Fixes Word Count & Canonical Tags for Headless.
 */

// ==============================================================================
// PART 1: SCHEMA CONFIGURATION (The "Expert" Force)
// ==============================================================================

// 1. Override Yoast Settings (Forces TechArticle for EVERYTHING)
add_filter( 'option_wpseo_titles', function( $options ) {
    // Custom Types
    $options['schema-article-type-case-study'] = 'TechArticle';
    $options['schema-article-type-malware-log'] = 'TechArticle';
    $options['schema-article-type-guide']       = 'TechArticle';
    
    // Force Standard Blog Posts to be TechArticle too
    $options['schema-article-type-post']        = 'TechArticle'; 
    $options['schema-page-type-post']           = 'WebPage'; 

    return $options;
});

// 2. Register Capabilities (Ensure 'post' is included)
add_filter( 'wpseo_schema_article_post_types', function( $post_types ) {
    return array_merge( $post_types, ['post', 'case-study', 'malware-log', 'guide'] );
});

// 3. Force the "Article" Graph Piece (Fixes "WebPage" default)
add_filter( 'wpseo_schema_needs_article', '__return_true' );

// 4. Force the "Author" Graph Piece (Ensures Profile appears)
add_filter( 'wpseo_schema_needs_profile', '__return_true' );

// 5. ✅ NEW: Fix "8 Word" Count Issue (Scans ACF/Meta if content is empty)
add_filter( 'wpseo_schema_article', function( $data, $context ) {
    // If Yoast detects < 50 words, it likely missed the ACF content. Let's recount.
    if ( !isset($data['wordCount']) || $data['wordCount'] < 50 ) { $post = $context->presentation->source;
        
        // Start with standard content
        $raw_text = $post->post_content;

        // Only proceed if we actually have a post object with an ID
        if ( ! $post || ! isset( $post->ID ) ) {
            return $data;
        }

        // Brute Force: Append all text-based Custom Fields (ACF) to the count
        $meta = get_post_meta($post->ID);
        foreach($meta as $key => $values) {
            // Skip hidden WP internal keys (start with _)
            if ( substr($key, 0, 1) === '_' ) continue;
            
            foreach($values as $val) {
                // If it looks like a sentence, add it to our text bucket
                if ( is_string($val) && strlen($val) > 3 ) {
                    $raw_text .= ' ' . $val;
                }
            }
        }

        // Strip HTML tags and count words
        $clean_text = strip_tags($raw_text);
        $real_count = str_word_count($clean_text);

        // Update Schema Data
        $data['wordCount'] = $real_count;
        
        // Update TimeToRead (Avg 200 words/min) - Format: PTxM (ISO 8601)
        $minutes = max(1, ceil($real_count / 200)); 
        $data['timeRequired'] = "PT{$minutes}M"; 
    }
    return $data;
}, 10, 2 );


// ==============================================================================
// PART 2: URL REWRITER (The Sanitizer)
// ==============================================================================

function mdpabel_headless_seo_rewriter($response, $post, $request) {
    if (!isset($response->data['yoast_head'])) {
        return $response;
    }

    // --- CONFIGURATION ---
    $cms_domain      = 'cms.mdpabel.com'; 
    $frontend_domain = 'https://www.mdpabel.com';

    // --- FOLDER MAPPING ---
    $folder = '/blog'; 
    if ( isset($post->post_type) ) {
        if ($post->post_type === 'case-study')  $folder = '/case-studies';
        if ($post->post_type === 'malware-log') $folder = '/malware-log';
        if ($post->post_type === 'guide')       $folder = '/guides';
    }

    $head = $response->data['yoast_head'];

    // 1. Force Indexing
    $head = str_replace('content="noindex', 'content="index', $head);

    // 2. Fix Author Link
    $head = str_replace(
        'content="https://www.facebook.com/in/mdpabe1"', 
        'content="' . $frontend_domain . '/author/mdpabel/"', 
        $head
    );

    // 3. ✅ FORCE CANONICAL (The Fix)
    // First, REMOVE any existing canonical (even if it points to CMS)
    $head = preg_replace('//i', '', $head);
    
    // Second, CREATE the correct one
    $canonical_url = $frontend_domain . $folder . '/' . $post->post_name . '/';
    
    // Third, PREPEND it to the top (so it is the first thing bots see)
    $head = '' . "\n" . $head;

    // 4. Main Domain Rewrite Loop
    $pattern = '/https?:\/\/' . preg_quote($cms_domain, '/') . '(\/[^"\'\s<]*)?/'; $head = preg_replace_callback($pattern, function($matches) use ($frontend_domain, $folder, $post) { $full_url = $matches[0]; $path = isset($matches[1]) ? $matches[1] : ''; // Skip Assets if (strpos($path, '/wp-content/') !== false || strpos($path, '/wp-includes/') !== false || preg_match('/\.(xml|xsl|json)$/', $path)) { return $full_url; } // Rewrite Logic if (strpos($path, $post->post_name) !== false) return $frontend_domain . $folder . '/' . $post->post_name . '/';
        if (strpos($path, '/author/') !== false) return $frontend_domain . $path;
        if (strpos($path, '?s=') !== false) return $frontend_domain . '/blog' . $path;

        return $frontend_domain . $path;

    }, $head);

    $response->data['yoast_head'] = $head;
    return $response;
}

// Apply Rewriter to All Content Types
add_filter('rest_prepare_post', 'mdpabel_headless_seo_rewriter', 10, 3);
add_filter('rest_prepare_page', 'mdpabel_headless_seo_rewriter', 10, 3);
add_filter('rest_prepare_case-study', 'mdpabel_headless_seo_rewriter', 10, 3);
add_filter('rest_prepare_malware-log', 'mdpabel_headless_seo_rewriter', 10, 3);
add_filter('rest_prepare_guide', 'mdpabel_headless_seo_rewriter', 10, 3);

FAQ: Headless WordPress SEO

Need help implementing this? If you are struggling with a complex Headless WordPress setup or dealing with SEO data leaks, hire me to audit your architecture. I specialize in fixing the technical debt that plugins leave behind.

Headless CMS architectures are becoming more popular in modern web development because they are flexible and improve performance. Developers can make fast, dynamic sites that use WordPress’s powerful content management features by separating the backend (like WordPress) from the frontend (like Next.js). However, some features, like tracking and showing how many people have seen a post, need to be carefully integrated using REST APIs.

This post will show you how to add view counters to your blog posts when you use WordPress and Next.js without a head. To make things easier, we will use the well-known “Post Views Counter” plugin, turn on its REST API mode, and set up a custom endpoint. This method makes sure that tracking is accurate without using standard WordPress themes.

Why it is important to have view counters in a website

View counters give you useful information about how popular and engaging your content is. Plugins make this easy with shortcodes or theme hooks on a regular WordPress site. But if you use Next.js to build the front end of a headless site, you have to use WordPress’s REST API to talk to it. This means getting post data (including views) on the server side during server-side rendering (SSR) or static site generation (SSG) and adding counts on the client side to get real user views.

What is the problem? A lot of plugins do not show view counts in the best way for apps that use APIs. That is when personalization comes into play.

Step 1: Set up and install the Post Views Counter plugin

The first step is to install the free “Post Views Counter” plugin from the WordPress plugin repository. It is light and has more than 100,000 active installations. It also works with REST API for headless use.

1. Go to your WordPress admin dashboard and log in.
2. To install or activate “Post Views Counter,” go to Plugins > Add New and search for it.
3. Go to Post Views tab and then Counter Mode.
4. Choose REST API from the list of options in Counter Mode. This lets you count using an API, which is important for headless setups because it does not need PHP to run in themes or JavaScript to run in the browser.
5. Set up other options:
   • Post Types: Check the box next to “post” (or any other type you want).
   • Set the time between counts to “1 day” to get unique views per user.
6. To register the new routes, save your changes and flush the permalinks (Settings > Permalinks > Save Changes).

With this, the plugin keeps track of views in post meta (post_views_count) and adds an endpoint for adding views: POST /wp-json/post-views-counter/view-post/{post_id}.

Step 2: The Limitation and Why We Need a Custom Endpoint

The default increment endpoint works perfectly; it follows rules for uniqueness (like using local storage or cookies) and updates the count on the server. But its answer does not include the new total number of views. It gives back something like this:

{
  "post_id": 1093,
  "counted": true,
  "storage": {
    "name": ["pvc_visits[0]"],
    "value": ["1756048474b1093"],
    "expiry": [1756048474]
  },
  "type": "post"
}

To make this work, we will make a custom REST API endpoint that adds to the view count and sends back the new count in one response.

Step 3: Putting the Custom Endpoint in functions.php

Change the functions.php file for your theme (or make a custom plugin to make it easier to keep up with). Put in the following code:

// Custom REST API endpoint to get and add to the view count
add_action('rest_api_init', function() {
    register_rest_route('custom/v1', '/post-views/(?P<id>\d+)', array(
        'methods' => 'POST',
        'callback' => 'custom_increment_and_get_views',
        'permission_callback' => '__return_true', // Public; add auth for safety
        'args' => array(
            'id' => array(
                'validate_callback' => function($param) {
                    return is_numeric($param) && get_post($param);
                },
            ),
        ),
    ));
});

function custom_increment_and_get_views($request) {
    $post_id = $request['id'];
    
    if (!function_exists('pvc_view_post') || !function_exists('pvc_get_post_views')) {
        return new WP_Error('plugin_missing', 'Post Views Counter functions not found.', array('status' => 500));
    }
    
    // Add one more view to the post
    pvc_view_post($post_id);
    
    // Get the new total
    $views = pvc_get_post_views($post_id);
    
    return array(
        'post_id' => $post_id,
        'views' => $views,
        'success' => true,
    );
}

• Endpoint: POST /wp-json/custom/v1/post-views/{post_id}
• Example response: {"post_id":1093,"views":42,"success":true}
• Benefits: One call for both increment and fetch. It uses the plugin’s built-in features, so it gets all of its settings, like uniqueness and exclusions.

Use curl to test it: curl -X POST https://your-site.com/wp-json/custom/v1/post-views/1093. Add nonce checks or API keys to make it safe in production.

Step 4: Working with Next.js

In your Next.js app, use getStaticProps or getServerSideProps to get the initial post data, which includes views. Then, on page load, use a useEffect hook to call the custom endpoint and update the display with the count that comes back.

In pages/posts/[slug].js, for example:

import { useEffect, useState } from "react";

export default function Post({ post }) {
    const [views, setViews] = useState(post.meta?.post_views_count || 0);

    useEffect(() => {
        const handleViews = async () => {
            const storageKey = "pvc_visits[0]";
            
            // Check if already viewed
            if (localStorage.getItem(storageKey)) return;

            try {
                const response = await fetch(`https://your-site.com/wp-json/custom/v1/post-views/${post.id}`, {
                    method: 'POST',
                    headers: {
                        'Content-Type': 'application/json'
                    },
                });
                
                if (response.ok) {
                    const data = await response.json();
                    setViews(data.views);
                    // Set storage for uniqueness
                    localStorage.setItem(storageKey, `some-value-b${post.id}`);
                }
            } catch (error) {
                console.error('Error:', error);
            }
        };

        handleViews();
    }, [post.id]);

    return (
        <div>
            <h1>{post.title.rendered}</h1>
            <p>Views: {views}</p>
            {/* Content of the post */}
        </div>
    );
}

This uses Incremental Static Regeneration (ISR) to refresh the page every so often and localStorage to mimic the plugin’s unique logic.

Final Thoughts

You can easily keep track of and show view counts in your headless WordPress + Next.js blog by turning on REST API mode in Post Views Counter and adding a custom endpoint. This setup works well, is accurate, and is easy to keep up with. If your endpoint gets a lot of traffic, you might want to add caching (like with Redis) or rate limiting.

Have you done something like this before? Please tell us about your experiences in the comments. If you want to learn more about headless CMS, read my other posts about how to make Next.js faster.