# Using the Advanced Next.js Demo Site

> Source: https://agilitycms.com/docs/nextjs/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

- **Live Demo**: [demo.agilitycms.com](https://demo.agilitycms.com)
- **GitHub Repository**: [github.com/agility/nextjs-demo-site-2025](https://github.com/agility/nextjs-demo-site-2025)
- **In-Site Documentation**: [demo.agilitycms.com/docs](https://demo.agilitycms.com/docs)
- **Basic Starter**: [Using the Next.js Starter](https://agilitycms.com/docs/nextjs/using-the-next-js-blog-starter)

## 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

### AI-Powered Search

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](https://demo.agilitycms.com/docs/developer/codebase/api-routes#ai-search-endpoint)

### 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](https://demo.agilitycms.com/docs/developer/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](https://demo.agilitycms.com/docs/architect/architecture#caching)

### 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](https://demo.agilitycms.com/docs/developer/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](https://demo.agilitycms.com/docs/architect/content-architecture)

## Getting Started

### Prerequisites

- Node.js 20+
- npm or yarn
- Agility CMS instance ([Get one free](https://agilitycms.com/free))

### Installation

```bash
# 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](https://demo.agilitycms.com/docs/developer/ENVIRONMENT_VARIABLES) 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

```bash
# 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

- **[Codebase Guide](https://demo.agilitycms.com/docs/developer/codebase)** - Project structure, components, API routes, deployment
- **[Environment Variables](https://demo.agilitycms.com/docs/developer/ENVIRONMENT_VARIABLES)** - Strongly typed configuration
- **[Multi-Locale Implementation](https://demo.agilitycms.com/docs/developer/MULTI_LOCALE_IMPLEMENTATION)** - i18n setup and routing
- **[Audience & Region System](https://demo.agilitycms.com/docs/developer/AUDIENCE_REGION_SYSTEM)** - Personalization implementation
- **[View Transitions](https://demo.agilitycms.com/docs/developer/VIEW_TRANSITIONS)** - Page transition API usage

### For Content Editors

- **[Content Editor Guide](https://demo.agilitycms.com/docs/content-editor)** - How to create and manage content
- **[Common Tasks](https://demo.agilitycms.com/docs/content-editor/common-tasks)** - Step-by-step workflows
- **[Content Models](https://demo.agilitycms.com/docs/content-editor/content-models)** - All 24 content models
- **[Components](https://demo.agilitycms.com/docs/content-editor/components)** - All 20 components

### For Administrators

- **[Admin Guide](https://demo.agilitycms.com/docs/admin)** - Instance configuration and setup
- **[Configuration](https://demo.agilitycms.com/docs/admin/configuration)** - Locales, sitemap, API keys
- **[Content Setup](https://demo.agilitycms.com/docs/admin/content-setup)** - Content model configuration
- **[Component Setup](https://demo.agilitycms.com/docs/admin/component-setup)** - Component definitions
- **[Workflows](https://demo.agilitycms.com/docs/admin/workflows)** - Role-based workflows

### For Architects

- **[Architecture Overview](https://demo.agilitycms.com/docs/architect)** - System architecture and design decisions
- **[Content Architecture](https://demo.agilitycms.com/docs/architect/content-architecture)** - Content model design
- **[Component Architecture](https://demo.agilitycms.com/docs/architect/component-architecture)** - Component patterns
- **[Integrations](https://demo.agilitycms.com/docs/architect/integrations)** - Third-party integrations

## 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

| Feature | Basic Starter | Advanced Demo |
|---------|--------------|---------------|
| **Content Models** | ~5-10 | 24 |
| **Components** | ~10 | 20 |
| **AI Search** | ❌ | ✅ Azure OpenAI + Algolia |
| **Internationalization** | ❌ | ✅ Multi-locale with clean URLs |
| **Personalization** | ❌ | ✅ Audience & Region targeting |
| **Advanced Caching** | Basic | Tag-based with webhooks |
| **A/B Testing** | ❌ | ✅ PostHog integration |
| **Analytics** | ❌ | ✅ PostHog tracking |
| **View Transitions** | ❌ | ✅ React 19 ViewTransition API |
| **Type Safety** | Basic | Comprehensive with custom types |
| **AI Assistant Support** | Basic | Full MCP server integration |
| **Documentation** | Basic README | Comprehensive in-site docs |

## Key Implementation Patterns

### Component Registration

All Agility CMS components must be registered:

```typescript
// 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:

```typescript
// 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:

```typescript
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](https://demo.agilitycms.com/docs/architect/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](https://github.com/agility/nextjs-demo-site-2025/blob/main/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](https://demo.agilitycms.com/docs/developer/codebase/deployment)

## Resources

- **Live Demo**: [demo.agilitycms.com](https://demo.agilitycms.com)
- **GitHub Repository**: [github.com/agility/nextjs-demo-site-2025](https://github.com/agility/nextjs-demo-site-2025)
- **In-Site Documentation**: [demo.agilitycms.com/docs](https://demo.agilitycms.com/docs)
- **Official Agility CMS Docs**: [agilitycms.com/docs](https://agilitycms.com/docs)
- **Official Training Guide**: [agilitycms.com/docs/training-guide](https://agilitycms.com/docs/training-guide)

## Next Steps

1. **Explore the Live Demo** - See all features in action at [demo.agilitycms.com](https://demo.agilitycms.com)
2. **Clone the Repository** - Get the full codebase from GitHub
3. **Read the Documentation** - Comprehensive guides at [demo.agilitycms.com/docs](https://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.