Deploying Next.js to Vercel

Vercel is built by the team behind Next.js, so every Next.js feature works there on the day it ships — including Cache Components, the proxy, and on-demand revalidation. This guide covers deploying an Agility-powered Next.js site, wiring up publish-triggered updates, and the two settings that most often break preview after a successful deploy.

Deploy via the Agility integration

The fastest path. In the Agility Manager, go to Settings → Deployment and click Setup Deployment for Vercel.

Note: You'll need a GitHub account and a Vercel account.

The wizard then:

1. Authorizes the Agility integration with your Vercel account.
2. Creates (or connects) a Git repository and clones the starter into it.
3. Sets your AGILITY_* environment variables on the Vercel project — for Production and Preview both.
4. Builds and deploys.
5. Writes the resulting Production and Preview domains back into your Agility instance.

That last step is what makes preview work without you configuring anything: Agility now knows which URL to open when an editor clicks Preview.

Deploy manually

If your project isn't based on a starter:

1. Push your repository to GitHub, GitLab or Bitbucket.

2. At vercel.com/new, import it. Vercel detects Next.js and needs no build configuration.

3. Add your environment variables:

   Variable	Purpose
   AGILITY_GUID	Your instance identifier
   AGILITY_API_FETCH_KEY	Live (published) content
   AGILITY_API_PREVIEW_KEY	Draft content, for preview
   AGILITY_SECURITY_KEY	Validates preview links and webhooks
   AGILITY_LOCALES	Comma-separated, first is the default
   AGILITY_SITEMAP	Sitemap channel name, usually website

   Set them for Production, Preview and Development. A missing key on Preview is the classic cause of "it works in production but every preview deploy 500s."

4. Deploy, then install the Agility CMS integration from the Vercel Marketplace to link the project back to your instance.

Updating content without rebuilding

Coming from the older recipe? This guide used to show getStaticPaths with fallback: true plus revalidate: 10 in getStaticProps — Incremental Static Regeneration on a timer. That model is gone in the App Router, and route segment configs like export const revalidate are rejected outright when cacheComponents is enabled. The replacement is better: instead of every page re-checking on a stopwatch, a publish webhook invalidates exactly the affected cache tags, so the change is live in seconds and nothing else re-renders.

With Cache Components, each content read is cached and tagged:

const cachedContentItem = async (params) => {
  "use cache"
  cacheTag(`agility-content-${params.contentID}-${params.languageCode}`)
  cacheLife("days")
  return fetchContentItem(params)
}

and a route handler clears those tags when Agility says something changed:

// app/api/revalidate/route.ts
import { revalidateTag } from "next/cache"

export async function POST(req: NextRequest) {
  const data = await req.json()

  if (data.state === "Published" && data.referenceName) {
    // Next 16 requires the second argument — the cache profile to expire
    revalidateTag(`agility-content-${data.referenceName}-${data.languageCode}`, "max")
  }

  return NextResponse.json({ revalidated: true })
}

revalidateTag(tag) with one argument is a Next 15 signature. In Next 16 it takes a cache-life profile as a second argument, and omitting it is a build error.

Point Agility at it

In the Manager, go to Settings → Web Hooks and add one pointing at https://your-site.com/api/revalidate. Check Receive Content Publish Events, and send a Test Payload to confirm you get a success response before relying on it.

If you want to trigger a full rebuild instead — appropriate if you don't use tag revalidation — create a Deploy Hook in Vercel under Settings → Git → Deploy Hooks and point the Agility webhook at that URL.

Making preview work on a deployed site

Two things bite here, and both only appear once the site is actually on Vercel.

1. Cached pages skip the proxy

Vercel serves prerendered pages straight from its edge cache without invoking your proxy. On exactly the pages that matter most, ?agilitypreviewkey= never reaches /api/preview, draft mode is never enabled, and Web Studio quietly shows published content.

The fix is a beforeFiles rewrite, which is compiled into the routes manifest and evaluated before the cache lookup:

// next.config.mjs
async rewrites() {
  return {
    beforeFiles: [
      {
        source: "/:path((?!api).*)",
        has: [{ type: "query", key: "agilitypreviewkey" }],
        destination: "/api/preview?slug=/:path",
      },
    ],
  }
}

Keep the proxy logic as well — it handles uncached requests. Full detail in Handling Preview URLs & Request Lifecycle.

2. Deployment Protection blocks Agility

Vercel protects preview deployments by default. Agility's preview requests and your webhook calls arrive unauthenticated and get an SSO page instead of your site — so preview shows a Vercel login screen, and publishes appear not to revalidate.

Under Settings → Deployment Protection, either add a Protection Bypass for Automation secret and configure it in your Agility integration, or scope protection so the domain Agility calls is reachable. Don't simply switch protection off.

Build settings worth checking

• Node version — set it explicitly under Settings → General, and keep it on a current LTS. Node 18 is end-of-life.
• prebuild — if your project syncs redirects or other data before building (npm runs prebuild automatically before build), confirm that step has the env vars it needs on Vercel, not just locally.
• Build cache — Vercel caches .next/cache between builds, which is what keeps incremental builds fast. Use Redeploy without cache when debugging a build that succeeds locally but not on Vercel.

Verify the deployment

curl -I https://your-site.com/about-us                  # 200, with cache headers
curl -I https://your-site.com/no-such-page              # a real 404, not a 200
curl -X POST https://your-site.com/api/revalidate \
  -H "Content-Type: application/json" -d '{"state":"Published", ...}'

Then publish a change in Agility and confirm it appears on the live site within seconds — the end-to-end test that actually proves the wiring.

Summary

1. Settings → Deployment in Agility for the automated path; Vercel Marketplace integration for a manual one.
2. Set every AGILITY_* variable on all three environments.
3. Forget timed ISR — use cached, tagged reads plus a publish webhook that calls revalidateTag(tag, "max").
4. Add the beforeFiles preview rewrite, or preview breaks on exactly the cached pages editors care about.
5. Deal with Deployment Protection deliberately, or Agility can't reach your preview deployments.