drupal-render-pipeline

Render Pipeline — Expert Rules

Basics (tags/contexts/max-age snippets, N+1) live in the performance-audit skill and the drupal-coding-standards rule. This skill covers the semantics that AI-generated code most often gets wrong — bugs that are invisible in development (cache disabled) and surface only in production.

Render arrays, not HTML strings or Response objects

An HTML page controller must return a render array. Returning new Response($html) or a concatenated string detaches the output from the render system: cache metadata from children is silently lost and the page becomes uncacheable or caches wrong.

• Return a Response only when intentionally bypassing rendering (file downloads).
• JSON endpoints: use CacheableJsonResponse and add cacheable dependencies — a plain JsonResponse carries no cache metadata.

Max-age bubbles minimum-wins — the reason lazy builders exist

Cache metadata propagates UP the render tree, and max-age takes the MINIMUM along the way: a single child with max-age: 0 forces the entire page to be uncacheable. So never place personalized content (username, cart count, per-user messages) directly in a render array — isolate it in a lazy builder so the rest of the page stays cached:

$build['greeting'] = [
  '#lazy_builder' => ['mymodule.greeting_builder:build', [$account_id]],
  '#create_placeholder' => TRUE,
];

Lazy builder arguments must be scalars (string, int, float, bool, NULL). They are serialized into placeholder markup — passing an entity or array throws. Pass the entity ID, load inside the builder. This is one of the most frequent AI-generated bugs.

BigPipe consumes these placeholders in production (streams the page, fills placeholders via chunked transfer). Rendering a placeholder to a string early defeats it.

Cache keys vs bubbling

#cache['tags'|'contexts'|'max-age'] describe the metadata that bubbles up. Only #cache['keys'] makes the render array ITSELF independently stored in the render cache. Without keys, the array is re-built every time its parent is — its metadata still bubbles.