Selective Per-Plugin Builds for Docusaurus Multi-Instance Sites

[TaushifAli1]

We've built and battle-tested a selective build system in production at UiPath (28 products, 2 locales). We'd like to extract it into a standalone package for the community.

The approach is simple and non-invasive — it works with Docusaurus, not against it:

1. The documentation is decomposed into logically independent Docusaurus plugin instances. Each plugin represents a coherent unit (e.g., product area, locale, or domain), enabling isolated builds.
2. Filter plugins via env vars → Only load requested plugins into Docusaurus
3. Run standard docusaurus build → Docusaurus builds normally, just fewer plugins
4. Copy output to merged directory → Each plugin's output lands in the right path
5. Fix asset paths → Post-process HTML/JS to correct asset references

---

Complete Build Flow Example

A content author edits guides/intro.md. Here's what CI/CD does:

1. Detect which plugin changed

changed_plugin="guides"

2. Build only that plugin (for each locale)

BUILD_FOLDERS=guides BUILD_LOCALES=en docusaurus build
→ copy build/guides/ to out/docs/guides/
→ copy build/assets/ to out/docs/guides/assets/
→ fix paths in out/docs/guides/**/*.html and *.js

BUILD_FOLDERS=guides BUILD_LOCALES=ja docusaurus build
→ copy build/ja/guides/ to out/docs/ja/guides/
→ copy build/assets/ to out/docs/ja/guides/assets/
→ fix paths in out/docs/ja/guides/**/*.html and *.js

3. Deploy only out/docs/guides/ and out/docs/ja/guides/

 (other plugins untouched)

Result: Instead of rebuilding all 4 plugins x 2 locales (8 builds), we do 2 builds. Only the changed content is rebuilt and deployed.

---

CLI Interface

• Build one plugin, default locale
  dbs guides

• Build one plugin, specific locale
  dbs guides:ja

• Build multiple plugins
  dbs guides api-reference

• Build multiple plugin:locale combinations
  dbs guides:en sdk:ja

• Build only shared assets (homepage, 404)
  dbs --common

---

Production Results (UiPath)

We've been running this in production with 28 doc plugins and 2 locales (56 plugin:locale combinations):

• Full build: 20+ minutes, 10GB+ RAM, all 56 plugin:locale instances
• Selective build: ~2 minutes, ~2GB RAM, 1 plugin:locale instance
• Build time reduction: ~90%
• Memory reduction: ~80%

---

What We're Proposing

1. Community package: Publish docusaurus-build-selective as a standalone npm package
2. Zero Docusaurus core changes: Works with Docusaurus 3.x as-is
3. Extensible: Lifecycle hooks for site-specific post-processing
4. Open for feedback: Does this align with Docusaurus v4 direction? Interest in core integration?

---

[slorber]

Hi

I find the idea interesting, but it's hard to review without seeing the implementation.

FYI, on our site we already rely on env variables too. For example, in deploy previews we only deploy a limited number of docs versions to have a faster feedback, and we have a prod / i18n-staging envs with a different set of locales.

---

I'm not sure I fully understand how your system works.

• 1. Are you creating one standalone SPA per plugin/locale combination
• 2. Are you rebuilding a "slice" of one global SPA based on what changed?
• 3. something else?

The 1st approach would work, and this is somehow what we recommend for i18n multi-domain deployments: https://docusaurus.io/docs/i18n/tutorial#multi-domain-deployment
You can create one SPA per locale and have all locales build in parallel instead of sequentially, and trigger per-locale rebuilds.

---

But I don't think the 2nd approach would work, unless you decide to isolate each plugin insteance in a standalone SPA (in which case you'd have to find a way to create "non-SPA links" between your distinct SPAs)

For example, I don't think you can selectively copy JS assets of a single JS plugin this way:

copy build/assets/ to out/docs/ja/guides/assets/

You can't easily mix/replace/override the assets of 2 SPA builds. At least if this works, I believe this is fragile and could eventually break depending on the changes you make to your site.

There are technologies that can help support this use case better. For example, Module Federation is used for assembling multiple frontend "micro-services" into a single SPA, and could probably be helpful, but it's not something we have already worked on.