Skip to main content

System Requirements

Ensure your system meets these requirements before installing FlatWP.

Development Environment​

Node.js​

Required Version: 20.0.0 or higher

FlatWP uses Next.js 15, which requires Node.js 20+.

Check your version:

node --version
# Should output: v20.0.0 or higher

Install/Update Node.js:

  • Official installer: nodejs.org/download
  • nvm (recommended): 
    nvm install 20
    nvm use 20
  • Homebrew (macOS): 
    brew install node@20

Package Manager​

Recommended: pnpm 8.0.0 or higher

FlatWP is optimized for pnpm but also works with npm and yarn.

Check your version:

pnpm --version
# Should output: 8.0.0 or higher

Install pnpm:

npm install -g pnpm

Alternatives:

  • npm: Comes with Node.js (7.0.0+)
  • yarn: 1.22.0+ or 3.0.0+

Operating System​

FlatWP works on:

  • macOS 10.15+ (Catalina or later)
  • Windows 10/11 (with WSL2 recommended)
  • Linux (Ubuntu 20.04+, Debian 10+, or equivalent)

WordPress Requirements​

WordPress Version​

Required: WordPress 6.4 or higher

Check WordPress version:

  1. Log in to WordPress admin
  2. Go to Dashboard → scroll to bottom
  3. Look for "WordPress X.X.X"

Update WordPress:

  1. Go to Dashboard → Updates
  2. Click Update Now

Required WordPress Plugins​

WPGraphQL​

Required Version: 1.19.0 or higher

Provides GraphQL API for WordPress content.

Installation:

  1. Go to Plugins → Add New
  2. Search for "WPGraphQL"
  3. Install and activate

Verify installation:

  • Visit https://your-site.com/graphql in browser
  • Should see GraphiQL interface

FlatWP Companion Plugin​

Latest version from releases

Handles webhooks and on-demand revalidation.

Installation:

  • Download from GitHub Releases
  • Or use pnpm run download-plugin in the starter project
  • Upload via WordPress Plugins → Add New → Upload

Optional WordPress Plugins​

Advanced Custom Fields (ACF) Pro​

For flexible content layouts and custom fields.

Get ACF Pro:

Yoast SEO or Rank Math​

For enhanced SEO features.

Benefits:

  • SEO metadata in GraphQL
  • Schema.org structured data
  • Social media previews

Database Requirements​

MySQL​

Recommended Version: 8.0 or higher Minimum Version: 5.7.8

Check MySQL version:

mysql --version

MariaDB​

Alternative to MySQL Recommended Version: 10.5 or higher

Database Configuration​

Recommended Settings:

max_allowed_packet = 64M
innodb_buffer_pool_size = 256M

Server Requirements (Production)​

PHP​

WordPress Requirement: PHP 8.0 or higher

FlatWP doesn't use PHP directly, but WordPress requires it.

Memory​

Minimum: 2 GB RAM Recommended: 4 GB RAM or higher

Disk Space​

Development: ~500 MB Production Build: ~200 MB

HTTPS​

Required for production

Modern browsers require HTTPS for many features. Use:

  • Let's Encrypt (free)
  • Cloudflare
  • Your hosting provider's SSL

Development Tools​

Code Editor​

Recommended: Visual Studio Code

Useful VS Code extensions:

  • ESLint
  • Prettier
  • Tailwind CSS IntelliSense
  • GraphQL: Language Feature Support

Alternatives:

  • WebStorm
  • Sublime Text
  • Vim/Neovim

Git​

Required for version control

Check installation:

git --version

Install Git:

Docker (Optional)​

For local WordPress development.

Recommended Version: Docker 20.10+

Install Docker Desktop:

Deployment Platform Requirements​

Vercel (Recommended)​

  • Free tier available
  • Automatic deployments
  • Built-in analytics
  • Edge network

Requirements:

  • GitHub, GitLab, or Bitbucket account
  • Credit card for usage beyond free tier

Netlify​

  • Free tier available
  • Automatic deployments
  • Form handling
  • Serverless functions

Requirements:

  • GitHub, GitLab, or Bitbucket account

Railway​

  • Pay-as-you-go pricing
  • Database hosting included
  • Custom domains

Requirements:

  • GitHub account
  • Credit card

Self-Hosted​

Minimum Server Specs:

  • 1 CPU core
  • 2 GB RAM
  • 10 GB storage
  • Node.js 20+ installed

Browser Compatibility​

Supported Browsers​

FlatWP sites work on:

  • Chrome 90+
  • Firefox 88+
  • Safari 14+
  • Edge 90+

Mobile Browsers​

  • iOS Safari 14+
  • Chrome Mobile 90+
  • Samsung Internet 14+

Network Requirements​

Bandwidth​

Development: Standard broadband sufficient Production: Depends on traffic (edge caching recommended)

Firewall Rules​

Ensure these ports are accessible:

Development:

  • 3010 - Next.js dev server
  • 10004 - WordPress (if using Docker)

Production:

  • 80 - HTTP (redirects to HTTPS)
  • 443 - HTTPS

Performance Recommendations​

For Development​

# System check
node --version     # ≥ v20.0.0
pnpm --version     # ≥ 8.0.0
git --version      # ≥ 2.0.0

Hardware:

  • CPU: 2+ cores
  • RAM: 8 GB minimum, 16 GB recommended
  • Storage: SSD with 10 GB free space

For Production​

Next.js Application:

  • Platform: Vercel, Netlify, or equivalent
  • Edge caching: Enabled
  • Image optimization: Enabled

WordPress Backend:

  • Hosting: Managed WordPress hosting preferred
  • PHP: 8.1+ with OPcache enabled
  • MySQL: 8.0+ with query caching
  • CDN: CloudFlare or equivalent

Quick Compatibility Check​

Run this compatibility check script:

# Create check script
cat > check-requirements.sh << 'EOF'
#!/bin/bash

echo "FlatWP Requirements Check"
echo "========================="

# Node.js
NODE_VERSION=$(node --version 2>/dev/null | cut -d'v' -f2 | cut -d'.' -f1)
if [ "$NODE_VERSION" -ge 20 ]; then
  echo "✓ Node.js $(node --version)"
else
  echo "✗ Node.js version too old. Need 20+, have $(node --version)"
fi

# pnpm
if command -v pnpm &> /dev/null; then
  echo "✓ pnpm $(pnpm --version)"
else
  echo "⚠ pnpm not installed (optional but recommended)"
fi

# Git
if command -v git &> /dev/null; then
  echo "✓ Git $(git --version)"
else
  echo "✗ Git not installed"
fi

echo ""
echo "========================="
EOF

chmod +x check-requirements.sh
./check-requirements.sh

Troubleshooting​

Node.js Version Too Old​

Problem: Using Node.js 18 or older

Solution:

# Using nvm
nvm install 20
nvm use 20

# Or download from nodejs.org

pnpm Not Found​

Problem: pnpm command not recognized

Solution:

npm install -g pnpm

Port 3010 Already in Use​

Problem: Another application using port 3010

Solutions:

  1. Change port in package.json: 
    "dev": "next dev -p 3011"
  2. Kill process using port: 
    # macOS/Linux
    lsof -ti:3010 | xargs kill

    # Windows
    netstat -ano | findstr :3010
    taskkill /PID <PID> /F

Insufficient Memory​

Problem: Build fails with out-of-memory errors

Solutions:

  1. Increase Node.js memory: 
    export NODE_OPTIONS="--max-old-space-size=4096"
  2. Close other applications
  3. Upgrade RAM if consistently insufficient

See Also​