Agility CMS & Next.js Starter

A modern, production-ready starter for building content-managed websites with Agility CMS and Next.js 15.

Live Website Demo

New to Agility CMS? Sign up for a FREE account

✨ Features

Next.js 15 & React 18

• App Router - Modern Next.js routing with Server Components
• TypeScript - Full type safety throughout the project
• Tailwind CSS 4 - Utility-first styling with dark mode support
• Static Site Generation (SSG) - Pre-rendered pages with Incremental Static Regeneration (ISR)
• Server Components - React Server Components for optimal performance

Agility CMS Integration

• Dynamic Page Routing - Automatic page generation from Agility CMS sitemap
• Component Module System - CMS components mapped to React components
• Content Fetching - Server-side data fetching with caching strategies
• Preview Mode - Real-time content preview for editors
• On-Demand Revalidation - Webhook-triggered cache invalidation
• Multi-Locale Ready - Framework supports multiple languages

Developer Experience

• Component-Level Data Fetching - Fetch data where you need it
• Cache Tag Strategy - Granular cache control with automatic invalidation
• Dark Mode - Built-in dark mode toggle with persistence
• Responsive Design - Mobile-first responsive layout
• Image Optimization - Next.js Image component integration
• TypeScript Interfaces - Strongly typed CMS content models

📋 Table of Contents

• Quick Start
• Project Structure
• Architecture
• Content Models
• Components
• Data Fetching
• Caching Strategy
• Preview Mode
• Deployment
• Advanced Guides

🚀 Quick Start

Prerequisites

• Node.js 18.x or higher
• npm or yarn package manager
• An Agility CMS instance (sign up for free)

Installation

1. Clone the repository

   1
   git clone https://github.com/agility/agilitycms-nextjs-starter.git
   2
   cd agilitycms-nextjs-starter

2. Install dependencies

   1
   npm install
   2
   # or
   3
   yarn install

3. Configure environment variables

   1
   cp .env.local.example .env.local

4. Get your API keys from Agility CMS

   • Log into Agility CMS
   • Navigate to Settings > API Keys
   • Copy your:
     • GUID (Instance ID)
     • Live API Key (for production)
     • Preview API Key (for development/preview)
     • Security Key (for webhooks)

5. Update .env.local with your credentials:

   1
   AGILITY_GUID=your-guid-here
   2
   AGILITY_API_FETCH_KEY=your-live-api-key
   3
   AGILITY_API_PREVIEW_KEY=your-preview-api-key
   4
   AGILITY_SECURITY_KEY=your-security-key
   5
   AGILITY_LOCALES=en-us
   6
   AGILITY_SITEMAP=website
   7
   AGILITY_FETCH_CACHE_DURATION=120
   8
   AGILITY_PATH_REVALIDATE_DURATION=10

6. Run the development server

   1
   npm run dev
   2
   # or
   3
   yarn dev

7. Open your browser to http://localhost:3000

Production Build

1
npm run build
2
npm run start

📁 Project Structure

1
agilitycms-nextjs-starter/
2
├── app/                              # Next.js App Router
3
│   ├── layout.tsx                   # Root layout with header/footer
4
│   ├── page.tsx                     # Home page (delegates to [...slug])
5
│   ├── [...slug]/                   # Dynamic catch-all route
6
│   │   ├── page.tsx                 # Main page component with SSG
7
│   │   ├── error.tsx                # Error boundary
8
│   │   └── not-found.tsx            # 404 page
9
│   └── api/                         # API routes
10
│       ├── preview/                 # Preview mode endpoints
11
│       ├── preview/exit/            # Exit preview mode
12
│       ├── revalidate/              # Webhook for cache invalidation
13
│       └── dynamic-redirect/        # ContentID-based redirects
14
├── components/                      # React components
15
│   ├── agility-components/          # CMS component modules
16
│   │   ├── FeaturedPost.tsx        # Featured post display
17
│   │   ├── PostDetails.tsx         # Dynamic post detail view
18
│   │   ├── PostsListing/           # Infinite scroll post list
19
│   │   ├── TextBlockWithImage.tsx  # Flexible layout component
20
│   │   ├── RichTextArea.tsx        # HTML content display
21
│   │   ├── Heading.tsx             # Typography component
22
│   │   └── index.ts                # Component registry
23
│   ├── agility-pages/              # Page templates
24
│   │   ├── MainTemplate.tsx        # Main page template
25
│   │   └── index.ts                # Template registry
26
│   └── common/                     # Shared components
27
│       ├── SiteHeader.tsx          # Responsive header with dark mode
28
│       ├── SiteFooter.tsx          # Footer with social links
29
│       ├── PreviewBar.tsx          # Preview/Live mode toggle
30
│       └── InlineError.tsx         # Error display
31
├── lib/                            # Utilities and helpers
32
│   ├── cms/                        # CMS data fetching
33
│   │   ├── getAgilityContext.ts    # Mode detection (preview/live)
34
│   │   ├── getAgilitySDK.ts        # SDK initialization
35
│   │   ├── getAgilityPage.ts       # Fetch pages with layout
36
│   │   ├── getContentItem.ts       # Fetch single content item
37
│   │   ├── getContentList.ts       # Fetch content lists
38
│   │   ├── getSitemapFlat.ts       # Flat sitemap retrieval
39
│   │   └── getSitemapNested.ts     # Nested sitemap retrieval
40
│   ├── cms-content/                # Domain-specific queries
41
│   │   ├── getPostListing.ts       # Blog posts with URLs
42
│   │   ├── getHeaderContent.ts     # Header navigation data
43
│   │   ├── getPageMetaData.ts      # Page SEO metadata
44
│   │   └── resolveAgilityMetaData.ts # Advanced metadata
45
│   └── types/                      # TypeScript interfaces
46
│       └── (IPost, IAuthor, ICategory, etc.)
47
├── styles/
48
│   └── globals.css                 # Tailwind imports & global styles
49
├── middleware.ts                   # Next.js middleware for routing
50
├── .env.local.example              # Environment template
51
├── tailwind.config.js              # Tailwind configuration
52
├── next.config.js                  # Next.js configuration
53
└── tsconfig.json                   # TypeScript configuration

🏗️ Architecture

Dynamic Page Routing

This starter uses Next.js App Router with a catch-all dynamic route [...slug] that maps to Agility CMS pages.

How it works:

1. Agility CMS sitemap defines your site structure
2. generateStaticParams() pre-renders all pages at build time
3. Each page fetches its layout template and content zones from Agility
4. Components are dynamically loaded based on CMS configuration

See ARCHITECTURE.md for detailed explanation.

Component Module System

CMS components (modules) are mapped to React components via a registry pattern:

1
// components/agility-components/index.ts
2
const allModules = [
3
	{name: "TextBlockWithImage", module: TextBlockWithImage},
4
	{name: "Heading", module: Heading},
5
	{name: "FeaturedPost", module: FeaturedPost},
6
	{name: "PostsListing", module: PostsListing},
7
	{name: "PostDetails", module: PostDetails},
8
	{name: "RichTextArea", module: RichTextArea},
9
]

When Agility CMS returns a page with a "TextBlockWithImage" module, the system automatically renders the corresponding React component.

Server Components & Data Fetching

This starter uses React Server Components for optimal performance:

• Server Components - Default for all components, fetch data server-side
• Client Components - Used only when necessary (interactive features, hooks)
• Component-level fetching - Each component fetches its own data
• Parallel data fetching - Multiple components fetch concurrently

Example:

1
// Server Component (default)
2
export default async function PostDetails({module, page}) {
3
	const post = await getContentItem({contentID: page.contentID})
4
	return <article>...</article>
5
}

📊 Content Models

The Agility CMS instance includes the following content models:

Blog Content

• Post - Blog posts with category, tags, author, image, and rich content
• Author - Author profiles with name, title, and headshot
• Category - Post categories with images and descriptions
• Tag - Post tags for classification

Global Content

• Header - Site header with navigation and logo
• Footer - Site footer with links and social media
• Global Settings - Site-wide configuration

Specialized Content

• Testimonial Item - Customer testimonials
• FAQ Item - Frequently asked questions
• Pricing Tier - Pricing plans and features
• Carousel Slide - Carousel content items

Personalization (Advanced)

• Audience - Custom demographic targeting
• Region - Geographic personalization
• Customer Profile - User profiles for personalization

See CONTENT-MODELS.md for complete schema documentation.

🧩 Components

Page Components

• MainTemplate - Standard page layout with content zones

Blog Components

• PostsListing - Paginated blog post list with infinite scroll
• PostDetails - Individual post view with author, category, and rich content
• FeaturedPost - Highlighted post display

Layout Components

• TextBlockWithImage - Flexible text + image layout (left/right)
• RichTextArea - Rich HTML content with Tailwind prose styling
• Heading - Page headings with various styles

Global Components

• SiteHeader - Responsive navigation with dark mode toggle
• SiteFooter - Footer with social links and copyright
• PreviewBar - Preview mode indicator (development only)

See COMPONENTS.md for complete component API documentation.

🔄 Data Fetching

CMS Utilities

Located in lib/cms/, these utilities handle all Agility CMS interactions:

Determines the current mode (preview vs. production):

1
const context = await getAgilityContext()
2
// Returns: { isPreview: boolean, locale: string, sitemap: string }

Fetches a single content item with cache tags:

1
const post = await getContentItem({
2
	contentID: 123,
3
	languageCode: "en-us",
4
})

Fetches content lists with pagination and filtering:

1
const posts = await getContentList({
2
	referenceName: "posts",
3
	languageCode: "en-us",
4
	take: 10,
5
	skip: 0,
6
	sort: "fields.date",
7
	direction: "desc",
8
})

Fetches a complete page with layout and content zones:

1
const page = await getAgilityPage({
2
	slug: "/blog",
3
	locale: "en-us",
4
	sitemap: "website",
5
})

Domain-Specific Utilities

Located in lib/cms-content/, these build on the CMS utilities for specific use cases:

• getPostListing() - Blog posts with category filtering and URLs
• getHeaderContent() - Navigation structure and branding
• getPageMetaData() - SEO metadata for pages

See AGILITY-CMS-GUIDE.md for complete data fetching patterns.

💾 Caching Strategy

This starter implements a sophisticated caching strategy for optimal performance:

Cache Levels

1. SDK Object Cache - Agility Fetch SDK caches content items

   • Controlled by AGILITY_FETCH_CACHE_DURATION (default: 120 seconds)
   • Works best with on-demand revalidation

2. Next.js Route Cache - Next.js caches rendered pages

   • Controlled by AGILITY_PATH_REVALIDATE_DURATION (default: 10 seconds)
   • ISR (Incremental Static Regeneration) automatically updates stale pages

Cache Tags

Content fetches use cache tags for granular invalidation:

1
// Automatically tagged as: agility-content-{contentID}-{locale}
2
const post = await getContentItem({contentID: 123})

When content is published in Agility CMS, a webhook triggers revalidation:

• Tags associated with changed content are invalidated
• Next.js regenerates affected pages on the next request

On-Demand Revalidation

The /api/revalidate endpoint handles webhook callbacks from Agility CMS:

1
// Revalidates specific content items and their dependent pages
2
POST /api/revalidate
3
{
4
  "contentID": 123,
5
  "languageCode": "en-us"
6
}

Environment Variables

1
# Cache content objects for 120 seconds
2
AGILITY_FETCH_CACHE_DURATION=120
3

4
# Revalidate page paths every 10 seconds
5
AGILITY_PATH_REVALIDATE_DURATION=10

Best Practices:

• Use higher values (120-600) with on-demand revalidation for production
• Use lower values (10-30) or 0 without webhooks for faster content updates
• Preview mode always bypasses cache for real-time editing

👁️ Preview Mode

Preview mode allows content editors to see draft content before publishing.

How It Works

1. Activate Preview - Click "Preview" in Agility CMS
2. Validation - System validates preview key and ContentID
3. Draft Mode - Next.js draft mode is enabled
4. Live Preview - Page displays with unpublished content
5. Exit - Click "Exit Preview" in the preview bar

Implementation

Preview Endpoint (app/api/preview/route.ts):

1
// Validates request and enables draft mode
2
export async function GET(request: Request) {
3
	const {agilitypreviewkey, ContentID, slug} = searchParams
4

5
	// Validate preview key
6
	if (agilitypreviewkey !== process.env.AGILITY_SECURITY_KEY) {
7
		return new Response("Invalid token", {status: 401})
8
	}
9

10
	// Enable draft mode
11
	draftMode().enable()
12

13
	// Redirect to preview page
14
	redirect(slug)
15
}

Middleware (middleware.ts):

1
// Intercepts preview requests before they reach pages
2
export function middleware(request: NextRequest) {
3
	const {pathname, searchParams} = request.nextUrl
4

5
	if (searchParams.has("agilitypreviewkey")) {
6
		// Rewrite to preview API for validation
7
		return NextResponse.rewrite(new URL("/api/preview", request.url))
8
	}
9
}

Preview Bar (components/common/PreviewBar.tsx):

• Shows when in preview/development mode
• Displays current mode (Preview/Live)
• Provides exit button to leave preview mode

Configuration

Set your security key in .env.local:

1
AGILITY_SECURITY_KEY=your-security-key-from-agility

This key must match the one configured in Agility CMS webhook settings.

🚀 Deployment

Vercel (Recommended)

Vercel provides the best Next.js experience with zero configuration:

1. Push to GitHub - Commit your code to a GitHub repository
2. Import to Vercel - Connect your repo at vercel.com
3. Configure Environment Variables - Add your .env.local values
4. Deploy - Vercel automatically builds and deploys

Environment Variables to Set:

1
AGILITY_GUID
2
AGILITY_API_FETCH_KEY
3
AGILITY_API_PREVIEW_KEY
4
AGILITY_SECURITY_KEY
5
AGILITY_LOCALES
6
AGILITY_SITEMAP
7
AGILITY_FETCH_CACHE_DURATION
8
AGILITY_PATH_REVALIDATE_DURATION

Configure Webhooks in Agility CMS:

• Navigate to Settings > Webhooks
• Add webhook URL: https://your-site.vercel.app/api/revalidate
• Set trigger: "Content Published"

Netlify

1. Push to GitHub
2. Import to Netlify - Connect your repo at netlify.com
3. Build Settings:
   • Build command: npm run build
   • Publish directory: .next
4. Environment Variables - Add your .env.local values
5. Deploy

Other Platforms

This starter can deploy to any platform supporting Next.js:

• AWS Amplify
• Digital Ocean App Platform
• Railway
• Render

Ensure your platform supports:

• Node.js 18+
• Next.js 15
• On-demand revalidation (optional but recommended)

🤖 AI-Powered Development (Vibe Coding)

This starter is designed to work seamlessly with AI coding assistants like Claude Code, GitHub Copilot, Cursor, and ChatGPT for rapid development.

What is Vibe Coding?

"Vibe coding" is the practice of using AI assistants to help you build features by describing what you want in natural language, rather than writing every line of code manually. This starter's comprehensive documentation makes it perfect for AI-assisted development.

Why This Starter is AI-Ready

1. Complete Documentation - All patterns and schemas are documented, giving AI context
2. Type Safety - TypeScript interfaces help AI understand data structures
3. Consistent Patterns - Clear architectural patterns AI can follow
4. Example Code - Real implementations AI can reference

Getting Started with AI

1. Open this README in your editor - AI assistants have full context
2. Ask natural language questions:
   • "Add a new component that displays team members in a grid"
   • "Create a contact form component with validation"
   • "Add a hero section with background image support"
   • "Implement multi-locale routing"
3. AI will:
   • Reference the documentation
   • Follow existing patterns
   • Create properly typed code
   • Register components correctly

Create a new component:

1
Create a "TeamGrid" component that:
2
- Fetches team members from a "teammembers" container
3
- Displays them in a responsive 3-column grid
4
- Shows name, title, photo, and bio
5
- Supports dark mode
6
- Follows the same patterns as PostsListing

Add a feature:

1
Add search functionality to the PostsListing component:
2
- Add a search input at the top
3
- Filter posts by title/content as user types
4
- Maintain infinite scroll behavior
5
- Use client component for interactivity

Extend existing code:

1
Looking at TextBlockWithImage component, create a similar
2
"ImageGallery" component that shows multiple images in a grid
3
with lightbox functionality.

Advanced AI Usage with MCP

This project includes the Agility CMS MCP Server configuration in .vscode/mcp.json, which gives AI coding assistants (like Claude Code) direct access to your CMS instance through the Model Context Protocol.

What is MCP?

MCP (Model Context Protocol) is a standard that allows AI assistants to connect to external services. The Agility MCP Server acts as a bridge between your AI assistant and your Agility CMS instance, providing real-time access to your content structure and data.

What AI can do with MCP:

• ✅ Query content models - See the exact schema of your Posts, Products, etc.
• ✅ List content items - Browse actual content from your CMS
• ✅ Inspect field types - Know if a field is text, image, linked content, etc.
• ✅ Generate accurate interfaces - Create TypeScript types that match your CMS exactly
• ✅ Validate component code - Ensure components use correct field names
• ✅ Build smart queries - Create filters based on actual available fields

Example Workflows with MCP:

Creating a new component:

1
Use the Agility MCP server to get the "Products" content model,
2
then create:
3
1. A TypeScript interface (IProduct) with all fields
4
2. A ProductGrid component with category filtering
5
3. A domain helper (getProductListing) for data fetching
6
4. Register the component in the index

Validating existing code:

1
Query the Agility MCP server for the "TeamMembers" model and
2
verify that the ITeamMember interface in lib/types/ has all
3
the correct fields with proper types.

Discovering opportunities:

1
Use MCP to list all content models in my instance, then
2
suggest 5 new components I could build based on unused models.

Why MCP Makes AI Development Better:

Getting Started with MCP:

1. Ensure .vscode/mcp.json exists - Already configured in this project
2. Use Claude Code or compatible AI - MCP is supported by Claude and others
3. Reference MCP in prompts - Say "Use the Agility MCP server to..."
4. Let AI query your CMS - AI will fetch schemas and data automatically

MCP Server Configuration:

The project includes a pre-configured MCP connection:

1
// .vscode/mcp.json
2
{
3
	"servers": {
4
		"Agility CMS": {
5
			"url": "https://mcp.agilitycms.com/api/mcp",
6
			"type": "http"
7
		}
8
	}
9
}

This connects to the public Agility MCP server, which requires your API keys (from .env.local) to access your specific instance.

Learn More:

• Model Context Protocol
• Agility MCP Server Documentation (coming soon)

Full-Featured Reference

For more advanced examples including AI integration, personalization, and complex patterns, see:

Next.js Demo Site 2025

This repository includes:

• AI-powered search with streaming responses
• Multi-locale implementation (3+ languages)
• Personalization system (audience/region targeting)
• A/B testing components
• Advanced caching strategies
• 27+ production-ready components
• Complete documentation for AI assistants

Use it as a reference when asking AI to build advanced features:

1
Looking at the nextjs-demo-site-2025 repo, implement a similar
2
AI search modal for this project.

Tips for AI-Assisted Development

1. Reference Documentation - Point AI to specific docs:

   • "Following docs/ARCHITECTURE.md, add..."
   • "Using patterns from docs/AGILITY-CMS-GUIDE.md, create..."
   • "Based on docs/COMPONENTS.md examples, build..."

2. Provide Context - Share your CMS structure:

   • "My 'Products' model has these fields: ..."
   • "I have a container called 'testimonials' with..."

3. Request Tests - Ask AI to validate:

   • "Create this component and test it renders correctly"
   • "Add error handling for missing data"

4. Iterate - Refine in steps:

   • Start with basic version
   • Add features incrementally
   • Request optimizations

5. Use Type Safety - Let AI leverage TypeScript:

   • "Generate the TypeScript interface first"
   • "Ensure all props are properly typed"

AI Development Workflow

1
1. Describe Feature → AI generates component
2
   ↓
3
2. Review Code → AI refines based on feedback
4
   ↓
5
3. Create CMS Model → AI generates TypeScript interface
6
   ↓
7
4. Register Component → AI updates index file
8
   ↓
9
5. Test & Iterate → AI fixes issues

This documentation-first approach makes AI assistants highly effective at extending this starter with new features, components, and integrations.

📚 Advanced Guides

Detailed documentation for specific topics:

• QUICK-START-AI.md - Quick reference for AI assistants (start here for vibe coding!)
• ARCHITECTURE.md - Deep dive into code structure and patterns
• AGILITY-CMS-GUIDE.md - CMS integration patterns and best practices
• COMPONENTS.md - Component API reference and usage
• CONTENT-MODELS.md - Complete CMS schema documentation

AI Assistant Configuration:

• .cursorrules - Rules for Cursor, Claude Code, and other AI tools (auto-loaded)

🛠️ Development

Development Mode

Shows latest content in real-time (uses Preview API Key):

1
npm run dev

Production Mode

Shows published content (uses Live API Key):

1
npm run build
2
npm run start

TypeScript

This project uses TypeScript with strict mode. Type definitions for CMS content are in lib/types/.

Linting

1
npm run lint

Code Style

• ESLint - Configured with next/core-web-vitals
• Prettier - (Optional) Add .prettierrc for consistent formatting

📖 Resources

Agility CMS

• Official Website
• Documentation
• Help Center
• API Reference

Next.js

• Official Website
• Documentation
• App Router
• Server Components

Community

• Agility CMS Slack
• Blog
• GitHub
• LinkedIn
• X (Twitter)

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

💬 Feedback and Questions

If you have feedback or questions about this starter:

• GitHub Issues - Report bugs or request features
• Community Slack - Join our Slack community
• Support - Email support@agilitycms.com

📄 License

This project is licensed under the MIT License.

Made with ❤️ by Agility CMS