The website for Pilot Protocol at pilotprotocol.network: marketing pages, docs, and the blog, learning center and newsroom.
- Next.js 16 (App Router), React 19, Tailwind CSS 4, Motion, Geist fonts
- Fumadocs for the docs, written as MDX in
content/docs - Payload CMS 3 for posts, with the admin at
/admin - Cloudflare Workers through OpenNext. Payload keeps its data in D1 and uploads in R2.
Marketing pages and docs are prerendered and served as static assets. The blog, learning center, newsroom, /about, /blog/feed.xml and the sitemap read Payload on every request, so a published post is live without a deploy. The live registry figures come from polo.pilotprotocol.network/api/public-stats, with build-time fallbacks in src/lib/site.ts.
One codebase builds two designs. NEXT_PUBLIC_SITE_VARIANT picks one at build time (src/lib/site.ts).
| Variant | Set | Deploy | Worker | URL |
|---|---|---|---|---|
| sky (production) | NEXT_PUBLIC_SITE_VARIANT=sky |
npm run deploy |
pilot-protocol-website |
https://pilotprotocol.network |
| green | nothing | npm run deploy:green |
pilot-protocol-website-green (env.green in wrangler.jsonc) |
its workers.dev address only |
Sky has the flight home page and the sky accent on every page. Green has the lime home page. next dev and next build build green unless the variable is set; the deploy scripts set it. Both Workers use the same D1 database and R2 bucket. Earlier home page designs stay at /v0, /v2, /v3 and /v4, marked noindex.
To run sky locally:
NEXT_PUBLIC_SITE_VARIANT=sky npm run devNode ^22.23.4 || >=24.22.1 (Payload's requirement). .nvmrc pins 26.
npm install
cp .env.example .env # set PAYLOAD_SECRET: openssl rand -hex 32
npm run migrate # create the schema in the local D1
npm run seed # import the posts in seed/posts
npm run dev # http://localhost:3000Open http://localhost:3000/admin and create the first user. The local D1 and R2 live in .wrangler/state; delete that folder to start from an empty database.
npm run preview makes the OpenNext build and runs the Worker locally in workerd, against the same local D1 and R2.
prebuild runs before every build. It refreshes public/install.sh from pilot-protocol/release, the installer's source of truth (keeping the committed copy if GitHub is down) and regenerates src/generated/*: the content and file sizes that pages used to read from disk, since Workers have no filesystem.
Pages. Each page is an MDX file in content/docs. The file name is the URL: content/docs/mcp.mdx is /docs/mcp. Frontmatter has a title and a description (used for search results and link previews). A heading can fix its anchor with [#id], as in ## Choose your transport [#choose-transport].
Order and groups. content/docs/meta.json lists the pages in sidebar order. Entries like "---SDKs---" are group headings. A page missing from the list still builds and has a URL, but it isn't in the sidebar.
Compiling. createMDX() from fumadocs-mdx/next wraps the config in next.config.ts and adds loaders for MDX, meta.json and the macro. There is no source.config.ts. The collection is declared in src/lib/source.ts with defineDocs from fumadocs-mdx/macro. At build time the macro loader evaluates that call (its scratch files go to .source/, which is git-ignored) and replaces it with imports of every file in content/docs. Each MDX file compiles to a React component plus its frontmatter, table of contents, search data and processed Markdown. Code blocks are highlighted with the site's Shiki themes from src/lib/shiki-themes.ts.
The loader. loader() in src/lib/source.ts turns the collection into source, with base URL /docs. Every route goes through it: source.getPage(slug), source.getPageTree(), source.generateParams().
Routes.
src/app/(site)/docs/layout.tsx: Fumadocs'RootProviderandDocsLayout, with the sidebar fromsource.getPageTree().src/app/(site)/docs/[[...slug]]/page.tsx: one docs page, prerendered for every slug./docsitself renderssrc/components/docs/docs-home.tsx;index.mdxgives it a sidebar entry and a search record.src/components/mdx.tsx: the components available in MDX (Fumadocs' defaults,<Install />,<Paper>and the rest).src/app/(site)/og/docs/[...slug]/route.ts: a share image per page. The sitemap lists every docs page.
Search. src/app/(site)/api/search/route.ts serves createFromSource(source) at /api/search. RootProvider points Fumadocs' search dialog at it. Open the dialog from the sidebar or with ⌘K.
For agents. /docs/<page>.mdx returns the page as Markdown. A rewrite in next.config.ts sends it to src/app/llms.mdx/docs/[[...slug]]/route.ts, which is prerendered for every page. The copy-page button and the view options menu on each page use the same URL. /llms.txt is a hand-written file in public/.
Adding a page.
-
Create
content/docs/my-page.mdx:--- title: "My page" description: "One sentence for search results and link previews." --- Text in Markdown, plus any component from src/components/mdx.tsx.
-
Add
"my-page"tocontent/docs/meta.jsonunder the right group. -
npm run devpicks it up at/docs/my-pageand/docs/my-page.mdx, and search finds it.
The config is src/payload.config.ts. The collections are in src/collections:
| Collection | Holds | Fields |
|---|---|---|
posts |
Blog, learning center and newsroom posts | title, description, content (Lexical rich text with code blocks and tables), slug (unique), section (blog, learn or news), publishedAt, author, tags, minutes (reading time, set on save), seoTitle. Drafts on, 25 versions per post. |
media |
Uploads, stored in R2 | alt. Crop and focal point are off because Workers have no sharp. |
users |
Admin accounts | Email and password (Payload auth), name |
Admin and API. The admin is at /admin and the REST API under /api, both from src/app/(payload), which Payload generates. GraphQL is off. After adding admin components, run npm run generate:importmap.
Local API. Pages read posts in-process: src/lib/posts.ts calls getPayload({ config }) and payload.find(). The blog, learn and news pages, their share images, the feed, /about and the sitemap use it. Visitors only get published posts (the read access rule in Posts.ts).
Storage. Data goes through sqliteD1Adapter on the D1 binding. Uploads go through r2Storage on the R2 binding.
Where the bindings come from. In production, from the Worker, through OpenNext's getCloudflareContext(). In next dev, during next build and from the Payload CLI, payload.config.ts calls Wrangler's getPlatformProxy(), which gives local D1 and R2 under .wrangler/state. With CLOUDFLARE_ENV=remote the CLI uses the env.remote bindings in wrangler.jsonc, which point at the production D1 and R2.
Migrations. They live in src/migrations. npm run migrate applies them to the local D1. After changing a collection:
npx payload migrate:create <name> # writes src/migrations/<timestamp>_<name>.ts
npm run migrate # apply it locally
npm run generate:types # refresh cloudflare-env.d.ts and src/payload-types.tsProduction gets new migrations from npm run deploy:database, which npm run deploy runs first.
Seed. scripts/seed.ts imports seed/posts/*.json, the posts converted from the previous site by scripts/html-to-lexical.py. Slugs that already exist are skipped, so it can run more than once. npm run seed writes to the local D1, npm run seed:production to production.
This needs a Workers Paid plan: the Worker with Payload is about 9 MB gzipped. wrangler.jsonc has no account_id; Wrangler takes the account from CLOUDFLARE_ACCOUNT_ID or from wrangler login.
One-time setup, on the account that holds the pilotprotocol.network zone:
npx wrangler login
npx wrangler d1 create pilot-protocol-website
npx wrangler r2 bucket create pilot-protocol-website-mediaPut the new database id into every database_id in wrangler.jsonc (top level, env.green and env.remote), in place of REPLACE_WITH_D1_DATABASE_ID. Then:
npx wrangler secret put PAYLOAD_SECRET # the production Worker
npx wrangler secret put PAYLOAD_SECRET --env green # the green Worker
npm run deploy:database # run the migrations on the production D1
npm run seed:production # optional: import the postsThe deploy scripts set NEXT_PUBLIC_SERVER_URL for production. OpenNext compiles the values in .env into the Worker as fallbacks; a Worker secret overrides them.
Each deploy:
npm run deploy # deploy:database, then deploy:app (sky, at pilotprotocol.network)
npm run deploy:green # green only; run deploy:database first if the schema changeddeploy:app and deploy:green run prebuild, build with opennextjs-cloudflare build and upload with opennextjs-cloudflare deploy. The build runs Next.js with one worker (experimental.cpus in next.config.ts): every build worker opens the local D1, and two at once fail with SQLITE_BUSY.
The domain. The production Worker's routes entry attaches pilotprotocol.network as a custom domain. Until this change the apex belonged to the Cloudflare Pages project pilotprotocol; remove it there before the first deploy, or the custom domain can't be attached. workers_dev stays on, so the Worker can be checked at its workers.dev address first. Responses on *.workers.dev carry X-Robots-Tag: noindex (headers() in next.config.ts).
Other Workers on the zone. The pilot-release Worker (pilot-protocol/release) has routes on pilotprotocol.network/install.sh, /.well-known/* and /api/*. Routes run in front of a custom domain, so it keeps serving the installer and /.well-known/latest.json. Its /api/* route also catches this site's /api/search (docs search), /api/media/file/* (uploads) and Payload's REST API, which the admin uses, and answers 404 for everything but /api/changelog. Narrow that route to pilotprotocol.network/api/changelog before the cutover.
The code ships with Cloudflare adapters: Payload on D1 and R2, and OpenNext to build the Worker. Vercel has no D1 or R2 bindings, so Payload needs a different database adapter and storage adapter. The marketing pages and Fumadocs need no changes. Nothing below is applied in this repo.
1. Swap the packages. Keep them on the same version as payload.
npm uninstall @payloadcms/db-d1-sqlite @payloadcms/storage-r2
npm install @payloadcms/db-postgres @payloadcms/storage-vercel-blobFor Turso (libSQL), install @payloadcms/db-sqlite in place of @payloadcms/db-postgres.
2. Edit src/payload.config.ts. Delete the Cloudflare part: the @opennextjs/cloudflare and wrangler imports, isCLI, isBuild, the cloudflare constant and getCloudflareContextFromWrangler() at the bottom. Then change db and plugins:
import { postgresAdapter } from "@payloadcms/db-postgres";
import { vercelBlobStorage } from "@payloadcms/storage-vercel-blob";
export default buildConfig({
// ...the rest stays as it is
db: postgresAdapter({ pool: { connectionString: process.env.DATABASE_URI } }),
plugins: [vercelBlobStorage({ collections: { media: true }, token: process.env.BLOB_READ_WRITE_TOKEN })],
});With Turso:
import { sqliteAdapter } from "@payloadcms/db-sqlite";
db: sqliteAdapter({ client: { url: process.env.DATABASE_URI!, authToken: process.env.DATABASE_AUTH_TOKEN } }),isProduction and the JSON logger can stay.
3. Make a fresh migration. The one in src/migrations is written for D1. With DATABASE_URI in .env:
rm -rf src/migrations
npx payload migrate:create initial
npx payload migrate
npx payload generate:types
npm run seed # optionalFor production, run npx payload migrate with DATABASE_URI pointing at the production database before deploying, or set the Vercel build command to npx payload migrate && npm run build.
4. Create the Vercel project. Import the repo with the Next.js preset. The default build command, npm run build, runs prebuild and then next build; opennextjs-cloudflare isn't used. Environment variables:
| Variable | Value |
|---|---|
PAYLOAD_SECRET |
A random string: openssl rand -hex 32 |
NEXT_PUBLIC_SERVER_URL |
The site's origin, e.g. https://pilotprotocol.network |
DATABASE_URI |
The Postgres connection string (Neon or Vercel Postgres), or the libsql:// URL for Turso |
DATABASE_AUTH_TOKEN |
Turso only |
BLOB_READ_WRITE_TOKEN |
Added by Vercel when you connect a Blob store |
NEXT_PUBLIC_SITE_VARIANT |
sky for the sky site; unset for green |
For both variants, make two Vercel projects from the same repo that differ only in NEXT_PUBLIC_SITE_VARIANT. They can share the database and Blob store.
5. Cloudflare-only files. Vercel ignores wrangler.jsonc, open-next.config.ts, cloudflare-env.d.ts and the preview and deploy* scripts; delete them or leave them. If you uninstall @opennextjs/cloudflare, delete open-next.config.ts too, or the type check fails. public/_headers and public/_redirects are Workers static-asset rules that Vercel doesn't read: move the headers and the /plain redirects into headers() and redirects() in next.config.ts if you need them.
.github/workflows/ci.yml runs on pull requests and pushes to main: npm ci, the type check (next typegen, then tsc --noEmit), npm run lint, and the production build (opennextjs-cloudflare build, sky). Its deploy step runs only when the workflow is started by hand on main (workflow_dispatch), and runs npm run deploy with the CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID secrets. The token needs Workers Scripts, Workers Routes, D1 and R2 edit rights on the account.
sync-install-sh.yml keeps the live /install.sh (served by pilot-release from R2) in step with pilot-protocol/release, and fails if public/install.sh drifts from it.
worker/ is a separate Cloudflare Worker (pilot-publish) with its own package, tests and wrangler.toml, deployed on its own. It publishes a post by committing an Astro page and src/data/blogPosts.ts to this repo, which this site no longer reads: posts now go through Payload at /admin.
cd worker
npm install
npm test # vitest run
npm run deploy # wrangler deploysrc/app/(site): the website, with its own root layout (banner, header, footer)src/app/(site)/globals.css: Tailwind and the colour tokens for the light and dark themessrc/app/(payload): Payload admin and REST API (generated)src/app/llms.mdx: docs pages as Markdownsrc/app/global-not-found.tsx: the 404 for unmatched URLs under both root layoutssrc/components/home: the green home page sections, in page order insrc/app/(site)/page.tsxsrc/components/v4: the sky home page;src/components/v0,v2,v3: the other alternate home pagessrc/components/pages/*: the standalone pages (service agents, App Store, cloud, security and others)src/collections,src/payload.config.ts,src/migrations: Payloadsrc/lib/source.ts,content/docs: Fumadocscontent/pages,content/apps: other content from the previous site, bundled intosrc/generatedbyprebuildseed/posts: the posts for the seedscripts/: the build helpers (sync-install.mjs,generate-static-data.mjs), the seed, and the one-off scripts that migrated the previous site (migrate-content.py,html-to-mdx.py,html-to-lexical.py)worker/: thepilot-publishWorker (above)
AGPL-3.0-or-later. See LICENSE.