[opensourcedex]

next-wp is a free, open source content management systems (cms) project written in TypeScript and released under MIT. It has 1,296 GitHub stars, 320 forks and 1 open issues, and was last pushed 1 months ago. On this registry it ranks #31 of 47 tracked projects in Content Management Systems (CMS), with 5 head-to-head comparisons available. It gained 1 stars over the last 3 tracked days.

What is next-wp?

What it is

Next WP is an MIT-licensed TypeScript starter for a headless WordPress site built with the Next.js App Router and React Server Components. It combines a WordPress content source with a Next.js frontend using Tailwind CSS, shadcn/ui components, and routes for posts, pages, authors, categories, tags, search, sitemap, and Open Graph images.

The project solves the problem of using WordPress as a publishing backend while presenting content through Next.js. It gives developers a starting codebase for connecting the WordPress REST API to typed frontend routes, server-rendered content pages, and cache revalidation, instead of building those integration pieces from scratch.

Key capabilities

  • It connects to a WordPress site through the REST API and provides type-safe access to content with TypeScript definitions.
  • It supports server-side pagination for large content libraries, so archive views load content in pages rather than rendering every item at once.
  • It includes cache revalidation through a WordPress plugin and a Next.js webhook route, so updated content can refresh the frontend cache.
  • It generates dynamic routes for posts, pages, authors, categories, and tags, with archive and individual content views.
  • It provides real-time search and filtering with debouncing, a dynamic XML sitemap, and dynamic Open Graph image generation.
  • It ships with dark mode, responsive Tailwind CSS v4 styling, shadcn/ui components, and a Vitest test suite.

Who uses it and how

  • Content teams use it when they want WordPress for editing and publishing, while developers control presentation with React Server Components and Next.js routing.
  • Developers use it by cloning the repository, installing dependencies with pnpm, adding environment variables, then running the local development server.
  • Deployers use the Railway and Vercel paths, configuring the WordPress URL, image hostname, and webhook secret for the hosted application.
  • Editors use it in a workflow where WordPress changes trigger cache revalidation, so the Next.js site can reflect new content without a manual redeploy.

Getting started

The typical local setup is to clone the repository, run pnpm install, copy the example environment file, set the WordPress URL, image hostname, and webhook secret, then run pnpm dev. The README also provides Railway and Vercel deployment buttons, and it requires Node.js 22.13 or later, pnpm 11, and a WordPress site with the REST API enabled.

When to use it — and when not to

Use it when you already operate WordPress and want a Next.js frontend with typed content routes, revalidation, sitemap, and social image generation. Do not use it if you need a complete CMS inside Next.js, because the content model, editing experience, and REST API depend on an external WordPress installation. Avoid it for WooCommerce storefronts, since the README points to next-woo for the commerce version.

project readme (upstream, from github) — read inline

Next WP

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

Deploy on Railway

Deploy with Vercel

Next WP Screenshot

Live Demo | Video Tutorial | Headless Theme (761)

Need a WooCommerce version? Try next-woo

Table of Contents

Quick Start

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

# Install dependencies
pnpm install

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

# Start development server
pnpm dev

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

Prerequisites

  • Node.js 22.13 or later
  • pnpm 11 (pinned via the packageManager field — enable with corepack enable)
  • WordPress site with REST API enabled (default in WordPress 4.7+)

Environment Variables

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

WORDPRESS_URL="https://your-wordpress-site.com"    # Full WordPress URL
WORDPRESS_HOSTNAME="your-wordpress-site.com"       # Domain for image optimization
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

next-wp/
├── __tests__/                # Vitest test suite
│   ├── api/                 # API route tests
│   └── lib/                 # Library tests
├── app/                      # Next.js App Router
│   ├── api/
│   │   ├── og/              # OG image generation
│   │   └── revalidate/      # Cache revalidation webhook
│   ├── pages/[slug]/        # Dynamic WordPress pages
│   ├── posts/
│   │   ├── [slug]/          # Individual post pages
│   │   ├── authors/         # Author archive
│   │   ├── categories/      # Category archive
│   │   └── tags/            # Tag archive
│   ├── layout.tsx           # Root layout
│   ├── page.tsx             # Homepage
│   └── sitemap.ts           # Dynamic sitemap
├── components/
│   ├── posts/               # Post-related components
│   │   ├── post-card.tsx    # Post card component
│   │   ├── filter.tsx       # Filter controls
│   │   └── search-input.tsx # Search component
│   ├── nav/                 # Navigation components
│   ├── theme/               # Theme toggle
│   └── ui/                  # shadcn/ui components
├── lib/
│   ├── wordpress.ts         # WordPress API functions
│   └── wordpress.d.ts       # TypeScript definitions
├── plugin/                  # WordPress revalidation plugin
├── menu.config.ts           # Navigation configuration
├── site.config.ts           # Site metadata
└── vitest.config.ts         # Test configuration

Deployment

Railway (Recommended)

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

CleanShot 2025-11-26 at 23 39 02@2x

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
┌─────────┐     ┌───────────┐     ┌─────────┐
│  MySQL  │────▶│ WordPress │◀────│ Next.js │
│   DB    │     │   (CMS)   │     │(Frontend)│
└─────────┘     └───────────┘     └─────────┘
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"

CleanShot 2025-11-27 at 00 01 29@2x

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

# Install dependencies
pnpm install

# Copy environment template
cp .env.example .env.local

# Configure your WordPress connection in .env.local
# Then start the dev server
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

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

Taxonomies

getAllCategories()                           // All categories
getCategoryById(id)                         // Category by ID
getCategoryBySlug(slug)                     // Category

readme truncated — read the full docs on github

Frequently asked questions

Is next-wp free to use?

next-wp is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does next-wp do?

Headless WordPress built with the Next.js App Router and React Server Components

What is next-wp written in?

next-wp is primarily written in TypeScript. Its source is publicly available at https://github.com/9d8dev/next-wp, and it has 1,296 GitHub stars.