Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions specs/epics/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,5 +7,6 @@ folder is the adoption; the merge creates the epic in the workspace.

| Epic | Cluster | Status | What it is |
|------|---------|--------|------------|
| [`cms-wordpress/`](./cms-wordpress/) | **WP** | In progress (WP0) | Vercel's Next.js Starter for WordPress Headless CMS — 9d8's next-wp, posts, pages and terms from a WordPress REST API — on Cloudflare Workers + Static Assets through OpenNext, serving sample content until a WordPress is connected, and an Orun baseline that instantiates it (WP2) |

As-built ≠ intent: what shipped lives in each epic's `IMPLEMENTATION-STATUS.md`.
11 changes: 11 additions & 0 deletions specs/epics/cms-wordpress/IMPLEMENTATION-STATUS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# cms-wordpress — implementation status

| Milestone | State | Landed |
|---|---|---|
| WP0 — the spec | ✅ | the repository's first commit |
| WP1 — the site on Workers | planned | WP-2 |
| WP2 — a baseline | planned | WP-3 |

## Departures from the upstream template

Recorded as they land, from WP1 on.
35 changes: 35 additions & 0 deletions specs/epics/cms-wordpress/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
# cms-wordpress — Vercel's Next.js Starter for WordPress Headless CMS on Cloudflare Workers

**9d8's next-wp — a Next.js front end that reads a WordPress site's REST
API — built by OpenNext into one Cloudflare Worker with Static Assets, every
page rendered on request against WordPress, deployed by Orun to stage and
prod on every merge, serving sample content until a WordPress is connected —
and the baseline that makes a copy of it somebody else's site in one
landing.**

| | |
|---|---|
| Status | In progress — WP0 on main |
| Upstream | [9d8dev/next-wp](https://github.com/9d8dev/next-wp) (MIT), at `4a2caeb` (2026-08-06) — Vercel's Next.js Starter for WordPress Headless CMS |
| Reference | [cms-sanity](https://github.com/sourceplane/cms-sanity) — the same scaffolding, tests and bootstrap, and the unconnected sample mode; [portfolio-starter-kit](https://github.com/sourceplane/portfolio-starter-kit) — the origin per environment |
| Key | `WP` |

## Read in this order

1. [design.md](design.md) — the template, how each Vercel piece maps to
Cloudflare, the unconnected sample mode, the repository and the build,
and the alternative rejected.
2. [implementation-plan.md](implementation-plan.md) — the milestones and
what each one lands.
3. [risks-and-open-questions.md](risks-and-open-questions.md) — what is not
proven, and what was accepted.
4. [IMPLEMENTATION-STATUS.md](IMPLEMENTATION-STATUS.md) — what shipped, and
every departure from the upstream template.

## Milestones

| Milestone | What it lands | Task |
|---|---|---|
| WP0 — the spec | the repository, its intent, CI, tooling and spec index; this doc set | WP-1 |
| WP1 — the site on Workers | the template in `apps/web`, built by OpenNext into one Worker, its sample mode; `tests/web` | WP-2 |
| WP2 — a baseline | the console card, the build document, the context pack and the baseline's tests | WP-3 |
88 changes: 88 additions & 0 deletions specs/epics/cms-wordpress/design.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
# cms-wordpress — design

## The template

[9d8dev/next-wp](https://github.com/9d8dev/next-wp) (Next.js 16.3 App
Router, React 19, Tailwind CSS 4, shadcn/ui), the template Vercel lists as
its Next.js Starter for WordPress Headless CMS, is a front end for a
WordPress site: one typed client (`lib/wordpress.ts`) reads the REST API
(`/wp-json/wp/v2`) — posts with their embedded author, featured image and
terms, pages, categories, tags and users — and the App Router renders the
home page, `/posts` (search, author/category/tag filters, pagination),
`/posts/[slug]`, `/pages`, `/pages/[slug]`, the category, tag and author
lists, a sitemap, Open Graph images (`/api/og`, next/og) and
`/api/revalidate`, the webhook its WordPress plugin (`next-revalidate`)
calls on a change to invalidate cache tags. The fetches carry tags and a
one-hour revalidate; posts and pages are pre-rendered from
`generateStaticParams`. Its options are `site.config.ts` and
`menu.config.ts`; it ships vitest tests for the client, the webhook and its
helpers, and a Railway template (WordPress, MySQL and the site in Docker).

## How it maps to Cloudflare

| Vercel | Here | Why |
|---|---|---|
| Next.js hosting | One Worker built by `@opennextjs/cloudflare` (`output: 'standalone'`) with the static-assets incremental cache | The OpenNext path every Next.js baseline here shares |
| ISR: `generateStaticParams`, the data cache with tags and `revalidate: 3600`, `revalidateTag` from the webhook | Every page that reads WordPress is `force-dynamic` and fetches `no-store`; the webhook is kept, secret-checked, with nothing to clear | The static-assets cache is read-only: a page or fetch cached at build could never refresh, and every write logs an error. The R2 cache plus a tag cache would make ISR work — a bucket, a Durable Object or D1 and their wiring, for a site that renders in tens of milliseconds |
| `runtime = "edge"` on `/api/og` | The Node.js runtime under `nodejs_compat` | OpenNext runs no edge functions; next/og renders the same PNG there |
| Image Optimization | Off: `images.unoptimized` | The Worker has no optimiser; media is served from WordPress as uploaded |
| `@vercel/analytics` | The Cloudflare Web Analytics beacon, rendered only with a token | The Cloudflare equivalent; nothing to install |
| `WORDPRESS_URL` in the project's env | Inlined by `next build` from an optional Orun secret per environment | The client reads it at module load; each environment builds anyway |
| `WORDPRESS_WEBHOOK_SECRET` | A Worker secret | Read at request time by the webhook only |
| `site_domain: https://next-wp.com` | `NEXT_PUBLIC_SITE_URL` per environment | Absolute links need the origin each environment is served on |

## Unconnected: the sample site

A bootstrap cannot know its owner's WordPress, so the site must deploy and
pass its smoke without one — cms-sanity's idea. Upstream, an unset
`WORDPRESS_URL` makes every list empty; here the client answers every
request it would send from `lib/sample.ts` instead: three posts, a page, two
categories, three tags and an author, in the REST API's own shapes
(`lib/wordpress.d.ts`), with the API's own filtering (author, categories,
tags, search, slug, pagination) and its 404 for an id it does not have. The
pages render them unchanged, and the layout shows a notice — "no WordPress
site is connected yet" — linking the first post, which says how to connect
one. The sample sits behind the fetch layer, so no page knows the
difference, and once a URL is set nothing in the file is read.

## The repository

cms-sanity's shape: `apps/web` (type `cloudflare-workers-assets-turbo`,
lane `isolated`, the WordPress URL an `optionalSecretEnv`) and `tests/web`
(type `turbo-package`, a vitest suite run on the `dev` rung, holding the
template's own tests unchanged plus the sample mode and the name seam). No
infrastructure: WordPress is the owner's own site. The site's name is one
seam, `SITE_NAME` in `site.config.ts`, which the nav, footer, mobile menu
and the root title read (upstream's title, "WordPress & Next.js Starter by
9d8", now reads it too). The home page's credit to next-wp is content and
stays.

## The build

`next build` (Turbopack), `opennextjs-cloudflare build --skipBuild`, then
`populateCache local` (the pre-rendered home page and 404 into the assets).
`repo-blueprint.yaml` is cms-sanity's: one landing (`01-product`) places,
brands and lands the whole tree, one convergence builds and deploys stage
and prod side by side, and `02-docs` records what went live, probing `/`,
`/posts` (sample or connected) and the webhook. The smoke checks `/posts`
renders its count and `/api/revalidate` refuses a webhook without the
secret.

## Out of scope

- The Railway template (`wordpress/`, `Dockerfile`, `railway.json`) and the
plugin's PHP source (`plugin/`): WordPress runs wherever its owner runs it;
the plugin is upstream's release download.
- Draft previews and authenticated REST reads: upstream has none.

## The alternative rejected

**ISR on the R2 incremental cache with a D1 or Durable Object tag cache**,
so the webhook's `revalidateTag` would refresh cached pages as it does on
Vercel. It is the faithful port of the caching, and it costs a bucket and a
tag store per environment, their Terraform roots and wiring, and a cache that
can serve a stale page when a webhook is missed — for pages that render in
tens of milliseconds against a REST API. Rendering per request is always
fresh, needs nothing provisioned, and leaves the webhook a no-op that the
plugin can keep calling; the R2 cache stays the upgrade if a site's
WordPress is too slow to call on every visit.
31 changes: 31 additions & 0 deletions specs/epics/cms-wordpress/epic.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
# The epic's declaration. metadata.name equals the directory name; metadata.key
# is the task-key prefix this epic reserves (WP → WP-1, WP-2, …). Owner, target
# date and health are the platform's — never written here.
apiVersion: orun.io/v1
kind: Epic
metadata:
name: cms-wordpress
key: WP
spec:
title: "Vercel's Next.js Starter for WordPress Headless CMS on Cloudflare Workers"
summary: "9d8's next-wp — a Next.js front end for a WordPress site used as a headless CMS: posts, pages, categories, tags and authors from its REST API, with search, filters, pagination, a sitemap, Open Graph images and a revalidation webhook — runs on Cloudflare Workers + Static Assets through @opennextjs/cloudflare, serves bundled sample content until a WordPress is connected, and becomes an Orun baseline that takes a new site from nothing to live on stage and prod in one landing."
state: started
milestones:
- name: "WP0 — the spec"
exitCriteria:
- "the repository is born with its intent, CI, tooling and spec index, and this doc set and the task contracts are on main"
tasks: [WP-1]
- name: "WP1 — the site on Workers"
exitCriteria:
- "apps/web is the upstream template, every page that reads WordPress rendered per request, built by OpenNext into one Worker with Static Assets"
- "with no WORDPRESS_URL the site renders bundled sample content in the REST API's shapes, under a notice, and never fails"
- "`pnpm typecheck`, `pnpm lint`, `pnpm test` (the template's own tests among them) and `pnpm build` are green"
- "`wrangler dev` serves every route — posts, filters, search, a post, pages, the term and author lists, the sitemap, the Open Graph image — and the webhook refuses a request without its secret"
- "the README says how to run, test, preview and deploy it, how to connect WordPress, and how every Vercel piece maps to Cloudflare"
tasks: [WP-2]
- name: "WP2 — a baseline"
exitCriteria:
- "blueprint.yaml (the console card) and repo-blueprint.yaml (the build) take a new site from nothing to live on stage and prod in one landing, then record it"
- "a site built from it carries the site only, renamed throughout to its own name, repository and Worker, with the template's credit intact"
- "Baseline CI is green: contract tests, generated component docs, the blueprint read by the pinned orun, the leak gate, the offline bootstrap and the end-to-end tier"
tasks: [WP-3]
39 changes: 39 additions & 0 deletions specs/epics/cms-wordpress/implementation-plan.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
# cms-wordpress — implementation plan

Three milestones, each one reviewed pull request (WP0 is the repository's
first commit), each green before it merges.

## WP0 — the spec (WP-1)

The repository is born: `intent.yaml` with the placeholder workspace
`ws_CHANGE_ME`, `ci.yml` (byte for byte turso-starter's, which plans nothing
until the workspace is set), the shared TypeScript and ESLint configuration,
the spec index, this doc set and the task contracts.

## WP1 — the site on Workers (WP-2)

- The template's `app/`, `components/`, `lib/`, `public/` and configuration
in `apps/web`; its dependencies, with `@opennextjs/cloudflare` and
`wrangler`, without `@vercel/analytics`; Next 16.3.8.
- `next.config.ts`: `output: 'standalone'`, the workspace root for the
trace, images unoptimised, `WORDPRESS_URL` inlined. `open-next.config.ts`
with the static-assets incremental cache; `wrangler.jsonc`.
- Every page that reads WordPress `force-dynamic`, the client's fetches
`no-store`, `/api/og` on the Node.js runtime.
- The sample site (`lib/sample.ts`) behind the client, and the notice.
- `SITE_NAME` in `site.config.ts`, `site_domain` from
`NEXT_PUBLIC_SITE_URL`; the Cloudflare Web Analytics beacon.
- `component.yaml`: the deploy contract (the origin per environment, the
optional `WORDPRESS_URL`) and its smoke. `tests/web`: the template's own
tests, the sample mode, the name and the origin.
- The README's "How it maps to Vercel" and "Connecting WordPress".

## WP2 — a baseline (WP-3)

cms-sanity's machinery, renamed: `blueprint.yaml`, `repo-blueprint.yaml`,
`.baseline/` (identity, the product's README with "Connecting WordPress" and
"Deploy by hand", task contracts), `tooling/rebrand`, `tooling/bootstrap`,
`hooks/render-deployment-docs.sh` (probing `/`, `/posts` and the webhook),
`docs/phases/`, the context pack, `testing/` (the leak and placement gates
on this tree's files; the e2e tier reading every route the site promises,
unconnected) and `baseline.yml` / `tag.yml`.
13 changes: 13 additions & 0 deletions specs/epics/cms-wordpress/risks-and-open-questions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
# cms-wordpress — risks and open questions

| ID | Risk | State | Notes |
|---|---|---|---|
| WP-A | `baseline-v1` is not yet proven live | OPEN | Proven offline in Baseline CI: the offline bootstrap with the blueprint's own hooks, the stage lane's own steps in a staged job tree, the site served by `wrangler dev` and smoke-tested with the component's own command, unconnected. A console bootstrap closes it |
| WP-B | Worker size | WATCH | About 10 MiB raw and 2.8 MiB gzipped, against Workers Free's 3 MiB — most of it next/og's WebAssembly (resvg, yoga) for `/api/og`. A dependency that grows it past 3 MiB needs Workers Paid (or `/api/og` dropped). Every pull request's dry run prints it |
| WP-C | Connected to a real WordPress | OPEN | The client is the template's, tested against a stubbed REST API by the template's own tests, and the sample mode answers in the API's shapes; no build has yet read a live WordPress. Connecting one (the README's steps) closes it |
| WP-D | Every page reads WordPress on every request | ACCEPTED | No ISR (design, "The alternative rejected"). Each page view costs a few REST calls to WordPress — a slow or rate-limited WordPress makes a slow site. The R2 incremental cache plus a tag cache is the upgrade, and the webhook already calls `revalidateTag` |
| WP-E | `/api/revalidate` clears nothing | ACCEPTED | Kept for the plugin, secret-checked as upstream; there is no cache for it to clear |
| WP-F | Images are not optimised | ACCEPTED | `images.unoptimized`; WordPress already serves sized variants. Cloudflare Images through OpenNext's `IMAGES` binding is the upgrade |
| WP-G | `/api/og` on the Node.js runtime instead of the edge | ACCEPTED | OpenNext runs no edge functions; the PNG is the same, checked by the e2e tier |
| WP-H | A wrong `WORDPRESS_URL` is not caught at build | ACCEPTED | The client degrades as upstream: lists render empty, a post 404s. The deployment record and the README say to probe `/posts` after connecting |
| WP-I | stack-tectonic 0.19.0, not 0.20.0 | ACCEPTED | 0.20.0's lane-shared install links each job's `node_modules` out of its tree, which Turbopack refuses |
15 changes: 15 additions & 0 deletions tasks/WP-1.TaskContract.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
apiVersion: orun.io/v1
kind: TaskContract
metadata:
name: WP-1
title: "The spec"
spec:
goal: The cms-wordpress repository is born with its intent, CI, tooling and spec index, and the cms-wordpress epic — declaration, doc set and task contracts — is on main
affects:
- specs/epics/cms-wordpress
- specs/epics/README.md
- tasks
doneWhen:
- epic.yaml, README, design, implementation plan, risks and status are on main
- the three task contracts exist
gates: []
18 changes: 18 additions & 0 deletions tasks/WP-2.TaskContract.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
apiVersion: orun.io/v1
kind: TaskContract
metadata:
name: WP-2
title: "The site on Workers"
spec:
goal: Vercel's Next.js Starter for WordPress Headless CMS runs on Cloudflare Workers + Static Assets through OpenNext, serving sample content until a WordPress is connected, with its tests and a README that says how it maps to Vercel
affects:
- apps/web
- tests/web
- pnpm-lock.yaml
- pnpm-workspace.yaml
- README.md
- .gitignore
doneWhen:
- pnpm typecheck, lint, test and build are green
- wrangler dev serves every route the template has, unconnected, and the webhook answers 401 without its secret
gates: []
29 changes: 29 additions & 0 deletions tasks/WP-3.TaskContract.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
apiVersion: orun.io/v1
kind: TaskContract
metadata:
name: WP-3
title: "cms-wordpress becomes an Orun baseline"
spec:
goal: blueprint.yaml and repo-blueprint.yaml take a new headless WordPress site from nothing to live on stage and prod in one landing, held by Baseline CI
affects:
- blueprint.yaml
- repo-blueprint.yaml
- BOOTSTRAP.md
- .baseline
- .github/workflows/baseline.yml
- .github/workflows/tag.yml
- ai/context
- docs/phases
- hooks
- testing
- tooling/rebrand
- tooling/bootstrap
- tooling/catalog
- apps/web/docs
- tests/web/docs
- specs/epics/cms-wordpress
- README.md
doneWhen:
- every Baseline CI tier is green
- a site placed from it carries the site only, branded, with the template's credit intact
gates: []
Loading