Using the Next.js Starter

A complete guide to setting up and running your Agility CMS + Next.js website locally and deploying to production.

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js 22.x or higher - Download Node.js. Next.js 16 needs at least 20.9, and Node 20 is past end-of-life.
• npm or yarn - Package manager (comes with Node.js)
• Git - Download Git
• Agility CMS Account - Sign up for free

Quick Start

Option 1: Deploy to Vercel First (Recommended)

The fastest way to get started is to deploy first, then clone and work locally:

1. Log in to your Agility CMS instance

2. Navigate to Settings > Deployment

3. Click "Setup Deployment" for Vercel

4. Follow the automated deployment wizard

   • Authorize the Agility Integration with Vercel
   • Select or create a Git repository
   • Vercel will automatically:
     • Clone this starter template
     • Set up environment variables
     • Deploy your site
     • Configure preview and production domains

5. Clone your repository locally

   git clone https://github.com/YOUR-USERNAME/YOUR-REPO-NAME.git
   cd YOUR-REPO-NAME
   npm install
   

6. Copy environment variables from Vercel

   • Go to your Vercel project settings
   • Copy the .env.local tab
   • Or manually create .env.local (see below)

Option 2: Start Locally First

If you prefer to start with local development:

1. Clone this repository

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

2. Install dependencies

   npm install
   

3. Get your Agility CMS credentials

   • Log in to Agility CMS
   • Go to Settings > API Keys
   • Copy the following values:
     • GUID - Your instance identifier
     • Live API Key - For production content
     • Preview API Key - For draft content
     • Security Key - For webhooks and previews

4. Create your environment file

   Copy .env.local.example to .env.local:

   cp .env.local.example .env.local
   

   Then edit .env.local with your credentials:

   # Your Agility CMS Instance GUID
   AGILITY_GUID=your-guid-here
   
   
   # API Keys (from Settings > API Keys)
   AGILITY_API_FETCH_KEY=your-live-api-key
   AGILITY_API_PREVIEW_KEY=your-preview-api-key
   
   
   # Security Key (for webhooks and preview mode)
   AGILITY_SECURITY_KEY=your-security-key
   
   
   # Locales (comma-separated list, first is default)
   AGILITY_LOCALES=en-us
   
   
   # Sitemap reference name (usually 'website')
   AGILITY_SITEMAP=website
   
   
   # Cache durations (in seconds)
   AGILITY_FETCH_CACHE_DURATION=120
   AGILITY_PATH_REVALIDATE_DURATION=60
   

5. Run the development server

   npm run dev
   

6. Open your browser

   Navigate to http://localhost:3000

   You should see your site with the sample content from your Agility instance!

Local Development

Development Server

Start the Next.js development server:

npm run dev

Features in dev mode:

• Hot module replacement (changes appear instantly)
• Real-time error reporting
• Source maps for debugging
• Draft content visible (uses Preview API Key)

Building for Production

Test a production build locally:

# Build the site
npm run build

# Start the production server
npm start

The build process will:

1. Generate static pages from your Agility sitemap
2. Optimize images and assets
3. Create optimized JavaScript bundles
4. Output to .next/ directory

Project Structure

agilitycms-nextjs-starter/
├── app/                          # Next.js App Router
│   ├── layout.tsx               # Root layout (header, footer)
│   ├── page.tsx                 # Homepage
│   ├── [...slug]/               # Dynamic catch-all route
│   │   ├── page.tsx            # Page renderer
│   │   ├── error.tsx           # Error boundary
│   │   └── not-found.tsx       # 404 page
│   └── api/                     # API routes
│       ├── preview/             # Preview mode activation
│       ├── revalidate/          # Webhook handler
│       └── dynamic-redirect/    # ContentID redirects
│
├── components/
│   ├── agility-components/      # CMS modules (registered)
│   │   ├── index.ts            # Module registry
│   │   ├── Heading.tsx
│   │   ├── RichTextArea.tsx
│   │   ├── PostsListing/
│   │   └── ...
│   ├── agility-pages/           # Page templates
│   │   ├── index.ts            # Template registry
│   │   └── MainTemplate.tsx
│   └── common/                  # Shared UI components
│       ├── SiteHeader.tsx
│       ├── SiteFooter.tsx
│       ├── PreviewBar.tsx
│       └── ...
│
├── lib/
│   ├── cms/                     # Generic CMS utilities
│   │   ├── getAgilitySDK.ts
│   │   ├── getContentItem.ts
│   │   ├── getContentList.ts
│   │   └── ...
│   ├── cms-content/             # Domain-specific queries
│   │   ├── getPostListing.ts
│   │   ├── getHeaderContent.ts
│   │   └── ...
│   └── types/                   # TypeScript interfaces
│       ├── IPost.ts
│       ├── IAuthor.ts
│       └── ...
│
├── docs/                        # Documentation
├── public/                      # Static assets
├── styles/                      # Global styles
└── proxy.ts                     # Proxy — preview mode & redirects

Key Files Explained

File	Purpose
app/[...slug]/page.tsx	Renders all content pages dynamically
components/agility-components/index.ts	Registers CMS modules → React components
components/agility-pages/index.ts	Registers page templates
lib/cms/getAgilityPage.ts	Fetches complete page with layout
proxy.ts	Handles preview mode and redirects (renamed from middleware.ts in Next.js 16)
.env.local	Environment variables (not committed)

Understanding the Project

How Pages Are Generated

1. Agility CMS manages your sitemap

   • Editors create pages in the CMS
   • Each page has a URL, template, and content zones

2. Build time: Static Generation

   // app/[...slug]/page.tsx
   export async function generateStaticParams() {
     // Fetches all pages from Agility CMS
     const sitemap = await getSitemapFlat({ languageCode: "en-us" });
     
     // Returns paths: ['/', '/about', '/blog', '/blog/post-1', ...]
     return sitemap.map((node) => ({
       slug: node.pagePath.split("/").filter(Boolean),
     }));
   }
   

3. Next.js generates HTML for each path

   • / → index.html
   • /about → about.html
   • /blog/post-1 → blog/post-1.html

4. Runtime: Page Rendering

   export default async function Page({ params }) {
     // Get page data from Agility
     const page = await getAgilityPage({ 
       slug: params.slug.join("/") 
     });
     
     // Render appropriate template
     const Template = getPageTemplate(page.templateName);
     return <Template page={page} />;
   }
   

How Components Work

In Agility CMS:

• Create a "Component Model" (e.g., "Heading")
• Define fields (e.g., "title", "subtitle")
• Add to pages via content zones

In Next.js:

• Create React component: components/agility-components/Heading.tsx
• Register in components/agility-components/index.ts
• Component automatically renders when added to pages

Example:

// components/agility-components/Heading.tsx
import { UnloadedModuleProps } from "@agility/nextjs";

interface IHeadingModule {
  title: string;
  subtitle?: string;
}

export default async function Heading({ 
  module 
}: UnloadedModuleProps) {
  const { fields } = module as { fields: IHeadingModule };

  return (
    <section className="py-12">
      <h1 className="text-5xl font-bold dark:text-white">
        {fields.title}
      </h1>
      {fields.subtitle && (
        <p className="text-xl text-gray-600 dark:text-gray-400">
          {fields.subtitle}
        </p>
      )}
    </section>
  );
}

Data Fetching Pattern

This starter uses a three-tier architecture:

Component
  ↓
Domain Helper (lib/cms-content/)
  ↓
CMS Utility (lib/cms/)
  ↓
Agility SDK

Example:

// Component
const posts = await getPostListing({ take: 10 });

// Domain Helper (lib/cms-content/getPostListing.ts)
export async function getPostListing({ take, skip }) {
  const posts = await getContentList({
    referenceName: "posts",
    take,
    skip
  });
  
  // Add computed fields (URLs, etc.)
  return { posts: postsWithUrls };
}

// CMS Utility (lib/cms/getContentList.ts)
export async function getContentList({ referenceName }) {
  const api = getAgilitySDK({ isPreview });
  return await api.getContentList({ referenceName });
}

Deployment Options

Vercel (Recommended)

Why Vercel?

• Built by Next.js creators
• Zero-config deployments
• Automatic HTTPS
• Global CDN
• Instant rollbacks
• Built-in analytics

Deploy via Agility Integration:

1. Go to Agility CMS > Settings > Deployment
2. Click "Setup Deployment" for Vercel
3. Follow the wizard (autorizes, sets env vars, deploys)
4. Done! Your site is live.

Manual Vercel Deployment:

1. Push your code to GitHub
2. Go to vercel.com/new
3. Import your repository
4. Add environment variables:
   • AGILITY_GUID
   • AGILITY_API_FETCH_KEY
   • AGILITY_API_PREVIEW_KEY
   • AGILITY_SECURITY_KEY
   • AGILITY_LOCALES
   • AGILITY_SITEMAP
5. Click "Deploy"

Setup Webhooks:

1. After deployment, copy your site URL
2. In Agility: Settings > Webhooks > Add Webhook
3. URL: https://your-site.vercel.app/api/revalidate
4. Events: "Content Published", "Content Deleted", "Page Modified"
5. Add header: x-agility-webhook-secret: YOUR_AGILITY_SECURITY_KEY

Azure Static Web Apps

This starter includes a GitHub Actions workflow for Azure Static Web Apps.

Deployment Steps:

1. Create Azure Static Web App

   • Go to Azure Portal
   • Create new Static Web App
   • Connect to your GitHub repository
   • Framework: Next.js
   • Output location: .next

2. Configure Build

   The included workflow at .github/workflows/azure-static-web-apps-wonderful-meadow-008797210.yml handles:

   • Building with npm run build-swa
   • Setting environment variables
   • Deploying to Azure

3. Set Repository Secrets

   In GitHub: Settings > Secrets and variables > Actions

   Add:

   • AZURE_STATIC_WEB_APPS_API_TOKEN_WONDERFUL_MEADOW_008797210 (from Azure)
   • AGILITY_API_FETCH_KEY

   And Variables:

   • AGILITY_GUID
   • AGILITY_LOCALES
   • AGILITY_SITEMAP

4. Setup Webhooks

   In Agility CMS: Settings > Webhooks

   • URL: https://your-site.azurestaticapps.net/api/revalidate
   • Same configuration as Vercel

Netlify

Deploy to Netlify:

1. Push code to GitHub
2. Go to app.netlify.com/start
3. Import your repository
4. Build settings:
   • Build command: npm run build
   • Publish directory: .next
5. Add environment variables (same as Vercel)
6. Deploy

Setup Webhooks: Same process as Vercel, using your Netlify URL.

Self-Hosted

You can deploy to any Node.js hosting:

npm run build
npm start

Requires:

• Node.js 22+ runtime
• Environment variables configured
• Reverse proxy (nginx, Apache)

Setting Up Preview Mode

Preview mode allows editors to see draft content before publishing.

1. Configure in Agility CMS

Settings > Deployment:

1. Set Preview Domain: https://your-site.vercel.app
2. Set Production Domain: https://your-site.com (or Vercel URL)
3. Save changes

2. How Preview Works

Editor clicks "Preview" in CMS
   ↓
Request: /page?agilitypreviewkey=SECRET&ContentID=123
   ↓
Proxy intercepts → /api/preview
   ↓
API validates key, enables draft mode
   ↓
Redirects to actual page URL
   ↓
Page renders with draft content
   ↓
Preview bar appears at top

3. Testing Preview Locally

1. Start dev server: npm run dev

2. Get a preview URL from any page in Agility CMS

3. Replace the domain:

   https://your-site.com/about?agilitypreviewkey=...&ContentID=123
   
   becomes
   
   http://localhost:3000/about?agilitypreviewkey=...&ContentID=123
   

4. You should see:

   • Draft content visible
   • Preview bar at top
   • "Exit Preview" button

4. Exit Preview

Click "Exit Preview" in the preview bar, or visit:

http://localhost:3000/api/preview/exit

Next Steps

For Content Editors

• Create pages: Add pages via Agility CMS sitemap
• Add content: Use page modules to build your pages
• Preview changes: Click "Preview" before publishing
• Publish: Click "Publish" to make changes live

For Developers

1. Read the architecture docs: ARCHITECTURE.md
2. Create your first component: COMPONENTS.md
3. Understand content models: CONTENT-MODELS.md
4. AI development guide: QUICK-START-AI.md

Customize Your Site

Add a new component:

# 1. Create component
touch components/agility-components/MyComponent.tsx

# 2. Register component
# Edit components/agility-components/index.ts

# 3. Create component model in Agility CMS
# Match the reference name to "MyComponent"

Add a new content model:

// 1. Define interface
// lib/types/IMyModel.ts
export interface IMyModel {
  contentID: number;
  title: string;
  // ... fields
}

// 2. Create helper
// lib/cms-content/getMyData.ts
export async function getMyData() {
  return await getContentList<IMyModel>({
    referenceName: "mymodel"
  });
}

Customize styling:

• Edit styles/globals.css for global styles
• Use Tailwind classes in components
• Modify tailwind.config.js for theme customization

Troubleshooting

Build Errors

Error: "Missing environment variables"

• Check .env.local file exists
• Verify all required variables are set
• Restart dev server after changes

Error: "Invalid API Key"

• Double-check API keys in Agility CMS
• Ensure you're using the correct instance GUID
• Try copying keys again (no extra spaces)

Error: "Module not found"

• Run npm install to ensure dependencies are installed
• Clear Next.js cache: rm -rf .next
• Rebuild: npm run build

Preview Mode Issues

Preview not working:

• Verify AGILITY_SECURITY_KEY is set correctly
• Check preview domain is configured in Agility CMS
• Test with full URL including agilitypreviewkey param
• Check browser console for errors

Can't exit preview mode:

• Visit /api/preview/exit directly
• Clear browser cookies
• Try incognito/private window

Content Not Updating

Changes not appearing:

• Check if webhooks are configured (production only)
• In development: Stop and restart npm run dev
• Verify content is Published (not just saved)
• Check cache duration settings in .env.local

Old content still showing:

• Trigger manual revalidation: /api/revalidate (POST)
• Clear Vercel cache (in Vercel dashboard)
• Wait for revalidate duration to expire
• Check webhook logs in Agility CMS

Performance Issues

Slow build times:

• Reduce number of pages being generated
• Check for duplicate API calls
• Review component complexity
• Consider incremental builds (ISR)

Slow page loads:

• Optimize images (use <AgilityPic>)
• Check bundle size: npm run build (see output)
• Review client-side JavaScript
• Use React Server Components when possible

Getting Help

• Documentation: Check the /docs folder
• Agility CMS Support: help.agilitycms.com
• GitHub Issues: github.com/agility/agilitycms-nextjs-starter/issues
• Community Slack: Join Agility Community
• Next.js Docs: nextjs.org/docs

---

Ready to build? Start by creating your first component! See COMPONENTS.md for a step-by-step guide.