Part of frameworks/sanity. [reference]
Real code: munakalati · Converting into it: the Wix migration
Part 1 — Portable Text
Why rich text isn’t stored as HTML
Portable Text is rich text as structured JSON:
{ "_type": "block", "_key": "a1b2c3d4", "style": "h2", "markDefs": [],
"children": [ { "_type": "span", "_key": "e5f6", "text": "Stories that shape", "marks": ["strong"] } ] }Four arguments against an HTML blob, in order of weight:
- An HTML blob is only renderable as HTML. The same content here renders to React on the web, native components in an app, or plain text for a search index — because it never encoded a rendering decision.
- Safe by construction. Nothing to sanitise, because there is no markup.
- Diffable and queryable. The query language can reach inside blocks; the CMS can merge concurrent edits.
- Custom embeds are first-class. An image in an article body is a structured node, so it can go through your framework’s image pipeline inside a semantic
<figure>— not an<img>parsed out of a string.
The cost: nothing renders until you say how.
The four things in the format
block— a paragraph-level unit.styleisnormal | h2 | h3 | blockquote | …;listItemandlevelhandle lists.span— a run of text inside a block, split wherever formatting changes. “This is bold text” is three spans.marks— strings on a span. Either a decorator ("strong","em") or a_keypointing intomarkDefs.markDefs— block-level definitions for marks carrying data. A link ismarkDefs: [{_key: "x1", _type: "link", href: "…"}]with the span carryingmarks: ["x1"].
The indirection is the part people get wrong. A link’s
hrefis not on the span; the span references a definition on its parent block. It’s a normalisation, so one annotation can cover several spans without repeating its data — and it’s why writing a converter that handles bold is trivial and one that handles links is not.
_key is mandatory on every block and span, unique among siblings. It’s what lets the CMS diff arrays for real-time collaboration; without stable keys, two editors typing in one document produce garbage.
Rendering: four buckets
const components = {
block: { // keyed by `style`
normal: ({ children }) => <p className="…">{children}</p>,
h2: ({ children }) => <h2 className="…">{children}</h2>,
blockquote: ({ children }) => <blockquote className="…">{children}</blockquote>,
},
list: { bullet: …, number: … }, // the <ul>/<ol> wrappers
marks: { // inline
strong: ({ children }) => <strong>{children}</strong>,
link: ({ value, children }) => ( // `value` is the markDefs entry
<a href={value?.href} target="_blank" rel="noopener noreferrer">{children}</a>
),
},
types: { // non-text blocks from the schema's `of: [...]`
image: ({ value }) => (
<figure>
<div className="relative aspect-video">
<Image src={urlFor(value).width(1200).url()} alt={value.alt ?? ""} fill className="object-cover" />
</div>
{value.caption && <figcaption>{value.caption}</figcaption>}
</figure>
),
},
};Knowing which bucket a thing goes in is most of the skill. types is the extension point — anything in the schema’s of: [...] that isn’t a block. Add { type: "youtube" } to the schema and it renders here.
rel="noopener noreferrer" on external links isn’t boilerplate: noopener stops the opened page reaching back through window.opener to navigate your tab somewhere hostile. Browsers imply it for target="_blank" now; writing it is still correct.
Part 2 — Images
An image field stores a pointer
{ "_type": "image",
"asset": { "_type": "reference", "_ref": "image-abc123-1600x900-jpg" },
"alt": "Children reading in a classroom" }The binary lives once in a shared asset store. Two consequences:
- Deduplication is automatic — uploading the same file twice returns the same asset ID.
- The ID encodes the dimensions (
-1600x900-), so an aspect ratio is computable without a round trip.
Extra fields on the image type
defineField({
name: "coverImage", type: "image",
options: { hotspot: true },
fields: [defineField({ name: "alt", type: "string" })],
})Alt text belongs on the field, not the asset — an image describes itself differently depending on where it appears. The same photo is “the team at the 2024 summit” on an About page and “our founder accepting the award” in a post.
Two habits: validate alt as required (a step this is usually skipped, and accessibility debt accumulates fast at bulk-import scale), and know that alt="" is a deliberate statement that the image is decorative and should be skipped by a screen reader. Omitting the attribute entirely is the bug.
hotspot: true — always turn it on
Without it, cropping to a different aspect ratio centre-crops and beheads people. With it, the editor drags a focal point in the Studio and the URL builder respects it when resizing. Costs nothing; prevents the most common CMS complaint.
The URL builder
<Image src={urlFor(post.coverImage).width(1600).url()} alt={…} fill className="object-cover" priority />A chainable builder; .url() produces the string. The chain compiles to query params on the CDN, and the transformation happens on demand, then caches — upload one 4000px original, serve a 600px thumbnail from it.
Match the width to the slot, and request 2× the CSS size for small fixed images (a 40px avatar at .width(80) is crisp on retina and still a few KB). Worth adding to a shared wrapper: .auto('format') for content-negotiated AVIF/WebP, which is close to free bytes.
Two CDNs, on purpose
With next/image (or any framework optimiser) there are now two: the CMS CDN resizes, then the framework’s optimiser re-encodes and serves the srcset. That’s not a mistake — requesting a sensibly-sized image from the CMS first means the optimiser isn’t handed a 4000px original to chew on.
Remote hosts must be allowlisted, and the reason is worth knowing: otherwise anyone could point your optimiser at any URL and bill you for the CPU.
images: { remotePatterns: [{ hostname: 'cdn.sanity.io' }] }The layout pattern
<div className="relative aspect-video overflow-hidden">
<Image src={…} alt={…} fill className="object-cover" />
</div>fill absolutely positions the image to fill its nearest positioned ancestor — so the wrapper needs relative and its own height (here from aspect-video). That’s what reserves layout space before load and prevents cumulative layout shift. priority for the LCP element only; never below the fold.
Related
Software engineering
Infrastructure & security
Computer science
Hardware & engineering