Skip to main content

Settings Overview

Configure FlatWP for optimal performance and functionality.

Configuration Areas​

FlatWP configuration is organized into these key areas:

1. Environment Variables​

Essential configuration through .env.local file.

Key Variables:

  • NEXT_PUBLIC_WORDPRESS_API_URL - WordPress GraphQL endpoint
  • REVALIDATION_SECRET - Webhook authentication
  • PREVIEW_SECRET - Draft preview authentication

Learn more: Environment Variables

2. WordPress Plugin​

FlatWP Companion Plugin settings in WordPress admin.

Features:

  • Webhook configuration
  • On-demand revalidation
  • Preview mode setup
  • Connection status monitoring

Learn more: WordPress Plugin Setup

3. ACF Setup​

Advanced Custom Fields configuration for flexible content.

Capabilities:

  • Custom post types
  • Flexible content layouts
  • Repeater fields
  • Custom field groups

Learn more: ACF Setup

4. Preview Mode​

Enable content editors to preview draft posts before publishing.

Benefits:

  • See changes before going live
  • Test layouts and formatting
  • Collaborate on content

Learn more: Preview Mode Setup

Quick Configuration Checklist​

Initial Setup​

  • WordPress GraphQL endpoint configured
  • Revalidation secret generated and set
  • WPGraphQL plugin installed and activated
  • FlatWP Companion plugin installed and activated
  • Plugin shows "Connected" status

Optional Enhancements​

  • Preview mode configured
  • ACF Pro installed (for flexible content)
  • Custom domain configured
  • Analytics integrated
  • SEO plugin installed (Yoast/Rank Math)

Configuration Files​

.env.local (Local Development)​

# WordPress
NEXT_PUBLIC_WORDPRESS_API_URL=http://localhost:10004/graphql
REVALIDATION_SECRET=local-dev-secret-1234567890
PREVIEW_SECRET=local-preview-secret-1234567890

# Site
NEXT_PUBLIC_SITE_URL=http://localhost:3010
NEXT_PUBLIC_SITE_NAME=FlatWP Dev

Production Environment​

Set these in your deployment platform (Vercel, Netlify, etc.):

# WordPress
NEXT_PUBLIC_WORDPRESS_API_URL=https://cms.yoursite.com/graphql
REVALIDATION_SECRET=<strong-random-secret>
PREVIEW_SECRET=<strong-random-secret>

# Site
NEXT_PUBLIC_SITE_URL=https://yoursite.com
NEXT_PUBLIC_SITE_NAME=Your Site Name

Configuration Best Practices​

1. Security​

  • Never commit secrets to version control
  • Use strong secrets (32+ characters, cryptographically random)
  • Different secrets for each environment
  • Rotate secrets periodically

2. Environment Separation​

Maintain separate WordPress instances:

  • Development: Local WordPress with test data
  • Staging: Staging WordPress for testing
  • Production: Production WordPress with real content

3. Secret Management​

Generate secure secrets:

# OpenSSL
openssl rand -base64 32

# Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

4. WordPress Configuration​

Recommended Plugins:

  • WPGraphQL (required)
  • FlatWP Companion (required)
  • ACF Pro (recommended)
  • Yoast SEO or Rank Math (optional)
  • WP GraphQL SEO (if using SEO plugin)

Permalink Settings:

  • Go to Settings → Permalinks
  • Use Post name structure
  • Click Save Changes

Common Configuration Patterns​

Single WordPress Instance​

Simplest setup - one WordPress for all environments:

# All environments use same WordPress
NEXT_PUBLIC_WORDPRESS_API_URL=https://cms.mysite.com/graphql

Pros:

  • Simpler to manage
  • Lower hosting costs
  • Content consistency

Cons:

  • No separation between environments
  • Testing affects production content

Separate WordPress Instances​

Recommended for production - different WordPress per environment:

# Development
NEXT_PUBLIC_WORDPRESS_API_URL=http://localhost:10004/graphql

# Staging
NEXT_PUBLIC_WORDPRESS_API_URL=https://staging-cms.mysite.com/graphql

# Production
NEXT_PUBLIC_WORDPRESS_API_URL=https://cms.mysite.com/graphql

Pros:

  • Complete environment separation
  • Safe testing
  • Production data protected

Cons:

  • More complex setup
  • Higher hosting costs
  • Content sync considerations

Hybrid Approach​

Shared staging/production WordPress, separate dev:

# Development (local)
NEXT_PUBLIC_WORDPRESS_API_URL=http://localhost:10004/graphql

# Staging & Production
NEXT_PUBLIC_WORDPRESS_API_URL=https://cms.mysite.com/graphql

Pros:

  • Balance between simplicity and safety
  • Moderate hosting costs
  • Good for small teams

Validation​

Check Configuration​

Create a validation script:

// lib/validate-config.ts
export function validateConfig() {
  const required = [
    'NEXT_PUBLIC_WORDPRESS_API_URL',
    'REVALIDATION_SECRET'
  ];

  const missing = required.filter(
    key => !process.env[key]
  );

  if (missing.length > 0) {
    throw new Error(
      `Missing required environment variables: ${missing.join(', ')}`
    );
  }

  // Validate URL format
  try {
    new URL(process.env.NEXT_PUBLIC_WORDPRESS_API_URL!);
  } catch {
    throw new Error('NEXT_PUBLIC_WORDPRESS_API_URL must be a valid URL');
  }

  // Validate secret length
  if (process.env.REVALIDATION_SECRET!.length < 16) {
    throw new Error('REVALIDATION_SECRET must be at least 16 characters');
  }
}

Run validation at build time:

// next.config.ts
import { validateConfig } from './lib/validate-config';

validateConfig();

export default {
  // ... next config
};

Troubleshooting Configuration​

WordPress Connection Issues​

Problem: Cannot connect to WordPress GraphQL

Check:

  1. WordPress URL is correct
  2. WPGraphQL plugin is activated
  3. WordPress is accessible from Next.js
  4. No CORS errors (plugin handles this)

Webhook Not Triggering​

Problem: Changes in WordPress don't update Next.js

Check:

  1. Plugin shows "Connected" status
  2. Secrets match exactly
  3. Next.js URL is correct
  4. Webhooks are enabled in plugin settings

Preview Mode Not Working​

Problem: Preview links show published content

Check:

  1. PREVIEW_SECRET is set
  2. Preview secret matches in WordPress
  3. User is logged into WordPress
  4. Preview mode is enabled in plugin

Next Steps​

Configure each area in detail:

  1. Environment Variables - Complete variable reference
  2. WordPress Plugin - Plugin setup and features
  3. ACF Setup - Flexible content configuration
  4. Preview Mode - Draft preview setup

See Also​