Book Call

How to use the WordPress REST API as a headless backend with Next.js?

So, you’re looking to use WordPress as a headless backend with Next.js? Great choice! In a nutshell, this means you’ll be using WordPress purely for its content management capabilities – creating posts, pages, custom post types, and so on – but a separate Next.js application will be handling the front-end display. Your Next.js app will fetch its content from WordPress using the WordPress REST API, delivering a super fast, flexible, and modern user experience, while still letting content creators stick with the familiar WordPress interface they know and love. It’s a powerful combination that gives you the best of both worlds.

Let’s break down what we’re actually doing here. Think of it like this: WordPress is your sophisticated content library, and Next.js is your sleek, custom-built website that grabs books (content) from that library whenever it needs them, then presents them beautifully to your visitors.

Why go headless with WordPress and Next.js?

There are some really solid reasons why folks choose this setup. First off, performance. Next.js, being a React framework, is incredibly fast. With features like server-side rendering (SSR) and static site generation (SSG), your site can achieve near-instantaneous load times, which is a huge win for user experience and SEO.

Secondly, flexibility. You’re not tied to WordPress’s theming system anymore. You can design absolutely anything you want with Next.js, using modern web development tools and practices. This means custom animations, complex UI components, and integrations with other services become much simpler.

Then there’s security. By separating your front-end from your back-end, you create a smaller attack surface. Your WordPress instance can even be hidden behind a firewall, accessible only by your Next.js application, further enhancing security.

Finally, developer experience. Working with React and Next.js is often a joy for developers, offering a powerful ecosystem of tools and libraries that can speed up development significantly.

What about the WordPress REST API?

This is the bridge between your WordPress content and your Next.js application. The WordPress REST API allows your Next.js app to “talk” to WordPress. It provides a standardized, programmatic way to retrieve your posts, pages, categories, tags, custom post types, and even media, all in a structured JSON format. It’s built right into WordPress core, so you don’t usually need to install any extra plugins just to get it working for basic content.

If you’re looking to enhance your web development skills further, you might find it beneficial to explore how to integrate email functionalities into your applications. A related article that discusses this topic is about sending emails using CyberPanel, which can be particularly useful when building applications with a headless backend like WordPress and a frontend framework such as Next.js. You can read more about it here: Sending Email Using CyberPanel. This resource can help you understand how to manage email services effectively while working with modern web technologies.

Setting Up Your WordPress Backend

Before we dive into the Next.js side, you need a WordPress installation ready to go. This can be local (like with Local by Flywheel or XAMPP/MAMP) or a hosted solution.

Local vs. Hosted WordPress

For development, a local WordPress setup is perfectly fine. It’s quick to get running and you can tinker without affecting a live site. For production, you’ll naturally need a hosted WordPress instance. Many hosting providers offer managed WordPress, which simplifies things considerably.

Permalinks Are Key

One crucial step in your WordPress admin is to configure your permalinks. Go to Settings > Permalinks and choose anything other than “Plain.” “Post name” is usually a good, clean option. This ensures your API endpoints are nicely structured and easy to work with. If you leave it as “Plain,” your API URLs will be full of ?p=123 type parameters, which is less ideal.

Understanding Your API Endpoints

Once permalinks are set, you can start exploring your API. Navigate to yourdomain.com/wp-json/wp/v2/. This is your main entry point for the REST API. You’ll see a JSON output detailing various endpoints available.

  • Posts: yourdomain.com/wp-json/wp/v2/posts
  • Pages: yourdomain.com/wp-json/wp/v2/pages
  • Categories: yourdomain.com/wp-json/wp/v2/categories
  • Custom Post Types: If you have custom post types (e.g., products), they’ll typically be available at yourdomain.com/wp-json/wp/v2/products. You might need to make sure the CPT is set to show_in_rest when it’s registered.

Take some time to explore these URLs in your browser. Add ?_embed to the end of a post or page URL (e.g., yourdomain.com/wp-json/wp/v2/posts?_embed). This will often include embedded details like featured images and author information, which is super handy for building out your front-end.

Building Your Next.js Frontend

Now, let’s switch gears to Next.js. Assuming you have Node.js and npm/yarn installed, we’ll start a new Next.js project.

Creating a New Next.js Project

Open your terminal and run:

“`bash

npx create-next-app@latest my-headless-wp-app

or

yarn create next-app my-headless-wp-app

“`

Follow the prompts. I usually opt for TypeScript, ESLint, Tailwind CSS (optional but great), src directory, App Router, and no custom import alias, but choose what suits you. Once it’s created, navigate into the directory:

“`bash

cd my-headless-wp-app

“`

Then start the development server:

“`bash

npm run dev

or

yarn dev

“`

You should see your new Next.js application running at http://localhost:3000.

Fetching Data in Next.js

This is where the magic happens. Next.js offers several ways to fetch data, and the best one depends on your specific needs. For static content that doesn’t change often, or where SEO is paramount, getStaticProps is excellent. For content that changes more frequently, or user-specific data, getServerSideProps is a good choice. With the App Router, you’ll be using fetch directly in server components, or React’s use hook in client components.

Let’s focus on using fetch in a server component for a simple blog post listing.

Example: Displaying Blog Posts

First, open my-headless-wp-app/app/page.tsx (or page.js if you didn’t choose TypeScript). We’ll modify this file to fetch and display our latest WordPress posts.

“`typescript jsx

// app/page.tsx or app/page.js

import Link from ‘next/link’;

// Define your WordPress API URL

const WORDPRESS_API_URL = process.env.NEXT_PUBLIC_WORDPRESS_API_URL;

// If you’re building locally and haven’t set an environment variable,

// you can temporarily hardcode it for testing, e.g.:

// const WORDPRESS_API_URL = ‘http://localhost:8888/your-wp-site/wp-json/wp/v2’;

// Remember to replace ‘http://localhost:8888/your-wp-site’ with your actual WordPress URL.

// IMPORTANT: Never hardcode sensitive API keys or production URLs directly in code.

// Always use environment variables for production.

async function getPosts() {

const res = await fetch(${WORDPRESS_API_URL}/posts?_embed&per_page=10);

if (!res.ok) {

// This will activate the closest error.js Error Boundary

throw new Error(‘Failed to fetch posts’);

}

return res.json();

}

export default async function Home() {

const posts = await getPosts();

return (

Latest Blog Posts from WordPress

{posts.map((post: any) => (

{post._embedded && post._embedded[‘wp:featuredmedia’] && post._embedded[‘wp:featuredmedia’][0] && (

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-md mb-4″

/>

)}

/posts/${post.slug}} className=”text-blue-600 hover:underline”>

Read more

))}

);

}

“`

Explanation:

  1. WORDPRESS_API_URL: This is where you put the base URL of your WordPress REST API (e.g., http://your-wordpress-domain.com/wp-json/wp/v2). It’s best practice to use an environment variable (NEXT_PUBLIC_) so it’s not hardcoded and can be different for development and production. Create a .env.local file in your project root and add NEXT_PUBLIC_WORDPRESS_API_URL=http://your-wordpress-domain.com/wp-json/wp/v2.
  2. getPosts() function: This async function uses the native fetch API to retrieve data from your WordPress endpoint. We’re fetching up to 10 posts and using ?_embed to get featured images and other linked data.
  3. Home component: This is a server component (async function Home()). Next.js automatically treats fetch calls in server components as server-side data fetching.
  4. posts.map(...): We iterate over the fetched posts and display their title, excerpt, and a featured image if available. dangerouslySetInnerHTML is used because WordPress content often contains HTML, but use it with caution and ensure your content source is trusted to prevent XSS attacks.
  5. Link component: We use Next.js’s Link component for client-side navigation to individual post pages. The href uses the post’s slug, which is a clean URL representation.

If you run npm run dev now, you should see your WordPress posts populating your Next.js homepage.

If you’re looking to enhance your understanding of integrating WordPress with modern frameworks, you might find it beneficial to explore a related article that delves into the nuances of using the WordPress REST API effectively. This resource provides valuable insights and practical examples that can complement your journey in utilizing WordPress as a headless backend with Next.js. For more information, check out this informative piece on WordPress and Next.js integration.

Creating Dynamic Pages for Single Posts

Listing posts is great, but clicking “Read more” should take us to the full post content. This requires dynamic routing in Next.js.

Dynamic Routing with App Router

In Next.js App Router, dynamic routes are created by enclosing a folder name in square brackets, like [slug]. So, for single posts, we’ll create the structure app/posts/[slug]/page.tsx.

Example: Single Post Page

Create a new file: app/posts/[slug]/page.tsx (or page.js).

“`typescript jsx

// app/posts/[slug]/page.tsx or page.js

import Link from ‘next/link’;

import { notFound } from ‘next/navigation’;

const WORDPRESS_API_URL = process.env.NEXT_PUBLIC_WORDPRESS_API_URL;

async function getPostBySlug(slug: string) {

const res = await fetch(${WORDPRESS_API_URL}/posts?slug=${slug}&_embed);

if (!res.ok) {

// If there’s an issue fetching, let the error boundary handle it.

throw new Error(‘Failed to fetch post’);

}

const posts = await res.json();

if (posts.length === 0) {

return null; // Post not found

}

return posts[0]; // The API returns an array, so we take the first item

}

// Generate static params for all existing posts to allow Next.js to pre-render them

export async function generateStaticParams() {

const res = await fetch(${WORDPRESS_API_URL}/posts?_per_page=100); // Fetch more posts for static generation

const posts = await res.json();

return posts.map((post: any) => ({

slug: post.slug,

}));

}

export default async function SinglePostPage({ params }: { params: { slug: string } }) {

const post = await getPostBySlug(params.slug);

if (!post) {

notFound(); // Display Next.js’s default 404 page if no post is found

}

return (

← Back to posts

{post._embedded && post._embedded[‘wp:featuredmedia’] && post._embedded[‘wp:featuredmedia’][0] && (

src={post._embedded[‘wp:featuredmedia’][0].source_url}

alt={post._embedded[‘wp:featuredmedia’][0].alt_text || post.title.rendered}

className=”w-full h-80 object-cover rounded-md mb-6″

/>

)}

Published on {new Date(post.date).toLocaleDateString()}

);

}

“`

Explanation:

  1. getPostBySlug(slug): This function fetches a single post from WordPress using its slug. We add slug=${slug} to the API query.
  2. generateStaticParams(): This is a key function in Next.js App Router for static site generation (SSG). It tells Next.js which dynamic paths (/posts/my-first-post, /posts/another-post) should be pre-rendered at build time. We fetch a list of all post slugs and return them. This significantly improves performance for public-facing blog posts.
  3. SinglePostPage component: This is another server component. It receives the slug from the URL via params.slug.
  4. notFound(): If getPostBySlug returns null (meaning no post was found for that slug), we call notFound() from next/navigation to render the default Next.js 404 page.
  5. Displaying Content: We render the full post title, date, and content.rendered. Again, dangerouslySetInnerHTML is used for the HTML content from WordPress. The prose classes (if you’re using Tailwind’s Typography plugin) help style the raw HTML nicely.

Now, if you click on a post title from your homepage, you should be navigating to a fully rendered single post page.

Handling Custom Post Types and Advanced Queries

WordPress is fantastic for more than just posts and pages. Custom Post Types (CPTs) and custom fields (with plugins like Advanced Custom Fields – ACF) are common. The REST API can handle these too.

Exposing Custom Post Types to the REST API

When you register a custom post type, ensure you set show_in_rest to true. If you’re using a plugin like CPT UI, there’s usually a checkbox for “Show in REST API.” Once enabled, your CPTs will be available endpoints, typically at /wp-json/wp/v2/your-cpt-slug.

Fetching ACF Fields

ACF fields aren’t part of the core WordPress REST API by default. You’ll need the free ACF to REST API plugin. Install and activate it. After activation, any ACF fields attached to your posts, pages, or CPTs will appear under the acf key in your API responses, making them easily accessible in Next.js.

Customizing API Queries

The WordPress REST API is quite powerful with its query parameters. Here are a few common ones you’ll use:

  • per_page: Number of items to return (e.g., ?per_page=5). Default is 10.
  • page: Page number for pagination (e.g., ?page=2).
  • categories: Filter by category ID (e.g., ?categories=1,5).
  • tags: Filter by tag ID (e.g., ?tags=2).
  • search: Search for content (e.g., ?search=keyword).
  • _embed: Embeds related resources (featured image, author, etc.). Absolutely essential.
  • _fields: To request only specific fields for performance (e.g., ?_fields=id,title,slug,content.rendered).
  • status: Filter by post status (e.g., ?status=publish,draft). Be careful with draft on a public API.

You can combine these with & in the URL (e.g., /posts?categories=1&per_page=5&_embed).

Enhancing User Experience and Workflow

While the basic setup works, there are several things you can do to make your headless WordPress experience even better.

Caching Strategies

For improved performance and reduced load on your WordPress server, caching is key.

Next.js Caching

Next.js’s fetch API has built-in caching mechanisms. By default, fetch requests are cached. For data that changes, you can configure revalidation:

  • Time-based revalidation: next: { revalidate: 60 } (every 60 seconds).
  • On-demand revalidation: By calling revalidatePath or revalidateTag from a route handler or server action after content changes in WordPress. This is typically triggered by a webhook from WordPress.

WordPress Caching

Even though Next.js does the heavy lifting, having a good caching plugin on your WordPress site (like WP Super Cache or W3 Total Cache) can still speed up the WordPress admin itself and ensure API requests are served quickly from its own cache, especially for more complex queries.

Setting Up Webhooks for Instant Content Updates

Static Site Generation (SSG) in Next.js is fantastic for performance and SEO, but it means your site is built at deploy time. If you update content in WordPress, your Next.js site won’t reflect those changes until you manually re-deploy or revalidate. Webhooks solve this.

How Webhooks Work

  1. WordPress action: When a post is published, updated, or deleted in WordPress, it sends an HTTP POST request to a specific URL.
  2. Next.js API Route: You create a Next.js API route (app/api/revalidate/route.ts) that listens for this POST request.
  3. Revalidation: When your Next.js API route receives the webhook, it uses revalidatePath() or revalidateTag() to tell Next.js to re-fetch and re-render the affected pages, regenerating the static content in the background.

Example Next.js Revalidation Route

“`typescript jsx

// app/api/revalidate/route.ts

import { revalidatePath, revalidateTag } from ‘next/cache’;

import { NextRequest, NextResponse } from ‘next/server’;

export async function POST(request: NextRequest) {

const secret = request.nextUrl.searchParams.get(‘secret’);

const path = request.nextUrl.searchParams.get(‘path’); // Or tag

// You can set up a custom secret token for security

if (secret !== process.env.MY_SECRET_TOKEN) {

return NextResponse.json({ message: ‘Invalid token’ }, { status: 401 });

}

try {

if (path) {

revalidatePath(path);

return NextResponse.json({ revalidated: true, now: Date.now(), path });

}

// Alternatively, revalidate all paths or specific tags

// revalidatePath(‘/’); // Revalidate homepage

// revalidateTag(‘posts’); // Revalidate data fetched with ‘posts’ tag

return NextResponse.json({ revalidated: false, message: ‘No path or tag provided’ });

} catch (err) {

return NextResponse.json({ message: ‘Error revalidating’, error: err }, { status: 500 });

}

}

“`

Then, you’d use a WordPress plugin like “WP Webhooks” or “Advanced Webhooks” to configure a POST request to https://your-nextjs-site.com/api/revalidate?secret=YOUR_SECRET_TOKEN&path=/posts/your-post-slug whenever a post is updated.

Handling Authentication (for private content)

If you have private, user-specific, or member-only content in WordPress that needs to be displayed in Next.js, you’ll need an authentication system.

The WordPress REST API supports several authentication methods:

  • Application Passwords: This is often the simplest for machine-to-machine communication if the content isn’t user-specific. You generate a password in WordPress admin, and your Next.js app includes it in the Authorization header.
  • JWT Authentication: A more robust solution for user-based authentication. You’d use a plugin like “JWT Authentication for WP REST API.” Your Next.js app would authenticate a user against WordPress, get a JWT token, and then include that token in subsequent API requests.
  • OAuth: More complex but highly secure for broader integrations.

For most basic headless setups, you might only need public content. If authentication becomes a requirement, plan it carefully, as it adds a layer of complexity.

Next Steps and Further Enhancements

  • Styling: Integrate a CSS framework like Tailwind CSS (as I’ve used in the examples) or CSS modules for professional styling.
  • Error Handling: Implement more robust error handling and display user-friendly messages for failed API requests or 404s.
  • Loading States: Show loading spinners or skeletons while data is being fetched, especially for pages that might take longer to load.
  • SEO Meta: Use next/head (or the new metadata API in App Router) to dynamically set titles, descriptions, and other SEO meta tags based on the WordPress content.
  • Comments: If you need comments, you’d integrate a third-party comment system like Disqus or Hyvor Talk, or build out a custom comment system using the WordPress REST API for posting comments.
  • Forms: For forms, you’d typically handle them directly in Next.js, perhaps integrating with a form service or your own API route that then submits to a WordPress backend or another service.

Using WordPress as a headless backend with Next.js opens up a world of possibilities for building high-performance, flexible, and powerful websites. It’s a fantastic blend of content management ease with modern front-end development capabilities. While there’s a learning curve, the benefits often outweigh the initial effort. Happy building!