Deploying Next.js to Netlify

Netlify runs Next.js through its Next.js Runtime, which is detected and installed automatically — App Router, React Server Components, streaming, route handlers, the proxy and on-demand revalidation all work. This guide covers deploying an Agility-powered site, wiring publish-triggered updates, and the two things that most often break preview after a green deploy.

Coming from the older recipe? This article used to tell you to let Netlify install the Essential Next.js Build Plugin and warned that "Netlify Preview for Next.js is still experimental." Both are out of date. The Essential Next.js plugin was superseded by the Next.js Runtime (v5), which Netlify installs for you — you should not be adding @netlify/plugin-nextjs to netlify.toml by hand on a new site. And preview is no longer experimental; it just needs the configuration in the "Making preview work" section below. The old guide also pointed you at Settings → Sitemaps, which is now Settings → Deployment.

Deploy via the Agility integration

In the Agility Manager, go to Settings → Deployment and click Setup Deployment, then choose the Netlify automated deployment.

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

The wizard authorizes Netlify against your Git provider, creates the repository, sets your AGILITY_* environment variables, builds, and writes the resulting domain back into your Agility instance.

Deploy manually

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

2. In Netlify, Add new site → Import an existing project, and pick the repo. Netlify detects Next.js; leave the build command (npm run build) and publish directory alone — the runtime handles them.

3. Under Site configuration → Environment variables, add:

   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 — no spaces
   AGILITY_SITEMAP	Sitemap channel name, usually website

   Make sure they're scoped to all deploy contexts, not just production. A variable missing from Deploy Previews is the usual reason a PR preview 500s while production is fine.

4. Deploy.

Then register the deployed URL in Agility under Settings → Deployment → Setup Deployment → Custom Deployment, so editors' preview links point at the right host.

Updating content without rebuilding

You do not need a full rebuild to publish a change. With Cache Components, each content read is cached under a tag:

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

and a route handler clears the tag 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.

In the Manager, go to Settings → Web Hooks and point a hook at https://your-site.com/api/revalidate, with Receive Content Publish Events checked. Send a Test Payload and confirm a success response before relying on it.

If you'd rather rebuild

For a fully static site, trigger a build instead:

1. In Netlify, go to Site configuration → Build & deploy → Build hooks and create a hook. Copy the URL it generates.
2. In Agility, Settings → Web Hooks, add a hook pointing at that URL.
   • Production builds — check Receive Content Publish Events.
   • Staging/preview builds — uncheck publish events, check Receive Content Save Events.

A rebuild takes minutes and re-renders the whole site; tag revalidation takes seconds and re-renders only what changed. Prefer the webhook above unless you have a reason not to.

Making preview work on a deployed site

1. Cached pages skip the proxy

This is the one that costs people a day. Netlify serves prerendered pages straight from its CDN without invoking your proxy (proxy.ts — Next 16's renamed middleware.ts). So on exactly the pages that matter most, ?agilitypreviewkey= never reaches /api/preview, draft mode is never enabled, and Web Studio silently renders the published page. No error appears anywhere, and you cannot reproduce it locally, because under next start the proxy always runs.

Fix it with 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 your proxy logic as well — it handles uncached requests, and the two converge on the same handler. Full detail in Handling Preview URLs & Request Lifecycle.

2. Draft renders must not reach a shared cache

Draft mode shows unpublished content. If your cache headers are unconditional, that content gets stored on a CDN and served to the public. Set them where the draft cookie is visible — in the proxy:

const DRAFT_COOKIE = "__prerender_bypass"

if (request.cookies.has(DRAFT_COOKIE)) {
  res.headers.set("Cache-Control", "private, no-store")
} else {
  res.headers.set("CDN-Cache-Control", "public, s-maxage=60, stale-while-revalidate=86400")
}

CDN-Cache-Control is honoured by Netlify and Vercel alike, so this stays vendor-neutral.

Deploy Previews

Netlify builds a Deploy Preview for every pull request automatically. Two things to check:

• Your AGILITY_* variables are available in the Deploy Preview context, not just Production.
• Deploy Preview URLs change per PR. If you want editors previewing against them, register the pattern in Agility rather than a single fixed host.

Verify the deployment

curl -I https://your-site.com/about-us         # 200, with CDN cache headers
curl -I https://your-site.com/no-such-page     # a real 404, not a 200

Then publish something in Agility and confirm it appears within seconds — the end-to-end test that actually proves the webhook, the tag and the cache are all wired together.

Summary

1. Settings → Deployment in Agility for the automated path, or import the repo in Netlify directly.
2. The Next.js Runtime is installed for you — don't hand-add the old Essential Next.js plugin.
3. Set every AGILITY_* variable in all deploy contexts.
4. Prefer a publish webhook calling revalidateTag(tag, "max") over a full rebuild.
5. Add the beforeFiles preview rewrite, or preview breaks on exactly the cached pages editors care about — silently.