• Accepted Date: 2023-09-13
• Reference Issues/Discussions:
  • Incremental build support #237
• Author: @natemoo-re
• Champion(s): @natemoo-re
• Implementation PR:

Summary

Incremental Build support in Astro aims to significantly speed up repeated runs of astro build. Initial builds will populate some kind of cache, which will allow subsequent builds to bypass Rollup for unchanged trees of the module graph.

Background & Motivation

The original incremental build support proposal is one of our oldest and most highly upvoted issues. Unfortunately, users have not shared many concrete examples in that thread. However, from the extensive performance profiling we've done, we know that Rollup is the main bottleneck in Astro's build process.

Now that our rendering, Markdown, and MDX performance has been optimized about as far as we can take it, now is the time to explore new options. The best option we have is to move as much of our build process out of Rollup as possible, likely with some sort of build cache. That is the goal of introducing incremental builds.

Why now? The reason is straightforward—caching is notoriously difficult to get right. We did not want to take on the additional complexity until our API surface was stable and our internal build process was easier to reason about. Thanks to significant effort from @bluwy and @ematipico in the past few months, we're now in a good place to tackle this.

Goals

• Improve astro build performance
• Avoid as much repeated processing during astro build as possible
• Implement a generic API that enables incremental builds
• Eventually, enable incremental builds by default
• Support existing static, hybrid, and server outputs

Non-Goals

• Vendor lock-in. Incremental builds will be implemented generically, supporting our existing ecosystem of deployment platforms where possible. If a host caches assets between builds, it is likely that they will support incremental builds automatically.
• Incremental Static Regeneration (also known as ISR or DPR). The proposal for supporting ISR is an entirely different topic, not covered by this accepted proposal. These features are not mutually exclusive. Implementing incremental build support benefits every user of Astro and does not prevent Astro from potentially introducing ISR in the future.
• Future: Adapter API. Some adapters perform a significant amount of processing and may also want some form of incremental build support. To reduce the scope of this proposal, we are not considering exposing a public Adapter API for this. This may be implemented in the future as an enhancement.