Next WP

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

Live Demo | Video Tutorial | Headless Theme (761)

Table of Contents

• Quick Start
• Prerequisites
• Environment Variables
• Features
• Project Structure
• Deployment
  • Railway (Recommended)
  • Vercel
  • Local Development
• WordPress API Functions
• Cache Revalidation
• Customization
• Troubleshooting
• 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
├── app/                      # Next.js App Router
3
│   ├── api/
4
│   │   ├── og/              # OG image generation
5
│   │   └── revalidate/      # Cache revalidation webhook
6
│   ├── pages/[slug]/        # Dynamic WordPress pages
7
│   ├── posts/
8
│   │   ├── [slug]/          # Individual post pages
9
│   │   ├── authors/         # Author archive
10
│   │   ├── categories/      # Category archive
11
│   │   └── tags/            # Tag archive
12
│   ├── layout.tsx           # Root layout
13
│   ├── page.tsx             # Homepage
14
│   └── sitemap.ts           # Dynamic sitemap
15
├── components/
16
│   ├── posts/               # Post-related components
17
│   │   ├── post-card.tsx    # Post card component
18
│   │   ├── filter.tsx       # Filter controls
19
│   │   └── search-input.tsx # Search component
20
│   ├── nav/                 # Navigation components
21
│   ├── theme/               # Theme toggle
22
│   └── ui/                  # shadcn/ui components
23
├── lib/
24
│   ├── wordpress.ts         # WordPress API functions
25
│   └── wordpress.d.ts       # TypeScript definitions
26
├── plugin/                  # WordPress revalidation plugin
27
├── menu.config.ts           # Navigation configuration
28
├── site.config.ts           # Site metadata
29
└── CLAUDE.md               # AI assistant guidelines

Deployment

Railway (Recommended)

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

What's Included

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
└─────────┘     └───────────┘     └─────────┘

Deployment

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

Post-Deployment Setup

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)

Customizing the Next.js Code

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
getAllPosts(filters?)        // Get all posts (max 100)
2
getPostsPaginated(page, perPage, filters?)  // Paginated posts
3
getPostBySlug(slug)          // Single post by slug
4
getPostById(id)              // Single post by ID

Taxonomies

1
getAllCategories()           // All categories
2
getCategoryBySlug(slug)      // Category by slug
3
getAllTags()                 // All tags
4
getTagBySlug(slug)           // Tag by slug
5
getPostsByCategory(id)       // Posts in category
6
getPostsByTag(id)            // Posts with tag

Authors & Pages

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

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
  { href: "/", label: "Home" },
3
  { href: "/posts", label: "Blog" },
4
  // Add more links...
5
];

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

Scripts

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

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.