Possible to do Incremental Static Regeneration?

[osseonews]

Currentlly, if we make a change in 1 file, we need to rebuild the entire site to see the change for that file. Is there any way to do incremental statisc regeneration (ISR) with Docusaurus, so we can just trigger a rebuild of the specific file that changed, rather than all files? If this is not possible now, can this be added as a feature? Just seems wasteful to have to rebuild everything when only one or even a few files change. Thanks.

[slorber]

Docusaurus is a static site generator and does not plan to introduce a server runtime (at least in the near future). That would prevent us from deploying to simple static hosts like GitHub Pages.

The name "Incremental Static Regeneration", as introduced by Vercel, is confusing because... it's not really "static", it relies on pre-rendering serverless functions and caching the result on a CDN:

• https://vercel.com/docs/incremental-static-regeneration
• https://vercel.com/docs/build-output-api/v3/primitives#prerender-functions

If your site is large, takes a long time to build, and changes often, then maybe a static site is not what you are looking for, and you should use a framework supporting a server runtime instead (Next.js, Remix, Gatsby...)

---

We don't have a way to build just a single static file that belongs from a markdown/MDX file. That would be quite challenging to achieve. Gatsby had significant resources and still took years to achieve that (and to be honest I'm not even sure it was so successful since nobody uses Gatsby anymore today)

Any change can have an impact on your module graph. A MDX file for example could add an import to another React component or library, impacting how bundles are code split in your SPA app. A MDX file could also become larger when introducing additional content, and be split in a different way by the bundler, affecting all the JS files/hashes, and then the references to those bundles in other static files get affected.

Also, CDNs do not always permit to "patch" an existing deployment. I mean, you can't tell the CDN to "take this existing deployment, add/update just one file in it, and consider it to be the new prod deployment". CDNs do optimizations internally to deploy files, but you should generally provide them a full static deployment.

So, I'm not an expert on all this, but it's unlikely we'll have anything like that anytime soon due to the complexity it involves.

---

Maybe what you want instead is "faster incremental builds"?

Somehow, we already have that, thanks to Webpack persistent caching and other internal optimizations.

docusaurus clear
docusaurus build # old build - slower
docusaurus build # warm (re)build - faster

On your CI you can achieve incremental builds by telling your CI to cache the ./node_modules/.cache. Some CI do that for you automatically by caching node_modules.

I plan to write some docs regarding how to optimize the build and prod hosting of a Docusaurus site. But as this is a bit CI/host-specific I'll have to gain experience on the most popular options first.

---

Note we regularly try to improve:

• cold build time
• warm build time
• dev server startup time
• dev server hot reload time

Recent minor releases introduced significant performance improvements, and I plan to ship more. Note that using a modern runtime can also increase speed. Node 22 is faster, and I'm also trying to get Docusaurus run with Bun.

We have a meta issue where various Docusaurus build performance, news, tips and experiments are shared: #4765