The ultimate headless WordPress solution - Transform any WordPress site into a blazing-fast, modern web application powered by Next.js 16 and React 19.
🌐 Created by WPTR - Free & Open Source
- ⚡ Lightning Fast - Next.js 16 with React 19 and React Compiler
- 🔌 Easy Setup - Connect to any WordPress site in minutes
- 🎨 Visual Customization - Theme colors, fonts, and layouts from admin panel
- 📱 Fully Responsive - Mobile-first design that looks great everywhere
- 🔍 SEO Optimized - Automatic meta tags, sitemaps, and hreflang support
- Homepage Builder - Drag & drop sections (Hero, Posts Grid, CTA, etc.)
- Menu Management - Primary & footer menus with submenu support
- Theme Editor - Real-time color customization
- Ads Management - Configure ad slots across your site
- Pages Manager - Create local pages without WordPress
- Language Settings - 80+ languages with customizable UI strings
- Security - Password-protected admin panel
- GraphQL Integration - Efficient data fetching from WordPress
- ISR Support - Incremental Static Regeneration for fresh content
- Image Optimization - Next.js Image component with lazy loading
- CSS Modules - Scoped, optimized styling
- TypeScript - Full type safety
- Node.js 18+
- A WordPress site with GraphQL plugin (WPGraphQL)
- Clone the repository
git clone https://github.com/Turkeyseo/headless-wordpress.git
cd headless-wordpress- Install dependencies
npm install- Start development server
npm run dev- Open your browser
Navigate to
http://localhost:3000/installand follow the setup wizard.
- Install WPGraphQL plugin on your WordPress site
- (Optional) Install Yoast SEO for enhanced SEO data
- Ensure your WordPress permalinks are set to "Post name"
Create a .env.local file:
# Optional: Override WordPress URL (otherwise set via admin panel)
WORDPRESS_URL=https://your-wordpress-site.comsrc/
├── app/ # Next.js App Router pages
│ ├── manager/ # Admin dashboard
│ ├── install/ # Setup wizard
│ ├── category/ # Category pages
│ └── [...slug]/ # Dynamic post/page routes
├── components/
│ ├── layout/ # Header, Footer
│ ├── sections/ # Homepage sections
│ ├── ui/ # Reusable UI components
│ └── manager/ # Admin components
├── lib/
│ ├── wordpress.ts # GraphQL queries
│ ├── config.ts # Site configuration
│ ├── actions.ts # Server actions
│ └── utils.ts # Helper functions
└── styles/ # Global styles
Access the admin panel at /manager and navigate to Theme tab to customize:
- Primary & Secondary colors
- Background & Foreground
- Accent colors
- Border & Muted colors
Available section types:
- Hero - Full-width banner with CTA
- Posts Grid - Card-based post layout
- Posts List - Compact list layout
- Posts Carousel - Sliding post cards
- Category Tabs - Tabbed post navigation
- CTA - Call-to-action blocks
- HTML Block - Custom HTML content
The system supports 80+ languages including:
- Major European languages (EN, DE, FR, ES, IT, PT, etc.)
- Asian languages (ZH, JA, KO, HI, TH, VI, etc.)
- Middle Eastern languages (AR, FA, HE, TR, etc.)
- African languages (SW, AM, HA, etc.)
- And many more...
Configure language and customize all UI strings from the Languages tab in admin panel.
Built-in ad management with predefined slots:
- Header Top
- Homepage - Below Hero
- Post Top / Middle / Bottom
- Sidebar Top
- Footer Top
Simply paste your ad code (Google AdSense, etc.) and toggle activation.
npm run build
npm start- Admin panel is password-protected
- Credentials stored with bcrypt hashing
- No direct database access from frontend
- WordPress remains hidden from visitors
This project includes a built-in update system that checks for new versions from GitHub:
- Version Check - Automatically checks for new releases on startup
- One-Click Update - Update directly from the admin panel
- Configuration Preserved - Your
site-config.json(settings, menus, theme) is preserved during updates - Release Notes - View what's new before updating
- Open the admin panel at
/manager - Click on the Updates tab
- If a new version is available, click Install Update
- Restart the application after the update
If you prefer to update manually:
# Backup your configuration
cp site-config.json site-config.backup.json
# Pull latest changes
git fetch origin main
git reset --hard origin/main
# Restore your configuration
cp site-config.backup.json site-config.json
# Install dependencies and rebuild
npm install
npm run buildThis project is licensed under the MIT License - see the LICENSE file for details.
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add some AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
- 🌐 Website: https://www.wptr.net
- 🐛 Issues: GitHub Issues
If you find this project useful, please consider giving it a star! ⭐
Made with ❤️ by WPTR