Previewing

# Handling Preview URLs & Request Lifecycle (App Router)

In the **Agility CMS Next.js Starter** (using the App Router), handling Preview URLs utilizes the Next.js `draftMode` functionality found in `next/headers`. This allows the application to securely bypass static caching and fetch the latest content drafts.

> **⚠️ Important: Save Your Content First**
> The Preview Mode fetches the latest **Saved** version of your content (Preview state).
> If you type into a field in Agility CMS but do not click **Save**, the API cannot see those changes yet unless you're using WebStudio.

The lifecycle consists of three distinct components:
1.  **The Entry Point** (`app/api/preview/route.ts`)
2.  **The Page Logic** (`app/[...slug]/page.tsx`)
3.  **The Exit Point** (`app/api/exit/route.ts`)

---

## 1. The Entry Point: `app/api/preview/route.ts`

This API route is triggered when a user clicks "Preview" in the Agility CMS Manager. Its primary role is to validate the security handshake and enable "Draft Mode" via cookies.

**Function:** Validates the `agilitypreviewkey` and enables `draftMode`.

```typescript
// app/api/preview/route.ts

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("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
	});

	console.log("validationResp", validationResp)

	if (validationResp.error) {
		return NextResponse.json({ message: validationResp.message }, { status: 401 });
	}

	let previewUrl = slug;

	//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);
}

```

---

## 2. The Page Logic: `app/[...slug]/page.tsx`

In the App Router, the page component itself determines whether to request **Preview** or **Published** content. This logic is centralized in the main page file.

**Function:** checks the environment and cookie state to determine the `preview` boolean.

```typescript
// app/[...slug]/page.tsx
import { getPageTemplate } from "components/agility-pages"
import { PageProps, getAgilityPage } from "lib/cms/getAgilityPage"
import { getAgilityContext } from "lib/cms/getAgilityContext"
import agilitySDK from "@agility/content-fetch"

import { Metadata, ResolvingMetadata } from "next"

import { resolveAgilityMetaData } from "lib/cms-content/resolveAgilityMetaData"
import NotFound from "./not-found"
import InlineError from "components/common/InlineError"
import { SitemapNode } from "lib/types/SitemapNode"
import { notFound } from "next/navigation"

export const revalidate = 60
export const runtime = "nodejs"
export const dynamic = "force-static"

/**
 * Generate the list of pages that we want to generate a build time.
 */
export async function generateStaticParams() {
	const isDevelopmentMode = process.env.NODE_ENV === "development";
	const isPreview = isDevelopmentMode;
	const apiKey = isPreview ? process.env.AGILITY_API_PREVIEW_KEY : process.env.AGILITY_API_FETCH_KEY;
	const agilityClient = agilitySDK.getApi({
		guid: process.env.AGILITY_GUID,
		apiKey,
		isPreview,
	});
	const languageCode = process.env.AGILITY_LOCALES || "en-us";

	agilityClient.config.fetchConfig = {
		next: {
			tags: [`agility-sitemap-flat-${languageCode}`],
			revalidate: 60,
		},
	};

	// Get the flat sitemap and generate the paths
	const sitemap: { [path: string]: SitemapNode } = await agilityClient.getSitemapFlat({
		channelName: process.env.AGILITY_SITEMAP || "website",
		languageCode,
	});

	const paths = Object.values(sitemap)
		.filter((node, index) => {
			if (node.redirect !== null || node.isFolder === true || index === 0) return false;
			return true;
		})
		.map((node) => {
			return {
				slug: node.path.split("/").slice(1),
			};
		});

	console.log("Pre-rendering", paths.length, "static paths.");
	return paths;
}

/**
 * Generate metadata for this page
 */
export async function generateMetadata(
	props: PageProps,
	parent: ResolvingMetadata
): Promise<Metadata> {
	const { params } = props;  // Remove the 'await' here

	const { locale, sitemap, isDevelopmentMode, isPreview } = await getAgilityContext();
	const agilityData = await getAgilityPage({ params });
	if (!agilityData.page) return {};
	return await resolveAgilityMetaData({
		agilityData,
		locale,
		sitemap,
		isDevelopmentMode,
		isPreview,
		parent,
	});
}
export default async function Page({ params }: PageProps) {

	const agilityData = await getAgilityPage({ params });
	if (!agilityData.page) notFound();

	const AgilityPageTemplate = getPageTemplate(agilityData.pageTemplateName || "");

	return (
		<div data-agility-page={agilityData.page?.pageID} data-agility-dynamic-content={agilityData.sitemapNode.contentID}>
			{AgilityPageTemplate ? (
				<AgilityPageTemplate {...agilityData} />
			) : (
				<InlineError message={`No template found for page template name: ${agilityData.pageTemplateName}`} />
			)}
		</div>
	);
}
```

> **Note on `NODE_ENV`:**
> The check for `process.env.NODE_ENV === "development"` ensures that developers running the site locally (`localhost`) always see the latest changes immediately without needing to manually invoke the Preview API.

---

## 3. The Exit Point: `app/api/exit/route.ts`

This route allows a user to "Turn off" preview mode and return to viewing the live/published version of the site (simulating a standard public visitor).

**Function:** Disables `draftMode` and clears the cookie.

```typescript
// app/api/exit/route.ts
"use server";
import { getDynamicPageURL } from '@agility/nextjs/node';
import { draftMode } from 'next/headers'
import { NextRequest, NextResponse } from "next/server";

export async function GET(request: NextRequest) {

	const searchParams = request.nextUrl.searchParams

	const slug = searchParams.get('slug');
	const ContentID = searchParams.get('ContentID');

	//disable draft/preview mode
	(await draftMode()).disable()

	let url = new URL(slug || '', request.nextUrl.origin).toString();

	if (ContentID) {
		const dynamicPath = await getDynamicPageURL({ contentID: Number(ContentID), preview: false, slug: slug || undefined });
		if (dynamicPath) {
			url = dynamicPath;
		}
	}

	// Remove the preview URL param if it exists
	const urlObj = new URL(url);
	urlObj.searchParams.delete('preview');
	url = urlObj.toString();


	// Redirect to the url
	return NextResponse.redirect(url, { status: 307, headers: { "Location": url } })

}
```

---

## Summary of the Data Flow

1.  **User Clicks Preview (Agility CMS)**
    * Opens the preview URL: `mysite.com/api/preview?slug=/about&agilitypreviewkey=xyz`
2.  **Entry (`api/preview`)**
    * Validates the Security Key.
    * Calls `draftMode().enable()` to set the cookie.
    * Redirects the browser to `/about`.
3.  **Rendering (`page.tsx`)**
    * The page loads and calls `draftMode().isEnabled`.
    * Since the cookie exists, it sets `isPreview = true`.
    * The SDK fetches **Draft** content from the Agility API.
4.  **Result**
    * The user sees the unpublished, work-in-progress content.

---

## Configure the Preview URL


> **⚠️ Important: Don't forget to configure your Agility instance**

![Agility CMS ](https://cdn.aglty.io/agility-cms-docs/images/block-editor/Screenshot%202024-11-07%20at%205.50.41%E2%80%AFPM-11072024215054.png)

Read the full guide on setting up your preview in your Agility CMS instances.

[https://agilitycms.com/docs/developers/setting-up-preview](https://agilitycms.com/docs/developers/setting-up-preview) 

---

## Troubleshooting

If Previews are not working in the App Router:

1.  **Check `.env.local`:** Ensure `AGILITY_SECURITY_KEY` matches the key generated in Agility CMS.
2.  **Check Localhost:** Remember that `process.env.NODE_ENV === 'development'` forces preview on. To test "Live" mode locally, you must run `npm run build` and `npm run start`.
3.  **Cookie Blocking:** If you are using Agility CMS inside an iframe (WebStudio), ensure your browser allows third-party cookies, or open the preview in a new tab.

Preview URL Lifecycle

Starter

System Status

Privacy Policy

GDPR

Security

Glossary

Headless CMS

Composable DXP

Enterprise

Marketers

Developers

Features

Roadmap

Pricing

Platform

App Marketplace

Ecosystem Partners

MACH Alliance Member

Case Studies

Solutions on Agility

Customers & Partners 

Resource Center

Documentation

Blog

Starters

Headless CMS Comparison

Resources

Overview

Editors

Owners & Admins

Apps

<p>Agility Academy: take courses and earn certifications. Learn at your own pace - it's free! <a class="link-line line-purple" href="/resources/agility-academy" rel="noopener">Learn More</a></p>

##Title##

nextjs-articles-dynamic

owners-admins-articles-dynamic

preview-url-lifecycle