Free & Open Source

Get Startedin Minutes

Download the starter template and WordPress plugin, follow the quick setup guide, and you'll have a lightning-fast headless WordPress site running in no time.

Download Now Quick Start Guide

Downloads

What You Need

Download both components to get started. The starter template runs your frontend, and the plugin connects WordPress.

FlatWP Starter

Next.js 15 frontend with all components, blocks, and configurations ready to go.

v0.7.0Latest Release

Download View on GitHub

WordPress Plugin

Connect your WordPress site with GraphQL extensions, preview support, and revalidation webhooks.

v0.7.5Latest Release

Download View on GitHub

Requirements

System Requirements

Make sure you have these installed before getting started.

Frontend

Node.js20.0+
pnpm8.0+
GitAny

WordPress

WordPress6.0+
PHP7.4+
WPGraphQL Plugin1.14+
ACF ProOptional

Quick Start

Setup Guide

Follow these steps to get FlatWP running in just a few minutes.

Clone the Starter Repository

Clone the FlatWP starter template from GitHub and navigate to the project directory.

bash

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

Install Dependencies

Install all Node.js dependencies using pnpm. This includes Next.js, React, and all UI components.

bash

# Install with pnpm (required)
pnpm install

# Or use the setup script
pnpm setup

Configure WordPress Connection

Create an environment file and add your WordPress GraphQL endpoint URL.

.env.local

# Create environment file
cp .env.example .env.local

# Edit .env.local with your WordPress URL
NEXT_PUBLIC_WORDPRESS_API_URL=https://your-wordpress-site.com/graphql
FLATWP_SECRET=your-secure-random-secret

Install WordPress Plugin

Upload and activate the FlatWP WordPress Connector plugin in your WordPress admin.

bash

# Download the plugin from GitHub releases
# Or use WP-CLI:
wp plugin install https://github.com/flatwp/flatwp-plugin/releases/latest/download/flatwp-wordpress-connector.zip --activate

Install WPGraphQL

The WPGraphQL plugin is required to expose your WordPress content via GraphQL.

bash

# Install via WP-CLI
wp plugin install wp-graphql --activate

# Or download from wordpress.org/plugins/wp-graphql

Start Development Server

Run the development server and open your site in the browser.

bash

# Start the development server
pnpm dev

# Open http://localhost:3010 in your browser

WordPress Setup

Configure WordPress

Additional WordPress configuration for optimal FlatWP integration.

FlatWP Plugin Settings

After activating the plugin, configure these settings in Settings → FlatWP

Frontend URL: Your Next.js site URL (e.g., https://your-site.com)
Shared Secret: Same value as FLATWP_SECRET in your .env.local
Enable Preview: Toggle preview support for drafts
Revalidation Webhook: Auto-configured, triggers ISR on content updates

Permalink Settings

Configure permalinks for clean URLs that match your Next.js routes.

WordPress Admin

# Recommended permalink structure
Settings → Permalinks → Post name
https://your-site.com/sample-post/

# Or custom structure for blogs
/blog/%postname%/

WPGraphQL Settings

Verify WPGraphQL is working by visiting the GraphQL IDE.

bash

# Test your GraphQL endpoint
curl -X POST \
  https://your-wordpress-site.com/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ generalSettings { title } }"}'

# Expected response:
# {"data":{"generalSettings":{"title":"Your Site Title"}}}

Next Steps

What's Next?

You're all set! Here are some resources to help you build amazing things.

Documentation

Comprehensive guides covering all features and customization options.

Features

Explore all the powerful features included in FlatWP.

Blocks Gallery

Preview all 18+ premium Gutenberg blocks with live demos.

GitHub Discussions

Ask questions and share ideas with the community.

Need Help Getting Started?

Join our community on GitHub Discussions or check out the documentation for detailed guides and troubleshooting.

Ask a Question View Documentation