Next WP

A modern headless WordPress starter built with Next.js 16, React 19, and TypeScript.

Live Demo | Video Tutorial | Headless Theme (761)

Need a WooCommerce version? Try next-woo

Table of Contents

• Quick Start
• Prerequisites
• Environment Variables
• Features
• Project Structure
• Deployment
  • Railway (Recommended)
  • Vercel
  • Local Development
• WordPress API Functions
• Cache Revalidation
• Customization
• Troubleshooting
• Testing
• Scripts
• Contributing
• License
• Credits

Quick Start

1
# Clone the repository
2
git clone https://github.com/9d8dev/next-wp.git
3
cd next-wp
4

5
# Install dependencies
6
pnpm install
7

8
# Set up environment variables
9
cp .env.example .env.local
10
# Edit .env.local with your WordPress URL and credentials
11

12
# Start development server
13
pnpm dev

Your site is now running at http://localhost:3000.

Prerequisites

• Node.js 18.17 or later
• pnpm 8.0 or later (recommended) or npm/yarn
• WordPress site with REST API enabled (default in WordPress 4.7+)

Environment Variables

Create a .env.local file in the root directory:

1
WORDPRESS_URL="https://your-wordpress-site.com"    # Full WordPress URL
2
WORDPRESS_HOSTNAME="your-wordpress-site.com"       # Domain for image optimization
3
WORDPRESS_WEBHOOK_SECRET="your-secret-key-here"    # Secret for cache revalidation

Features

• Type-safe WordPress API - Full TypeScript support with comprehensive type definitions
• Server-side pagination - Efficient handling of large content libraries
• Automatic cache revalidation - WordPress plugin for instant updates
• Dynamic routes - Posts, pages, authors, categories, and tags
• Search & filtering - Real-time search with debouncing
• Dynamic sitemap - Auto-generated XML sitemap
• OG image generation - Dynamic social media cards
• Dark mode - Built-in theme switching
• shadcn/ui components - Beautiful, accessible UI components
• Responsive design - Mobile-first with Tailwind CSS v4

Project Structure

1
next-wp/
2
├── __tests__/                # Vitest test suite
3
│   ├── api/                 # API route tests
4
│   └── lib/                 # Library tests
5
├── app/                      # Next.js App Router
6
│   ├── api/
7
│   │   ├── og/              # OG image generation
8
│   │   └── revalidate/      # Cache revalidation webhook
9
│   ├── pages/[slug]/        # Dynamic WordPress pages
10
│   ├── posts/
11
│   │   ├── [slug]/          # Individual post pages
12
│   │   ├── authors/         # Author archive
13
│   │   ├── categories/      # Category archive
14
│   │   └── tags/            # Tag archive
15
│   ├── layout.tsx           # Root layout
16
│   ├── page.tsx             # Homepage
17
│   └── sitemap.ts           # Dynamic sitemap
18
├── components/
19
│   ├── posts/               # Post-related components
20
│   │   ├── post-card.tsx    # Post card component
21
│   │   ├── filter.tsx       # Filter controls
22
│   │   └── search-input.tsx # Search component
23
│   ├── nav/                 # Navigation components
24
│   ├── theme/               # Theme toggle
25
│   └── ui/                  # shadcn/ui components
26
├── lib/
27
│   ├── wordpress.ts         # WordPress API functions
28
│   └── wordpress.d.ts       # TypeScript definitions
29
├── plugin/                  # WordPress revalidation plugin
30
├── menu.config.ts           # Navigation configuration
31
├── site.config.ts           # Site metadata
32
└── vitest.config.ts         # Test configuration

Deployment

Railway (Recommended)

Railway deploys the complete stack with one click: MySQL + WordPress + Next.js.

The Railway template uses a custom WordPress Docker image (ghcr.io/9d8dev/next-wp-wordpress) with:

• next-revalidate plugin - Pre-installed and auto-activated for cache revalidation
• nextjs-headless theme - Redirects WordPress frontend to your Next.js site
• WP-CLI - Automated WordPress setup
• MySQL 8.0 - Database with persistent volume
• Next.js - Your frontend application

1
┌─────────┐     ┌───────────┐     ┌─────────┐
2
│  MySQL  │────▶│ WordPress │◀────│ Next.js │
3
│   DB    │     │   (CMS)   │     │(Frontend)│
4
└─────────┘     └───────────┘     └─────────┘

1. Click the Deploy on Railway button above
2. Wait for all 3 services to deploy (MySQL, WordPress, Next.js)
3. Note the WordPress and Next.js public URLs from the Railway dashboard

1. Complete WordPress Installation

1. Visit your WordPress URL (e.g., https://wordpress-xxx.up.railway.app)
2. Complete the installation wizard:
   • Site Title
   • Admin Username
   • Admin Password
   • Admin Email
3. Click "Install WordPress"

2. Configure the Revalidation Plugin

The next-revalidate plugin is pre-installed and activated.

1. Go to WordPress Admin → Settings → Next.js Revalidation
2. Enter your Next.js URL (e.g., https://next-wp-xxx.up.railway.app)
3. Enter the Webhook Secret:
   • In Railway, go to your Next.js service → Variables
   • Copy the WORDPRESS_WEBHOOK_SECRET value
   • Paste it in the plugin settings
4. Click Save

3. Test the Setup

1. Create a test post in WordPress and publish it
2. Visit your Next.js site - the post should appear
3. Edit the post in WordPress
4. Refresh the Next.js site - changes should appear (revalidation working)

By default, the template deploys from the 9d8dev/next-wp repository. To customize:

1. In Railway, click on the Next.js service
2. Go to Settings → Source → Upstream Repo
3. Click "Eject"
4. Select your GitHub account/organization
5. Click "Eject service"

Railway creates a copy of the repository in your GitHub. You can then:

• Clone the repo locally
• Make customizations (styling, components, pages)
• Push changes → Railway auto-deploys

Vercel

1. Click the Deploy with Vercel button above
2. Fill in environment variables:
   • WORDPRESS_URL - Your existing WordPress site URL
   • WORDPRESS_HOSTNAME - WordPress domain (for images)
   • WORDPRESS_WEBHOOK_SECRET - Generate a secure random string
3. Deploy and wait for build to complete
4. Install the revalidation plugin on your WordPress site
5. Configure the plugin with your Vercel deployment URL

Local Development

1
# Install dependencies
2
pnpm install
3

4
# Copy environment template
5
cp .env.example .env.local
6

7
# Configure your WordPress connection in .env.local
8
# Then start the dev server
9
pnpm dev

Required: Your WordPress site must have the REST API enabled (default since WP 4.7).

WordPress API Functions

All WordPress interactions are centralized in lib/wordpress.ts:

Posts

1
getRecentPosts(filters?)                    // Recent posts (max 100)
2
getPostsPaginated(page, perPage, filters?)  // Paginated posts with headers
3
getPostBySlug(slug)                         // Single post by slug (with _embed)
4
getPostById(id)                             // Single post by ID
5
getAllPostSlugs()                            // All slugs (for static generation)
6
getAllPostsForSitemap()                      // All slugs + modified dates

Taxonomies

1
getAllCategories()                           // All categories
2
getCategoryById(id)                         // Category by ID
3
getCategoryBySlug(slug)                     // Category by slug
4
getAllTags()                                // All tags
5
getTagById(id)                              // Tag by ID
6
getTagBySlug(slug)                          // Tag by slug
7
getPostsByCategory(id)                      // Posts in category
8
getPostsByTag(id)                           // Posts with tag
9
getTagsByPost(postId)                       // Tags on a post

Authors & Pages

1
getAllAuthors()                              // All authors
2
getAuthorById(id)                           // Author by ID
3
getAuthorBySlug(slug)                       // Author by slug
4
getPostsByAuthor(id)                        // Posts by author
5
getAllPages()                               // All pages
6
getPageById(id)                             // Page by ID
7
getPageBySlug(slug)                         // Page by slug

Paginated Queries

1
getPostsByCategoryPaginated(categoryId, page, perPage)
2
getPostsByTagPaginated(tagId, page, perPage)
3
getPostsByAuthorPaginated(authorId, page, perPage)

Search

1
searchCategories(query)                     // Search categories
2
searchTags(query)                           // Search tags
3
searchAuthors(query)                        // Search authors

Example Usage

1
import { getPostsPaginated } from "@/lib/wordpress";
2

3
const { data: posts, headers } = await getPostsPaginated(1, 9, {
4
  category: "news",
5
  search: "nextjs"
6
});
7

8
console.log(`Found ${headers.total} posts across ${headers.totalPages} pages`);

Cache Revalidation

The starter uses Next.js cache tags for efficient revalidation:

1. Install the plugin - Download next-revalidate.zip and upload to WordPress
2. Configure - Go to Settings > Next.js Revalidation
3. Set URL - Enter your Next.js site URL
4. Set secret - Use the same WORDPRESS_WEBHOOK_SECRET value

When content changes in WordPress, only affected pages are revalidated.

Note: If using the Railway template, the plugin is pre-installed automatically.

Customization

Site Configuration

Edit site.config.ts for site metadata:

1
export const siteConfig = {
2
  site_name: "Your Site",
3
  site_domain: "yourdomain.com",
4
  site_description: "Your site description"
5
};

Navigation

Edit menu.config.ts for navigation links:

1
export const mainMenu = {
2
  home: "/",
3
  blog: "/posts",
4
  // Add more links...
5
};
6

7
export const contentMenu = {
8
  categories: "/posts/categories",
9
  tags: "/posts/tags",
10
  authors: "/posts/authors",
11
};

Theming

This project uses shadcn/ui with Tailwind CSS. Customize colors in your CSS or update the shadcn theme.

Troubleshooting

REST API not accessible

• Ensure your WordPress site is publicly accessible
• Check that permalinks are set (Settings > Permalinks)
• Verify REST API at your-site.com/wp-json/wp/v2/posts

Images not loading

• Add your WordPress domain to WORDPRESS_HOSTNAME
• Check next.config.ts has the correct remotePatterns

Revalidation not working

• Verify WORDPRESS_WEBHOOK_SECRET matches in both WordPress and Next.js
• Check the plugin is activated in WordPress
• Test the webhook endpoint at /api/revalidate

CORS errors

• Install a CORS plugin on WordPress, or
• Configure your server to allow requests from your Next.js domain

Testing

The project uses Vitest for unit testing.

1
pnpm test          # Run all tests
2
pnpm test:watch    # Run in watch mode

Tests cover the core modules:

Scripts

1
pnpm dev       # Start development server
2
pnpm build     # Build for production
3
pnpm start     # Start production server
4
pnpm lint      # Run ESLint
5
pnpm test      # Run tests

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see LICENSE for details.

Credits

Built with Next.js, Tailwind CSS, shadcn/ui, and brijr/craft.

Created by Bridger Tower and Cameron Youngblood at 9d8.