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-drupal/`](./cms-drupal/) | **DR** | In progress (DR0) | Vercel's Drupal Marketing Site (next-drupal's example-marketing) on Cloudflare Workers, every page cached in R2 and re-rendered on Drupal's call, drafts in preview — and an Orun baseline that instantiates it in one landing, live with sample content before a Drupal is connected (DR2) |

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

| Milestone | State | Landed |
|---|---|---|
| DR0 — the spec | ✅ | DR-1 |
| DR1 — the site on Workers | planned | DR-2 |
| DR2 — a baseline | planned | DR-3 |

## Departures from the upstream template

Recorded as they land, from DR1 on.
41 changes: 41 additions & 0 deletions specs/epics/cms-drupal/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# cms-drupal — Vercel's Drupal Marketing Site on Cloudflare Workers

**Vercel's Drupal Marketing Site is next-drupal's `example-marketing`: a
Next.js Pages Router site whose pages are built in Drupal — landing pages from
paragraphs, a blog, a properties listing with a filterable view, menus,
English and Spanish — pre-rendered, refreshed when Drupal says a page
changed, and previewed from Drupal before publishing. The port keeps that
whole model and moves it onto Cloudflare: one Worker, every page in R2, the
re-render going through the Worker's own service binding. Drupal's router,
on-demand revalidation and preview were the unproven part; a spike proved
all three on the adapter before anything was built on it. A product built
from it deploys with sample content in the template's content model before
its owner connects a Drupal, and renders theirs once they set its URL.**

| | |
|---|---|
| Status | In progress — DR0 on main |
| Upstream | [chapter-three/next-drupal](https://github.com/chapter-three/next-drupal) `examples/example-marketing` (MIT), at `80a89f1` (2026-10-23) — the template [Vercel lists](https://vercel.com/templates/next.js/drupal-nextjs-marketing-site) |
| Reference | [cms-sanity](https://github.com/sourceplane/cms-sanity) (the CMS-frontend baseline shape, an unconnected state), [sfcc-commerce](https://github.com/sourceplane/sfcc-commerce) (the R2 cache root, the wiring, Worker secrets and a connected e2e against a stand-in) |
| Key | `DR` |

## Read in this order

1. [design.md](design.md) — the site, how each Vercel piece maps to
Cloudflare, the cache and the spike that proved it, build-time settings,
the sample Drupal, revalidation and preview, the tests, and the
alternatives 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 upstream.

## Milestones

| Milestone | What it lands | Task |
|---|---|---|
| DR0 — the spec | this doc set and the three task contracts | DR-1 |
| DR1 — the site on Workers | `apps/web`, the R2 root, `tests/web` | DR-2 |
| DR2 — a baseline | the card, the build document, the rename, the tiers | DR-3 |
151 changes: 151 additions & 0 deletions specs/epics/cms-drupal/design.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,151 @@
# cms-drupal — design

## 1. The site

Vercel's Drupal Marketing Site (chapter-three/next-drupal
`examples/example-marketing` at `80a89f1`): a Next.js Pages Router app read
from a headless Drupal with next-drupal. One catch-all page,
`pages/[[...slug]].tsx`, resolves every path through Drupal's decoupled
router (`/router/translate-path`) and renders the node it names —
`node--landing_page` (a list of paragraphs: hero, feature, cards, FAQ, and a
`view` paragraph that embeds the `properties--listing` view), `node--page`
(formatted text, inline images turned into `next/image`) or `node--article`.
`getStaticPaths` lists every node's path in both languages (en, es) and
`fallback: "blocking"` renders a path Drupal adds later; `getStaticProps`
reads the node with its includes (`lib/get-params.ts`), the menus
(`jsonapi_menu_items`) and, for a view paragraph, the view's first page
(`jsonapi_views`). `/blog` is `/blog/page/0` (two articles a page). The
properties view is re-queried in the browser with TanStack Query against the
view's own `self` link, with the filters as `views-filter[...]`.
`/api/revalidate?path&secret` calls `res.revalidate(path)`;
`/api/preview` is next-drupal's `preview()` — it asks Drupal to validate the
link (`/next/draft-url`, where Drupal's `next` module holds the secret),
then sets Next's preview cookies and redirects; a page in preview reads the
draft revision (`resourceVersion`) with the OAuth consumer's token.

## 2. Vercel → Cloudflare

| Vercel | Here |
|---|---|
| Next.js hosting | `@opennextjs/cloudflare` 1.20.11: one Worker (`.open-next/worker.js`) + Static Assets |
| ISR cache | R2 (`NEXT_INC_CACHE_R2_BUCKET`), a bucket per environment from `infra/terraform/cloudflare-r2` |
| `res.revalidate` | the same; the adapter routes its self-request through `WORKER_SELF_REFERENCE` |
| Preview mode | unchanged |
| Image Optimization | off — Drupal's files served as Drupal sends them |
| Env vars | `DRUPAL_BASE_URL` and `DRUPAL_SITE_ID` as optional build secrets, inlined; the OAuth consumer and `DRUPAL_REVALIDATE_SECRET` as Worker secrets the deploy sets |
| `NEXT_PUBLIC_BASE_URL` | `NEXT_PUBLIC_SITE_URL`: the environment's `SITE_URL`, else its workers.dev URL |

The scaffolding is cms-sanity's CMS-frontend shape with sfcc-commerce's
cache root: the CMS baselines (cms-sanity, cms-contentful, cms-wordpress)
render per request or statically and have no R2 cache; sfcc-commerce carries
the settled R2 root, the wiring render, the Worker-secret hand-over and a
connected e2e against a stand-in, which this site needs as they are.

## 3. The cache

`open-next.config.ts`: the R2 incremental cache and the in-isolate memory
queue. No tag cache and no Durable Objects: the Pages Router revalidates by
path, the template sets no time-based `revalidate`, and nothing reads a tag.
Entries are keyed by build ID, so a deploy starts from fresh pages. The
Worker binds itself (`services: WORKER_SELF_REFERENCE` → its own name, per
environment) for `res.revalidate` and the queue.

## 4. The router, ISR and preview on Workers — the spike

The template's backend is gone (cms.next-drupal.org is an Umami demo without
the marketing content model), so the spike ran the whole example — upgraded to
Next 16.3.8, React 19 and next-drupal 2.0.1 — on OpenNext 1.20.11 with the R2
cache under `wrangler dev`, against a stand-in Drupal answering the
decoupled router, JSON:API, the menus, OAuth and `/next/draft-url`
(`~/orunbase/spikes/cms-drupal.md` holds the log):

- **router**: `/` and `/about` served from the cache; unknown paths 404 in
both languages (`translate-path` 404 → `notFound`); `/es/about` asked
Drupal for `/es/about` (the locale prefix kept), and after the stand-in
learned that alias a revalidation turned the cached 404 into the page.
- **ISR**: an edit in Drupal stayed cached; `/api/revalidate` with a wrong
secret 401, with the right one `{}`; the next visit had the edit, still a
cache hit. It works because @opennextjs/cloudflare's `patch-res-revalidate`
rewrites Next's `fetch(https://${host}${path}, HEAD)` into
`WORKER_SELF_REFERENCE.fetch` — the binding is required.
- **preview**: a wrong secret 401 (Drupal's answer); the right one 307 with
both cookies; the page with them was the draft revision, `private,
no-store`; without them the published page; exit-preview expired both.
- the Worker 1.2 MiB gzipped; no workerd errors (next-drupal's module-scope
`node-cache` timer is created inside the first request).

It also found what the port had to change (§7, IMPLEMENTATION-STATUS).

## 5. Build-time settings

`next.config.ts` `env` inlines `NEXT_PUBLIC_DRUPAL_BASE_URL` (from the
`DRUPAL_BASE_URL` secret, trailing slashes dropped), `DRUPAL_SITE_ID`,
`DRUPAL_FRONT_PAGE` and `NEXT_PUBLIC_BASE_URL` (from `NEXT_PUBLIC_SITE_URL`).
The build pre-renders every page Drupal lists, so it reads Drupal; at request
time a Worker's `process.env` holds only its vars and secrets, which is
where the OAuth consumer and the revalidation secret are read.

## 6. Before a Drupal, and after

With no `DRUPAL_BASE_URL` the client is constructed with a never-contacted
origin and next-drupal's own `fetcher` option set to
`lib/sample-drupal.mjs`: every request the pages make — the router, nodes
with includes, collections with sorting and paging, the menus, the view with
its filters — is answered in the Worker in the shapes those Drupal modules
return, from the template's content model with sample words (the headings,
the author and the dates the template's Cypress tests look for) and four
photos (`public/sample`, Payload's, MIT). The same code renders the same
pages; a layout notice says no Drupal is connected; `/api/preview` answers
401; the browser's view search reaches the sample at `/api/sample-drupal`.
The module is plain JavaScript so the stand-in Drupal the tests run serves
exactly it over HTTP. With a URL set, the sample route answers 404 and the
view links point at Drupal.

## 7. Revalidation and preview

`/api/revalidate` is upstream's, with one change: it refuses every call
while `DRUPAL_REVALIDATE_SECRET` is unset. Upstream compared
`secret !== process.env.DRUPAL_REVALIDATE_SECRET`, so with no secret set a
call without one passed and anyone could re-render any page. Drupal's front
page path (`/home`) is revalidated as `/`. Preview is next-drupal's, unchanged;
the OAuth consumer is given to the client only when both its id and secret
are set. The multi-site filter (`field_site`) is applied only when
`DRUPAL_SITE_ID` is set, so a Drupal without the template's site field works.

## 8. Tests

`tests/web` (vitest): the sample Drupal read through next-drupal's own
client — the front page's paragraphs with their media, the Spanish
translation, an unknown path, the articles' order and paging, every static
path in both languages, the view and its filters, the menus as serialisable
data; a connected Drupal over HTTP (`fake-drupal.mjs` on a free port) — read
over the network, a draft only in preview with a token, the preview secret
validated by Drupal, a wrong OAuth client refused; the two routes Drupal
calls; the name seam and the multi-site filter. The e2e tier
(`testing/e2e.test.sh`) builds the product in the stage lane's staged tree,
serves it as born and reads every route through `testing/lib/e2e-visit.py`,
then builds it again connected to the stand-in and proves the cache, the
revalidation and preview end to end.

## 9. The rename

`SITE_NAME` in `apps/web/site.ts` (the template's navbar brand,
"Marketing") is the one name seam; the slug `cms-drupal` appears only in its
identity forms (the Worker, the buckets, the secret project, the
repository link), and its Pascal form nowhere.

## 10. Alternatives rejected

- **Static-assets cache with `force-dynamic` pages** (cms-wordpress's shape):
drops the template's ISR and makes Drupal's revalidation meaningless.
- **Durable Object tag cache and queue** (the commerce shape): nothing in a
Pages Router site reads a tag, and no page revalidates on a timer.
- **Rendering the self-request in-process instead of the service binding**:
the adapter already routes `res.revalidate` through `WORKER_SELF_REFERENCE`;
a binding to the Worker's own name is configuration, not code.
- **A sample-content branch in every page**: the fetcher seam keeps the
template's pages untouched and makes the sample answer exactly what a Drupal
answers.
- **Running a real Drupal for the sample or the tests**: needs PHP and a
database (a container), which the platform has no composition for; the
stand-in is deterministic and offline.
30 changes: 30 additions & 0 deletions specs/epics/cms-drupal/epic.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
# The epic's declaration. metadata.name equals the directory name; metadata.key
# is the task-key prefix this epic reserves (DR → DR-1, DR-2, …). Owner, target
# date and health are the platform's — never written here.
apiVersion: orun.io/v1
kind: Epic
metadata:
name: cms-drupal
key: DR
spec:
title: "Vercel's Drupal Marketing Site on Cloudflare Workers"
summary: "Vercel's Drupal Marketing Site template — next-drupal's example-marketing: a Next.js Pages Router site read from a headless Drupal over JSON:API, landing pages from paragraphs, a blog, a properties view, menus, English and Spanish, Drupal's on-demand revalidation and preview — runs as one Cloudflare Worker with Static Assets, every page cached in R2 and re-rendered through the Worker's own service binding, live with sample content before a Drupal 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: "DR0 — 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: [DR-1]
- name: "DR1 — the site on Workers"
exitCriteria:
- "a spike proves next-drupal's router, on-demand revalidation and preview on OpenNext with the R2 cache, against a stand-in Drupal"
- "apps/web is the template on Next 16.3.8 built by OpenNext into one Worker with Static Assets, the R2 incremental cache and the self-reference binding"
- "typecheck, lint, tests/web and build are green with no Drupal"
- "with no Drupal every page renders the sample Drupal under the notice, never a 500; connected, wrangler dev serves Drupal's pages, reuses the cache, revalidates on Drupal's call and opens a draft in preview"
tasks: [DR-2]
- name: "DR2 — 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 product only, renamed throughout to its own name, repository, Worker and buckets, with the template's licence intact"
- "Baseline CI is green: contract tests, the wiring path, generated component docs, the blueprint read by the pinned orun, the leak gate, the offline bootstrap and the end-to-end tier — the stage lane's steps in a staged tree, served as born, then connected to a stand-in Drupal and browsed"
tasks: [DR-3]
14 changes: 14 additions & 0 deletions specs/epics/cms-drupal/implementation-plan.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
# cms-drupal — implementation plan

| Milestone | Lands | Done when |
|---|---|---|
| DR0 — the spec | the repository born (intent, CI, tooling, spec index), this doc set, DR-1…DR-3 | on main |
| DR1 — the site on Workers | `apps/web` (upstream at `80a89f1` plus the departures in IMPLEMENTATION-STATUS), `infra/terraform/cloudflare-r2`, `tests/web` | typecheck, lint, tests/web and build green with no Drupal; served unconnected and connected under `wrangler dev` |
| DR2 — a baseline | `blueprint.yaml`, `repo-blueprint.yaml`, `.baseline/`, the rename engine and bootstrap helpers, the record renderer, the context pack, `testing/` with the stand-in Drupal, `baseline.yml`, `tag.yml` | Baseline CI green; `baseline-v1` tagged |

Order inside DR1: the spike (the template on Next 16.3.8 and next-drupal 2.0.1,
the R2 cache and the self-reference binding, a stand-in Drupal; the router,
on-demand revalidation and preview under `wrangler dev`; the Worker's size);
the build-time settings; the sample Drupal as next-drupal's fetcher; the
revalidation route's secret; the Next 16 API moves; the workspace; the tests
with the stand-in over HTTP.
15 changes: 15 additions & 0 deletions specs/epics/cms-drupal/risks-and-open-questions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
# cms-drupal — risks and open questions

| ID | Risk | State | Notes |
|---|---|---|---|
| DR-A | No live bootstrap yet (tokens, a real R2 apply, a real deploy with the R2 and self-reference bindings and the Worker secrets, the probes, a real Drupal) | OPEN | Closed by one bootstrap from a tag, a Drupal with the template's model connected, a node saved, a draft previewed |
| DR-B | The template's content model is the owner's to provide: unknown paragraph types render nothing, `/properties` needs the `properties` view | OPEN — the owner's | README, "Connecting Drupal"; next-drupal ships the model as Drupal configuration (`drupal/`) |
| DR-C | The properties search is a browser request to Drupal's view link: the Drupal must allow the site's origin (CORS) | WATCH | As upstream; with no Drupal it is the site's own `/api/sample-drupal` |
| DR-D | Next pinned to 16.3.8 (the adapter refuses 15.5 and fails on 16.4.x); next-drupal 2.0.1's own `next ^14 \|\| ^15` dependency overridden to the app's | ACCEPTED | `pnpm-workspace.yaml` `overrides`; one Next in the bundle |
| DR-E | Images unoptimized | ACCEPTED | Workers has no Next.js image optimizer; Drupal's image styles are the place to size images |
| DR-F | A deploy starts from fresh pages: the cache is keyed by build, so the first visit to each page after a deploy reads Drupal | ACCEPTED | As on Vercel, where a deploy is a new build |
| DR-G | The stand-in Drupal answers the shapes next-drupal reads, for the sample content; it is not a Drupal | ACCEPTED | DR-A closes it |
| DR-H | The site-name seam: the navbar, titles and footer read `SITE_NAME`; the leak and placement gates fail on the name spelled anywhere else | ACCEPTED, gated | `testing/leak.test.sh`, `testing/placement.test.sh` |
| DR-I | The sample content is written in the template's content model (field names from next-drupal's Drupal configuration, headings, author and dates from its Cypress tests), not exported from a running Drupal: the template's demo backend is gone and its Drupal ships no content | ACCEPTED | Every shape is read back through next-drupal's own deserializer in `tests/web` |
| DR-J | next-drupal creates a `node-cache` (a timer) when it loads; on workerd that happens during the first request, not at global scope | ACCEPTED | Proven in the spike and the e2e; no errors in the Worker's log |
| DR-M | Preview's cookies are `SameSite=None; Secure` for Drupal's iframe preview: proven over HTTP on wrangler dev, not inside Drupal's iframe | WATCH | A preview from a real Drupal |
13 changes: 13 additions & 0 deletions tasks/DR-1.TaskContract.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
apiVersion: orun.io/v1
kind: TaskContract
metadata:
name: DR-1
title: "The cms-drupal epic doc set"
spec:
goal: The epic's README, design, plan, risks and status, and the three task contracts, are on main
affects:
- specs/epics/cms-drupal
- tasks
doneWhen:
- the doc set and DR-1, DR-2 and DR-3 are merged
gates: []
19 changes: 19 additions & 0 deletions tasks/DR-2.TaskContract.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
apiVersion: orun.io/v1
kind: TaskContract
metadata:
name: DR-2
title: "The site on Workers"
spec:
goal: Vercel's Drupal Marketing Site runs as one Cloudflare Worker with Static Assets, every page cached in R2 and re-rendered on Drupal's call through the Worker's own binding, Drupal's preview opening drafts, live with sample content before a Drupal is connected
affects:
- apps/web
- infra/terraform/cloudflare-r2
- tests/web
- pnpm-lock.yaml
- pnpm-workspace.yaml
- README.md
doneWhen:
- a spike proves next-drupal's router, on-demand revalidation and preview on OpenNext with the R2 cache
- pnpm typecheck, lint, test and build are green with no Drupal
- wrangler dev serves the sample site without a 500, and a connected one from cached pages revalidated through /api/revalidate, with a draft in preview
gates: []
23 changes: 23 additions & 0 deletions tasks/DR-3.TaskContract.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
apiVersion: orun.io/v1
kind: TaskContract
metadata:
name: DR-3
title: "cms-drupal becomes an Orun baseline"
spec:
goal: A new site goes from nothing to live on stage and prod in one landing, its own name throughout, with Baseline CI proving it offline
affects:
- blueprint.yaml
- repo-blueprint.yaml
- .baseline
- testing
- tooling
- hooks
- docs/phases
- ai/context
- .github/workflows
- BOOTSTRAP.md
- README.md
doneWhen:
- Baseline CI is green on main
- baseline-v1 is tagged
gates: []
Loading