Inline partials vs registered partials: lexical context capture vs global reuse for component libraries

The short answer

Use registered partials for anything shared across templates (header, footer, layout chrome), and reserve inline partials for components that are defined and consumed inside a single template. There is no official rule because the two mechanisms solve different problems: inline partials are a scoping tool, registered partials are a distribution tool. The hybrid you describe — authoring each shared component once and registering it programmatically at startup — is the standard way to get both.

Why inline partials can't share a header across 50 pages

An inline partial ({{#*inline "name"}}) exists only within the template block where it is defined. It captures the lexical context at its definition site, which is exactly the isolation you want for encapsulated components — but it also means the definition is invisible to every other template. Adopting inline partials everywhere forces copy-paste for anything global, so that option answers itself: it doesn't scale to shared layout.

Guardrails against context leakage in registered partials

Registered partials execute against whatever context the call site passes, so ../user inside a partial can silently read the caller's data. Two guardrails cover most of the risk:

• Pass a narrow, explicit context at every call site. Prefer {{> lib/header user=currentUser}} or {{> lib/header this.headerData}} over rendering against the ambient parent context. The partial then only sees what it declares.
• Ban ../ inside library partials by convention, enforced by linting or review. Handlebars does not enforce this — without a check, the convention erodes. A simple template-source scan for ../ in the component directory is usually enough.

Combined with @partial-block for forwarded content, a registered partial behaves like an encapsulated component: callers supply only the parameters and block content it declares.

The hybrid pattern

Author each shared component in its own template file, then register them all once at application bootstrap:

Handlebars.registerPartial('lib/header', headerSource);
Handlebars.registerPartial('lib/modal', modalSource);

This gives global reuse without duplication, and isolation comes from the parameter-passing convention above rather than from lexical scoping. Two operational details matter:

• Namespace the names. The registry is global and collisions are silent — a later registration overwrites an earlier one. Prefixes like lib/ prevent a page template from clobbering a library component.
• Register synchronously before the first render. Handlebars resolves partials from the registry at render time, so async loading of partial sources must complete during startup. This keeps the SSR pipeline simple.

Verifying the assumptions

These behaviors are well established but worth confirming against your pinned Handlebars version, since decorator and @partial-block semantics have shifted across releases:

1. Render a test partial containing ../user from a parent whose context has user; confirm the leak, then re-render with a narrowed explicit context to confirm isolation.
2. Register the same name twice with different bodies and confirm the last one wins — this validates the namespacing requirement.
3. Define an inline partial in one template and invoke it from another; confirm it is not visible, confirming inline partials can't serve shared layout.

One caveat: inline partials defined inside loops or blocks are re-evaluated per iteration, which surprises teams expecting a single definition — another reason to keep them local and small.