Spike evaluation: Next.js (static export) + Pagefind + Decap CMS

Second SSG iteration through SPECIFICATION.md's open questions, built to the same bar as the Astro spike (spikes/astro/content-pages/evaluation.md) and reading the same shared /data + /schema, so the two are directly comparable rather than independently scoped. Pagefind was reused as-is rather than re-running the 5-engine search comparison a second time — that comparison doesn't change per SSG, see spikes/astro/content-pages/search-engines.md.

What this spike proves works

• Static export genuinely produces plain HTML, everything included. output: 'export' in next.config.ts + trailingSlash: true produces out/entries/<id>/index.html etc, each containing the entry's full rendered content in the raw document (verified by grepping the built file directly, not by trusting the config) — no client JS is required to see any page's content. React hydration payload scripts are also present (for fast client-side navigation once JS loads), but they're additive, not a requirement for the visible content to exist.
• The same data model, read a different way. Next.js has no equivalent of Astro's content collections — src/lib/entries.ts reads /data/entries/*.yaml directly with fs/yaml at build time (process.cwd()-relative, not import.meta.url-relative — see friction below), with a hand-written TypeScript interface mirroring /schema/hdc-entry.schema.json instead of Astro's Zod schema. Same hand-sync tradeoff as Astro, different mechanism.
• Filters, Pagefind search, and the "Sangya" test all carry over unchanged. Same 8 facets, same Go/Reset behaviour, same FilterForm/DOM-driven filter-matching split as the Astro spike (reimplemented, since there's no code-sharing between two independent spike directories — see src/lib/domFilters.ts). Confirmed by directly querying the built Pagefind index in Node: searching "Sangya" returns cohort-discovery-service, via contactTeamPerson — which at the time of this test appeared on no visible page text, identical to the Astro spike. (Since changed: SPECIFICATION.md's later "Render the whole record" requirement means every field, contactTeamPerson included, is now visible on the entry page; the Sangya test still passes as a full-record-coverage check.)
• Client components don't need to embed the entry dataset. The interactive filter/search logic (FilterInteractivity.tsx) is a Client Component, but it reads the DOM (data-* attributes already present in the server-rendered HTML) rather than receiving entries as a prop — avoiding shipping the full dataset a second time into the client JS bundle. This mirrors the Astro spike's architecture deliberately; a naive Next.js implementation (pass entries as a prop to a 'use client' list component) would have embedded the entire corpus into the page's JS payload, which static export doesn't stop you from doing by default.
• CMS wiring is nearly copy-paste from the Astro spike's config, confirming SPECIFICATION.md's "Progress so far" expectation. public/admin/config.yml needed only path changes (spikes/nextjs/... instead of spikes/astro/...) — same entries folder collection, same generic pages folder collection over content-pages/, same settings singleton for the banner. Verified via decap-server's proxy API directly: entriesByFolder returned all 13 entries and both markdown pages; getEntry returned the banner settings file.
• "Drop a markdown file, get a page" holds here too. Dropped a throwaway test-drop.md into content-pages/ with zero code changes, ran npm run build, confirmed a real /test-drop/ page with the dropped heading and markdown-body styling, then removed it — same result as the Astro spike, via a different mechanism (marked, since Next.js has no native markdown rendering — see friction below).
• The shared banner singleton (/data/site-settings.yaml) renders identically here, confirming the CMS's "turn on/off and edit text + link for a banner" requirement (SPECIFICATION.md, "CMS gui like options") is satisfiable the same way regardless of SSG — the file and its CMS config are the shared part; each SSG only needs its own few lines to read and conditionally render it.

Friction encountered (and fixed)

• import.meta.url-relative file reads break under Next.js's bundler, same mistake as Astro's, different cause. First instinct was to read /data/entries relative to the calling module's location. Used process.cwd()-relative paths instead (path.join(process.cwd(), '..', '..', 'data', 'entries')) — process.cwd() is documented and stable as the project root during both next dev and next build, unlike a bundled module's own path. Worth calling out because this is the second SSG in a row where the naive "resolve relative to this file" approach breaks, for a different underlying reason each time (Astro: Vite relocates the compiled chunk; Next.js: no relocation issue, but there's no import.meta.url-based convention that's safe to rely on across dev/build/export). Lesson: for any future SSG, assume file-system reads at build time need the SSG's own documented "project root" convention, not a path computed from the current module.
• next.config.ts's AGENTS.md warning was justified. This Next.js version (16.2.10) ships an AGENTS.md/CLAUDE.md at the project root warning that APIs may have changed since training data and to check node_modules/next/dist/docs/ first. That check caught a real breaking change before it caused a bug: params in a dynamic route's page component is now Promise<{ id: string }>, not a plain object — confirmed by reading the vendored docs rather than assuming the older synchronous-params shape.
• The admin page can't fully opt out of the site's shared layout. Astro's Base.astro is just a component a page chooses to wrap itself in — the admin page simply didn't use it, giving Decap CMS a bare page with no site header. Next.js's App Router has exactly one root layout applied to every route by default; genuinely excluding it needs a route-group restructure (multiple independent root layouts, each with their own <html>/<body>) that wasn't done for this spike, so /admin/ inherits the site header, nav, and banner above the CMS UI. Functionally harmless — Decap mounts into its own #nc-root div regardless — but a real deployment would probably want the route-group version for a cleaner admin experience. Difference worth weighing: Astro's per-page layout opt-in is more convenient here than Next's default-everywhere root layout.
• No native markdown rendering. Astro's content collections render markdown via its own pipeline (render() + <Content />) with zero extra dependencies. Next.js has nothing built in — marked (already used once, then removed, in the Astro spike's own false-start — see its EVALUATION.md) is used here instead, via dangerouslySetInnerHTML. Not a workaround so much as the actual, expected way to do it in Next.js; still a genuine capability gap worth naming directly when comparing the two frameworks for a CMS-driven content site.
• Turbopack's dynamic import('/pagefind/pagefind.js') needed the same "don't statically resolve this" treatment as Vite. Vite's magic comment is /* @vite-ignore */; the webpack/Turbopack equivalent used here is /* webpackIgnore: true */. Without it, the bundler would try to resolve a path that doesn't exist until the postbuild Pagefind step runs (same failure mode hit in the Astro spike, different bundler, same fix shape).

Second layout, images, and environment rendering (SPECIFICATION.md, "Demonstrate alternative layouts and images" / "Individual environments/rendering")

• A second, fully independent layout required a route-group restructure — this is where the earlier-noted "one root layout" limitation had to actually be resolved, not just flagged. Next.js's App Router applies exactly one root layout.tsx to every route unless every top-level route belongs to a route group (a (name) folder that doesn't affect the URL). Confirmed via Next's own vendored docs (node_modules/next/dist/docs/.../route-groups.md): "If you use multiple root layouts without a top-level layout.js file, make sure your home route (/) is defined within one of the route groups." So the whole src/app/ tree was restructured into (site)/ (everything that existed before, unchanged in behaviour) and a new (articles)/ group with its own independent <html>/<body>, own stylesheet (article-theme.css, not an import of (site)/hdc-theme.css), own header/footer. Verified no site chrome (c-header/c-banner) leaks into /articles/outline/. This is Next's own sanctioned mechanism for the requirement, not a workaround — but it's a materially bigger lift than Astro's per-page layout opt-in (a folder restructure of the whole project vs one new component).
• No native markdown, confirmed a second time, now for content living outside the project entirely. /markdown/outline.md is read via plain fs (src/lib/articles.ts, process.cwd()-relative, same convention as entries.ts) and rendered with marked — same library, same dangerouslySetInnerHTML approach as content-pages/.
• Relative image paths in markdown need an explicit, deterministic rewrite — Next.js has nothing like Astro's automatic resolution. getArticleMarkdown() does a plain string replace (../images/ → ${basePath}/images/articles/) before handing the markdown to marked; the two PNGs are copied once into public/images/articles/ (a real file copy, not a symlink or a build step). Verified correct under both the default build (/images/articles/amr_portal.png) and a BASE_PATH=/nextjs build (/nextjs/images/articles/amr_portal.png) — confirms the rewrite is BASE_PATH-aware, unlike a hardcoded absolute path would be.
• Environment/rebadging flags need one extra hop compared to Astro: next.config.ts's env field. Plain process.env.SITE_ENV reads work fine in Node-side code (src/lib/articles.ts), but client/shared code needs the value baked in at build time via next.config.ts's env: { NEXT_PUBLIC_SITE_ENV: process.env.SITE_ENV || 'prod', ... }, then read back as process.env.NEXT_PUBLIC_SITE_ENV in src/lib/deploymentConfig.ts. Verified: SITE_ENV=preprod SITE_BRAND="Gateway Preview" npm run build shows the ribbon and rebadged wordmark/title in both (site) and (articles) layouts simultaneously — confirming the flag is genuinely global, not layout-specific, despite the two layouts sharing no other code.
• Decap's articles folder collection carried over with the same one-line-different shape as every other collection so far (folder: "markdown", not spikes/nextjs/..., since /markdown is shared like /data) — confirmed via decap-server's proxy API.

Search-index-driven listing and pagination (SPECIFICATION.md, "Search-index-driven listings with pagination")

• The homepage no longer server-renders any entry cards, and the replacement is more idiomatic React than what it replaced. The first pass rendered all 13 cards into the HTML with the dataset re-encoded into data-* attributes, then a Client Component mutated card.hidden — filtering React couldn't see, over a hand-synced parallel encoding. Now src/components/EntryResults.tsx fetches /search-data.json, holds the matched set/page/page-size in React state, and renders the current page of cards as ordinary JSX — so React escapes CMS-authored fields itself (no dangerouslySetInnerHTML, no |-delimited attribute encoding, no docFromCard). The old FilterInteractivity component and docFromCard are deleted.
• The corpus endpoint is a static route handler (src/app/(site)/search-data.json/route.ts) — Next's documented mechanism for emitting non-HTML files under output: 'export'. One version-specific catch, found the usual way (build error, then vendored docs): this Next version requires export const dynamic = 'force-static' on the handler even though the static-export guide's example omits it.
• Pagination + page size: previous/next with a page indicator, per-page selector 5/10/20/50/100 defaulting to 20, page resets to 1 on any query/filter/size change, Reset restores the default size. Pagination is pure derivation from state — page changes don't re-query Pagefind.
• The filter form stays a server-rendered component (shared markup with the other two spikes), so its inputs are still read via DOM listeners rather than converted to controlled components — a deliberate hybrid to keep the three spikes' filter forms directly comparable, noted here so it isn't mistaken for an oversight.
• The dev-mode fallback now substring-searches the corpus's full body field (which includes contactTeamPerson), so even pre-build dev search passes the "Sangya" test — it lacks Pagefind's ranking, and the mode label says so.
• Trade-off accepted knowingly: the listing is client-rendered, so it's empty without JavaScript (a <noscript> note says so). Entry pages remain fully static; Pagefind indexes those, so content search/SEO is unaffected.
• The dedicated /search/ page (PagefindUI's default UI) was removed along with its nav link — user testing found it non-functional, and once the homepage became the full, paginated search surface it was redundant; the homepage is now this site's single search surface, which is what the spec's "one search implementation per site" rule wanted all along. Same removal made in all three spikes.
• Verified: built out/index.html contains zero pre-rendered cards; out/search-data.json carries all 13 entries with body including never-displayed fields; a BASE_PATH=/nextjs build produces correctly-prefixed corpus URLs.

CMS future-requirements read-through (SPECIFICATION.md, "CMS gui like options")

No different from the Astro spike's read on these, since Decap CMS's actual capabilities don't change per SSG — only the config file changes, and barely:

• Non-developer content/wording edits: works — folder collections for entries and pages, both editable through the Decap UI.
• Banner on/off + text/link: works — the shared singleton file, same as Astro.
• Separate instances per Gateway environment: partially addressed this round — see "Second layout, images, and environment rendering" above for the build-time SITE_ENV/SITE_BRAND mechanism. Still not tested: genuinely separate Decap backend/branch config per environment (this round only covers front-end rendering flags, not CMS backend routing).
• Images/embedded video: images now tested (see above) — a real markdown-authored image reference, rewritten and rendered correctly. Video embedding was not part of this round's scope; still open.
• Unique page layouts per page: now tested — /articles/* proves a second, visually distinct layout is achievable, via route groups. Still not implemented: a layout frontmatter field letting a single folder collection choose between layouts per entry (this round used two separate folder collections/layouts rather than one collection with a layout switch).

What was actually run (for reproducibility)

npx create-next-app@latest nextjs --typescript --eslint --app --src-dir --import-alias "@/*" --turbopack --no-tailwind --yes
npm install yaml marked
npm install -D pagefind decap-server serve
npm run build          # next build && pagefind --site out
npm run preview         # serve out — verified via curl
npm run cms             # decap-server from repo root; queried its API directly for entries/pages/banner

Also run directly against the built output, not inferred from code:

• Grepped out/entries/<id>/index.html directly to confirm full entry content is present in the raw static HTML, not just in a hydration payload.
• Queried the built Pagefind index directly in Node (pagefind.search('Sangya') against the running serve server) — returned cohort-discovery-service.
• Dropped a throwaway markdown file into content-pages/, rebuilt, confirmed a matching styled page, removed it.

Post-spike code review (senior developer/architect pass)

An independent review of this spike's code, conducted after completion, from the perspective of a senior developer/architect deciding what carries into the next stage of development. The spike passed its functional bar; the findings below are the patterns that must not be copied verbatim into a product, plus the questions to answer before the first production sprint.

AI declaration: original implementation by Claude Sonnet 5 (claude-sonnet-5); this review by Claude Fable 5 (claude-fable-5), based on a full read of every source file in this spike plus the spec, report, and canonical schema for cross-checking. Every finding below was verified against the actual code, not inferred.

Code-level improvements

• Triple hand-maintained schema, with no build gate. /schema/hdc-entry.schema.json, the Entry interface in src/lib/entries.ts, and the enum options duplicated through public/admin/config.yml must all agree, and nothing enforces it — no ajv validation runs during next build, so a bad YAML edit saved through Decap ships silently. Generate the TS types (json-schema-to-typescript) and Decap fields from the schema, and validate entries as part of the build.
• The DOM-reading filter architecture was a deliberate tradeoff that needed re-examining, not inheriting. Avoiding double-shipping the dataset into the client bundle was real and correct for static export — but the result was filtering React couldn't see (card.hidden mutation), a hand-synced parallel structure between the data-* write side and the docFromCard() read side including an unescaped | delimiter, and a guard that silently disabled all filtering if one selector drifted. (Since replaced — see "Search-index-driven listing and pagination" above: the listing is now React state rendering JSX from a fetched corpus, which resolves this finding wholesale.)
• Dead create-next-app scaffold survives: public/{file,vercel,next,globe,window}.svg are unused and README.md is still the stock template. Delete before anyone copies this directory as a starter.
• src/lib/filterOptions.ts:23 — Math.min(...[]) yields Infinity when no entry carries numberAdopting; latent NaN placeholders in the range inputs.
• Accessibility: the result count in FilterForm.tsx has no aria-live, so screen-reader users get no feedback when filtering.

Architectural concerns

• The regex image rewrite (src/lib/articles.ts) replaces ../images/ anywhere it appears in the source text — including inside code blocks or prose — and depends on a one-off manual copy of PNGs into public/images/articles/. Fine for two images; a product needs a build-time copy step and an AST-level rewrite (a marked renderer hook or remark plugin).
• The dev-mode search fallback degraded to name/description-only substring matching when the Pagefind index was absent — the exact "two search implementations" failure SPECIFICATION.md bans. (Since improved — the fallback now substring-searches the corpus's full body field, so it reaches never-displayed attributes too; the remaining divergence is ranking/stemming, stated in the mode label.)
• Org-standards divergence is deliberate and should stay recorded as such: App Router and server-components-first — aligned with the HDR UK handbook. Tanstack/Zustand — absent, and rightly so: a static export has no client data-fetching or shared state to manage, and server actions are impossible under output: 'export'. This divergence shouldn't be "fixed" later by someone applying the handbook mechanically.

Security considerations

• Unsanitized dangerouslySetInnerHTML on both CMS-editable routes: src/app/(site)/[page]/page.tsx and src/app/(articles)/articles/[article]/page.tsx render marked.parse() output raw — marked does not sanitize, and no sanitizer exists anywhere in the dependency tree. The inline comment calls the markdown "trusted, repo-local", but the entire point of the Decap pages/articles collections is non-technical editors authoring it: a <script> tag saved through the CMS is stored XSS. Add rehype-sanitize/DOMPurify (or sanitize at build) before production — highest-priority fix.
• Decap CMS loads from unpkg with a floating version range (decap-cms@^3.0.0, no SRI hash) in src/app/(site)/admin/page.tsx — an unpinned third-party script that will run with editors' GitHub tokens. Pin + hash, or self-host. /admin/ also ships in the public static output with local_backend: true committed — production needs an environment-split config.
• bannerLink renders into href unvalidated — a CMS editor can inject javascript: URLs.

Questions for the next stage

1. What generates the TS types and Decap config from the JSON Schema, and where does entry validation run — build gate, CI, or CMS-side?
2. Decap's github backend needs an OAuth proxy that a GCS bucket + CDN cannot host — what serves that in production?
3. Zero automated tests exist — what's the minimum harness (build + ajv gate + a Playwright "Sangya" smoke test) before iteration two?
4. Is the (site)/(articles) route-group split — two full root layouts to maintain — actually needed in a product, or was it spec-driven demonstration only?
5. Given this scaffold's own AGENTS.md breaking-changes warning and the async-params change already encountered, who owns Next.js major-version upgrades — and does that maintenance cost tip the balance further toward the recommended Eleventy?