@agility/create-next-app 1.0.0-beta.2

package/templates/app/api/preview/route.ts

@@ -0,0 +1,63 @@
+import { localizeUrl } from "@/lib/i18n/localizeUrl";
+import { validatePreview, getDynamicPageURL } from "@agility/nextjs/node";
+import { draftMode } from 'next/headers'
+import { NextRequest, NextResponse } from "next/server";
+
+
+/**
+ * This endpoint is used as a rewrite for preview requests from middleware.
+ * Therefore, the URL will be the original preview request url...
+ * @param request
+ * @param res
+ * @returns
+ */
+export async function GET(request: NextRequest) {
+
+	const searchParams = request.nextUrl.searchParams
+
+	const agilityPreviewKey = searchParams.get("agilitypreviewkey") || ""
+
+	//locale is also passed in the querystring on preview requests
+	const locale = searchParams.get("locale") || searchParams.get("lang")
+	const slug = searchParams.get("slug") || "/"
+
+	const ContentID = searchParams.get('ContentID')
+
+	//validate our preview key, also validate the requested page to preview exists
+	const validationResp = await validatePreview({
+		agilityPreviewKey,
+		slug
+	});
+
+
+	if (validationResp.error) {
+		return NextResponse.json({ message: validationResp.message }, { status: 401 });
+	}
+
+	let previewUrl = slug
+	if (locale) previewUrl = localizeUrl(slug, locale);
+
+	//if we have a content id, get the dynamic page url for it
+	if (ContentID) {
+		const dynamicPath = await getDynamicPageURL({ contentID: Number(ContentID), preview: true, slug: slug || undefined });
+		if (dynamicPath) {
+			previewUrl = dynamicPath;
+		}
+
+	}
+
+	//enable draft/preview mode
+	(await draftMode()).enable()
+
+	// Redirect to the slug
+	// Construct an absolute URL for the redirect
+	const baseUrl = `${request.nextUrl.protocol}//${request.nextUrl.host}`;
+	let url = `${baseUrl}${previewUrl}`;
+	if (url.includes("?")) {
+		url = `${url}&preview=1`;
+	} else {
+		url = `${url}?preview=1`;
+	}
+
+	return NextResponse.redirect(url, 307);
+}

package/templates/app/api/revalidate/route.ts

@@ -0,0 +1,118 @@
+
+
+import { revalidatePath, revalidateTag } from "next/cache";
+import { NextRequest, NextResponse } from "next/server";
+import agilitySDK from "@agility/content-fetch"
+import type { SitemapNode } from "@/lib/types/SitemapNode";
+
+interface IRevalidateRequest {
+	state: string,
+	instanceGuid: string
+	languageCode?: string
+	referenceName?: string
+	contentID?: number
+	contentVersionID?: number
+	pageID?: number
+	pageVersionID?: number
+	changeDateUTC?: string
+}
+
+export async function POST(req: NextRequest) {
+
+	//parse the body
+	const data = await req.json() as IRevalidateRequest
+
+
+	//only process publish events
+	if (data.state === "Published") {
+
+		let sitemapFlat: {
+			[path: string]: SitemapNode
+		} = {}
+
+		//grab the sitemap flat so we can revalidate the full path if needed
+		if (data.contentID || data.pageID) {
+			const apiKey = process.env.AGILITY_API_FETCH_KEY
+
+			const agilityClient = agilitySDK.getApi({
+				guid: process.env.AGILITY_GUID,
+				apiKey
+			})
+
+			const languageCode = process.env.AGILITY_LOCALES || "en-us"
+
+			//don't cache the sitemap here... we want to get the latest
+			agilityClient.config.fetchConfig = {
+				cache: "no-store"
+			}
+
+
+			sitemapFlat = await agilityClient.getSitemapFlat({
+				channelName: process.env.AGILITY_SITEMAP || "website",
+				languageCode
+			})
+		}
+
+		//revalidate the correct tags based on what changed
+		if (data.referenceName) {
+			//content item change
+			const itemTag = `agility-content-${data.referenceName.toLowerCase()}-${data.languageCode}`
+			const listTag = `agility-content-${data.contentID}-${data.languageCode}`
+			revalidateTag(itemTag)
+			revalidateTag(listTag)
+
+			console.info("Revalidating content tags:", itemTag, listTag)
+
+			//grab the sitemap and check if this content is in there so we can revalidate a full path
+			if (sitemapFlat) {
+				const sitemapNode = Object.values(sitemapFlat).find(s => s.contentID === data.contentID)
+				if (sitemapNode) {
+					const path = sitemapNode.path
+					revalidatePath(path)
+					console.info("Revalidating path:", path)
+
+				}
+			}
+
+
+		} else if (data.pageID !== undefined && data.pageID > 0) {
+			//page change
+			const pageTag = `agility-page-${data.pageID}-${data.languageCode}`
+			revalidateTag(pageTag)
+
+
+			//also revalidate the sitemaps
+			const sitemapTagFlat = `agility-sitemap-flat-${data.languageCode}`
+			const sitemapTagNested = `agility-sitemap-nested-${data.languageCode}`
+			revalidateTag(sitemapTagFlat)
+			revalidateTag(sitemapTagNested)
+
+			console.info("Revalidating page and sitemap tags:", pageTag, sitemapTagFlat, sitemapTagNested)
+
+			if (sitemapFlat) {
+				const sitemapNode = Object.values(sitemapFlat).find(s => s.pageID === data.pageID)
+				if (sitemapNode) {
+					const path = sitemapNode.path
+					revalidatePath(path)
+					console.info("Revalidating path:", path)
+
+				}
+			}
+		}
+	} else if (data.contentID === undefined && data.pageID === undefined) {
+		//if no content or page id is provided, it's for a URL redirection
+		//trigger the rebuild hook for netlify's rebuild...
+		const hookUrl = process.env.BUILD_HOOK_URL
+		if (hookUrl) {
+			await fetch(hookUrl, {
+				method: 'POST'
+			})
+		}
+	}
+
+	return new Response(`OK`, {
+		status: 200
+	})
+
+
+}

package/templates/components/agility-components/RichTextArea.tsx

@@ -0,0 +1,66 @@
+/**
+ * RichTextArea Component
+ *
+ * An Agility CMS module component that displays rich text content.
+ * This component fetches a content item from Agility CMS and renders
+ * the HTML content with proper styling and Agility CMS data attributes
+ * for in-context editing.
+ */
+
+import { getContentItem } from "@/lib/cms/getContentItem"
+import { renderHTML, type UnloadedModuleProps } from "@agility/nextjs"
+
+/**
+ * Interface defining the structure of the RichText content item fields.
+ * The field name must match the field reference name in Agility CMS.
+ */
+export interface RichText {
+	textblob: string
+}
+
+/**
+ * RichTextArea Component
+ *
+ * Fetches and renders rich text content from Agility CMS.
+ *
+ * @param module - The Agility CMS module object containing contentID
+ * @param languageCode - The language code for localized content
+ * @returns A section element with the rendered rich text content
+ *
+ * @remarks
+ * - Uses `data-agility-component` attribute for Agility CMS component identification
+ * - Uses `data-agility-field` and `data-agility-html` attributes for in-context editing
+ * - Applies Tailwind CSS prose classes for typography styling
+ * - Supports responsive typography sizing (sm, lg, xl)
+ * - Includes dark mode support via `dark:prose-invert`
+ */
+const RichTextArea = async ({ module, languageCode }: UnloadedModuleProps) => {
+	// Fetch the content item from Agility CMS
+	const {
+		fields: { textblob },
+		contentID,
+	} = await getContentItem<RichText>({
+		contentID: module.contentid,
+		languageCode,
+	})
+
+	return (
+		<section id={`${contentID}`} className="relative px-8" data-agility-component={contentID}>
+			<div className="max-w-2xl mx-auto my-12 md:mt-18 lg:mt-20">
+				{/*
+					Rich text content container with Agility CMS editing attributes.
+					The renderHTML function sanitizes and prepares the HTML for safe rendering.
+				*/}
+				<div
+					data-agility-field="textblob"
+					data-agility-html
+					className="my-6 prose prose-sm sm:prose lg:prose-lg xl:prose-xl max-w-full dark:prose-invert"
+					dangerouslySetInnerHTML={renderHTML(textblob)}
+				></div>
+			</div>
+		</section>
+	)
+}
+
+export default RichTextArea
+

package/templates/components/agility-components/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Agility CMS Module Components
+ *
+ * This file exports a getModule function that maps Agility CMS module names
+ * to their corresponding React components. When a module is rendered in a
+ * ContentZone, this function is called to retrieve the appropriate component.
+ *
+ * To add a new module component:
+ * 1. Create a new component file in this directory (e.g., MyComponent.tsx)
+ * 2. Import it at the top of this file
+ * 3. Add a case in the switch statement below with the module's reference name
+ */
+
+import RichTextArea from "./RichTextArea"
+
+/**
+ * Returns the React component for a given Agility CMS module name.
+ *
+ * @param moduleName - The reference name of the module as defined in Agility CMS
+ * @returns The React component for the module, or null if not found
+ */
+export const getModule = (moduleName: string) => {
+	switch (moduleName) {
+		case "RichTextArea":
+			return RichTextArea
+		default:
+			return null
+	}
+}
+

package/templates/components/agility-pages/MainTemplate.tsx

@@ -0,0 +1,36 @@
+/**
+ * MainTemplate Component
+ *
+ * The default page template for Agility CMS pages. This template defines
+ * the main content zone where modules can be added and rendered.
+ *
+ * The ContentZone component handles the rendering of all modules added to
+ * the "main-content-zone" in Agility CMS, using the getModule function to
+ * map module names to their corresponding React components.
+ */
+
+import React from "react"
+import { ContentZone } from "@agility/nextjs"
+import { getModule } from "../agility-components"
+
+/**
+ * MainTemplate Component
+ *
+ * Renders the main content zone for an Agility CMS page.
+ *
+ * @param props - Agility CMS page props including page data, sitemap, etc.
+ * @returns A ContentZone component that renders all modules in the main-content-zone
+ *
+ * @remarks
+ * - The ContentZone name "main-content-zone" must match the zone name in Agility CMS
+ * - The getModule function is used to resolve module components by their reference name
+ * - All props are spread to the ContentZone for proper context passing
+ */
+const MainTemplate = (props: any) => {
+	return (
+		<ContentZone name="main-content-zone" {...props} getModule={getModule} />
+	)
+}
+
+export default MainTemplate
+

package/templates/components/agility-pages/index.ts

@@ -0,0 +1,11 @@
+import MainTemplate from "./MainTemplate"
+
+export const getPageTemplate = (templateName: string) => {
+	switch (templateName) {
+		case "MainTemplate":
+			return MainTemplate
+		default:
+			return MainTemplate
+	}
+}
+

package/templates/docs/01-agility-cms-overview.md

@@ -0,0 +1,139 @@
+# Agility CMS Overview
+
+This Next.js project is integrated with Agility CMS, a headless content management system. This document provides an overview of how Agility CMS works in this project.
+
+## What is Agility CMS?
+
+Agility CMS is a headless CMS that provides:
+- **Content Management**: Create and manage content using a web-based interface
+- **Page Management**: Build pages by combining components (called "modules" in CMS)
+- **Multi-locale Support**: Manage content in multiple languages
+- **API Access**: Fetch content via REST API or SDK
+- **Preview Mode**: Preview draft content before publishing
+
+## Key Concepts
+
+### 1. Pages
+Pages in Agility CMS are composed of:
+- **Title and SEO**: Meta title, description, keywords
+- **Template**: Defines the layout structure (e.g., MainTemplate, TwoColumnTemplate)
+- **Zones**: Areas where components (modules) can be added (e.g., "main-content-zone", "sidebar")
+- **Path**: The URL path for the page (e.g., `/about`, `/blog/post-1`)
+
+### 2. Page Templates
+Templates define the layout structure of a page. Each template has:
+- **Named Zones**: ContentZone components where components (modules) are placed
+- **Layout Structure**: Header, footer, sidebars, etc.
+- **React Component**: A server component that renders the zones
+
+Example: `MainTemplate.tsx` has a single zone called "main-content-zone"
+
+### 3. Components (Called "Modules" in CMS)
+**Components** (referred to as "modules" in the Agility CMS interface) are reusable building blocks that can be added to page zones:
+- **Reference Name**: Unique identifier (e.g., "RichTextArea", "Hero", "PostListing")
+- **Fields**: Content fields defined in Agility CMS
+- **React Component**: The implementation that renders the component
+
+**Note**: While these are called "modules" in the CMS, we refer to them as "components" in code to align with React terminology.
+
+### 4. Content Items
+Standalone content that can be:
+- **Referenced by Components**: A component can reference a content item by ID or reference name
+- **Listed in Collections**: Grouped content (e.g., blog posts, team members)
+- **Shared Across Pages**: Reusable content (e.g., site settings, navigation)
+
+### 5. Content Lists
+Collections of content items:
+- **Reference Name**: Identifier for the list (e.g., "posts", "testimonials")
+- **Content Type**: Type of items in the list (e.g., "BlogPost", "Testimonial")
+- **Pagination**: Support for paginated lists
+
+## How This Project Works
+
+### Data Flow
+```
+Agility CMS → API Fetch → Next.js Page → Page Template → Components
+```
+
+1. **User visits a page**: Next.js receives the request
+2. **Middleware processes**: Handles preview, redirects, locale routing
+3. **Page fetches data**: `getAgilityPage()` fetches page data from Agility CMS
+4. **Template renders**: The appropriate page template component is selected
+5. **Components render**: ContentZone renders each component in order
+6. **Component receives data**: Each component receives its data and renders
+
+### File Organization
+
+```
+src/
+├── app/
+│   └── [locale]/
+│       └── [...slug]/
+│           └── page.tsx          # Dynamic page route
+├── components/
+│   ├── agility-pages/            # Page templates
+│   │   ├── index.ts              # Template registry
+│   │   └── MainTemplate.tsx      # Main page template
+│   └── agility-components/       # CMS components (called "modules" in CMS)
+│       ├── index.ts              # Component registry
+│       └── RichTextArea.tsx      # Example component
+└── lib/
+    └── cms/                      # CMS helper functions
+        ├── getAgilitySDK.ts      # Initialize SDK
+        ├── getAgilityPage.ts     # Fetch page data
+        ├── getContentItem.ts     # Fetch single content
+        ├── getContentList.ts     # Fetch content lists
+        ├── getSitemapFlat.ts     # Fetch flat sitemap
+        ├── getSitemapNested.ts   # Fetch nested sitemap
+        └── getRedirections.ts    # Fetch redirects
+```
+
+## Environment Configuration
+
+Required environment variables (in `.env.local`):
+
+```env
+# Agility Instance
+AGILITY_GUID=your-instance-guid
+
+# API Keys
+AGILITY_API_FETCH_KEY=your-fetch-key         # Published content
+AGILITY_API_PREVIEW_KEY=your-preview-key     # Draft content
+
+# Security
+AGILITY_SECURITY_KEY=your-security-key       # For webhooks
+
+# Locale Settings
+AGILITY_LOCALES=en-us                        # Comma-separated (e.g., "en-us,fr,es")
+AGILITY_SITEMAP=website                      # Sitemap name
+
+# Caching
+AGILITY_FETCH_CACHE_DURATION=60              # Seconds
+AGILITY_PATH_REVALIDATE_DURATION=60          # Seconds
+```
+
+## Preview Mode
+
+To preview draft content:
+1. Add `?agilitypreviewkey=your-preview-key` to any URL
+2. The middleware redirects to `/api/preview`
+3. A cookie is set to enable preview mode
+4. All subsequent requests use the preview API key
+
+To exit preview mode:
+1. Add `?AgilityPreview=0` to any URL
+2. The preview cookie is cleared
+
+## Caching Strategy
+
+The project uses Next.js caching with Agility CMS:
+
+1. **Time-based Revalidation**: Pages revalidate every 60 seconds (configurable)
+2. **Cache Tags**: Each piece of content has a tag (e.g., `agility-content-123-en-us`)
+3. **On-demand Revalidation**: Webhook can revalidate specific content via `/api/revalidate`
+
+## Next Steps
+
+- Read [02-page-routing.md](./02-page-routing.md) to understand page routing
+- Read [03-creating-components.md](./03-creating-components.md) to create new components
+- Read [04-data-fetching.md](./04-data-fetching.md) to fetch content from Agility CMS