Does Eleventy Perform Deep Merges Across the Data Cascade?

Question

Data Cascade Merging
Eleventy builds a single data object for each template by merging global data files, directory‑specific data, and the template’s front matter. The process is documented to resolve key conflicts by overriding earlier sources with later ones, but the exact depth of the merge is not explicitly described.
Current Understanding
When a key exists in multiple data layers, the value from the template front matter takes precedence over directory data, which in turn overrides global data. However, it is unclear whether nested objects are merged recursively or simply replaced, and how array values are handled when they appear in more than one layer.
Unresolved Questions

Does Eleventy perform deep merges when combining nested objects across the Data Cascade, or are nested objects overwritten?
When arrays are defined in both global data and a directory data file, how does Eleventy merge or override them?
Is there a configurable option to switch between shallow and deep merging behavior?

Tasadduq Burney · Answer

Answer
Eleventy does perform a deep merge for object values across the Data Cascade, while array values are overridden (not merged).
Confirmed facts

When the same top‑level key holds an object in two or more data sources, Eleventy recursively merges the object properties, giving precedence to the later source for conflicting nested keys.
If the value is not a plain object (e.g., an array, string, number), the later source completely replaces the earlier one.
This behavior relies on a lodash‑style merge implementation and is present in Eleventy v1.0 and later; very old releases (pre‑v0.12) behaved the same way.

Verification steps

Create _data/global.json with { "nested": { "a": 1, "b": 2 }, "items": [1,2] }
Add a subdirectory subdir/ with its own _data/subdir.json containing { "nested": { "b": 20, "c": 30 }, "items": [3,4] }
Place a template subdir/index.njk with front matter --- nested: { "c": 300 } --- and output {{ nested }} | {{ items }}
Run eleventy and inspect the rendered output. You should see nested equal to { "a": 1, "b": 20, "c": 300 } (deep‑merged object) and items equal to [3,4] (array from the directory data, overridden by the later source).

If the output matches the above, the cascade is performing a deep merge for objects and a shallow override for arrays.

Does Eleventy Perform Deep Merges Across the Data Cascade?

Data Cascade Merging

Current Understanding

Unresolved Questions

1 answer

Answer

Confirmed facts

Verification steps

Your perspective belongs here.

0 question comments