Setup guide · Next.js

Serve ConveyLoop’s SEO pages from a Next.js site

One route handler and a few lines in your sitemap. conveyloop.com serves its own guides this way.

← How Git publishing works

Before you start

  • A Next.js site on the App Router, in a repository on GitHub.com, GitLab.com or Bitbucket Cloud, deployed by a host that builds on every push, such as Vercel.
  • The code below is tested on Next.js 16.4, with Cache Components off and on.
  • It assumes the connection’s defaults: Standalone HTML, the Target subdirectory /conveyloop/seo, and pages served at /guides. If yours differ, the Git window shows them: use your values where the code has these.

1. Connect your repository

In ConveyLoop, open Project setup and connect Git. Choose the repository and the branch your site deploys from, and keep Standalone HTML: each page is then a complete document with ConveyLoop Metrics built in, which the route sends as it is.

The pages publish to conveyloop/seo/content/ at the root of your repository. You can add the code below before the first publish: until then, the route answers 404 and the build passes.

2. Read the folder

One module finds the pages and reads them. Both the route and the sitemap use it, so they always agree on which pages exist.

lib/conveyloop-pages.ts
import { readdirSync, readFileSync } from 'node:fs';
import path from 'node:path';

// Your connection's "Target subdirectory", followed by /content.
const FOLDER = path.join(process.cwd(), 'conveyloop/seo/content');
// Your connection's "Where your site serves these pages".
export const PAGES_PATH = '/guides';

const PAGE = /^[a-z0-9-]+$/;
const STYLESHEET = /^[a-z0-9-]+\.css$/;
const HTML = 'text/html; charset=utf-8';
const CSS = 'text/css; charset=utf-8';

function names(): string[] {
  try {
    return readdirSync(FOLDER);
  } catch {
    return []; // Nothing published yet.
  }
}

/** The pages' names: example-page for example-page.html. */
export function pageNames(): string[] {
  return names()
    .filter((name) => name.endsWith('.html'))
    .map((name) => name.slice(0, -'.html'.length))
    .filter((name) => PAGE.test(name));
}

/** What the route serves: the section page, the pages, the stylesheets. */
export function pageParams(): Array<{ slug: string[] }> {
  const stylesheets = names().filter((name) => STYLESHEET.test(name));
  return [
    { slug: [] },
    ...pageNames().map((name) => ({ slug: [name] })),
    ...stylesheets.map((name) => ({ slug: [name] })),
  ];
}

/** The file a request asks for, or null when it isn't one of them. */
function fileFor(slug: string[]): { name: string; type: string } | null {
  if (slug.length === 0) return { name: '_index.html', type: HTML };
  if (slug.length !== 1) return null;
  const [name] = slug;
  if (PAGE.test(name)) return { name: `${name}.html`, type: HTML };
  if (STYLESHEET.test(name)) return { name, type: CSS };
  return null;
}

/** The file for a request, exactly as committed, or null. */
export function readPageFile(
  slug: string[] = [],
): { body: string; type: string } | null {
  const file = fileFor(slug);
  if (!file) return null;
  try {
    const body = readFileSync(path.join(FOLDER, file.name), 'utf8');
    return { body, type: file.type };
  } catch {
    return null;
  }
}

The folder path is relative to where next build runs, normally the folder with your package.json. Only names of lowercase letters, digits and hyphens are pages, so no request can read anything else in the folder.

3. Add the route

The route’s folder is the path the pages are served under. An optional catch-all serves the section page at /guides itself as well as each page under it.

app/guides/[[...slug]]/route.ts
import { pageParams, readPageFile } from '@/lib/conveyloop-pages';

export function generateStaticParams() {
  return pageParams();
}

export async function GET(
  _request: Request,
  { params }: { params: Promise<{ slug?: string[] }> },
) {
  const file = readPageFile((await params).slug);
  if (!file) return new Response('Not Found', { status: 404 });
  return new Response(file.body, {
    headers: { 'Content-Type': file.type },
  });
}
  • A route handler, not a page, because each file is a whole HTML document. A page would wrap it in your site’s layout.
  • generateStaticParams prerenders every page with the build. Each publish is a commit, and the build it starts picks the new pages up.
  • Anything else under /guides is a 404. Don’t add export const dynamicParams = false: the route doesn’t need it, and Next.js 16 fails the build with it when Cache Components is on.
  • Serving under another path, such as /learn? Name the folder app/learn/[[...slug]] and set PAGES_PATH to '/learn'.
  • If your project keeps app/ inside src/, put both files under src/. @/ is the import alias create-next-app sets up; use a relative import if your project has none.

4. List the pages in your sitemap

Search engines and ConveyLoop’s own crawl both read your site’s sitemap. Use your site’s address for SITE, the same one your ConveyLoop project has.

app/sitemap.ts
import type { MetadataRoute } from 'next';
import { PAGES_PATH, pageNames } from '@/lib/conveyloop-pages';

const SITE = 'https://www.example.com';

export default function sitemap(): MetadataRoute.Sitemap {
  const pages = pageNames();
  const section = `${SITE}${PAGES_PATH}`;
  return [
    { url: SITE },
    ...(pages.length > 0 ? [{ url: section }] : []),
    ...pages.map((name) => ({ url: `${section}/${name}` })),
  ];
}

Already have an app/sitemap.ts? Copy pages, section and the two lines that list them into it. If another tool writes your sitemap, add the same addresses there.

5. Let ConveyLoop read the pages

  • If your proxy.ts (middleware.ts before Next.js 16) signs visitors in or redirects them, make sure it lets /guides through.
  • If your site has bot protection or a firewall rule, Vercel’s or any other, allow requests whose User-Agent starts with ConveyLoopBot or ConveyLoop-Crawler for your public pages, /guides among them, plus /robots.txt and /sitemap.xml (or the sitemap your robots.txt names). The crawl starts at your homepage, so allowing only /guides isn’t enough. Keep the protection for everything else, such as login and account pages: a User-Agent is easy to fake.

6. Publish and check

Deploy the change, then publish a page. A few minutes after it lands, ConveyLoop fetches it at its address, and the Git window shows Live on your site. If the page isn’t there, the Git window says what ConveyLoop found instead and gives you a prompt for your AI coding agent that fixes it.

Let your Next.js site publish its own SEO pages

Set up the route once. ConveyLoop writes the pages, commits them and keeps improving them.