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

🚀 Quick Start

Prerequisites

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

Installation

Clone the repository

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

Install dependencies
```
npm install
# or
yarn install
```
Configure environment variables
```
cp .env.local.example .env.local
```
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)

Update .env.local with your credentials:

AGILITY_GUID=your-guid-here
AGILITY_API_FETCH_KEY=your-live-api-key
AGILITY_API_PREVIEW_KEY=your-preview-api-key
AGILITY_SECURITY_KEY=your-security-key
AGILITY_LOCALES=en-us
AGILITY_SITEMAP=website
AGILITY_FETCH_CACHE_DURATION=120
AGILITY_PATH_REVALIDATE_DURATION=10

Run the development server
```
npm run dev
# or
yarn dev
```
Open your browser to http://localhost:3000

Production Build

npm run build
npm run start

📁 Project Structure

agilitycms-nextjs-starter/
├── app/                              # Next.js App Router
│   ├── layout.tsx                   # Root layout with header/footer
│   ├── page.tsx                     # Home page (delegates to [...slug])
│   ├── [...slug]/                   # Dynamic catch-all route
│   │   ├── page.tsx                 # Main page component with SSG
│   │   ├── error.tsx                # Error boundary
│   │   └── not-found.tsx            # 404 page
│   └── api/                         # API routes
│       ├── preview/                 # Preview mode endpoints
│       ├── preview/exit/            # Exit preview mode
│       ├── revalidate/              # Webhook for cache invalidation
│       └── dynamic-redirect/        # ContentID-based redirects
├── components/                      # React components
│   ├── agility-components/          # CMS component modules
│   │   ├── FeaturedPost.tsx        # Featured post display
│   │   ├── PostDetails.tsx         # Dynamic post detail view
│   │   ├── PostsListing/           # Infinite scroll post list
│   │   ├── TextBlockWithImage.tsx  # Flexible layout component
│   │   ├── RichTextArea.tsx        # HTML content display
│   │   ├── Heading.tsx             # Typography component
│   │   └── index.ts                # Component registry
│   ├── agility-pages/              # Page templates
│   │   ├── MainTemplate.tsx        # Main page template
│   │   └── index.ts                # Template registry
│   └── common/                     # Shared components
│       ├── SiteHeader.tsx          # Responsive header with dark mode
│       ├── SiteFooter.tsx          # Footer with social links
│       ├── PreviewBar.tsx          # Preview/Live mode toggle
│       └── InlineError.tsx         # Error display
├── lib/                            # Utilities and helpers
│   ├── cms/                        # CMS data fetching
│   │   ├── getAgilityContext.ts    # Mode detection (preview/live)
│   │   ├── getAgilitySDK.ts        # SDK initialization
│   │   ├── getAgilityPage.ts       # Fetch pages with layout
│   │   ├── getContentItem.ts       # Fetch single content item
│   │   ├── getContentList.ts       # Fetch content lists
│   │   ├── getSitemapFlat.ts       # Flat sitemap retrieval
│   │   └── getSitemapNested.ts     # Nested sitemap retrieval
│   ├── cms-content/                # Domain-specific queries
│   │   ├── getPostListing.ts       # Blog posts with URLs
│   │   ├── getHeaderContent.ts     # Header navigation data
│   │   ├── getPageMetaData.ts      # Page SEO metadata
│   │   └── resolveAgilityMetaData.ts # Advanced metadata
│   └── types/                      # TypeScript interfaces
│       └── (IPost, IAuthor, ICategory, etc.)
├── styles/
│   └── globals.css                 # Tailwind imports & global styles
├── middleware.ts                   # Next.js middleware for routing
├── .env.local.example              # Environment template
├── tailwind.config.js              # Tailwind configuration
├── next.config.js                  # Next.js configuration
└── 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:

Agility CMS sitemap defines your site structure
generateStaticParams() pre-renders all pages at build time
Each page fetches its layout template and content zones from Agility
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:

// components/agility-components/index.ts
const allModules = [
	{name: "TextBlockWithImage\

Blog with Agility CMS and Next.js

Description

文档