Optimize Static Builds: Tree-shake Unused Components in CMS Page Builder Patterns

[moritzlaube]

Body

Summary

When building static sites with a CMS page builder approach, where pages are dynamically composed of a library of components, Astro currently includes all potential components in every page bundle, even when only a subset is actually used. This RFC proposes build optimizations for static sites to only include components that are actually used in the final bundle, either through static imports with tree-shaking or optimized dynamic imports.

Background & Motivation

Modern headless CMSs like Strapi, Prismic, Directus or even WordPress with the Gutenberg Blocks offer page builder capabilities where content editors can freely compose pages from a predefined set of components. For example, they can build a landing page by combining a hero section, feature list, testimonials, and a contact form – all through the CMS interface.

When building such sites with Astro (output: 'static'), the current behavior includes all available components in every page bundle, even though:

1. We know exactly which components each page needs at build time from the CMS data
2. The pages are pre-rendered to static HTML
3. There's no streaming happening in static builds

This leads to unnecessarily bloated bundles in static sites, where pages might only use 3–4 components but include scripts and styles from, let's say, all 20-30 available components. While the current behavior makes sense for SSR where streaming requires knowing all possible scripts upfront, it seems unnecessary for static builds.

This issue was previously discussed in #4863 but was closed due to perceived technical constraints related to streaming. However, since streaming isn't relevant for static builds, this limitation should be revisitable.

Goals

• Optimize static builds by only including actually used components in the final bundle
• Analyze component usage at build time to determine which components are actually needed
• Reduce bundle sizes for statically generated sites with dynamic component composition
• Eliminate console errors from unused component scripts
• Maintain Astro's excellent DX while working with CMSs and dynamic component loading
• Keep the current behavior for SSR builds where streaming is beneficial

Example

In my humble opinion, there are two possible approaches to implement this optimization, using either static or dynamic imports. Both approaches would solve the same problem of unnecessary component loading.

Current behavior can be seen in this Stackblitz example – although using an outdated Astro version, the issue still applies –, where even unused components are included in the final bundle.

Static Import Approach (Preferred)

---
// product.astro
// Statically import all possible components that could be used in the CMS
import Benefits from '../components/marketing/Benefits.astro';
import TextOnly from '../components/marketing/TextOnly.astro';
import BlogFeed from '../components/marketing/BlogFeed.astro';
import Ingredients from '../components/product/Ingredients.astro';
import Contact from '../components/marketing/Contact.astro';

// Create a map of all available components
const componentMap = {
  'marketing.benefits': Benefits,
  'marketing.text-only': TextOnly,
  'marketing.blog-feed': BlogFeed,
  'product.product-ingredients': Ingredients,
  'marketing.contact': Contact
};

// Get data from CMS
const product = await getCmsData();

// Map CMS data to actual components
const components = product.attributes.dynamicZone.map(z => ({
  Component: componentMap[z.__component],
  data: z
}));
---

{components.map(({ Component, data }) => 
  <Component data={data} />
)}

Dynamic Import Approach (Alternative)

---
// product.astro
// Get data from CMS
const product = await getCmsData();

// Map component types to their file paths
const getComponentPath = (type) => {
  switch (type) {
    case 'marketing.benefits':
      return '../components/marketing/Benefits.astro'
    case 'marketing.text-only':
      return '../components/marketing/TextOnly.astro'
    case 'marketing.blog-feed':
      return '../components/marketing/BlogFeed.astro'
    case 'product.product-ingredients':
      return '../components/product/Ingredients.astro'
    case 'marketing.contact':
      return '../components/marketing/Contact.astro'
  }
};

// Load components dynamically
const components = await Promise.all(
  product.attributes.dynamicZone.map(async z => ({
    Component: (await import(getComponentPath(z.__component))).default,
    data: z
  }))
);
---

{components.map(({ Component, data }) => 
  <Component data={data} />
)}

With either approach, Astro should:

1. Analyze which components are actually used during the build of each page
2. Only include the scripts and styles of components that are actually rendered
3. Tree-shake unused components from the final bundle

The static import approach offers several advantages:

1. Simpler build-time analysis
2. No need for dynamic import path resolution
3. More explicit component mapping
4. Easier to validate CMS component references

Both approaches would achieve the same goal: ensuring only used components are included in the final static build. The static import approach might be easier to implement since it leverages existing static analysis capabilities of bundlers.

This feature would be crucial for anyone building CMS-powered static sites where pages are dynamically composed through a page builder interface (which is really common when working with clients).

While my understanding of Astro's internal architecture is quite limited, I hope this proposal can spark a discussion about this important feature. And thank you for creating such an amazing tool!

[tedevra]

We would like to see that in dynamic SSR rendering as well and would even waive the streaming option since every page is cached through our cdn for an hour anyway.

[iankduffy]

Definitely interested in this, today I had a video component in my articles page, which added 240kb to the bundle because it used mux-player library, even if the article didn't have one.

Changed this to dynamic imports with intersection observer, which solved it, but almost slipped past me.

[matthewp]

Hi @moritzlaube, I don't think I quite understand what you are asking for. In particular:

When building static sites with a CMS page builder approach, where pages are dynamically composed of a library of components, Astro currently includes all potential components in every page bundle, even when only a subset is actually used.

What do you mean here? What is a "page bundle"?