Skip to main content

Introduction to FlatWP

FlatWP is a production-ready headless WordPress starter kit that combines WordPress's powerful content management capabilities with Next.js's cutting-edge performance features.

What Makes FlatWP Special?​

FlatWP isn't just another WordPress theme or Next.js template. It's a complete, battle-tested architecture for building blazingly fast, SEO-optimized websites that are a joy to develop and maintain.

Key Highlights​

  • Next.js 15 with App Router - Leverages React Server Components for optimal performance
  • React 19 - The latest React features and improvements
  • Full Type Safety - GraphQL Code Generator creates types from your WordPress schema
  • WordPress Core Blocks - Full Gutenberg block support out of the box
  • FlatWP Custom Blocks - Hero, Features, CTA, Testimonials, Pricing, and more
  • ISR with On-Demand Revalidation - Content updates without rebuilds via webhooks
  • TailwindCSS v4 - Modern utility-first styling
  • SEO Optimized - Automatic sitemaps, meta tags, and structured data

The FlatWP Ecosystem​

FlatWP consists of two main components working together:

1. FlatWP Starter (Next.js Application)​

The frontend application built with Next.js 15 that fetches content from WordPress via GraphQL and renders it as a blazingly fast static site with intelligent revalidation.

Repository: github.com/flatwp/flatwp-starter

2. FlatWP WordPress Connector Plugin​

A modern WordPress plugin with a React-powered admin dashboard that manages the connection between WordPress and your Next.js site, handles webhooks for on-demand revalidation, and provides cache management.

Features:

  • Real-time connection monitoring
  • Cache management dashboard
  • Activity logs
  • REST API endpoints
  • Settings management

How It Works​

┌─────────────────────────────────────────────────┐
│ WordPress CMS                                   │
│ - Content Management                            │
│ - WPGraphQL Plugin                              │
│ - FlatWP WordPress Connector                    │
│ - ACF (Optional)                                │
└────────────────┬────────────────────────────────┘
                 │ GraphQL API
                 ▼
┌─────────────────────────────────────────────────┐
│ FlatWP Starter (Next.js)                        │
│ - Server Components                             │
│ - ISR + On-Demand Revalidation                  │
│ - Image Optimization                            │
│ - Core Gutenberg Blocks                         │
│ - Custom FlatWP Blocks                          │
└────────────────┬────────────────────────────────┘
                 │ Deploy
                 ▼
┌─────────────────────────────────────────────────┐
│ Vercel / Netlify / Your Platform                │
│ - Edge Network                                  │
│ - Automatic Deployments                         │
└─────────────────────────────────────────────────┘

Quick Start​

Get started with FlatWP in just a few minutes:

# Clone the starter
git clone https://github.com/flatwp/flatwp-starter.git my-site
cd my-site

# Install dependencies
pnpm install

# Configure environment (interactive)
pnpm run setup

# Generate types from WordPress
pnpm run graphql:codegen

# Start development server
pnpm run dev

Visit http://localhost:3010 to see your site!

For detailed instructions, see the Quick Start Guide.

One-Click Deploy​

Deploy FlatWP to production instantly:

Deploy with Vercel

Deploy to Netlify

What's Included​

FlatWP Starter Template​

  • Production-ready Next.js 15 application
  • TypeScript strict mode configuration
  • TailwindCSS v4 with Shadcn/ui components
  • GraphQL queries with full type generation
  • WordPress Core Gutenberg blocks renderer
  • FlatWP custom blocks (Hero, Features, CTA, etc.)
  • Image optimization with next/image
  • SEO optimization with meta tags and sitemaps
  • Preview mode for draft content
  • ISR with on-demand revalidation
  • One-click deploy configurations

FlatWP WordPress Connector Plugin​

  • Modern React admin dashboard (React 18 + TypeScript)
  • Real-time connection monitoring
  • Cache management interface
  • Activity logging system
  • REST API endpoints
  • Webhook automation for revalidation
  • Settings management
  • Menu location support with icon fields

Use Cases​

FlatWP is perfect for:

  • Marketing Websites - Fast loading, SEO-friendly, easy content management
  • Blogs & Publications - Content-focused sites with exceptional performance
  • Portfolio Sites - Beautiful presentations with type-safe development
  • Small Business Sites - Professional websites without the complexity
  • Agency Projects - Repeatable architecture for client sites

Requirements​

  • Node.js 20+ - Required for Next.js 15
  • pnpm 8+ - Package manager (npm and yarn also work)
  • WordPress 6.4+ - With WPGraphQL plugin
  • PHP 7.4+ - For WordPress and the FlatWP plugin

See System Requirements for details.

Next Steps​

  1. Quick Start - Set up your FlatWP site in minutes
  2. WordPress Plugin Setup - Configure the WordPress connector
  3. WordPress Blocks - Learn about block support
  4. GraphQL API - Understand the data layer
  5. Deployment - Deploy to production

Community & Support​

License​

FlatWP is open source software licensed under the MIT License.

Free to use for personal and commercial projects.