Headless WordPress CMS with Next.js, ACF & Reusable Component Architecture

We built a headless WordPress + Next.js architecture using Advanced Custom Fields (ACF) as a flexible content modeling layer, a reusable component system on the frontend, and automated SEO optimization throughout.

Architecture

• CMS: WordPress (headless) with ACF Pro for structured content modeling
• API Layer: WPGraphQL + WPGraphQL for ACF to expose typed content via GraphQL
• Frontend: Next.js with App Router, React Server Components, TypeScript
• Styling: Tailwind CSS for utility-first, design-system-aligned styling
• SEO: Next.js Metadata API, JSON-LD structured data, automated sitemap generation
• Hosting: Vercel (frontend) + managed WordPress hosting (CMS)
• Media: Next.js Image optimization with WordPress media library as source

Content Modeling with ACF

Flexible Content Fields

ACF Flexible Content fields allow editors to compose pages from pre-defined content blocks. Each block maps directly to a React component on the frontend, covering common patterns like hero sections, feature grids, testimonial carousels, CTAs, FAQ accordions, stats counters, image-text layouts, video embeds, pricing tables, and blog feeds.

Repeater & Group Fields

• Repeater fields for lists (team members, portfolio items, timeline entries)
• Group fields for structured nested data (address blocks, social links, SEO overrides)
• Relationship fields for linking posts, pages, and custom post types
• Options pages for global settings (header, footer, social links, brand colors)

Reusable Component Architecture

Component Design Principles

The frontend follows a modular architecture with distinct layers:

• Block components — One React component per ACF Flexible Content block
• Primitive UI components — Reusable elements like buttons, cards, and badges
• Layout components — Header, footer, navigation, and container wrappers
• SEO components — Schema generators and meta tag utilities

Block Resolver Pattern

A central resolver maps ACF block types to React components, enabling editors to compose pages without developer involvement:

1. WordPress editor selects blocks from a dropdown and fills in fields
2. WPGraphQL exposes the page as structured JSON with block types and field data
3. Next.js fetches the page data at build time (ISR) or request time (SSR)
4. Block resolver iterates through the blocks array and renders the matching React component
5. Each component receives its ACF field data as typed props

SEO Optimization

Technical SEO

• Dynamic meta tags — Title, description, Open Graph, and Twitter Card tags generated per page from CMS data
• Canonical URLs — Automated canonical tag generation preventing duplicate content
• Sitemap Generation — Dynamic XML sitemap built from WordPress page/post data at build time
• robots.txt — Programmatic generation with environment-aware rules
• Structured Data — JSON-LD schema for Organization, Article, FAQ, BreadcrumbList, and Product types

Performance SEO (Core Web Vitals)

• Static Generation (ISR) — Pages pre-rendered and revalidated on content change via webhook
• Image Optimization — Automatic WebP/AVIF conversion, lazy loading, responsive srcset
• Font Optimization — Zero-layout-shift custom font loading
• Code Splitting — Automatic per-route code splitting with React Server Components
• Edge Caching — Global edge network for sub-100ms TTFB

Content SEO

• Per-page SEO fields — Meta title, description, and OG image override via custom fields
• Breadcrumbs — Auto-generated breadcrumb navigation with schema markup
• Internal Linking — Relationship fields enable structured internal link suggestions
• Alt Text Enforcement — Required alt text on all image fields

WordPress-to-Next.js Data Flow

1. Content Change — Editor publishes or updates content in WordPress admin
2. Webhook Trigger — WordPress fires a webhook to the Next.js revalidation endpoint
3. ISR Revalidation — Next.js regenerates only the affected pages
4. CDN Invalidation — Updated pages served from edge within seconds of publish

Key Features

1. Visual Page Builder — Editors compose pages from ACF blocks without touching code
2. Typed Content API — WPGraphQL + ACF provides fully typed GraphQL schema
3. Component Library — 10+ reusable blocks covering all common marketing page patterns
4. ISR + Webhooks — Content updates reflected on the live site within seconds
5. SEO Automation — Structured data, sitemaps, and meta tags generated from CMS data
6. Core Web Vitals — Optimized images, fonts, and code splitting for top Lighthouse scores
7. Preview Mode — WordPress preview button shows draft content in the Next.js frontend
8. Multi-Language Ready — ACF + WPML/Polylang integration for internationalized content