Skip to main content

Environment Variables

Complete guide to environment variables used in FlatWP configuration.

Overview​

FlatWP uses environment variables for:

  • WordPress API credentials
  • Secret keys for security
  • Feature toggles
  • Site metadata
  • Third-party service keys
File Location

Create .env.local in your app root (not tracked by git) for local development.

Required Variables​

These variables must be set for FlatWP to work.

NEXT_PUBLIC_WORDPRESS_API_URL​

Type: URL Example: https://cms.example.com/graphql Description: WordPress GraphQL API endpoint

.env.local
NEXT_PUBLIC_WORDPRESS_API_URL=https://your-wordpress-site.com/graphql
Public Variable

The NEXT_PUBLIC_ prefix exposes this to the browser. Only use for public APIs.

Setup:

  1. Install WPGraphQL plugin in WordPress
  2. Navigate to GraphQL → Settings
  3. Copy the GraphQL endpoint URL
  4. Paste into .env.local

REVALIDATION_SECRET​

Type: String (min 16 characters) Example: your-secure-random-secret-here Description: Secret key for authenticating revalidation webhooks from WordPress

.env.local
REVALIDATION_SECRET=your-secure-random-secret-here
Security
  • Never commit this to version control
  • Use a cryptographically random string
  • Minimum 16 characters required
  • Store securely in production (environment secrets)

Generate Secure Secret:

# Using OpenSSL
openssl rand -base64 32

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

Optional Variables​

PREVIEW_SECRET​

Type: String (min 16 characters) Example: another-secure-random-secret Description: Secret key for draft preview mode

.env.local
PREVIEW_SECRET=another-secure-random-secret

When Required:

  • Enabling preview mode in FlatWP
  • Allowing editors to preview drafts

Site Metadata​

NEXT_PUBLIC_SITE_URL​

Type: URL Example: https://example.com Description: Public site URL for SEO and canonical URLs

.env.local
NEXT_PUBLIC_SITE_URL=https://example.com

Used For:

  • Open Graph URLs
  • Canonical URLs
  • Sitemaps
  • Structured data

NEXT_PUBLIC_SITE_NAME​

Type: String Example: My Awesome Blog Default: 'FlatWP' Description: Site name for metadata and branding

.env.local
NEXT_PUBLIC_SITE_NAME=My Awesome Blog

NEXT_PUBLIC_SITE_DESCRIPTION​

Type: String Example: The best blog about web development Default: 'A modern headless WordPress site built with Next.js'

.env.local
NEXT_PUBLIC_SITE_DESCRIPTION=The best blog about web development

Environment-Specific Configuration​

Development (.env.local)​

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

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

Production​

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

# Site
NEXT_PUBLIC_SITE_URL=https://example.com
NEXT_PUBLIC_SITE_NAME=My Site

Platform-Specific Setup​

Vercel​

Environment Variables:

  1. Go to Project Settings → Environment Variables
  2. Add each variable with appropriate scope:
    • Production: Production deployments
    • Preview: Preview deployments
    • Development: Local development

Netlify​

Environment Variables:

  1. Go to Site Settings → Build & Deploy → Environment
  2. Add variables
  3. Redeploy to apply changes

Railway​

Environment Variables:

  1. Go to Project → Variables
  2. Add variables
  3. Redeploy service

Security Best Practices​

Secret Management​

  1. Never commit secrets to version control

    • Add .env.local to .gitignore
    • Use .env.example for documentation

  2. Use environment-specific secrets

    • Different secrets for dev/staging/production
    • Rotate secrets periodically

  3. Minimum secret length

    • At least 16 characters
    • Recommend 32+ characters
    • Use cryptographically random generation

Public vs Private Variables​

Public Variables (NEXT_PUBLIC_*):

  • Exposed to browser
  • Safe to use for public APIs
  • Can be seen in browser DevTools
  • Examples: GraphQL URL, site URL

Private Variables (no prefix):

  • Server-side only
  • Never exposed to browser
  • Use for secrets and API keys
  • Examples: REVALIDATION_SECRET, admin API keys
Never Expose Secrets

Never use NEXT_PUBLIC_ prefix for:

  • API secrets
  • Authentication tokens
  • Admin credentials
  • Private keys

Troubleshooting​

Variables Not Loading​

Problem: Environment variables show as undefined

Solutions:

  1. Restart dev server after changing .env.local
  2. Check variable name spelling (case-sensitive)
  3. Verify .env.local is in app root
  4. Ensure no trailing spaces in variable values

Public Variables Not Available​

Problem: NEXT_PUBLIC_* variables undefined in browser

Solutions:

  1. Ensure NEXT_PUBLIC_ prefix is present
  2. Restart dev server (required for new variables)
  3. Check browser console for value
  4. Rebuild production build

Example Files​

.env.example​

Create this file for documentation (committed to git):

.env.example
# WordPress Configuration
NEXT_PUBLIC_WORDPRESS_API_URL=https://your-wordpress-site.com/graphql

# Secrets (generate secure random strings)
REVALIDATION_SECRET=your-secure-secret-min-16-chars
PREVIEW_SECRET=your-preview-secret-min-16-chars

# Site Configuration
NEXT_PUBLIC_SITE_URL=https://your-site.com
NEXT_PUBLIC_SITE_NAME=Your Site Name
NEXT_PUBLIC_SITE_DESCRIPTION=Your site description

.gitignore​

Ensure environment files are ignored:

.gitignore
# Environment variables
.env
.env.local
.env.*.local
.env.production

# Keep example file
!.env.example

See Also​