How to Set Up Headless Wordpress with Next.js and Wpgraphql in 2026

ByAkensai

Learning how to set up headless WordPress with Next.js and WPGraphQL in 2026 opens up powerful possibilities for modern web development. This architecture separates your content management from the frontend presentation layer. You’ll get faster loading times, better SEO, and more flexibility in design choices.

Headless WordPress acts as a content API while Next.js handles the frontend rendering. WPGraphQL provides a GraphQL endpoint for efficient data fetching. This combination creates a modern, scalable web application that performs exceptionally well.

This tutorial covers the complete setup process from installing WordPress to deploying your Next.js frontend. You’ll learn to configure WPGraphQL, create GraphQL queries, and build dynamic pages. By the end, you’ll have a fully functional headless WordPress site running with Next.js.

Prerequisites and Requirements for Headless WordPress with Next.js Setup

Before starting this tutorial, you need several tools and accounts ready. First, ensure you have Node.js version 18 or higher installed on your system. You can download it from the official Node.js website.

You’ll also need a WordPress installation with admin access. This can be a local development environment using XAMPP, MAMP, or Docker. Alternatively, use a staging server or shared hosting account. The WordPress version should be 5.0 or newer for full WPGraphQL compatibility.

Basic knowledge of JavaScript, React, and WordPress is essential. You should understand how to navigate the WordPress admin panel and install plugins. Familiarity with command-line operations will help during the Next.js setup process.

Plan to dedicate 2-3 hours for this complete setup. The process involves multiple steps including plugin installation, configuration, and frontend development. Having a code editor like VS Code ready will streamline your workflow.

Installing and Configuring WPGraphQL for Headless WordPress

This event shares similarities with: Host File Edit: Viewing Websites Without DNS

Step 1: Install the WPGraphQL plugin in your WordPress admin dashboard. Navigate to Plugins > Add New and search for “WPGraphQL”. Click Install Now and then Activate the plugin.

Step 2: Verify the GraphQL endpoint is working by visiting your site’s GraphQL IDE. Go to `yoursite.com/graphql` in your browser. You should see the GraphiQL interface where you can test queries.

Step 3: Install additional WPGraphQL extensions for enhanced functionality. The WPGraphQL for Advanced Custom Fields plugin is particularly useful if you use ACF. Search for it in the plugin directory and install it.

// Test query to verify WPGraphQL is working
query GetPosts {
  posts {
    nodes {
      id
      title
      content
      slug
      date
    }
  }
}

Step 4: Configure CORS settings to allow your Next.js frontend to access the GraphQL endpoint. Add this code to your theme’s `functions.php` file:

function add_cors_http_header(){
    header("Access-Control-Allow-Origin: ");
    header("Access-Control-Allow-Methods: GET, POST, OPTIONS");
    header("Access-Control-Allow-Headers: Content-Type, Authorization");
}
add_action('init','add_cors_http_header');

Step 5: Test your GraphQL queries using the GraphiQL interface. Try fetching posts, pages, and any custom post types you have. This ensures your data is accessible through the API before building the frontend.

Setting Up Next.js Frontend for Headless WordPress Integration

Step 1: Create a new Next.js project in your preferred directory. Open your terminal and run the following commands:

npx create-next-app@latest my-headless-wp
cd my-headless-wp
npm install

Step 2: Install the necessary GraphQL packages for data fetching. You’ll need `graphql-request` for making GraphQL queries and `@apollo/client` for more advanced features:

npm install graphql-request graphql
npm install @apollo/client

Step 3: Create a GraphQL client configuration file. Make a new file called `lib/graphql.js` in your project root:

import { GraphQLClient } from 'graphql-request'

const endpoint = 'https://yourwordpresssite.com/graphql'

export const graphQLClient = new GraphQLClient(endpoint, {
  headers: {
    'Content-Type': 'application/json',
  },
})

Step 4: Create your first GraphQL query to fetch WordPress posts. Make a new file `lib/queries.js`:

export const GET_POSTS = `
  query GetPosts {
    posts {
      nodes {
        id
        title
        content
        slug
        date
        featuredImage {
          node {
            sourceUrl
            altText
          }
        }
      }
    }
  }
`

Step 5: Update your homepage to display WordPress content. Modify `pages/index.js` to fetch and display posts:

import { graphQLClient } from '../lib/graphql'
import { GET_POSTS } from '../lib/queries'

export default function Home({ posts }) {
  return (
    

      
My Headless WordPress Site

      {posts.map((post) => (
        

          
{post.title}

          

        

      ))}
    

  )
}

export async function getStaticProps() {
  const data = await graphQLClient.request(GET_POSTS)
  
  return {
    props: {
      posts: data.posts.nodes,
    },
    revalidate: 60, // Revalidate every minute
  }
}

Step 6: Create dynamic pages for individual posts. Make a new file `pages/posts/[slug].js`:

import { graphQLClient } from '../../lib/graphql'

const GET_POST_BY_SLUG = `
  query GetPostBySlug($slug: String!) {
    postBy(slug: $slug) {
      id
      title
      content
      date
    }
  }
`

export default function Post({ post }) {
  return (
    

      
{post.title}

      

    

  )
}

export async function getStaticPaths() {
  const data = await graphQLClient.request(GET_POSTS)
  
  const paths = data.posts.nodes.map((post) => ({
    params: { slug: post.slug },
  }))

  return { paths, fallback: 'blocking' }
}

export async function getStaticProps({ params }) {
  const data = await graphQLClient.request(GET_POST_BY_SLUG, { slug: params.slug })
  
  return {
    props: {
      post: data.postBy,
    },
    revalidate: 60,
  }
}

Troubleshooting Common Headless WordPress and Next.js Issues

CORS errors are the most frequent problem when setting up this configuration. If you see “blocked by CORS policy” errors, double-check your CORS headers in WordPress. The code provided earlier should resolve most CORS issues, but some hosting providers require additional configuration.

GraphQL query errors often occur due to incorrect field names or missing data. Use the GraphiQL interface at `yoursite.com/graphql` to test queries before implementing them in Next.js. The interface provides helpful error messages and auto-completion.

Build failures in Next.js typically happen when WordPress returns null data. Always add null checks in your components and provide fallback values. For example, check if `post.featuredImage` exists before trying to access its properties.

Performance issues may arise with large amounts of content. Implement pagination in your GraphQL queries and use Next.js’s built-in image optimization. The Next.js Image component automatically optimizes images from WordPress.

SSL certificate problems can prevent GraphQL requests from working. Ensure your WordPress site has a valid SSL certificate. Most hosting providers offer free SSL certificates through Let’s Encrypt.

Authentication issues occur when trying to access private content. WPGraphQL supports JWT authentication for protected content. Install the WPGraphQL JWT Authentication plugin if you need to access private posts or user-specific data.

Optimizing and Deploying Your Headless WordPress Setup

Performance optimization starts with efficient GraphQL queries. Only request the fields you actually need in your frontend. Avoid fetching large content fields on listing pages where you only need titles and excerpts.

Implement proper caching strategies using Next.js’s Incremental Static Regeneration (ISR). Set appropriate `revalidate` values based on how frequently your content changes. News sites might revalidate every minute, while corporate sites could revalidate daily.

Consider using a Content Delivery Network (CDN) for your WordPress media files. Services like Cloudflare or AWS CloudFront can significantly improve image loading times globally.

Deploy your Next.js frontend to platforms like Vercel, Netlify, or AWS Amplify. These platforms provide excellent performance and automatic deployments from Git repositories. Connect your repository and configure environment variables for your WordPress GraphQL endpoint.

Set up webhook integrations between WordPress and your deployment platform. This automatically rebuilds your Next.js site when content changes in WordPress. The WordPress Webhooks plugin makes this process straightforward.

Monitor your site’s performance using tools like Google PageSpeed Insights and Core Web Vitals. The headless architecture should provide excellent performance scores, but optimization is ongoing.

Successfully implementing how to set up headless WordPress with Next.js and WPGraphQL in 2026

Similar Posts