Eleventy Incremental Builds: Faster Rebuilds for Content-Heavy Sites

The problem: waiting for full rebuilds on every edit

On a site with hundreds of Markdown posts, a single typo fix can trigger a 15-second rebuild. Eleventy’s --incremental flag (stable since v2.0) changes that by caching the dependency graph and re-rendering only templates whose inputs actually changed. The result: sub-500 ms rebuilds during development, even on 10 k+ page sites.

How incremental mode works

When you run npx @11ty/eleventy --serve --incremental, Eleventy builds a full dependency graph on the first run. It tracks every file read via the EleventyWatchTargets API — templates, data files, includes, and any paths registered through addWatchTarget. On subsequent changes, it compares the modified file against that graph and reprocesses only the affected templates and their downstream dependents (like collection indexes).

The flag is tied to watch/server mode; it does not apply to one-shot eleventy builds. Production builds should still run without --incremental to guarantee a clean output.

Worked example: verifying the speedup on a test site

Create a minimal project to see the difference:

npm init -y
npm i -D @11ty/eleventy
mkdir src
# generate 500 simple posts
for i in {1..500}; do echo "---
title: Post $i
---
Content $i" > src/post-$i.md; done
# add a collection index
cat > src/index.njk <<'EOF'
---
title: Home
pagination:
  data: collections.post
  size: 50
---

{%- for post in pagination.items %}
  
{{ post.data.title }}
{%- endfor %}

EOF

Run the dev server with incremental mode:

npx @11ty/eleventy --serve --incremental

Edit src/post-1.md and watch the console. Eleventy logs [11ty] Writing _site/post-1/index.html and the paginated index pages — nothing else. Without --incremental, the same edit rewrites all 500 posts plus indexes.

To measure: run time npx @11ty/eleventy (full build) and compare with the incremental rebuild timestamp printed in the serve console. On a 500-page test site, full builds take ~8 s; incremental edits finish in ~200 ms.

Where it breaks: missing watch targets

The dependency graph is only as complete as the watch targets registered. A common pitfall: a shortcode that reads a JSON file directly with fs.readFileSync without calling addWatchTarget.

// .eleventy.js
const fs = require('fs');
eleventyConfig.addShortcode('badge', () => {
  const data = JSON.parse(fs.readFileSync('./src/_data/badge.json', 'utf8'));
  return `${data.text}`;
});

If you edit badge.json, the page using the shortcode will not rebuild because Eleventy never knew about that file. The fix is to register the dependency:

eleventyConfig.addWatchTarget('./src/_data/badge.json');

Plugins that write generated assets (e.g., image optimization outputting to _site) must also call addWatchTarget on their output directories, or changes won’t trigger rebuilds.

Trade-offs and limitations

• Memory: The full dependency graph stays in memory during the watch session. Sites with 50 k+ templates may hit Node heap limits during long runs.
• Stale cache risk: Incomplete dependency tracking can produce missing pages. Never rely on incremental builds in CI; always run a clean eleventy build for production.
• Custom data files: JavaScript data files that import external modules need those modules added to watch targets manually, otherwise edits to the imported modules are ignored.
• Not for one-shot builds: The flag only works with --serve or --watch.

When to use it

Enable --incremental for local development on content-heavy sites where you edit one or two files at a time. Disable it for CI, production deploys, and any scenario where you suspect the dependency graph is incomplete (e.g., after adding a new plugin that reads files outside Eleventy’s watch system). A quick sanity check: after enabling incremental mode, edit a data file used by a collection — if the collection index doesn’t rebuild, you have a missing watch target.