Connect Next.js to Fondoo

What Fondoo can do with it

Once the adapter is installed, Fondoo can change the following within about two minutes of an update:

• Redirects, through your proxy file. They apply to GET and HEAD requests and keep the query string.
• SEO metadata per path: title, description, canonical, robots, Open Graph, Twitter cards and hreflang, through Next's metadata API. JSON-LD schema comes through the FondooSchema component.
• Fondoo scripts: analytics, forms, the support widget and a checkout link, each switchable on or off, through the FondooScripts component.
• Pause: turn everything off at once.

Things that need your approval when an agent asks for them:

• disconnect_site_proxy.
• Any update_site_proxy call that changes SEO on more than 20 paths.

Every SEO change is stored as a reversible fix record.

Next.js proxy code cannot rewrite the HTML of a downstream response. That is why SEO goes through generateMetadata rather than through the proxy. Middleware mode also does not include DNS-level proxying, request budgets or bot limits; those need Fondoo's edge proxy.

Before you start

• A Fondoo site and its site ID (a UUID).
• A Next.js App Router project. metadata and generateMetadata work only in Server Components (generateMetadata).
• Your public hostname, for example www.yourdomain.com.
• A separate origin URL. This is a public HTTPS address that reaches your host directly, such as your Vercel deployment URL.
• The Fondoo packages. @fondoo/next and @fondoo/site-edge are MIT-licensed but not yet published on npm. Copy or link them into your project from the Fondoo source.

There is no vendor cost.

Proxy or middleware? As of Next.js 16, the middleware file convention is deprecated and renamed to proxy. The file is now proxy.ts and the exported function is proxy (Next.js proxy). On Next.js 15 or older, use middleware.ts instead. Next provides a codemod: npx @next/codemod@canary middleware-to-proxy .

Step by step: get your credentials

There is no Next.js API key. Fondoo gives you a public verification key that your app uses to check the signed settings feed. It is not secret, but pin it exactly.

1. Ask your agent to register the site in middleware mode (see the next section). Copy publicKey from the response.
2. Create a shared options object, for example lib/fondoo.ts:

export const fondooOptions = {
  endpoint: 'https://api.getfondoo.com',
  siteId: 'YOUR-SITE-UUID',
  hostname: 'www.yourdomain.com',
  publicKey: 'PUBLIC-BASE64-ED25519-KEY',
};

3. Proxy file (proxy.ts on Next.js 16). Run Fondoo first. If it returns a response, return it. Otherwise continue with your existing logic:

import { NextResponse, type NextRequest } from 'next/server';
import { fondooMiddleware } from '@fondoo/next';
import { fondooOptions } from './lib/fondoo';

const fondoo = fondooMiddleware(fondooOptions);

export async function proxy(request: NextRequest) {
  const redirect = await fondoo(request);
  if (redirect) return redirect;
  return NextResponse.next(); // or your existing auth/i18n logic
}

4. Root layout. Add <FondooScripts options={fondooOptions} path={pathname} /> once. If you use a Content Security Policy nonce, pass nonce.
5. Metadata. In each route's generateMetadata, merge in await fondooMetadata(fondooOptions, pathname). Add <FondooSchema options={fondooOptions} path={pathname} /> where you want managed JSON-LD.
6. Build and deploy as usual.

The adapter only acts when the request hostname matches hostname, so preview URLs are untouched.

Connect it in Fondoo

In the dashboard: the Connections page has no Next.js card. Use your agent or the REST API.

By asking your agent. For example:

"Connect my Next.js site www.yourdomain.com to Fondoo in middleware mode. The origin is https://my-app.vercel.app."

The agent can call connect_service({provider:"next", siteId}) for a signed 15-minute setup link, then:

connect_site_proxy({siteId, hostname:"www.yourdomain.com", originUrl:"https://my-app.vercel.app", mode:"middleware"})

The status connection_required is normal. It means "install the adapter". Next.js has no API key, so add_connection_key and test_connection are not used.

REST: POST https://api.getfondoo.com/v1/ops/connect_site_proxy with Authorization: Bearer <your Fondoo key> and the same JSON body.

Later changes use update_site_proxy. Its settings object replaces the whole settings object. Read get_site_proxy_status first, merge, and send the complete object.

Test that it works

1. Call get_site_proxy_status({siteId}) and confirm the site is registered in middleware mode.
2. Ask your agent to add a test redirect, for example /fondoo-test to /.
3. After up to two minutes, open https://www.yourdomain.com/fondoo-test. You should land on the home page.
4. Ask for a test title on one page, reload it and check the <title> in the page source.

Troubleshooting

• Redirects work but titles do not change. fondooMetadata is missing from that route's generateMetadata, or the page is statically generated and needs revalidation or a rebuild.
• Nothing happens at all. Check that your proxy file is in the right place for your Next.js version, and that hostname matches the live hostname exactly. The adapter fails open: a missing, slow (over 500 ms), tampered or expired feed simply leaves your app unchanged.
• Error about runtime in proxy.ts. Next.js 16 proxy files do not accept the runtime option. Remove it.
• Scripts blocked. Allow the Fondoo API origin, and challenges.cloudflare.com for forms, in your Content Security Policy. Pass your nonce.
• "Site already connected". Use update_site_proxy instead of connecting again.

Limits, data and security

• No Next.js credentials are stored. The public feed contains no origin URL and no secrets. It is cacheable for 60 seconds and expires within 120.
• Never put a Fondoo owner or server key in NEXT_PUBLIC_ variables. The adapter does not need one.
• Pause: pause_site_proxy({siteId}). Resume with update_site_proxy({siteId, paused:false}).
• Disconnect: remove the adapter code, then call disconnect_site_proxy({siteId}). This is destructive, so agents need your approval. Nothing on your host is deleted.

Official links

• Next.js proxy file convention: https://nextjs.org/docs/app/api-reference/file-conventions/proxy
• generateMetadata: https://nextjs.org/docs/app/api-reference/functions/generate-metadata
• Fondoo guide (in this repository): docs/connect-your-site.md, section "Framework integration"