Skip to main content

Quick Start

Get your FlatWP site up and running in under 10 minutes!

Prerequisites​

Before you begin, make sure you have:

  • Node.js 20.0+ installed (Download)
  • WordPress 6.4+ running with admin access
  • Package manager: npm, yarn, or pnpm (we recommend pnpm)
  • A code editor (VS Code recommended)
Don't Have WordPress Yet?

Check out WordPress.org for installation guides. Local development options include:

Step 1: Clone the Starter Template​

Clone the FlatWP starter repository:

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

Or use the GitHub "Use this template" button for a cleaner start without git history.

Step 2: Install Dependencies​

Install the required packages:

# Using pnpm (recommended - faster)
pnpm install

# Or using npm
npm install

# Or using yarn
yarn install
Why pnpm?

pnpm is faster and uses less disk space than npm. Install it with: npm install -g pnpm

Step 3: Configure Environment Variables​

You can configure your environment variables interactively or manually.

Option A: Interactive Setup (Recommended)​

Run the interactive setup script:

pnpm run setup

This will guide you through setting up your .env.local file with all required variables.

Option B: Manual Setup​

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

cp .env.example .env.local

Edit .env.local with your WordPress details:

# WordPress GraphQL endpoint
NEXT_PUBLIC_WORDPRESS_API_URL=https://your-wordpress.com/graphql

# Secret for revalidation webhooks
FLATWP_SECRET=your-secure-random-string
Generate Secure Secrets
openssl rand -base64 32

Step 4: Set Up WordPress​

Install Required Plugins​

1. Install WPGraphQL​

  1. Log in to your WordPress admin dashboard
  2. Go to Plugins → Add New
  3. Search for "WPGraphQL"
  4. Click Install Now, then Activate

2. Install FlatWP Companion Plugin​

The FlatWP plugin connects WordPress to Next.js and provides on-demand revalidation:

  1. Download flatwp-wordpress-connector.zip from GitHub Releases
  2. Go to Plugins → Add New → Upload Plugin
  3. Choose the ZIP file and click Install Now
  4. Click Activate

Alternatively, use the download script included in the starter:

pnpm run download-plugin

This downloads the latest plugin version to your project folder.

Configure Plugin Settings​

  1. In WordPress, go to FlatWP in the admin menu
  2. Navigate to the Settings tab
  3. Enter your configuration:
SettingValue
Next.js URLhttp://localhost:3010
Revalidation SecretYour FLATWP_SECRET from .env.local
Preview SecretSame as revalidation secret (optional)
  1. Enable Webhooks toggle
  2. Click Save Settings
  3. Return to Dashboard tab and verify "Connected" status with green indicator

Step 5: Generate GraphQL Types​

Generate TypeScript types from your WordPress GraphQL schema:

# Using pnpm
pnpm graphql:codegen

# Or using npm
npm run graphql:codegen

This creates type-safe interfaces in graphql/generated/.

Step 6: Start Development Server​

Run the development server:

# Using pnpm
pnpm dev

# Or using npm
npm run dev

Open http://localhost:3010 in your browser. You should see your FlatWP site! 🎉

Port Configuration

The development server runs on port 3010 by default. Change it in package.json if needed.

Step 7: Create Your First Page​

Let's create a simple "About" page to see everything working:

In WordPress​

  1. Go to Pages → Add New
  2. Title: "About Us"
  3. Add your content in the editor
  4. Click Publish

View Your Page​

  1. Go to http://localhost:3010 in your browser
  2. Your new "About Us" page should appear automatically
  3. Click on it to see your content! ✨

Success Checklist​

Make sure everything is working:

  • Next.js site loads at http://localhost:3010
  • WordPress pages appear in navigation
  • FlatWP plugin shows green "Connected" status
  • Making changes in WordPress updates the Next.js site
  • No errors in browser console (F12)

If everything is checked, congratulations! Your FlatWP site is running! 🎉

Common Issues & Solutions​

GraphQL Endpoint Not Found​

Error: "Failed to fetch from WordPress GraphQL endpoint"

Solutions:

  1. Verify WPGraphQL plugin is activated in WordPress
  2. Check your .env.local has the correct NEXT_PUBLIC_WORDPRESS_API_URL
  3. Test the endpoint in browser: https://your-wordpress-site.com/graphql
  4. Make sure WordPress site is accessible from your computer

CORS Errors​

Error: "Access-Control-Allow-Origin blocked"

Solution: The FlatWP companion plugin handles CORS automatically. If you still see errors:

  1. Ensure the plugin is activated
  2. Check that your Next.js URL is correctly configured in plugin settings
  3. Clear your browser cache

GraphQL Types Not Generated​

Error: "Cannot find module './graphql/generated'"

Solution:

# Make sure WordPress is running
# Then generate types
pnpm graphql:codegen

If it fails, check:

  • WordPress site is accessible
  • WPGraphQL plugin is activated
  • .env.local has correct URL

FlatWP Plugin Shows "Disconnected"​

Problem: Red status in WordPress FlatWP settings

Solutions:

  1. Make sure Next.js dev server is running (pnpm dev)
  2. Check secrets match between WordPress and .env.local
  3. Verify Next.js URL is correct in WordPress settings

Next Steps​

Now that your FlatWP site is running, here's what to explore:

Immediate Next Steps​

  1. Environment Variables - Configure your site
  2. WordPress Plugin Setup - Advanced plugin features
  3. Content Management - Learn to create and manage content

When You're Ready​

  1. ISR & Caching - Understand rendering strategies
  2. Customization - Customize your site
  3. Deployment - Deploy your site

Quick Reference​

Common Commands​

# Development
pnpm dev                  # Start dev server (port 3010)
pnpm build                # Build for production
pnpm start                # Run production build locally

# Code Quality
pnpm lint                 # Check code quality
pnpm type-check           # TypeScript validation
pnpm graphql:codegen      # Update WordPress types

# Utilities
pnpm clean                # Clear build cache

Project Structure​

my-flatwp-site/
├── app/                  # Next.js pages and routes
├── components/           # React components
├── lib/                 # Utilities and helpers
├── graphql/             # GraphQL queries
├── public/              # Static files
└── .env.local           # Your secrets (not in git)

Need Help?​

Got stuck? Here's how to get help:

  1. Check this guide - Reread the troubleshooting section
  2. Search docs - Use the search bar at the top
  3. Ask the community - Post in GitHub Discussions
  4. Report bugs - Open an issue on GitHub

Happy building!