Next.js Starter for WordPress Headless CMS

Watch the Demo Video

Need a headless theme? Use 761

This is a starter template for building a Next.js application that fetches data from a WordPress site using the WordPress REST API. The template includes functions for fetching posts, categories, tags, authors, and featured media from a WordPress site and rendering them in a Next.js application.

next-wp is built with Next.js 15, React, Typescript, Tailwind, shadcn/ui, and brijr/craft. It pairs nicely with brijr/components for a rapid development experience. Built by Cameron and Bridger at 9d8.

Table of Contents

• Next.js Starter for WordPress Headless CMS
  • Table of Contents
  • Overview
  • WordPress Functions
  • Pagination System
  • WordPress Types
  • Post Card Component
  • Filter Component
  • Dynamic Sitemap
  • Dynamic OG Images
  • Revalidation Setup
  • Search Functionality
  • AI Assistant Guidelines

Overview

What's included?

✅ Type-safe data layer with the WordPress RestAPI ✅ Efficient server-side pagination system ✅ WordPress Plugin for revalidation ✅ Granular access to revalidation and cache tags ✅ Setup for all basic WordPress options: Posts, Pages, Authors, Categories, Tags ✅ Easy integration with custom post types and ACF ✅ Dynamic routes for Posts and Pages ✅ Design system for layout and prose styling (craft-ds.com) ✅ Filter, Search, and Card components ✅ Dynamically rendered sitemap ✅ Dynamically generated metadata ✅ Dynamically generated OG/Twitter Cards for Posts and pages ✅ Responsive Nav and Footer components ✅ Site configuration file ✅ Menu configuration file ✅ Lite and dark mode support ✅ shadcn/ui components and theming ✅ Vercel analytics

Important files

• lib/wordpress.ts -> Functions for fetching WordPress CMS via Rest API with cache tags
• lib/wordpress.d.ts -> Type declarations for the WordPress Rest API
• components/craft.tsx -> Handles the design system for the site and prose styling
• components/posts/post-card.tsx -> Component and styling for posts
• components/posts/filter.tsx -> Filter component for Posts
• components/posts/search-input.tsx -> Search component for Posts
• menu.config.ts -> Site nav menu configuration for desktop and mobile
• site.config.ts -> Configuration for sitemap.ts and more
• app/sitemap.ts -> Dynamically generated sitemap

The following environment variables are required in your .env.local file:

1
WORDPRESS_URL="https://wordpress.com"
2
WORDPRESS_HOSTNAME="wordpress.com"
3
WORDPRESS_WEBHOOK_SECRET="your-secret-key-here"

You can find the example of .env.local file in the .env.example file (and in Vercel).

WordPress Functions

The lib/wordpress.ts file contains a comprehensive set of functions for interacting with the WordPress REST API. Each function is optimized for Next.js 15's caching system and includes proper error handling.

Core Functionality

1
// Default fetch options for all WordPress API calls
2
const defaultFetchOptions = {
3
  next: {
4
    tags: ["wordpress"],
5
    revalidate: 3600, // 1 hour cache
6
  },
7
  headers: {
8
    Accept: "application/json",
9
    "Content-Type": "application/json",
10
  },
11
};

Available Functions

Posts

• getAllPosts(filterParams?: { author?: string; tag?: string; category?: string; search?: string; }): Fetches posts with optional filtering by author, tag, category, or search query. Uses cache tags for efficient revalidation. Note: Limited to 100 posts for performance.
• getPostsPaginated(page?: number, perPage?: number, filterParams?: { author?: string; tag?: string; category?: string; search?: string; }): Recommended - Fetches posts with server-side pagination and filtering. Returns both data and pagination headers for efficient large-scale post handling.
• getPostById(id: number): Retrieves a specific post by ID with proper error handling.
• getPostBySlug(slug: string): Fetches a post using its URL-friendly slug.

Categories

• getAllCategories(): Retrieves all categories with cache invalidation support.
• getCategoryById(id: number): Gets a specific category with error handling.
• getCategoryBySlug(slug: string): Fetches a category by its slug.
• getPostsByCategory(categoryId: number): Gets all posts in a category, using proper cache tags.

Tags

• getAllTags(): Fetches all available tags.
• getTagById(id: number): Retrieves a specific tag.
• getTagBySlug(slug: string): Gets a tag by its slug.
• getTagsByPost(postId: number): Fetches all tags associated with a post.
• getPostsByTag(tagId: number): Gets all posts with a specific tag.

Pages

• getAllPages(): Retrieves all WordPress pages.
• getPageById(id: number): Gets a specific page by ID.
• getPageBySlug(slug: string): Fetches a page by its slug.

Authors

• getAllAuthors(): Fetches all WordPress authors.
• getAuthorById(id: number): Gets a specific author.
• getAuthorBySlug(slug: string): Retrieves an author by slug.
• getPostsByAuthor(authorId: number): Gets all posts by a specific author.

Media

• getFeaturedMediaById(id: number): Retrieves featured media (images) with size information.

Error Handling

All functions use the custom WordPressAPIError class for consistent error handling:

1
class WordPressAPIError extends Error {
2
  constructor(
3
    message: string,
4
    public status: number,
5
    public endpoint: string,
6
  ) {
7
    super(message);
8
    this.name = "WordPressAPIError";
9
  }
10
}

Cache Management

Each function supports Next.js 15's cache tags for efficient revalidation:

1
// Example cache configuration
2
{
3
  next: {
4
    tags: ["wordpress", "posts", `post-${id}`],
5
    revalidate: 3600,
6
  }
7
}

Usage Example

1
try {
2
  // Fetch posts with filtering
3
  const posts = await getAllPosts({
4
    author: "123",
5
    category: "news",
6
    tag: "featured",
7
  });
8

9
  // Handle errors properly
10
} catch (error) {
11
  if (error instanceof WordPressAPIError) {
12
    console.error(`API Error: ${error.message} (${error.status})`);
13
  }
14
}

These functions are designed to work seamlessly with Next.js 15's App Router and provide proper TypeScript support through the types defined in wordpress.d.ts.

Pagination System

The starter includes an efficient pagination system designed for high-performance WordPress sites with large amounts of content.

Server-Side Pagination

Instead of fetching all posts and paginating client-side, the getPostsPaginated function implements true server-side pagination:

1
// Fetch page 2 with 10 posts per page
2
const response = await getPostsPaginated(2, 10, {
3
  author: "123",
4
  category: "news",
5
  search: "nextjs"
6
});
7

8
const { data: posts, headers } = response;
9
const { total, totalPages } = headers;

Pagination Response Structure

The getPostsPaginated function returns a WordPressResponse<Post[]> object:

1
interface WordPressResponse<T> {
2
  data: T;                    // The actual posts array
3
  headers: {
4
    total: number;            // Total number of posts matching the query
5
    totalPages: number;       // Total number of pages
6
  };
7
}

Benefits of Server-Side Pagination

1. Performance: Only fetch the posts you need (e.g., 9 posts instead of 100+)
2. Memory Efficiency: Reduced memory usage, especially for sites with many posts
3. Network Optimization: Smaller response payloads (up to 90% reduction)
4. Scalability: Handles thousands of posts without performance degradation
5. Real Pagination Info: Access to total count without processing all data

Migration from getAllPosts

For existing implementations using getAllPosts, you can migrate to the more efficient pagination:

1
// Before: Client-side pagination
2
const allPosts = await getAllPosts({ author, category });
3
const page = 1;
4
const postsPerPage = 9;
5
const paginatedPosts = allPosts.slice((page - 1) * postsPerPage, page * postsPerPage);
6
const totalPages = Math.ceil(allPosts.length / postsPerPage);
7

8
// After: Server-side pagination
9
const { data: posts, headers } = await getPostsPaginated(page, postsPerPage, { author, category });
10
const { total, totalPages } = headers;

Example Implementation

The main posts page (app/posts/page.tsx) demonstrates the pagination system:

1
export default async function PostsPage({ searchParams }) {
2
  const params = await searchParams;
3
  const page = params.page ? parseInt(params.page, 10) : 1;
4
  const postsPerPage = 9;
5

6
  // Efficient server-side pagination
7
  const { data: posts, headers } = await getPostsPaginated(
8
    page,
9
    postsPerPage,
10
    {
11
      author: params.author,
12
      category: params.category,
13
      tag: params.tag,
14
      search: params.search
15
    }
16
  );
17

18
  const { total, totalPages } = headers;
19

20
  return (
21
    <div>
22
      <p>{total} posts found</p>
23
      {posts.map(post => <PostCard key={post.id} post={post} />)}
24
      {totalPages > 1 && <PaginationComponent />}
25
    </div>
26
  );
27
}

WordPress API Headers

The pagination system leverages WordPress REST API headers:

• X-WP-Total: Total number of posts matching the query
• X-WP-TotalPages: Total number of pages based on per_page parameter

These headers are automatically parsed and included in the response for easy access to pagination metadata.

Cache Tags Integration

The pagination system includes sophisticated cache tags for optimal performance:

1
// Dynamic cache tags based on query parameters
2
["wordpress", "posts", "posts-page-1", "posts-category-123"]

This ensures that when content changes, only the relevant pagination pages are revalidated, maintaining excellent performance even with large content sets.

WordPress Types

The lib/wordpress.d.ts file contains comprehensive TypeScript type definitions for WordPress entities. The type system is built around a core WPEntity interface that provides common properties for WordPress content:

1
interface WPEntity {
2
  id: number;
3
  date: string;
4
  date_gmt: string;
5
  modified: string;
6
  modified_gmt: string;
7
  slug: string;
8
  status: "publish" | "future" | "draft" | "pending" | "private";
9
  link: string;
10
  guid: {
11
    rendered: string;
12
  };
13
}

Key type definitions include:

Content Types

• Post: Blog posts and articles (extends WPEntity)
• Page: Static pages (extends WPEntity)
• Author: User information
• Category: Post categories (extends Taxonomy)
• Tag: Post tags (extends Taxonomy)
• FeaturedMedia: Media attachments (extends WPEntity)

Pagination Types

• WordPressResponse<T>: Wrapper for paginated responses containing data and headers
• WordPressPaginationHeaders: Contains pagination metadata (total, totalPages)

Shared Interfaces

• RenderedContent: For content with HTML rendering
• RenderedTitle: For titles with HTML rendering
• Taxonomy: Base interface for categories and tags

Component Types

1
interface FilterBarProps {
2
  authors: Author[];
3
  tags: Tag[];
4
  categories: Category[];
5
  selectedAuthor?: Author["id"];
6
  selectedTag?: Tag["id"];
7
  selectedCategory?: Category["id"];
8
  onAuthorChange?: (authorId: Author["id"] | undefined) => void;
9
  onTagChange?: (tagId: Tag["id"] | undefined) => void;
10
  onCategoryChange?: (categoryId: Category["id"] | undefined) => void;
11
}

Media Types

1
interface MediaDetails {
2
  width: number;
3
  height: number;
4
  file: string;
5
  sizes: Record<string, MediaSize>;
6
}
7

8
interface MediaSize {
9
  file: string;
10
  width: number;
11
  height: number;
12
  mime_type: string;
13
  source_url: string;
14
}

All types are designed to be:

• Fully type-safe
• Extensible
• Self-documenting
• Compatible with the WordPress REST API

Post Card Component

The components/posts/post-card.tsx file contains the PostCard component, which is responsible for rendering a single post card in the application. Here's an overview of the component:

Props

• post: A Post object representing the WordPress post to be rendered.

Functionality

1. The component fetches the featured media, author, and category associated with the post using the getFeaturedMediaById, getAuthorById, and getCategoryById functions from lib/wordpress.ts.

2. It formats the post date using the toLocaleDateString method with the specified options.

3. The component renders a link to the individual post page using the post's slug.

4. Inside the link, it displays the post's featured image, title, excerpt, category, and date.

5. The post title and excerpt are rendered using the dangerouslySetInnerHTML attribute to handle HTML content.

6. The component applies various CSS classes to style the post card, including hover effects and transitions.

Usage

To use the PostCard component, import it into your desired page or component and pass a Post object as the post prop.

Filter Component

The components/posts/filter.tsx file contains the FilterPosts component, which provides a filtering interface for posts based on tags, categories, and authors. Here's an overview of the component:

Props

• authors: An array of Author objects representing the available authors to filter by.
• tags: An array of Tag objects representing the available tags to filter by.
• categories: An array of Category objects representing the available categories to filter by.
• selectedAuthor: An optional string representing the currently selected author ID.
• selectedTag: An optional string representing the currently selected tag ID.
• selectedCategory: An optional string representing the currently selected category ID.

Functionality

1. The component uses the useRouter hook from Next.js to handle navigation and URL updates based on the selected filters.

2. It renders three Select components for filtering posts by tag, category, and author. Each Select component displays the available options and allows the user to select a specific value or choose "All" to reset the filter.

3. When a filter value is changed, the handleFilterChange function is called with the filter type and selected value. It updates the URL query parameters accordingly and navigates to the updated URL.

4. The component also includes a "Reset Filters" button that, when clicked, calls the handleResetFilters function to navigate back to the /posts page without any filters applied.

5. The selected filter values are passed as props to the component and used to set the initial values of the Select components.

Search Functionality

The template includes a powerful search system that works seamlessly with WordPress's REST API:

Search Component

Located in components/posts/search-input.tsx, the SearchInput component provides real-time search capabilities:

1
// Usage example
2
import { SearchInput } from "@/components/posts/search-input";
3

4
<SearchInput defaultValue={search} />

Features:

• Real-time search with 300ms debouncing
• URL-based state management
• Maintains filters while searching
• Server-side rendering for SEO
• Combines with existing category, tag, and author filters

Search Implementation

The search system is implemented across several layers:

1. Client-Side Component (search-input.tsx):

   • Uses Next.js App Router's URL handling
   • Debounced input for better performance
   • Maintains search state in URL parameters

2. Server-Side Processing (page.tsx):

   • Handles search parameters server-side
   • Combines search with other filters
   • Parallel data fetching for better performance

3. WordPress API Integration (wordpress.ts):

   • Comprehensive search across:
     • Post content and titles
     • Author names
     • Category names
     • Tag names
   • Smart query construction
   • Filter combination support

Search API Functions

The following search-related functions are available in lib/wordpress.ts:

1
// Search posts with combined filters
2
getAllPosts({
3
  search?: string,
4
  author?: string,
5
  tag?: string,
6
  category?: string
7
})
8

9
// Search specific content types
10
searchCategories(query: string)
11
searchTags(query: string)
12
searchAuthors(query: string)

Example Usage

1
// In your page component
2
const { search } = await searchParams;
3
const posts = search ? await getAllPosts({ search }) : await getAllPosts();

The search functionality automatically updates filters and results as you type, providing a smooth user experience while maintaining good performance through debouncing and server-side rendering.

Dynamic OG Images

This starter includes automatic OG image generation for both posts and pages. The OG images are generated on-demand using the Edge Runtime and include:

• Dynamic title and description
• Modern, responsive design
• Proper social media card sizes
• Automatic text wrapping and scaling

You can test the OG image generation by visiting:

1
/api/og?title=Your Title&description=Your Description

The OG images are automatically generated for:

• Blog posts: /posts/[slug]
• Pages: /pages/[slug]

Each OG image includes:

• The post/page title
• A snippet of the content (automatically trimmed and cleaned)
• Consistent branding across your site
• Proper dimensions for social media platforms

Dynamic Sitemap

The sitemap for next-wp is generated at @/app/sitemap.ts and will appear live on your site at yourdomain.com/sitemap.xml. In order to set up your sitemap correctly please make sure to update the site_domain in the site.config.ts to be the domain of your frontend (not your WordPress instance).

Revalidation Setup

This starter implements an intelligent caching and revalidation system using Next.js 15's cache tags. Here's how it works:

Cache Tags System

The WordPress API functions use a sophisticated hierarchical cache tag system for granular revalidation:

Global Tags

• wordpress - Affects all WordPress content

Content Type Tags

• posts - All post content
• categories - All category content
• tags - All tag content
• authors - All author content

Pagination-Specific Tags

• posts-page-1, posts-page-2, etc. - Individual pagination pages
• posts-search - Search result pages
• posts-author-123 - Posts filtered by specific author
• posts-category-456 - Posts filtered by specific category
• posts-tag-789 - Posts filtered by specific tag

Individual Item Tags

• post-123 - Specific post content
• category-456 - Specific category content
• tag-789 - Specific tag content
• author-123 - Specific author content

This granular system ensures that when content changes, only the relevant cached data is invalidated, providing optimal performance.

Automatic Revalidation

1. Install the WordPress Plugin:

   • Navigate to the /plugin directory
   • Use the pre-built next-revalidate.zip file or create a ZIP from the next-revalidate folder
   • Install and activate through WordPress admin
   • Go to Settings > Next.js Revalidation
   • Configure your Next.js URL and webhook secret

2. Configure Next.js:

   • Add WORDPRESS_WEBHOOK_SECRET to your environment variables (same secret as in WordPress plugin)
   • The webhook endpoint at /api/revalidate is already set up
   • No additional configuration needed

3. How it Works:

   • When content is updated in WordPress, the plugin sends a webhook
   • The webhook includes content type and ID information
   • Next.js intelligently revalidates specific cache tags based on the change:
     • Post changes: Revalidates posts, post-{id}, and posts-page-1
     • Category changes: Revalidates categories, category-{id}, and posts-category-{id}
     • Tag changes: Revalidates tags, tag-{id}, and posts-tag-{id}
     • Author changes: Revalidates authors, author-{id}, and posts-author-{id}
   • Only affected cached content is updated, maintaining optimal performance

Plugin Features

The Next.js Revalidation plugin includes:

• Automatic revalidation when posts, pages, categories, tags, authors, or media are modified
• Settings page to configure your Next.js site URL and webhook secret
• Manual revalidation option for full site refresh
• Support for custom post types and taxonomies
• Optional admin notifications for revalidation events

Manual Revalidation

You can manually revalidate content using Next.js cache functions:

1
import { revalidateTag } from "next/cache";
2

3
// Revalidate all WordPress content
4
revalidateTag("wordpress");
5

6
// Revalidate specific content types
7
revalidateTag("posts");
8
revalidateTag("categories");
9
revalidateTag("tags");
10
revalidateTag("authors");
11

12
// Revalidate specific items
13
revalidateTag("post-123");
14
revalidateTag("category-456");
15

16
// Revalidate pagination-specific content
17
revalidateTag("posts-page-1");
18
revalidateTag("posts-category-123");
19
revalidateTag("posts-search");

This system ensures your content stays fresh while maintaining optimal performance through intelligent caching.

AI Assistant Guidelines

This codebase includes a CLAUDE.md file that provides guidance to AI assistants (like Claude) when working with code in this repository. It contains:

• Project architecture overview
• Code style guidelines
• Build and development commands
• TypeScript and component patterns
• Environment variable configuration

This ensures AI assistants maintain consistency and follow project conventions when helping with development tasks.

Built by Bridger Tower and Cameron Youngblood at 9d8