Duffer Derek

# Candid Next.js Application

A headless WordPress + Next.js application for Candid.org, featuring Incremental Static Regeneration (ISR) and real-time content updates from WordPress CMS.

## 📋 Table of Contents

- [Overview](#overview)
- [Architecture](#architecture)
- [Tech Stack](#tech-stack)
- [Project Structure](#project-structure)
- [Getting Started](#getting-started)
- [Environment Variables](#environment-variables)
- [Development](#development)
- [Build & Deployment](#build--deployment)
- [Key Features](#key-features)
- [Documentation](#documentation)

## 🎯 Overview

This is a headless CMS setup where:
- **WordPress** (hosted on WP Engine) serves as the content management system
- **Next.js** (hosted on WP Engine) serves as the frontend application
- Content is fetched via **GraphQL** (WPGraphQL) and **REST API** endpoints
- Pages are statically generated with **ISR (Incremental Static Regeneration)**
- Content updates trigger automatic revalidation of affected pages

## 🏗️ Architecture

```
┌─────────────────┐         ┌──────────────────┐         ┌──────────────┐
│   WordPress     │────────▶│   GraphQL/REST   │────────▶│   Next.js    │
│   (WP Engine)   │         │      APIs        │         │  (WP Engine) │
│                 │         │                  │         │              │
│  Content Edit   │         │  Data Fetching   │         │  Static Pages│
│  Save/Update    │────────▶│  Revalidation    │────────▶│  ISR Cache   │
└─────────────────┘         └──────────────────┘         └──────────────┘
```

### Data Flow

1. **Content Creation**: Editor creates/updates content in WordPress
2. **Webhook Trigger**: WordPress hooks (`save_post`, `post_updated`) trigger revalidation
3. **Cache Purge**: WP Engine cache layers are cleared (Varnish, Memcached, CDN)
4. **Revalidation**: Next.js `/api/revalidate` endpoint is called
5. **ISR Update**: Next.js regenerates the affected page in the background
6. **Serving**: Updated page is served to users

## 💻 Tech Stack

### Frontend
- **Next.js 14.2.26** - React framework with Pages Router
- **React 18** - UI library
- **GraphQL Request** - GraphQL client
- **SCSS/SASS** - Styling
- **Material-UI** - Component library
- **React Query** - Data fetching and caching

### Backend
- **WordPress** - Headless CMS
- **WPGraphQL** - GraphQL API
- **ACF (Advanced Custom Fields)** - Custom field management
- **Custom REST API** - Additional endpoints

### Hosting
- **WP Engine** - Hosting for both WordPress and Next.js
- **Multiple Cache Layers**: Varnish, Memcached, CDN

## 📁 Project Structure

```
candid-nextjs-app-v2/
├── api/                    # API fetchers and queries
│   ├── pages/             # Page data fetching
│   ├── blogs/             # Blog post fetching
│   ├── press/             # Press release fetching
│   ├── people/            # People/team data
│   ├── settings/          # Global settings
│   └── misc/              # Miscellaneous data
├── components/            # React components
│   ├── common/           # Shared components
│   ├── forms/            # Form components
│   ├── hero/             # Hero sections
│   └── ...
├── pages/                 # Next.js pages (routes)
│   ├── [...pageSlug]/    # Dynamic page routes
│   ├── api/              # API routes
│   ├── blogs/            # Blog pages
│   └── press/            # Press pages
├── pageTemplates/         # Page template components
├── templateBlocks/        # Reusable content blocks
├── wp-theme/             # WordPress theme (headless)
│   └── candid/           # Custom theme files
├── constants/            # Configuration constants
├── helpers/             # Utility functions
├── hooks/               # Custom React hooks
└── public/              # Static assets
```

See [Documentation](#documentation) section for detailed directory documentation.

## 🚀 Getting Started

### Prerequisites

- Node.js 18+ and npm
- Access to WordPress backend (for API endpoints)
- Environment variables configured (see [Environment Variables](#environment-variables))

### Installation

```bash
# Install dependencies
npm install

# Run development server
npm run dev

# Build for production
npm run build

# Start production server
npm start
```

The application will be available at `http://localhost:3000` (or port 3018 for production mode).

## 🔐 Environment Variables

Create a `.env.local` file in the root directory with the following variables:

```env
# WordPress Backend URLs
BASE_URL=https://cms.candid.org - Live
BASE_URL_DEV=https://cms-dev.candid.org - Dev

# Next.js Frontend URLs
NXT_URL=https://candid.org (https://dev.candid.org - Dev)
NXT_DOMAIN=candid.org

# GraphQL Endpoint
API_URL=https://cms.candid.org/graphql

# Revalidation Secret (must match WordPress theme)
REVALIDATE_SECRET=your-secret-key-here

# Environment
CURRENT_ENV=development  # or 'production'
```

**Note**: The `constants/general.js` file contains default values but should be overridden with environment variables in production.

## 💻 Development

### Available Scripts

- `npm run dev` - Start development server with hot reload
- `npm run build` - Build production bundle
- `npm start` - Start production server (port 3018)
- `npm run lint` - Run ESLint

### Development Workflow

1. **Local Development**: Run `npm run dev` and connect to staging WordPress backend
2. **Testing**: Test against staging WordPress API endpoints
3. **Build Testing**: Run `npm run build` to test production build locally
4. **Deployment**: Push to repository (WP Engine handles deployment)

### Code Style

- Use functional components with hooks
- Follow React best practices
- Use SCSS for styling (component-scoped files)
- Follow existing naming conventions

## 🏗️ Build & Deployment

### Build Process

1. **Static Generation**: Next.js pre-renders pages at build time
2. **ISR Setup**: Pages are configured with `revalidate` intervals
3. **API Routes**: Serverless functions are created for `/api/*` routes
4. **Asset Optimization**: Images, fonts, and CSS are optimized

### Deployment

- **Hosting**: WP Engine (managed hosting)
- **Build Command**: `npm run build`
- **Start Command**: `npm start`
- **Port**: 3018 (production)

### ISR Revalidation

Pages are automatically revalidated when:
- WordPress content is updated (via webhook)
- Revalidation interval expires (configured per page)
- Manual revalidation is triggered via `/api/revalidate`

## ✨ Key Features

### 1. Incremental Static Regeneration (ISR)
- Pages are statically generated at build time
- Background revalidation keeps content fresh
- Configurable revalidation intervals per page

### 2. Dynamic Routing
- Catch-all routes for WordPress pages: `[...pageSlug]`
- Dynamic routes for blogs, press, people, authors
- Server-side rendering for search and dynamic content

### 3. Content Management
- Real-time content updates from WordPress
- Automatic cache invalidation
- WP Engine cache layer integration

### 4. Performance
- Static page generation for fast loads
- Image optimization via Next.js Image component
- Code splitting and lazy loading
- CDN caching via WP Engine

## 📚 Documentation

Detailed documentation is available in the following directories:

- [`/api/README.md`](./api/README.md) - API structure and data fetching
- [`/components/README.md`](./components/README.md) - Component architecture
- [`/pages/README.md`](./pages/README.md) - Page structure and routing
- [`/wp-theme/README.md`](./wp-theme/README.md) - WordPress theme documentation
- [`/constants/README.md`](./constants/README.md) - Configuration constants
- [`/helpers/README.md`](./helpers/README.md) - Utility functions

## 🐛 Troubleshooting

### Common Issues

1. **White Screen of Death**
   - Check browser console for errors
   - Verify API endpoints are accessible
   - Check revalidation logs in WordPress
   - See [Troubleshooting Guide](./docs/TROUBLESHOOTING.md) (if available)

2. **Build Failures**
   - Ensure all environment variables are set
   - Check WordPress API connectivity
   - Verify GraphQL queries are valid

3. **Revalidation Not Working**
   - Verify `REVALIDATE_SECRET` matches in both WordPress and Next.js
   - Check WordPress error logs
   - Verify network connectivity between WordPress and Next.js

## 🤝 Contributing

1. Create a feature branch
2. Make your changes
3. Test thoroughly (local and staging)
4. Submit a pull request

## 📝 Notes

- **WP Engine Specific**: This setup is optimized for WP Engine hosting
- **Cache Layers**: Multiple cache layers (Varnish, Memcached, CDN) require careful cache invalidation
- **Revalidation**: Automatic revalidation depends on WordPress hooks and network connectivity

## 🔗 Related Resources

- [Next.js Documentation](https://nextjs.org/docs)
- [WPGraphQL Documentation](https://www.wpgraphql.com/)
- [WP Engine Documentation](https://wpengine.com/support/)

---

**Last Updated**: 2026-01-28