Using the Advanced Next.js Demo Site

Production-ready example showcasing enterprise features, AI-powered search, internationalization, and advanced caching patterns

The Advanced Next.js Demo Site is a comprehensive, production-ready example of an Agility CMS-powered website built with Next.js 15, React 19, and TypeScript. This demo goes far beyond the basic starter, showcasing enterprise-level features and modern development patterns.

🚀 Quick Links

What Makes This Advanced?

This demo site demonstrates production-ready patterns and enterprise features that go beyond the basic starter:

🎯 Enterprise Features

  • AI-Powered Search - Azure OpenAI + Algolia integration for intelligent, conversational content search
  • Internationalization - Multi-locale support with clean URL routing and locale-aware content
  • Advanced Caching - Next.js cache tags with automatic revalidation via webhooks
  • Audience & Region Personalization - URL-based personalization system for targeted content
  • A/B Testing Integration - PostHog feature flags for experimentation
  • Analytics Integration - PostHog tracking and event management
  • View Transitions - Smooth page transitions using React 19's ViewTransition API
  • Type Safety - Strongly-typed environment variables and CMS content throughout

🏗️ Architecture Highlights

  • 24 Content Models - Comprehensive content architecture with 6 Content Items and 18 Content Lists
  • 20 Component Definitions - Reusable, composable components including personalized variants
  • Custom Caching Layer - Advanced Next.js caching with tag-based invalidation
  • Middleware Routing - Sophisticated routing handling preview mode, redirects, and i18n
  • API Routes - Custom endpoints for AI search, preview, revalidation, and dynamic redirects

🛠️ Developer Experience

  • AI Coding Assistant Support - Comprehensive AGENTS.md file for Cursor, Copilot, Windsurf, and more
  • Agility CMS MCP Server - Direct AI assistant integration with your CMS instance
  • TypeScript Throughout - Full type safety with custom interfaces for all content models
  • Modern Stack - Next.js 15.5.3, React 19, Tailwind CSS v4, Turbopack dev server

Key Features Explained

The demo includes a fully functional AI search system that combines Azure OpenAI with Algolia:

  • Conversational Search - Users can ask questions in natural language
  • Streaming Responses - Real-time response streaming for better UX
  • Context-Aware - Search understands your content structure and relationships
  • Tool Calling - AI can fetch and display relevant content dynamically

Learn More: AI Search Implementation

Internationalization (i18n)

Multi-locale support with clean URL patterns:

  • Default Locale - No URL prefix (e.g., /blog)
  • Secondary Locales - Explicit prefix (e.g., /fr/blog, /es/blog)
  • Locale-Aware Content - All CMS content respects locale settings
  • Middleware Routing - Automatic locale detection and routing

Learn More: Multi-Locale Implementation

Advanced Caching

Production-ready caching strategy:

  • Cache Tags - Automatic tagging for all CMS fetches
  • Tag Format - agility-content-{contentID|referenceName}-{locale}
  • Webhook Revalidation - Automatic cache invalidation on content publish
  • 60-Second TTL - Configurable cache duration with tag-based override

Learn More: Caching Strategy

Personalization System

URL-based personalization for audience and region targeting:

  • Query Parameters - ?audience=enterprise&region=north-america
  • Persistent State - Parameters persist across navigation
  • Server & Client Components - Hooks and utilities for both rendering contexts
  • Conditional Content - Components can show/hide based on targeting

Learn More: Audience & Region System

Content Architecture

The demo site includes a comprehensive content model:

Content Models (24 total)

  • Blog System: Posts, Authors, Categories, Tags
  • Personalization: Audiences, Regions, Customer Profiles
  • Component Content: Bento Cards, Testimonials, FAQ Items, Pricing Tiers, Stats
  • Navigation: Header, Footer, Nav Links
  • Configuration: Global Settings, AI Search Configuration

Components (20 total)

  • Content Display: Post Listing, Post Details, Testimonials, Team Listing
  • Hero Variants: Hero, Background Hero, A/B Test Hero, Personalized Background Hero
  • Interactive: Carousel, Contact Us, Frequently Asked Questions
  • Layout: Bento Section, Logo Strip, Personalized Logo Strip
  • Data Display: Company Stats, Pricing Cards, Pricing Table

Learn More: Content Architecture

Getting Started

Prerequisites

  • Node.js 20+
  • npm or yarn
  • Agility CMS instance (Get one free)

Installation

# Clone the repository
git clone https://github.com/agility/nextjs-demo-site-2025.git
cd nextjs-demo-site-2025

# Install dependencies
npm install

# Copy environment variables
cp .env.example .env.local

# Edit .env.local with your Agility CMS credentials

Environment Variables

The demo requires several environment variables. See the Environment Variables documentation for complete details.

Required:

  • AGILITY_GUID - Your Agility CMS instance GUID
  • AGILITY_API_FETCH_KEY - Production API key
  • AGILITY_API_PREVIEW_KEY - Preview API key
  • AGILITY_SECURITY_KEY - Security key for webhooks
  • AGILITY_LOCALES - Comma-separated locales (e.g., "en-us,fr")
  • AGILITY_SITEMAP - Sitemap channel name

Optional (for AI features):

  • Azure OpenAI configuration
  • Algolia configuration
  • PostHog analytics keys

Development

# Start development server with Turbopack
npm run dev

# Run prebuild (rebuilds redirect cache - required before production build)
npm run prebuild

# Build for production
npm run build

# Start production server
npm run start

⚠️ Important: Always run npm run prebuild before npm run build to rebuild the redirect cache.

Documentation

The demo site includes comprehensive in-site documentation at /docs:

For Developers

For Content Editors

For Administrators

For Architects

When to Use This Demo

This advanced demo is ideal for:

  • Enterprise Projects - Need personalization, i18n, advanced caching
  • Learning Advanced Patterns - Want to see production-ready implementations
  • AI Integration - Building AI-powered features with CMS content
  • Multi-Locale Sites - Need internationalization support
  • Performance Optimization - Want to see advanced caching strategies
  • TypeScript Projects - Need examples of strongly-typed CMS integration

Comparison: Basic Starter vs Advanced Demo

FeatureBasic StarterAdvanced Demo
Content Models~5-1024
Components~1020
AI Search❌✅ Azure OpenAI + Algolia
Internationalization❌✅ Multi-locale with clean URLs
Personalization❌✅ Audience & Region targeting
Advanced CachingBasicTag-based with webhooks
A/B Testing❌✅ PostHog integration
Analytics❌✅ PostHog tracking
View Transitions❌✅ React 19 ViewTransition API
Type SafetyBasicComprehensive with custom types
AI Assistant SupportBasicFull MCP server integration
DocumentationBasic READMEComprehensive in-site docs

Key Implementation Patterns

Component Registration

All Agility CMS components must be registered:

// src/components/agility-components/index.ts
import { ComponentName } from "./ComponentName"

const allModules = [
  { name: "ComponentName", module: ComponentName },
  // ... other modules
]

Nested Content Fetching

The demo shows how to handle nested content relationships:

// Get parent with nested reference
const { fields: { nestedRef: { referencename } } } = await getContentItem<MainType>({
  contentID: module.contentid,
  languageCode,
})

// Fetch nested collection separately
const nestedItems = await getContentList<NestedType>({
  referenceName: referencename,
  languageCode,
  take: 20
})

Image Handling

Always use <AgilityPic> for Agility CMS images:

import { AgilityPic } from "@agility/nextjs"

<AgilityPic
  image={imageField}
  fallbackWidth={600}
  className="w-full h-auto rounded-2xl"
  data-agility-field="image"
/>

Learn More: See the Component Architecture documentation for complete patterns.

AI Coding Assistant Integration

This demo includes comprehensive support for AI coding assistants:

  • AGENTS.md - Complete project documentation for AI assistants
  • MCP Server - Direct CMS access for AI tools
  • Type Definitions - Full TypeScript interfaces for all content
  • Code Patterns - Examples and conventions throughout

Supported assistants: Cursor, GitHub Copilot, Windsurf, Claude Code, and more.

Learn More: See AGENTS.md in the repository.

Deployment

Pre-build Steps

  1. Set all required environment variables
  2. Run npm run prebuild to rebuild redirect cache
  3. Run npm run build for production build

Environment-Specific Notes

  • Preview Mode: Automatically enabled in development
  • Redirects: Bloom filter cache must be rebuilt before production
  • Cache Revalidation: Configure webhook in Agility CMS to point to /api/revalidate

Learn More: Deployment Guide

Resources

Next Steps

  1. Explore the Live Demo - See all features in action at demo.agilitycms.com
  2. Clone the Repository - Get the full codebase from GitHub
  3. Read the Documentation - Comprehensive guides at demo.agilitycms.com/docs
  4. Start Building - Use this as a foundation for your own advanced Agility CMS site

Ready to build something advanced? Start with this demo site and customize it for your needs. The comprehensive documentation and code examples will help you implement enterprise-level features in your own Agility CMS projects.