How the site’s content is shaped, validated, and kept honest. The decisions
themselves are logged in the app repo’s DECISIONS.md (D5, D13, D16); this
explains the thinking well enough to redo it elsewhere.
See also: 01-shell.md · 03-frontend.md ·
index.md
1. The problem: JSON you import is a promise, not a fact
import about from "@/content/pages/about.json";
const page = about as Page; // ← a lie, potentiallyTypeScript types are erased at runtime. as Page compiles regardless of
what the file actually contains. If someone deletes a field, TypeScript is
perfectly happy and the page renders blank in production.
There is a second, subtler problem specific to imported JSON: TypeScript widens
string literals to string. So "type": "hero" imports as string, not as
the literal "hero" — which quietly destroys any discriminated union built on
that field.
The fix is a runtime check at the boundary where content enters the app.
2. Zod: one definition, both jobs
export const seoSchema = z.object({
title: z.string().min(1),
description: z.string().min(1).max(160),
});
export type Seo = z.infer<typeof seoSchema>;z.infer derives the TypeScript type from the validator. Write the shape
once and you cannot have a type that says one thing and a check that enforces
another — the classic failure mode of hand-writing an interface next to a
hand-written validate().
The validation runs in the content loader, which runs at build time, so bad
content fails next build instead of rendering an empty section to a
visitor. That is the whole point: move the failure from production to CI.
Error messages are part of the design
Invalid content in about.json:
whoWeAre.body — Required
versus invalid content. The first tells you the file and the field. Worth the
dozen lines it takes:
function describe(label: string, error: z.ZodError): string {
const lines = error.issues.map((issue) => {
const path = issue.path.length > 0 ? issue.path.map(String).join(".") : "(root)";
return ` ${path} — ${issue.message}`;
});
return `Invalid content in ${label}:\n${lines.join("\n")}`;
}Throw, do not return null
A loader that returns null pushes an error case onto every caller, and the
lazy caller renders nothing. Throwing makes the build the thing that fails.
3. Blocks vs named fields — the real decision
Two ways to model a page.
A page-builder / block model:
sections: z.array(z.discriminatedUnion("type", [heroSchema, richTextSchema]))Named fields:
const aboutPageSchema = z.object({
seo, hero, whoWeAre, whatWeDo, objectives,
});The block model buys exactly one thing: an author can assemble a page that
nobody wrote a component for. That is genuinely valuable for a CMS with
non-technical editors and dozens of pages.
What it costs on a six-page site maintained by one developer:
- Every page has the same loose type.
page.sections[1]is
Hero | RichText, unnarrowable without a cast.page.whoWeAre.bodyis
checked at compile time. Types you cannot use are types you do not have. - Presentation leaks into array position. The first renderer alternated
section backgrounds withindex % 2. Insert one block and every surface
below it flips — a bug that is invisible in a diff and obvious to a
designer. - The page stops being readable. A
switchover section types tells you
nothing about what the About page is. This tells you everything:
<Hero {...page.hero} headingLevel="h1" />
<MediaText {...page.whoWeAre} />
<Pillars {...page.whatWeDo} tone="alt" />
<MediaText {...page.objectives} reverse />The migration argument does not rescue the block model. A page document
with named fields is the normal way to model a fixed page in Sanity too;
page-builder arrays are the other option there, not the mature one. If a
page-builder is ever wanted, it can be added for the pages that need it without
dragging every fixed page through the abstraction.
Revisit when: someone other than a developer needs to create pages, or the
same block genuinely repeats across pages in author-chosen order.
4. What does not belong in content
From the schema file, written as a rule:
no colours, no column counts, no image side, no heading levels
The test: if a field would stop making sense after a redesign, it is not
content. “Which side is the picture on” is a layout rhythm the component
owns; an author toggling it per block is how a page ends up with three pictures
down one edge.
Heading level is the sharpest example. <h1> vs <h2> depends on position in
the document, not on the block itself — the same component is an h1 at the
top of a page and an h2 further down. Storing it in content guarantees a page
with two h1s or none, which breaks screen-reader navigation. So it is a prop:
<Hero {...page.hero} headingLevel="h1" />5. Cross-field validation: .refine()
The old site’s “Why Ghana?” section claimed Ghana invests “75–85bn, so
the claim exceeded the whole economy by about 2×. A second card cited a “$1+
trillion value chain” — the World Bank’s projection for Africa’s food
market.
This is not a typo class of error, it is a credibility class of error: the
audience is investors and trade attachés who check numbers.
The structural fix — make it impossible to ship a number without saying where
it came from:
export const sectorSchema = z
.object({
title: z.string().min(1),
figure: z.string().optional(), // "$1tn by 2030"
source: z.string().optional(), // "World Bank, 2023"
})
.refine((sector) => !sector.figure || Boolean(sector.source), {
message: "a figure must name its source — unsourced numbers do not ship",
path: ["source"],
});Things worth noticing:
.refine()runs on the whole object, which is what lets it express a
relationship between fields. Per-field validators cannot see each other.path: ["source"]attaches the error to the field the author must fix.
Without it the error lands on the object root and the message is harder to
act on..refine()returns aZodEffects, not aZodObject— so.extend(),
.merge()and.pick()are no longer available on it. Refine last, after
all composition, or keep the plain object around separately.- The implication direction matters.
!figure || sourcemeans “if there is
a figure, there must be a source”. A figure-less card is still valid — the
current content ships qualitative cards precisely because nobody has verified
the numbers yet.
The general lesson: when a mistake has already been made once and is
expensive, prefer a constraint over a convention. A comment saying “please cite
sources” is a hope. A schema that rejects the document is a guarantee.
This is the same instinct as putting invariants in database constraints rather
than only in application code — a rule enforced in one place is a rule the
system will eventually let you break.
6. The content boundary
// src/lib/content.ts — the ONLY module that imports a content file
export const getHomePage = cache(async (): Promise<HomePage> =>
parseOrThrow("home.json", homePageSchema, homeJson),
);Two deliberate choices:
asynceven though reading a local import is not. Matching the eventual
shape now means swapping JSON for a Sanity client touches this one file
instead of every caller.- One getter per page, not
getPage(slug). A generic getter can only
return a union of every page shape;getHomePage()returns exactly
HomePage. Generic-looking APIs that throw away type information are a bad
trade.
cache() is React’s request-scoped memoisation. Next.js calls
generateMetadata() and the page component separately, both needing the same
content. Without cache, the file parses twice per request.
Outstanding — promote to the general vault
- Zod as a runtime boundary:
z.infer, parse-don’t-validate,.refine()
for cross-field rules and itsZodEffectscaveat →backend/or a new
validation/folder - “Constraint over convention” as a general engineering principle —
pairs with the database-constraints material
Software engineering
Infrastructure & security
Computer science
Hardware & engineering