Harnessing Eleventy's Data Cascade for Environment‑Aware Builds

Why the Data Cascade Matters

Eleventy’s build pipeline stitches together data from four sources in a precise order:

• Global data files in _data/
• Directory data files (e.g., blog.11tydata.json)
• Template front‑matter (YAML/JSON/TOML at the top of each file)
• Computed data via eleventyComputed (v2.0+)

Each successive layer overrides the previous one on a key‑by‑key basis. Objects are deep‑merged by default, so nested properties combine rather than replace. This predictable merge order lets you keep environment flags, site defaults, and page‑specific overrides in a single, maintainable place.

Case Study: A Production‑Aware Site

Suppose you want a flag that tells templates whether the build is for production or staging, and you want that flag to be available everywhere without writing a custom script in eleventy.config.js. The data cascade gives you a clean solution.

1. Create a global data file that exposes the environment variable:

/* _data/env.js */
module.exports = () => ({
  isProd: process.env.NODE_ENV === 'production',
  isDev: process.env.NODE_ENV !== 'production'
});

Running npx @11ty/eleventy will execute this function once per build, reading process.env.NODE_ENV at build time. The exported object becomes available in every template as env.

1. Use the flag in a layout or partial to branch logic:

{% if env.isProd %}
  <script src="/js/analytics.min.js"></script>
{% else %}
  <script src="/js/analytics.dev.js"></script>
{% endif %}

Because env is global, you can reference it in any page without duplicating the environment check.

Adding Section‑Wide Defaults with Directory Data

Imagine a blog section that should always use a specific layout and default tags. Place a blog.11tydata.json in the blog/ folder:

{
  "layout": "post.njk",
  "tags": ["blog"]
}

All files in blog/ and its sub‑directories inherit these defaults. A simple blog/post1.md can omit the layout and tags entirely:

---
# title: Hello World
---

Welcome to my first post.

Eleventy will apply the layout and tags from the directory data file automatically.

Fine‑Tuning with Front‑Matter and Computed Data

Sometimes you need per‑page overrides that depend on other data. Use eleventyComputed to build values after the cascade has resolved.

---
layout: post.njk
title: "My Post"
site:
  meta:
    description: "A short description"
eleventyComputed:
  fullTitle: data => `${data.title} | ${data.site.meta.title}`
---

Content goes here.

The fullTitle field will contain the page title plus the global site title, thanks to deep merging of site.meta from _data/site.js.

Trade‑offs and Caveats

• Async global data runs once per build and cannot access the current page’s context (e.g., URL). If you need page‑specific data, use computed data or shortcodes.
• Deep merge is enabled by default (v1.0+). If you prefer a shallow merge, set eleventyConfig.setDataDeepMerge(false) in eleventy.config.js.
• Performance: Large async fetches in _data/ can slow cold builds. Cache results to disk or rely on Eleventy’s incremental build mode to avoid re‑fetching unchanged data.
• Directory scope: blog.11tydata.json only affects blog/ and its sub‑directories. It does not cascade to sibling folders.
• Computed data order matters. A computed field cannot reference another computed field defined in the same front‑matter block; it can only reference already resolved keys.

Practical Checklist

1. Place environment‑specific flags in _data/env.js and reference them via env.
2. Use directory data files for section defaults; keep the directory structure tidy.
3. Leverage eleventyComputed for derived values that depend on merged data.
4. Disable deep merge only when you need strict overrides.
5. Cache heavy async data or enable incremental builds to keep build times reasonable.

By treating the data cascade as a single, uniform source of truth, you eliminate the need for ad‑hoc build scripts and keep your Eleventy configuration DRY and maintainable.