Skip to navigation Skip to main content
Blog
Back Build Awesome Pro and make it easier to build for the web!
Versions
Stable
3.1.7
Canary
4.0.0-alpha.10

Incremental Builds

Incremental builds via the command line flag --incremental perform a partial build operating only on files that have changed to improve build times when doing local development.

Let’s check in on the current capabilities and the roadmap:

  • Templates (Incremental template builds):
    • If you create/update a template file, Eleventy will run the build for that file and only that file.
    • Layouts Added in v2.0.0: When you change a layout file, any templates using that layout file are rebuilt.
    • Template Dependencies Added in v2.0.0Any templates using a dependency mapped via the addDependencies method will be rebuilt when those dependencies change.
      • Added in v1.0.0This feature was previously exposed as part of the API for Custom template extensions via the isIncrementalMatch function.
    • Includes Pre-release only: v4.0.0-alpha.11: When you change an include, any templates using it (directly or through other includes) are rebuilt.
      • Nunjucks: {% include %}, {% import %}, {% from %}, and {% extends %}.
      • Liquid: {% include %}, {% render %}, and {% layout %}, including in Liquid-preprocessed Markdown.
      • A full build runs instead when no template uses the file, before the first full build finishes (e.g. with --ignore-initial), after a failed build, or when the file was deleted.
    • JavaScript Dependencies Pre-release only: v4.0.0-alpha.11: When you change a JavaScript module imported by a JavaScript template (.11ty.js and the other JavaScript template extensions, e.g. .11ty.mjs, .11ty.ts, .server.js) or by a JavaScript layout, only templates using that module are rebuilt.
      • A full build runs instead when the module is also imported by your configuration file or a data file.
      • Requires watchJavaScriptDependencies (enabled by default) and only applies to --watch/--serve.
    • Data Files Pre-release only: v4.0.0-alpha.11:
      • Template and directory data files: only templates using that data file are rebuilt.
      • Global data files: only templates that read the file’s top-level key are rebuilt (e.g. _data/site.json or _data/site/meta.json rebuild templates using site). Reads are tracked as templates use their data, including in layouts.
      • A full build runs when a data file is new, deleted, or unused by any template.
      • Global data used outside of template data (e.g. imported directly in a JavaScript file, or captured by a plugin) isn’t tracked.
    • Render Plugin Pre-release only: v4.0.0-alpha.11:
      • {% renderFile %}: when the rendered file changes (including files outside the input directory), only templates rendering it are rebuilt, along with the rendered file’s own includes.
      • {% renderTemplate %}: templates using it are rebuilt when an include or component used inside a renderTemplate block of the same template language changes (e.g. a Nunjucks include or a WebC component).
      • Files outside your input directory still need to be watched (e.g. via addWatchTarget).
    • Collections Added in v2.0.0: When you add or delete a tag from a template, any templates using that collection tag (as declared by pagination.data or eleventyImport.collections) will be rebuilt. Pre-release only: v4.0.0-alpha.11This also applies when a data file change adds or removes a tag.
  • Passthrough Copy (Incremental passthrough copy) :
    • Only copy a passthrough copy file when it actively changed. Don’t run a template or full build if only a passthrough copy file has changed.
    • When running a template build, skip the passthrough copy step.
    • Added in v2.0.0 Passthrough copy can be emulated during --serve to speed up both incremental and non-incremental builds. It was decided not to ship incremental passthrough copy as the default behavior (#1109), instead deferring to this emulated copy feature.
  • Configuration File
    • If you create/update your Eleventy configuration file, a full build will run.
  • Don’t build on startup: Added in v2.0.0 --ignore-initial was added and works great with --incremental.
  • Explicit Incremental Added in v3.0.0 Pass in a filename to only build an incremental for one file (and it’s dependencies) with --incremental=filename (more in #3324)
    • Pre-release only: v4.0.0-alpha.8Added support for multiple incremental files (also called Batched Incremental) with --incremental=file1 --incremental=file2 or --incremental=file1,file2 (more in #4274)

Additional Template Syntax Specific Features

The previously stated incremental features are implemented in Eleventy core and are available to all template languages. Some template types offer additional --incremental build support:

  • WebC: Deep knowledge of the full component dependency graph allows us to smartly build templates that use a WebC component when the component is changed.

🗓 To Do

  • Cold Start Incremental: --incremental does a full build to start out to provide a fresh starting point to work from. This feature would save the state of the build to the file system for faster cold starts. #984
  • Incremental on a Build Server: Cache the output folder between builds on a CI server like Netlify, and only process/write templates that have changed since the last build. #2775
  • Collections dependencies improvements:
    • While we have eleventyImport.collections to declaratively log collections dependencies, we may be able to dive deeper into template syntax APIs to find the symbols in use. #1615
    • Alternatively, we may be able to change the collections API to use Proxies to get smarter about this in an easier way (though previous experiments with this for eleventyComputed failed in some languages).
  • Stretch goal: Pagination-level incremental that operates on a subset of data #1087
This page on Build Awesome